plan-interview

Plan Interview

Stress-test a plan through a structured conversational interview before implementation begins.

Table of Contents

• Step 0 — Create progress todos
• Step 1 — Resolve the plan file
• Step 2 — Read, validate plan name, and analyze the plan
• Step 2.5 — Skill tool analysis
• Step 2.6 — Skill quality checklist
• Step 3 — Conduct the structured interview
• Step 4 — Surface out-of-scope concerns
• Step 5 — Compile and present the review summary
• Step 6 — Offer to save findings

Instructions

Step 0 — Create progress todos

Before doing any other work, use TodoWrite to create todos for each step of this interview. This gives the user visibility into progress and ensures no step is skipped.

Create the following todos (all starting with status: "pending"):

• Step 2: Read, validate plan name, and analyze the plan
• Step 2.5: Skill tool analysis (skill-review mode only)
• Step 2.6: Skill quality checklist (skill-review mode only)
• Step 3a: Round 1 — Technical & Trade-offs
• Step 3b: Round 2a — UI/UX & Flows (if applicable)
• Step 3c: Round 2b — Accessibility & Semantic (if applicable)
• Step 3d: Round 3 — Edge Cases & Best Practices (if applicable)
• Step 4: Surface out-of-scope concerns & complexity check
• Step 5: Compile and present review summary
• Step 6: Offer to save findings

Mark each todo status: "completed" as you finish that step.

Step 1 — Resolve the plan file

Use the first match from this priority order:

