--- name: plan-feature description: Clarify a vague scope through interview, then compile it into a PRD. Triggers "help me figure out", "define requirements", "PRD", "product spec", "feature spec". context: fork agent: planner --- # Plan Feature Two-phase pre-implementation planning: clarify requirements via interview, then compile a complete PRD. ## Phase 1: Discovery Help clarify requirements and scope through structured questioning. ### Interview Framework The interview is a fog-of-war walk across four quadrants of the unknown. Open by listing the **known knowns** (what the user has already decided), then work the questions below to surface **known unknowns** (open questions they're aware of), **unknown knowns** (constraints they hold but haven't said — the questions in 2–4 exist to shake these loose), and close by hunting **unknown unknowns** ("what would surprise us mid-build? what reference implementation should we read first?"). A discovery that ends with all four quadrants visited produces a PRD that doesn't get re-planned in week two. ### Goal Quality Bar (gate before interviewing) Before opening the interview questions below, try to state the goal in one line that answers five things: - What's true when this is done? - What evidence shows it — a command, a test, a metric, a reviewed artifact? - What threshold counts as success — pass/fail, or a number? - What's explicitly out of scope, where that would matter? - What's the stop condition — the point where you ask the user instead of guessing? If a clean one-liner falls out, skip straight to Phase 2's clarifying questions — the interview below exists for when it doesn't. Reject pure activity goals — "make progress," "keep investigating," "improve things" — until sharpened into a verifiable outcome: - Weak: "Make checkout faster." Sharpened: "Reduce checkout API p95 latency below 250ms for the documented slow path, verified with `npm run test:checkout` and 3 consecutive benchmark runs under 250ms." - Weak: "Clean up the auth code." Sharpened: "Resolve the open change-request threads on PR 123, touching only the affected auth files and tests, verified with the targeted auth test command plus `gh pr view 123` showing no unresolved threads." Pick the validator shape by domain: | Domain | Success looks like | |---|---| | Bug | Reproduce first, fix second — a failing-then-passing test or repro script | | Test | The exact command and its pass condition | | Performance | Metric + threshold + measurement method + run count | | Quality | Reviewed examples, or lint/typecheck/test passing | | Research | The decision the research needs to unblock | | Ops | Healthy state + monitoring window + rollback trigger | *Goal Quality Bar adapted from openai/skills `define-goal`, Apache-2.0.* #### 1. Understand the Goal - What problem are you solving? - Who is this for? - What does success look like? #### 2. Define Scope - What must be included (MVP)? - What's nice to have (future)? - What's explicitly out of scope? #### 3. Identify Constraints - Timeline constraints? - Technical constraints? - Resource constraints? #### 4. Clarify Details - What are the inputs/outputs? - What are the edge cases? - What are the error scenarios? #### 5. Validate Understanding - Summarize back what you heard - Confirm priorities - Identify open questions ### Output ``` ## Discovery Summary: [Feature/Project] ### Goal [Clear statement of what we're building and why] ### Requirements **Must Have (MVP)** - [ ] Requirement 1 - [ ] Requirement 2 **Nice to Have** - [ ] Feature A - [ ] Feature B **Out of Scope** - Not doing X - Not doing Y ### Technical Approach [High-level approach] ### Open Questions - [ ] Need to clarify: ... - [ ] Decision needed: ... ### Next Steps 1. [First action] 2. [Second action] ``` ### Remember - Ask, don't assume - Summarize frequently - Document decisions - Store requirements as learnings --- ## Phase 2: PRD Compilation Structured 6-phase process to produce a complete PRD from a feature idea, including user stories, task breakdown, and parallel execution plan. ### Workflow #### Phase 1: Clarifying Questions Ask 5-8 targeted questions to fill gaps. Use smart defaults so the user can skip. ```markdown ## Clarifying Questions 1. **Target users?** [default: existing app users] 2. **Platform scope?** [default: web only] 3. **Auth required?** [default: yes, existing auth] 4. **Performance targets?** [default: <2.5s LCP, <200ms INP] 5. **Accessibility level?** [default: WCAG 2.1 AA] 6. **Data persistence?** [default: existing database] 7. **Mobile responsive?** [default: yes] 8. **Analytics needed?** [default: basic events] Press enter to accept all defaults, or answer specific questions. ``` #### Phase 2: Scope Definition Define what is IN and OUT of scope. ```markdown ## Scope ### In Scope - [feature 1] - [feature 2] ### Out of Scope - [explicitly excluded 1] - [explicitly excluded 2] ### Assumptions - [assumption 1] - [assumption 2] ``` #### Phase 3: User Stories Write user stories with acceptance criteria. ```markdown ## User Stories ### US-1: [Title] **As a** [role] **I want** [capability] **So that** [benefit] **Acceptance Criteria:** - [ ] Given [context], when [action], then [result] - [ ] Given [context], when [action], then [result] **Priority:** P1 | P2 | P3 **Complexity:** trivial | small | medium | large | epic ``` #### Phase 4: Task Breakdown Break into implementable tasks with metadata. `Dependencies`/`Blocks` feed the batch algorithm and must match the Functional DAG's joins from Phase 5 — on conflict the DAG wins, so reconcile the metadata to it rather than redrawing to match a stale field. ```markdown ## Tasks ### T-1: [Title] - **Description:** [what to implement] - **User Story:** US-1 - **Priority:** 1 (1=highest, 5=lowest) - **Complexity:** medium - **Estimated Tokens:** 15000 - **Dependencies:** none - **Blocks:** T-2, T-3 - **Verification:** [how to verify completion] ### T-2: [Title] - **Dependencies:** T-1 - ... ``` #### Phase 5: Parallel Batch Detection Draw the Functional DAG first (`docs/functional-dag.md`) — inputs left, operations merging rightward, one terminal verification node — then read the batches off its columns. Same column with disjoint inputs = same batch. The DAG is the source; the batch list below is its rendering, not a second dependency graph to keep in sync. ```markdown ## Functional DAG [recipe-table brace diagram in a fenced code block — see docs/functional-dag.md] ## Execution Plan ### Batch 1 (parallel) — estimated: 25k tokens - T-1: Setup data models - T-4: Create UI scaffolding - T-7: Write test fixtures ### Batch 2 (parallel, depends on Batch 1) — estimated: 40k tokens - T-2: Implement API endpoints (depends: T-1) - T-5: Build form components (depends: T-4) ### Batch 3 (sequential) — estimated: 20k tokens - T-3: Integration wiring (depends: T-2, T-5) ### Batch 4 (parallel) — estimated: 15k tokens - T-6: E2E tests (depends: T-3) - T-8: Documentation (depends: T-3) ### Batch 5 (terminal gate) — estimated: 5k tokens - T-9: typecheck + full test run (depends: T-6, T-8) — the DAG's single terminal node Total estimated tokens: 105k Estimated context windows: 2 ``` Every plan ends on the terminal gate, so the last batch is always one verification task depending on all preceding work — never a fan-out of unverified parallel tasks. #### Phase 6: Final PRD Compile everything into the final document. ```markdown # PRD: [Feature Name] ## Functional DAG [from Phase 5 — inputs left, operations merging rightward, one terminal node] ## Overview [1-2 paragraph summary] ## Goals - [measurable goal 1] - [measurable goal 2] ## Scope [from Phase 2] ## User Stories [from Phase 3] ## Technical Design ### Architecture [high-level approach] ### Data Model [key entities and relationships] ### API Surface [endpoints or interfaces] ## Task Breakdown [from Phase 4] ## Execution Plan [from Phase 5] ## Success Metrics - [metric 1: target value] - [metric 2: target value] ## Risks | Risk | Likelihood | Impact | Mitigation | |------|-----------|--------|------------| | [risk] | Low/Med/High | Low/Med/High | [approach] | ## Timeline - Phase 1: [dates] — [deliverable] - Phase 2: [dates] — [deliverable] ``` ### Smart Defaults When the user provides minimal input, apply these defaults: - **Platform:** Web — detect from `package.json` (`next` → Next.js / satus, `react-router` → RR / novus) - **Auth:** Existing auth system - **Performance:** LCP <2.5s, INP <200ms, CLS <0.1 - **Accessibility:** WCAG 2.1 AA - **Testing:** E2E tests that each end in a verifiable, repeatable artifact; isolated tests only against a failure list written before the code - **Styling:** Project's existing system (Tailwind if detected) ### Task Sizing Reference See `docs/enhanced-todos.md` for the complexity/token sizing reference table. --- ## Phase 3: Close (plan → durable record) A PRD is a **build plan** while building and a **rationale record** once shipped — closing flips it from one to the other. When the feature lands (merged, gates green), rewrite the PRD instead of letting it rot as a stale plan: - Keep the **why**: the problem, the principles, the invariants that must never break, the approaches tried and rejected. - Cut every paragraph that restates what the code does — point at the code instead; it is the source of truth for *how*. - Record every **divergence from the plan** (dropped tasks, renamed seams, assumptions that broke). Divergences are the most valuable content: they're exactly what a future reader would otherwise re-derive the hard way. - Archive it where the project keeps finished plans (e.g. `docs/prd/done/`), and promote anything decision-shaped into an ADR via `/context-doc`. If the plan lives as GitHub issues (`/project`), the close pass is the closing comment on the epic: what shipped, what diverged, and why.