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)

1. 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).

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

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

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

1. 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

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

Example Question Patterns

Instead of: "What should the button do?" Ask: "When the user clicks submit and the network request fails mid-way, should we: (a) show an error and let them retry, (b) automatically retry N times silently, or (c) save as draft and notify them later?"

Instead of: "How should errors work?" Ask: "If the external API returns a 429 rate limit error during bulk import of 100 items where 47 have already succeeded, should we: (a) fail the entire operation and rollback, (b) pause and retry after the rate limit window, or (c) mark partial success and let user resume?"

Instead of: "What's the UI?" Ask: "When showing the list of 500+ items, should we: (a) paginate with explicit page numbers, (b) infinite scroll with virtualization, or (c) load-more button? Consider that users mentioned they often need to jump to specific items."

Output Expectations

• The final spec should be detailed enough that another engineer could implement it without asking clarifying questions
• Include concrete examples where helpful
• List explicit decisions made during the interview
• Note any accepted limitations or future improvements deferred

Examples

Example 1: New feature spec

User says: "I want to plan a recurring transactions feature" Actions:

1. Read existing transaction-related code for context
2. Interview user across all dimensions (3-4 rounds)
3. Write spec to docs/prds/recurring-transactions.md

Result: Detailed spec covering technical design, edge cases, UI/UX, and implementation notes

Example 2: Refactoring spec

User says: "Let's plan the migration from REST to tRPC" Actions:

1. Explore current API structure and patterns
2. Interview about scope, rollout strategy, backwards compatibility
3. Write spec with phased migration plan

Result: Actionable spec with clear phases, dependencies, and risk assessment

Troubleshooting

User gives vague answers

Cause: Questions are too open-ended or user hasn't thought through details yet Solution: Offer concrete options with tradeoffs instead of open-ended questions. Use the "Instead of X, ask Y" patterns.

Interview goes too long

Cause: Too many dimensions explored at once Solution: Prioritize dimensions most relevant to the feature. Skip Security/Privacy for internal-only features, skip UI/UX for pure backend work.