Playbook: Idea to Spec

Objective

Turn "we should build something like X" into an ordered set of specs, each verifiable and sized to one agent session. The trick is inversion: instead of you writing a spec cold, the agent interviews you. Agents are mediocre at deciding what to build and excellent at noticing what you haven't decided yet — this playbook uses only the second capability.

When to use

Before New Project or MVP Build when requirements exist mostly in your head. Also for a single large feature whose shape is fuzzy. Skip it when a real spec already exists — go build.

Inputs required

• The idea, however rough. Three sentences is enough to start.
• 1–3 hours of your attention. The interview only works if you answer honestly, including "I don't know" — an unanswered question in the interview is a silent assumption in the code.

Step-by-step process

1. The interview

I have a rough product idea. Your job is to interrogate it into a buildable
spec. Do NOT write the spec yet, and do NOT propose solutions.

The idea: <2–5 sentences, as rough as it really is>

Interview me in rounds of 3–5 questions. Cover, over the rounds:
- Users and the single job-to-be-done (who, doing what, instead of what?)
- The walking-skeleton scenario: the ONE end-to-end path that must work first
- Data: what entities exist, what's the source of truth, what must never be lost
- Boundaries: integrations, auth expectations, multi-tenancy or not
- Scale and constraints that are REAL on day one (not aspirational)
- What is explicitly NOT in v1

Rules:
- One round at a time; wait for my answers before the next round.
- If my answer is vague, push back with a concrete either/or scenario
  rather than accepting it.
- When I say "I don't know", record it as an open question — do not fill
  the gap with an assumption.
- Stop after at most 4 rounds or when new questions stop changing the
  design, whichever comes first. Then say "ready to draft".

After "ready to draft":

Draft the spec now as specs/000-overview.md. Sections: Problem, Users,
Walking-skeleton scenario, Functional requirements (numbered), Data model
sketch, Out of scope (explicit list), Open questions (from the interview,
verbatim), Acceptance criteria (observable behaviors only — no "should be
robust"). Where I said "I don't know", the item goes under Open questions,
not into a requirement.

2. Harden the draft — the two sections you can't delegate

Edit the draft personally. Most sections you're checking; two you must author:

• Acceptance criteria — these are the contract every future implementation session is judged against, and later the basis of tests. An agent drafting them writes criteria its own median implementation will pass: "user can log in" instead of "5 failed attempts within 10 minutes lock the account for 15 and emit an auth.lockout event". The value of criteria is exactly the part the agent wouldn't guess — so by construction it can't write them. See Writing Effective Specs.
• Out of scope — the only fence against enthusiasm-driven scope creep in every later session. The agent has no idea what you're deliberately not building, or why; it only knows what's typical, and typical products have the features you're cutting. Every item you list here is a future "while I was at it, I also added…" prevented.

A useful smell test: if you didn't change a single acceptance criterion during hardening, you weren't reviewing — you were skimming.

3. Decompose into session-sized tasks

Read specs/000-overview.md. Decompose it into an ordered task list in
specs/PLAN.md. Rules for each task:

- Completable in one focused agent session (roughly: touches < 15 files,
  one subsystem, one spec's worth of context).
- Independently verifiable: name the exact command, test, or manual check
  that proves it done. "Works" is not a check.
- States its dependencies on earlier tasks by number.
- Ordered so every task lands on a system that still runs — walking
  skeleton first, then vertical slices in risk order (riskiest
  integration earliest).

Output: a table — number, task name, verification, depends-on. Then flag
any task you couldn't make verifiable, and any task that smells like two
tasks. Do not start implementing.

Review the ordering yourself: the agent optimizes for logical dependency order; you also know political and risk order (demo dates, the integration most likely to kill the project). Promote the scary tasks earlier. Each task then becomes its own mini-spec at implementation time — the Specs and Planning templates have the per-task format.

Human review points

1. Interview answers — every answer is a product decision; "I don't know" is honest input, a guessed answer is debt.
2. Acceptance criteria and Out of scope — personally authored, not reviewed (step 2).
3. Task ordering and sizing — you re-order for risk; split anything that smells like two sessions.

Expected artifacts

specs/000-overview.md (human-hardened) · specs/PLAN.md with numbered, verifiable, dependency-ordered tasks · an Open questions list that survives into the overview rather than disappearing into assumptions.

Common failures

Symptom	Root cause	Early detection	Fix
Agent answers its own interview questions and drafts in one shot	Prompt didn't force rounds	First reply contains a spec	"One round at a time; wait for my answers" — restart if violated
Spec reads beautifully but criteria are unfalsifiable ("intuitive", "robust", "fast")	Criteria delegated to the agent	Try to turn each criterion into a test in your head; the vague ones resist	Step 2: author criteria yourself as observable behaviors
Open questions silently become requirements	Agent fills gaps with median assumptions	Diff the Open questions count between interview and draft	The "record it, don't fill it" rule; restore lost questions by hand
Tasks sized to "implement the backend"	Decomposition by layer, not by slice	Any task without a runnable verification	Re-run decomposition demanding vertical slices; see MVP Build
40-task plan for a 10-task product	Agent enumerates exhaustively, including ceremony tasks	Tasks whose output is only documents or setup already done	Delete; a plan is not more credible for being longer

Recovery strategy

A spec discovered mid-build to be wrong is normal, not a failure of this playbook — update the spec first, then the code, or the spec dies as a source of truth. See Keeping Specs Alive. If implementation sessions keep stalling on ambiguity, the interview was too shallow: re-run step 1 scoped to the ambiguous area only, and fold the answers back into the overview.

Acceptance criteria

• [ ] Interview ran in rounds with real pushback; open questions preserved verbatim
• [ ] You personally edited Acceptance criteria and Out of scope (and changed something)
• [ ] Every task in PLAN.md names its verification command/check
• [ ] No task exceeds one session; no task depends on an unbuilt later task
• [ ] Riskiest integration appears in the first third of the plan

Related

• Writing Effective Specs — what makes acceptance criteria load-bearing.
• Specs and Planning templates — the overview, per-task spec, and PLAN.md formats.
• Prompts vs Specs — why this document outlives any prompt.
• New Project — the playbook that consumes spec 001.
• MVP Build — executing PLAN.md one slice per session.
• Project and Planning prompts — variations of the interview and decomposition prompts.