feat(planning): add questionnaire skill for person-held decisions (0.19.0)

[kyle-sexton]

Summary

Adds /planning:questionnaire — a user-invoked-only skill that turns a decision the user cannot answer, because another person holds the knowledge, into a Markdown discovery questionnaire handed off async. Adapted from Matt Pocock's to-questionnaire (mattpocock/skills, in-progress) per the evaluation that greenlit the port, with the grill→interview vocabulary rename throughout.

The defining move: interview the send, not the subject. The skill asks the user only what they can always answer — who the questionnaire goes to (role, expertise, relationship) and what they need back — then writes questions aimed at the gap between what the recipient knows and what the user needs. It never quizzes the user on the subject the recipient holds.

Decisions from the evaluation, all carried through:

• Home + name: planning plugin, artifact-noun questionnaire (the prd precedent); keeps the future interview→questionnaire routing intra-plugin. disable-model-invocation: true (a side-effecting hand-off the user times, matching upstream).
• Composition: third routing bucket beside /planning:interview's facts-vs-decisions split — a person-arbitered deferral. Ships standalone; the interview-side one-line pull-out lands separately as an additive edit.
• PII: output relocated from upstream's cwd write to the topic-docs memory slice (default .work/, self-ignoring), so recipient names never enter git history. No egress — the skill authors a local file; delivery is out-of-band.
• Tracker seam: optional "awaiting answer" lifecycle item goes through the work-item-tracker seam (title/topic only, never the recipient's name), skipped gracefully when no tracker is bound. Never a hardcoded gh call.
• Config: none — output path rides the existing topic-docs binding; no speculative knobs (Rule of Three).
• Evals (warranted): four cases — send-only happy path, the never-quiz-the-subject guardrail, self-answerable routing back to /planning:interview, tracker-absent graceful degrade.

Also fixes the planning README's stale "depth-first Q&A" phrasing in the interview row (missed residue from the frontier-rounds propagation).

Planning plugin bumped 0.18.0 → 0.19.0. Security review clears trivially: no hooks, scripts, MCP, network, secrets, or userConfig.

Related

Closes #284. Same upstream gap-analysis batch as #278/#282 (#294), #283 (#297), #285 (#298).

Verification

• jq empty on evals.json and plugin.json
• claude plugin validate plugins/planning ✔
• markdownlint-cli2 on all new/touched markdown: 0 errors
• node scripts/generate-catalog.mjs: catalog in sync (plugin description unchanged)

🤖 Generated with Claude Code

[claude]

Claude finished @kyle-sexton's task in 3m 1s —— View job

---

PR Review — feat(planning): add questionnaire skill (0.19.0)

• Gather context — read changed files
• Validate plugin manifest & structure
• Review SKILL.md for correctness and guardrails
• Review template for PII/egress concerns
• Review evals for coverage
• Check CHANGELOG and README alignment
• Post findings

---

Summary

Well-structured addition. The PII discipline (memory-slice routing, excluding recipient names from the tracker seam), the disable-model-invocation: true choice, and the four-eval coverage are all sound. The CHANGELOG and README entries are accurate and properly describe the new capability. Three findings below — one important, two nits.

---

🔴 Important

reference/topic-docs.md not updated — new artifact unregistered

The plugin's reference/topic-docs.md is the authoritative artifact registry (${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md) that every planning skill reads to understand where artifacts land. All existing memory-tier artifacts are listed there — interview-checklist.md, plan-checklist.md, baselines/, brainstorm.md. The new questionnaire-<slug>.md artifact is absent.

This matters because other skills and the setup skill need a complete picture of what the planning plugin writes. A user re-running /planning:setup or another skill cross-referencing what lives in the memory slice will have an incomplete view.

Fix: Add a row to the "What this plugin writes, per tier" table:

| `questionnaire-<topic-slug>.md` (`/planning:questionnaire`) | Memory | `.work/<topic-slug>/` — never committed |

Fix this →

---

🟡 Nit 1

Filename questionnaire-<slug>.md is inconsistent with the rest of the memory tier

All other memory-tier artifacts from planning skills use a type-only name within the topic directory — interview-checklist.md, plan-checklist.md, brainstorm.md — without re-embedding the topic slug in the filename (the directory already carries that context). The questionnaire's path at SKILL.md line 29 produces .work/database-sharding/questionnaire-database-sharding.md — the slug appears twice. A consistent name would be questionnaire.md, matching the established pattern. If multiple-recipient support is anticipated, questionnaire-<recipient-role>.md would be more descriptive than repeating the topic slug. Worth aligning before 1.0.

---

🟡 Nit 2

Self-answerable routing is only in the frontmatter description, not the skill body

The routing redirect — "skip when the user can answer themselves (run /planning:interview)" — appears in the frontmatter description field but not in the body's Stance or The Loop sections. Eval 3 (routes-self-answerable-to-interview) tests for this behaviour, which is good. However, a model executing this skill reads the body sections as the authoritative instruction; frontmatter descriptions are primarily for routing and discovery. A brief routing note at the top of "Stance" (alongside the "Interview the send, not the subject" principle) would make this guardrail harder to miss and easier to verify against the eval.

Fix this →

---

Not reported

Security checks from REVIEW.md (authorization, injection, secrets, audit logging) are not applicable — this PR adds only Markdown skill files, a JSON evals file, and a JSON manifest update with no code execution, secrets, or data access.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 23fca8e8f2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fde703c921

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 1m 25s —— View job

---

PR Re-Review — feat(planning): add questionnaire skill (0.19.0)

• Gather context — read changed files at HEAD fde703c
• Verify fix 1: topic-docs.md registration
• Verify fix 2: filename convention alignment
• Verify fix 3: self-answerable routing in Stance body
• Assess Codex P2: path-collision guard
• Post findings

---

Previous findings — all resolved ✅

Fix 1 — topic-docs.md registration (line 25)

The new artifact is correctly registered in the per-tier table, and the note that the memory tier's self-ignore is load-bearing because the document names a real person is exactly right. Clean fix.

Fix 2 — filename convention (SKILL.md line 31)

questionnaire-<recipient-role-slug>.md (e.g., questionnaire-dba.md, questionnaire-legal.md) is the right shape — the topic directory already carries slug context, and the role slug is semantically meaningful as a differentiator when one topic fans out to several recipients. Consistent with the established memory-tier pattern.

Fix 3 — routing guard in Stance (SKILL.md lines 23–24)

"Route away when no one else holds the answer" is well-placed as a named Stance principle alongside the core "interview the send" rule. The phrasing is tight and unambiguous. Aligns correctly with eval 3.

---

Codex P2 — path collision on same-role repeat invocation

Finding is valid; severity is nit-level for an initial skill.

The design intent is explicit: the role slug is the primary key that distinguishes questionnaires when one topic has multiple recipients. The collision scenario requires the same role queried twice for the same topic — e.g., two separate questionnaire-dba.md files for different DBA question sets. That is an edge case, not the happy path.

The current skill is silent on what happens if the file already exists. A silent overwrite is the worst outcome because the user loses prior work without knowing. The fix is small: a one-line note in step 3 of The Loop instructing the model to check for an existing file and ask the user whether to overwrite, append, or use a disambiguating name (e.g., questionnaire-dba-2.md).

This is not a blocker for merging — the collision requires deliberate, unusual usage and the questionnaire is already a memory-tier artifact the user controls. Worth a follow-up issue or a one-line addition to The Loop before the skill reaches broad use.

Fix this →

---

Verdict

The PR is in good shape. The three findings from the initial review are cleanly resolved, and the only open item is the edge-case silent-overwrite behaviour flagged by Codex — a nit, not a blocker. Merging as-is is reasonable with the expectation of a follow-up issue or small patch before broad rollout.

[claude]

Claude finished @kyle-sexton's task in 1m 22s —— View job

---

PR Re-Review — feat(planning): add questionnaire skill (0.19.0)

• Gather context — PR history and previous review rounds
• Read HEAD files at e2910c4 — verify path-collision guard fix
• Confirm all prior findings resolved
• Post final verdict

---

All findings resolved ✅

Fix 1 — topic-docs.md registration (line 25)

questionnaire-<recipient-role-slug>.md is registered in the per-tier table with the correct tier (Memory), path (.work/<topic-slug>/), and a note that the memory tier's self-ignore is load-bearing because the document names a real person. Clean.

Fix 2 — Filename convention (SKILL.md line 31)

questionnaire-<recipient-role-slug>.md (e.g., questionnaire-dba.md, questionnaire-legal.md) is the right shape. Consistent with memory-tier naming; the topic directory carries the slug, the role carries semantic meaning as a differentiator.

Fix 3 — Routing guard in Stance body (SKILL.md lines 23–24)

"Route away when no one else holds the answer." is a named Stance principle alongside the core "interview the send" rule. Matches eval 3 (routes-self-answerable-to-interview).

Fix 4 — Path-collision guard (SKILL.md line 31)

Step 3 of The Loop now reads: "If a file already exists at that path … never overwrite silently — ask whether to revise it (fold the new questions in) or write a new document with a short disambiguating suffix (questionnaire-<recipient-role-slug>-2.md, or a sharper role slug)." The two-choice design (revise vs. new) is the right call — both are valid intents the user might have, and neither silently clobbers prior work.

---

Verdict

The PR is clean and all four rounds of findings — three from the initial review, one Codex P2 path-collision guard — are fully resolved. No new findings at HEAD. Ready to merge.