--- name: spec-first-planning description: Interrogates an idea or feature request with pointed questions until every ambiguity is resolved, then writes a concise spec and an ordered implementation plan with verifiable steps. Use before starting any non-trivial build, when a request is vague, or when the user says "plan this", "spec this out" or "let's think before we code". license: MIT compatibility: Any project. No tools required beyond reading the codebase; writes markdown to a docs or specs folder. metadata: category: productivity version: "1.0.0" --- # Spec-First Planning Most wasted agent work comes from building the wrong thing confidently. This skill front-loads the disagreement: ask until the design is unambiguous, write it down, then plan in steps small enough to verify. ## Phase 1 — Interrogate Ask questions **one or two at a time**, not as a wall. Prefer questions the user can answer with a choice. Keep going until you can answer every item in the spec template without guessing. Question families, in order: 1. **Outcome.** Who is this for, what will they be able to do afterwards that they cannot now, and how would we know it worked (a metric, a demo, a passing test)? 2. **Scope edges.** What is explicitly *out*? What is the smallest version that would still be worth shipping? 3. **Existing constraints.** Which parts of the current codebase does this touch? (Read them first; ask only about what the code cannot tell you.) Which patterns must be followed, which libraries are off limits? 4. **Data and state.** What new data exists, where does it live, who owns it, what happens on delete, migration needs? 5. **Failure modes.** What happens when input is invalid, the network fails, the user is unauthorised, or two people act at once? 6. **Non-functional.** Performance budget, accessibility, i18n, audit/logging, privacy of the data involved. 7. **Rollout.** Feature flag? Backwards compatibility? Who reviews, how is it released, how is it rolled back? 8. **Unknowns.** For each thing neither of you knows, decide: spike it now, assume and note it, or defer. Challenge weak answers politely: "You said 'fast enough' — is 200 ms p95 acceptable or does it need to feel instant?" If the user says "you decide", record the decision and the reason so it can be revisited. Stop interrogating when three consecutive questions produce no change to the spec. ## Phase 2 — Write the spec Save to `docs/specs/-.md` (or the project's convention). Keep it under two pages. ``` # ## Problem — one paragraph, user's words where possible ## Goal and success criteria — measurable ## Non-goals ## Design - User-facing behaviour (bullets or a short scenario) - Data model changes - API / interface changes (signatures, routes, events) - Key decisions and the alternatives rejected, with reasons ## Edge cases and error handling — table: case → behaviour ## Risks and open questions — owner and due date for each ## Rollout — flags, migration order, rollback ``` Read it back to the user and get an explicit "yes" before planning. ## Phase 3 — Plan in tracer bullets Break the work into steps where each one is independently verifiable and leaves the codebase working. Order so that the thinnest end-to-end slice lands first, then widen. For each step: ``` ### Step 3 — Persist invoice status Files: prisma/schema.prisma, src/invoices/repo.ts, src/invoices/repo.test.ts Do: add `status` column with check constraint; repo method `setStatus` Verify: `pnpm test src/invoices` passes; migration applies on a fresh DB Depends on: Step 2 Estimate: S ``` Rules: - Steps are S (under an hour) or M (a few hours); split anything larger. - Every step names how it is verified. "Works" is not a verification. - Mark steps that need a human decision or a credential with `[needs human]`. - Put spikes for open questions before the steps that depend on them. - End with a final step that runs the full checklist from the spec's success criteria. ## Output format Deliver the spec file, the plan file (`docs/plans/.md` or appended to the spec), and a short message summarising: the three most consequential decisions made, the open questions, and the first step you propose to start. ## Checklist - [ ] Every success criterion is measurable. - [ ] Non-goals are listed. - [ ] Every open question has an owner. - [ ] Every plan step has files, a verification command and a dependency. - [ ] The user approved the spec before the plan was written. ## Pitfalls - Asking ten questions at once produces shallow answers; drip them. - Do not ask what the code can tell you. Read first. - A plan without verification steps becomes a to-do list that is impossible to hand off. - Do not let the spec grow into a design document for the entire system; scope it to this change. - If the user resists questions, offer a default for each and ask them to veto rather than answer. - Revisit the spec when implementation reveals a false assumption; do not silently diverge.