plan-questions
Question-quality rubric for AskUserQuestion calls during /plan mode. Triggers when the developer says /plan-questions, "ask better questions", "that question was confusing", or as a mid-session reset.
SKILL.mdskills/plan-questions/SKILL.md
GitHubPlan-Mode Question Quality Rubric
Every AskUserQuestion call during /plan mode MUST satisfy these 10 rules.
If a question fails any rule, rewrite it before sending.
The 10 rules
Frame the WHY in one sentence. The question body opens with what decision this affects in the implementation. Not "Which library?" but "We need to format trade timestamps for the CSV export endpoint at
OrderExportController.cs:88— which library?"Reference concrete files/symbols. Use
path/to/file.cs:42orClassName.MethodAsyncin the question body or in option descriptions. No abstract phrasing like "the existing service" or "the relevant component".Each option states the concrete consequence. What gets added, modified, or deleted. "Adds
XxxStatesignal service + refactorsdashboard.component.ts." Not "Use signals."Each option states the cost. Lines touched, migrations created, new dependencies, blast radius. If two options have identical costs you are not really offering a choice — collapse them.
One AskUserQuestion = one decision. If the answer to question B depends on the answer to question A, split them and ask sequentially. Never bundle "which library AND which migration strategy?" into one call.
Use
previewfor visual/structural differences. Layout choices, code-structure variants, schema shapes — populate thepreviewfield with an ASCII mockup, a code snippet, or a schema sample. Text labels alone cannot communicate visual differences.Recommend when you have an opinion. First option = recommended. Suffix the label with " (Recommended)". The description must state why it is recommended in one phrase.
Headers are the concrete artifact name. "Index strategy", "Auth method", "Migration name" — not "Approach", "Strategy", "Option". Max 12 chars (per the AskUserQuestion schema).
Bound open-ended questions. If asking "which fields go in this DTO?", list the candidate fields. Never ask the user to invent the set from scratch — propose, then let them edit.
Skip the question if you can read the answer. Before asking, grep
CLAUDE.md, the active concept contract under.claude/concepts/, the recent git log, the existing config file. Asking what is already documented wastes the user's time.
Worked examples
Example A — Library choice
Bad:
Question: Which date library? Header: Library Options:
- date-fns
- dayjs
- luxon
Good:
Question: We need to format trade timestamps for the CSV export at
OrderExportController.cs:88. The output must round-trip through Excel (NYC time, no DST surprises). Which library?Header: Date library
Options:
- dayjs + timezone plugin (Recommended) — 7kb, already a transitive dep via
@angular/material. Cost: 1 new import line.- luxon — 22kb, native Intl API, no plugin needed. Cost: new dependency in
package.json+ 1 import line.- date-fns + date-fns-tz — 13kb, tree-shakeable. Cost: 2 new dependencies, no Intl support without the tz package.
Example B — Migration strategy
Bad:
Question: How should we add the new column? Header: Approach Options:
- Nullable
- Default value
- Backfill
Good:
Question: Adding
LastReviewedAt(datetime2) toStrategiestable (~50k rows). EF migration goes inPersistence/Migrations/. Which approach?Header: Column add
Options:
- Nullable, no default (Recommended) — zero downtime, no row lock, existing queries unaffected. Cost: every read must
??the value. Reversible.- NOT NULL with
GETUTCDATE()default — backfills 50k rows during migration, ~2s table lock at our row size. Cost: irreversible without manual SQL.- Nullable now, backfill in a follow-up job, ALTER to NOT NULL later — three deploys. Cost: highest operational complexity, safest for
10M-row tables.
Example C — Layout choice (uses preview)
Bad:
Question: Which layout? Header: Layout Options:
- Two-column
- Stacked
Good:
Question: The strategy-detail page at
features/strategies/detail/needs to show metadata + live PnL chart. Viewport target is 1440px. Which layout?Header: Detail layout
Options (with preview):
Side-by-side (Recommended) — metadata 1/3, chart 2/3. Cost: 1 new
<div class="grid grid-cols-3 gap-4">wrapper. Preview:+---------------+-------------------------+ | Name | | | Status | PnL chart | | Symbol | (live signal) | | Last fill | | +---------------+-------------------------+Stacked — metadata row above chart. Cost: same wrapper, easier mobile reflow. Hurts dense-information feel. Preview:
+-------------------------------------------+ | Name Status Symbol Last fill | +-------------------------------------------+ | | | PnL chart | | | +-------------------------------------------+
When to invoke
- Developer types
/plan-questionsor says "that question was confusing" / "ask better questions". - Mid-plan, before any
AskUserQuestioncall, mentally walk the 10 rules. - Plan mode is active and no reminder will arrive: the plan-question advisor hook that used to inject one at every prompt was retired in 0.7.0, so invoke this skill yourself.