plan-interview

# Plan Interview Skill ## Purpose Run a structured requirements interview before planning implementation. This ensures alignment between you and the user by gathering explicit requirements rather than making assumptions. ## When Invoked User calls `/plan-interview <task description>`. **Skip this skill** if the task is purely research/exploration (not implementation). ## Interview Process ### Phase 1: Upfront Interview (Before Exploration) Interview the user using `AskUserQuestion` in **thematic batches of 2-3 questions**. #### Required Question Domains Cover ALL four domains before proceeding: 1. **Technical Constraints** - Performance requirements - Compatibility needs - Existing patterns to follow - Architecture understanding (if codebase is unfamiliar) 2. **Scope Boundaries** - What's explicitly OUT of scope - MVP vs full vision - Dependencies on other work 3. **Risk Tolerance** - Acceptable tradeoffs (speed vs quality) - Tech debt tolerance - Breaking change acceptance 4. **Success Criteria** - How will we know it's done? - What defines "working correctly"? - Testing/validation requirements #### Question Generation - Generate questions **dynamically** based on the task - no fixed template - Group related questions into thematic batches - **2-3 questions per batch** (do not exceed) - Continue until you have **actionable specificity** (can describe concrete implementation steps) #### Handling Edge Cases | Scenario | Action | |----------|--------| | Contradictory requirements | Make a recommendation with rationale, ask for confirmation | | User pivots requirements | Restart interview fresh with new direction | | Interrupted session | Ask user: continue where we left off or restart? | #### Anti-Patterns to Avoid - Do NOT ask variations of the same question - Do NOT make major assumptions without asking - Do NOT over-engineer plans for simple tasks ### Phase 2: Codebase Exploration After interview completes, explore the codebase to understand: - Existing patterns relevant to the task - Files that will be affected - Integration points - Potential risks ### Phase 3: Plan Generation Write plan to `docs/plans/plan-NNN-<slug>.md` where NNN is the source issue number, zero-padded to three digits (e.g., issue #7 → `007`, issue #123 → `123`, issue #1042 → `1042`). #### Required Elements Every plan MUST include: ```markdown ## Success Criteria [Clear definition of done from interview] ## Risk Assessment [What could go wrong + mitigations] ## Affected Files/Areas [Which parts of codebase will be touched] ## Open Questions [Uncertainties to resolve during implementation] - [ ] Question 1 - [Blocks implementation / Can proceed] - [ ] Question 2 - [Blocks implementation / Can proceed] ## Implementation Checklist - [ ] Step 1 - [ ] Step 2 ... ``` #### Optional Elements Include when relevant: - **Rejected Alternatives**: Only for major architectural decisions - **Decision Tree**: Only when multiple valid approaches exist - **Visual Diagrams**: ASCII or Mermaid when helpful for understanding #### Constraints - **No time estimates** - describe what needs doing, not how long - **No length limits** - plan should match task complexity - Freeform structure beyond required elements ### Phase 4: Post-Approval When user approves the plan: 1. **Auto-start implementation** immediately (no "proceed" confirmation needed) 2. Populate `TodoWrite` with checklist items 3. At **natural breakpoints** (significant decisions), compare progress to plan ## Fast Mode If user wants quick planning, use **draft + refine**: 1. Perform task-focused codebase search 2. Generate draft plan 3. Run abbreviated interview to refine ## Resume Support If a partial plan exists in `docs/plans/`: ``` AskUserQuestion: "I found an existing partial plan. Would you like to:" - "Continue from where we left off" - "Start fresh with a new plan" ``` ## Example ``` User: /plan-interview Add OAuth authentication to the API Claude: I'll help you plan the OAuth authentication feature. Let me gather requirements first. [AskUserQuestion - Scope batch] 1. Which OAuth providers need to be supported (Google, GitHub, etc.)? 2. Is this replacing existing auth or adding alongside it? User: Google and GitHub. Adding alongside existing JWT auth. [AskUserQuestion - Technical batch] 1. Should OAuth tokens be stored in the existing session table or separately? 2. Any specific callback URL constraints from your hosting setup? User: Separate table. We're on Vercel so callback URLs need to be configured per environment. [AskUserQuestion - Risk/Success batch] 1. What's the acceptable degradation if an OAuth provider is down? 2. How should we handle users who already exist with the same email? User: Fall back to standard login. Link accounts by email if user confirms. Claude: [Explores codebase for auth patterns, session handling, database schema] Claude: [Writes docs/plans/plan-042-oauth-authentication.md] ← issue #42 Plan created. The main decision point is whether to use Passport.js or implement OAuth flows directly - I've documented both approaches with tradeoffs. Ready to review? User: Looks good, go with Passport.js Claude: [Auto-starts implementation with TodoWrite tracking] ```