1. User message: If a file path appears in the user's message, treat it as the plan file path and read it directly.
2. Currently open file: If no path was given, check whether a .md file is currently open or selected in the IDE (provided via context). If it exists and its content looks like a plan (contains headings like ## Implementation, ## Plan, ## Steps, ## Instructions, or similar structural markers), use it.
3. Project-level config override: Read .claude/settings.json in the current project directory. If a "plansDirectory" key exists, glob *.md files from that path and use the most recently modified file. This takes precedence over the global config.
4. Global config: Read ~/.claude/settings.json. If a "plansDirectory" key exists, glob *.md files from that path and use the most recently modified file.
5. Default fallback: Use Glob on ~/.claude/plans/*.md, sort by modification time, and select the most recently modified file.

Once resolved, detect the review mode before proceeding:

Skill detection — the resolved file is a skill if:

• Its filename is SKILL.md, or
• Its YAML frontmatter contains both a name: and description: field but the body has no plan-style headings (## Implementation, ## Plan, ## Steps, ## Context)

Set mode = skill-review if detected, otherwise mode = plan-review.

Announce the file and mode:

• Plan: "Interviewing plan: ~/.claude/plans/my-feature.md"
• Skill: "Reviewing skill: path/to/SKILL.md"

If no file can be found via any of these methods, tell the user and stop.

Step 2 — Read, validate plan name, and analyze the plan

In skill-review mode: skip the plan name validation section entirely and proceed directly to Step 2.5 after reading the file.

Read the resolved file.

Plan name validation: Before extracting plan details, check whether the plan's filename and H1 heading accurately describe the plan's content.

1. Extract identifiers: Get the filename (without path or .md extension) and the H1 heading (first line matching # ...).

2. Determine the plan's purpose: Read enough of the plan to form a one-sentence summary of what it intends to accomplish.

3. Evaluate the filename against these criteria:

   • Descriptive: Contains words that relate to the plan's goal or content. Good: create-skill-reviewer-plugin, fix-marketplace-json-location. Bad: fuzzy-swimming-pearl, hidden-popping-moonbeam.
   • Not random: Does not follow a random adjective-noun or adjective-verb-noun pattern with no connection to the plan's subject matter. Note: add-dark-mode-toggle is descriptive even though it contains adjectives — the key test is whether the words relate to the plan content.
   • Not too generic: Not a placeholder like plan.md, untitled.md, draft.md, temp.md, or new-plan.md.

4. Evaluate the H1 heading:

   • Does an H1 heading exist?
   • Does it describe the plan's purpose? (Good: # Plan: Create 'skill-reviewer' Plugin. Bad: # Plan alone, or missing entirely.)
   • Does it align with the filename? Flag misalignment only when the filename and heading refer to entirely different topics — not when they describe the same topic at different scopes (e.g., fix-auth-bug and # Plan: Refactor Authentication Module are aligned because both concern authentication).

5. Record the result as one of:

   • Pass: Both filename and heading are descriptive and aligned — proceed silently.
   • Needs attention: One or both are non-descriptive, generic, or misaligned. Record:
     • Which element(s) failed (filename, heading, or both)
     • Why (random pattern, too generic, misaligned, or missing)
     • A suggested filename in kebab-case derived from the plan's goal
     • A suggested H1 heading in # Plan: [Description] format

If the name needs attention, present the finding immediately before continuing:

### Plan Name Review

| Element    | Current                   | Issue                         | Suggested                                |
| ---------- | ------------------------- | ----------------------------- | ---------------------------------------- |
| Filename   | `fuzzy-swimming-pearl.md` | Random — unrelated to content | `create-skill-reviewer-plugin.md`        |
| H1 Heading | _(missing)_               | No H1 heading found           | `# Plan: Create 'skill-reviewer' Plugin` |

Then ask the user via AskUserQuestion: "Would you like me to rename this plan file to [suggested-name].md?" (and if the H1 heading was also flagged, include it in the offer: "…and update the heading to # Plan: [Description]?").

If the user confirms:

• Rename the file using Bash mv.
• Update the H1 heading in the file using Edit (if it was flagged).
• Update the resolved file path for the remainder of the interview so that Steps 4–6 (especially Step 6's save operation) reference the new path.

If the user declines, proceed without changes.

If the name passes validation, skip this section silently.

Extract the following to guide question generation:

• Goal: What is being built and why?
• Key components: What files, services, or systems are involved?
• Tech stack: Languages, frameworks, libraries, APIs
• Scope: Is this a focused change, a medium-sized feature, or a complex multi-area effort?
• UI involvement: Does the plan reference components, pages, forms, styles, or HTML? (Used to determine whether Round 2 runs regardless of scope.)
• Open questions: Any unresolved questions listed in the plan?

Also extract complexity signals from the plan:

• Multiple new abstractions or layers (factories, registries, adapters, base classes) introduced for a focused task
• Third-party libraries proposed for tasks covered by native APIs or the standard library
• Custom implementations of patterns the framework or language already provides
• Premature optimization signals (caching, queuing, batching) without stated scale requirements
• More than 3 new files proposed for a single-concern change
• Complex state management (Redux, Zustand, XState) proposed for local or ephemeral state

Use the scope assessment to determine how many interview rounds to conduct:

• Short/focused plan (single concern, 1–2 files): 1 round
• Medium plan (feature with UI + logic): 2 rounds
• Complex/multi-area plan (architecture, cross-cutting concerns, 3+ domains): 3 rounds

After scope assessment, also check for UI involvement: look for any of the following signals in the plan:

• Framework keywords: React, Vue, Svelte, Angular, or similar component-based UI libraries
• HTML/CSS terms: className, style, CSS, Tailwind, styled-components, or similar
• File types: .tsx, .jsx, .css, .scss, .html
• UX terminology: button, modal, form, dialog, dropdown, input, layout, page, screen, component

If any UI signals are detected, always include Round 2 — even for plans classified as short/focused. When triggering Round 2 on a short plan, briefly note what was detected (e.g., "Running Round 2 — plan references React components and .tsx files") so the user understands why.

Step 2.5 — Skill tool analysis (skill-review mode only)

Skip this step entirely when mode = plan-review.

Analyze the skill file to detect tool usage and recommend allowed-tools for the skill's frontmatter.

1. Parse existing allowed-tools: Extract the current allowed-tools value from the YAML frontmatter. If absent, treat as empty.

2. Scan for tool references: Search the skill body for any of the following known Claude tool names (match as whole words or within backticks):

   Read, Write, Edit, MultiEdit, Glob, Grep, Bash, AskUserQuestion,
   TodoWrite, Agent, WebFetch, WebSearch, NotebookRead, NotebookEdit
   

   Also detect filtered patterns such as Bash(git *) or Bash(gh *).

3. Classify each tool as one of:

   • Declared — already present in allowed-tools
   • Missing — detected in the skill body but absent from allowed-tools
   • Undeclared — listed in allowed-tools but not detected in the body (flag for review, do not auto-remove)

4. Present the analysis table:

   ### Skill Tool Analysis
   
   | Status     | Tool  | Detected In                         |
   | ---------- | ----- | ----------------------------------- |
   | Declared   | Read  | Step 1 — reading skill file         |
   | Missing    | Grep  | Step 3 — interview codebase references |
   | Undeclared | Write | In allowed-tools but not detected   |
   

5. Output a suggested allowed-tools line, listing all detected tools in alphabetical order:

   **Suggested frontmatter** (commands only — `allowed-tools` is not supported
   in SKILL.md files):
   
   ```yaml
   allowed-tools: AskUserQuestion, Bash, Edit, Glob, Grep, Read, TodoWrite
   ```
   

   
   > Note: `allowed-tools` is only valid in command files (`.md` files in
   > `commands/`). If the reviewed skill has a paired command file, the
   > recommendation applies there.
   

Step 2.6 — Skill quality checklist (skill-review mode only)

Skip this step entirely when mode = plan-review.

Read reference/skill-checklist.md and evaluate the reviewed skill against every item in the checklist. For each category, mark items as passing or failing based on what you can observe in the skill file and its directory.

Present the results as a scored table:

### Skill Quality Checklist

| Category        | Passing | Failing | N/A |
| --------------- | ------- | ------- | --- |
| Core quality    | 8       | 2       | 0   |
| Code & scripts  | —       | —       | 8   |
| Testing         | 0       | 3       | 1   |

Then list only the failing items with a brief note on each:

**Failing items:**

- [ ] Description does not include when to use the Skill
- [ ] No concrete examples provided
- [ ] Not tested with multiple models

Mark items as N/A (not applicable) when the skill has no scripts or code (entire "Code and scripts" category may be N/A for instruction-only skills).

Step 3 — Conduct the structured interview

Generate questions dynamically from the plan content — do not use generic or hardcoded questions. Each AskUserQuestion call may include up to 4 questions.

Round 1 — Technical & Trade-offs (always run):

Ask up to 4 questions covering:

• The most uncertain architectural or implementation decision in the plan
• Build vs. buy, library choice, or API design trade-offs
• Performance, scalability, or data model concerns specific to this plan
• Any unclear integration points or dependencies

Use multiSelect: true for questions where the user may want to flag multiple concerns (e.g., "Which of these areas need more investigation?").

Round 2a — UI/UX & Flows (run for medium and complex plans, or any plan with UI involvement — see Step 2):

Ask up to 4 questions covering:

• User flows: happy path, error states, loading states, empty states
• Mobile or responsive behavior concerns
• Motion and animation: prefers-reduced-motion, transitions, focus indicators after animation
• Any UI state not covered by the plan (e.g., skeleton loading, optimistic updates, error recovery)

Round 2b — Accessibility & Semantic Structure (run immediately after Round 2a when Round 2 is triggered):

Ask up to 4 questions covering:

• Keyboard navigation, focus order, focus trapping (modals/dialogs), skip-nav links
• Screen reader support: ARIA roles, labels, aria-describedby for errors, live regions
• WCAG 2.1 AA compliance: color contrast (4.5:1 text, 3:1 UI), touch targets (44×44px min)
• Semantic HTML: heading hierarchy, landmark regions, form label association

Round 3 — Edge Cases & Best Practices (run for complex plans only):

Ask up to 4 questions covering:

• Critical failure modes or race conditions
• Concurrent user scenarios or data conflicts
• Regression risks: which existing tests might break, what backward-compatibility contracts exist (API shape, component props, data schema), and whether visual or behavioral regression testing is in place
• Which best practices should guide implementation: security, performance, test coverage, DX
• Any remaining open questions from the plan that haven't been addressed

Deep Grill: To walk every decision branch in depth after this interview, run the standalone deep-grill skill. Say "deep grill this plan" or invoke it directly with /plan-interview:deep-grill [plan-file-path].

Step 4 — Surface out-of-scope concerns

After the structured rounds, review the full plan one more time and identify any issues that were not covered by the interview questions. These are concerns you observed independently — not topics already raised by the user. Look for:

• Missing sections a plan of this type would normally include (e.g., rollback strategy, auth/permissions, data migration, monitoring)
• Implicit assumptions in the plan that could silently break implementation
• Ownership or responsibility gaps (who handles what is unclear)
• Naming, scope, or intent ambiguities that could cause misalignment during implementation
• Risks that fall outside the Technical / UI / Edge Case domains
• Regression blind spots: the plan does not identify which existing tests, API contracts, or user-visible behaviors could break

If any out-of-scope concerns exist, present them as a clearly labelled section in the chat before the summary:

### Additional Concerns (Outside Structured Rounds)

- [Concern 1]: [Brief explanation of why this matters]
- [Concern 2]: [Brief explanation of why this matters]

If no additional concerns exist, skip this section silently.

Complexity Check (always run):

After the out-of-scope scan, evaluate the proposed approach against what the simplest working solution would look like. For each element that appears over-engineered, ask: Could a built-in, a single function, or a native API replace this abstraction? Only surface real issues — do not flag complexity for its own sake on genuinely complex plans. Only name a simpler alternative when one is clearly apparent; omit concerns where no obvious alternative exists.

If any complexity concerns are found, present them under a clearly labelled section:

### Complexity Concerns

- [Over-engineered element]: [Why it's unnecessary] — Simpler alternative:
  [specific suggestion]

Skip this section silently if no complexity concerns are found.

Step 5 — Compile and present the review summary

After all rounds and the out-of-scope check are complete, output a structured summary in the chat:

## Plan Interview Summary

### Key Decisions Confirmed

[List decisions the user confirmed or clarified during the interview]

### Plan Naming

[Include only if name validation found issues in Step 2. Reproduce the table
showing current name(s), the issue, and suggested replacement(s). Note whether
the user accepted or declined the rename offer. Omit this section entirely if
the name passed validation.]

### Open Risks & Concerns

[List risks, unknowns, or concerns surfaced — with brief context]

### Recommended Next Steps

[Amendments to the plan, additional spikes, or clarifications needed before
implementation]

### Simplification Opportunities

[Concise list of areas where the plan can be reduced in scope or abstraction,
with specific simpler alternatives — omit this section if no complexity concerns
were found]

### Skill Quality Checklist Results

[Include only in `skill-review` mode. Reproduce the scored table and failing
items from Step 2.6. Omit this section entirely when reviewing a plan file.]

### Allowed Tools Recommendation

[Include only in `skill-review` mode. Reproduce the tool analysis table from
Step 2.5, plus the suggested `allowed-tools` line for any paired command file.
Omit this section entirely when reviewing a plan file.]

Step 6 — Offer to save findings

After presenting the Step 5 summary, ask the user:

"Would you like me to update the plan with suggested changes and append this interview summary to the plan file?"

Do not write to the plan file unless the user explicitly confirms. If they confirm, update the plan with suggested changes and append the summary as a new ## Interview Summary section at the end of the plan file using the Edit tool. If they decline, do not modify the file.

In skill-review mode: if Step 2.5 identified missing tools, also ask:

"Would you like me to apply the allowed-tools recommendation to the paired command file?"

If confirmed, use Edit to add or update the allowed-tools line in the YAML frontmatter of the corresponding command file (look for a .md file in commands/ with a matching name). If no paired command file exists, note that allowed-tools is only applicable to command files and skip.