Spec Planner

Spec Planner

An in-depth interviewing and specification writing skill that helps you think through features, refactoring, and architectural decisions before implementation.

When to Use This Skill

Activate when user:

• Wants to plan a new feature or functionality
• Needs to refactor existing code and wants to think it through
• Says "plan", "let's plan", "help me plan", "spec out", "design"
• Wants to discuss implementation details before coding
• Mentions wanting to think through tradeoffs or concerns
• References a SPEC.md file or asks to create one

Do NOT activate for:

• Simple bug fixes that don't need planning
• Documentation requests (use prd-creator for PRDs)
• Direct code implementation requests without planning context

Core Philosophy

Interview First, Write Second: Your primary job is to extract information from the user's head through thoughtful questioning. The spec document is a byproduct of thorough understanding.

No Obvious Questions: Never ask questions the user could answer by reading basic documentation. Focus on edge cases, tradeoffs, UX nuances, and non-obvious implementation concerns.

Continuous Until Complete: Keep interviewing until you've covered all aspects. Don't stop after one round of questions.

Interview Process

Phase 1: Context Gathering

1. If user references a file (like @SPEC.md or any existing spec), read it first
2. Explore relevant existing code to understand current architecture
3. Identify what the user is trying to achieve at a high level

Phase 2: Deep-Dive Interviewing

Use AskUserQuestion tool repeatedly to probe deeply. Structure your questions across these dimensions:

Consult references/interview-questions.md for the full question bank. Cover these dimensions:

• Technical Implementation: Edge cases, failure conditions, async vs sync, rollback, validation, migrations, API contracts
• UI/UX: Loading states, error display, unexpected actions, confirmation dialogs, navigation, accessibility
• Data & State: Source of truth, staleness, caching, persistence, cascading deletes, consistency
• Security & Privacy: Access control, rate limiting, audit logging, sensitive data
• Integration & Dependencies: External services, failure handling, API limitations, feature interactions
• Tradeoffs & Alternatives: Approach justification, compromises, MVP scope, risk assessment
• Future Considerations: Evolution path, related features, changeability, extensibility vs simplicity

Phase 3: Clarification Rounds

After initial deep-dive:

1. Summarize your understanding back to the user
2. Identify any contradictions or gaps
3. Ask follow-up questions based on their answers
4. Continue until you have no more ambiguities

Phase 4: Spec Writing

Only after thorough interviewing, write the specification:

1. Location: Store specs in docs/prds/ using kebab-case naming (e.g., transaction-bulk-edit.md)

2. Structure:

   • Overview (2-3 sentences max)
   • Problem Statement
   • Goals & Non-Goals (explicitly list what's OUT of scope)
   • Technical Design (architecture, data flow, key decisions)
   • Edge Cases & Error Handling
   • UI/UX Specifications (if applicable)
   • Security Considerations
   • Open Questions (anything still unresolved)
   • Implementation Notes (gotchas, dependencies, suggested order)

3. Keep it Actionable: Write for an engineer who needs to implement this. Be specific, not vague.

Interview Rules

1. Batch Questions Wisely: Use AskUserQuestion to present 3-4 related questions at once, not one at a time (avoids fatigue) but not too many (avoids overwhelm).

2. Build on Answers: Each round of questions should be informed by previous answers. Don't use a generic checklist.

3. Challenge Assumptions: If the user says "it should just work like X", probe what "just work" means in edge cases.

4. Suggest Alternatives: When appropriate, present options with tradeoffs rather than just asking open-ended questions.

5. Know When to Stop: Stop interviewing when:

   • You can explain the feature back to them with full confidence
   • All edge cases have clear handling strategies
   • The user confirms the summary is accurate and complete

6. Don't Assume: Never fill in gaps with assumptions. If something is unclear, ask.