Output language: answer and write artifacts in the user's own language (match their messages, not the repo's history).
Overview
Turn an approved design into a durable product spec that a new teammate (or future you) can understand without the meeting recording.
Spec = what & why. Plan = how & in what order. Do not mix them.
REQUIRED UPSTREAM: grill (or an already-approved design the user points at). Do not invent product decisions while writing the spec.
Announce: "Using write-spec to …"
When to Use
- After grill approval, before write-plan
- User asks for a design doc / spec / PRD-lite
- Handing work to another person or agent who was not in the grill
When NOT to use: pure bugfix with known fix; one-line change with no product ambiguity; user already has an approved written spec and only wants write-plan.
The Iron Law
A SPEC NO NEWCOMER CAN ACT FROM IS THEATER.
Write in plain language. Drive with user-visible scenarios.
Every "should" must become a concrete case someone can demo or test.
No file paths, TDD steps, or commit lists — those belong in write-plan.
Voice: builder who lives in their own product
Write for one reader who is both the engineer and a daily user of what they build:
- Pair value with mechanism — say what the experience feels like and name the tech choice behind it, so they keep control of both product and code
- Lead with perceivable upside / downside / cost, but never drop the mechanism into vague "user speak"
- Prefer "what the user sees + the mechanism that delivers it" over "the system should have pluggable…"
- Name the trade-off you chose and what you explicitly skip this round
- Scenarios carry the product story (§2); "How we'll build it" (§7) carries the precise tech — keep them distinct, keep both honest
Spec vs Plan (do not blur)
Spec (write-spec) |
Plan (write-plan) |
|
|---|---|---|
| Question | What should the product do, and why? | Which files, in what order, how do we verify? |
| Reader | Product owner, new hire, future you | Implementer / coding agent |
| Content | Scenarios, scope, trade-offs, acceptance | Paths, interfaces, RED→GREEN→commit |
| Bad smell | File lists, "Task 3", pytest commands | "Maybe we should also support X" undecided |
Workflow
- Confirm source — approved grill summary or user-supplied design; unresolved decisions → back to grill; if explore produced a fact checklist, fold it into §0 Current state
- Pick path — default
docs/creed/specs/YYYY-MM-DD-<topic>-design.md(user path overrides) - Write the spec — use the template below; scale length to complexity
- Self-review — checklist at bottom
- User gate — ask them to skim before planning
- Hand off — if the slice adds modules / ports / IO edges → solid (Gate); else → write-plan → tdd
Spec template (required sections)
# <Feature> Spec
**Status:** Draft | Approved
**Date:** YYYY-MM-DD
**Owner:** <who decides product calls>
**Issue:** #<N> ← only when this session already has an issue number; omit the line otherwise
## 0. Current state (from explore) — refactor/legacy only
When explore produced a fact checklist (the task modified existing code), open the
spec with it so a newcomer doesn't re-read the repo. Skip this section for greenfield.
- **Anchors:** <methods/classes/tables read, current behavior>
- **Assertion check:** <user's claims → ✓/✗ with evidence>
- **Conflicts:** <constraint vs repo reality, resolved by the decisions below>
## 1. One-liner (board slide)
<One sentence: who gets what benefit, and the main cost/risk we accept.>
## 2. User scenarios (source of truth)
### Happy path
- **Who:** …
- **When:** …
- **Does:** …
- **Sees:** …
### Failure / edge
- **Who:** …
- **When:** … (timeout, empty, permission, conflict, …)
- **Sees / system does:** …
(Add more scenarios until a newcomer can role-play the feature.)
## 3. Scope
**In:**
- …
**Out (this round):**
- … — why skipped: …
## 4. Decision log (mentoring)
| Decision | Chose | Rejected | Why (user/business impact) |
|----------|-------|----------|----------------------------|
| … | A | B | Users get …; we accept … |
## 5. Acceptance (demo / test language)
- [ ] Scenario: … → observable result …
- [ ] Scenario: … → observable result …
## 6. Constraints
- Platforms / versions / naming / perf floors (quantify if it matters to users)
## 7. How we'll build it (short)
<2–5 sentences: main components and boundaries. No task list.>
## 8. Open risks
- … → mitigation / accept
Writing rules
- Scenario before mechanism — if you cannot write a Who/When/Does/Sees case, you do not understand the requirement yet → grill
- Replace adjectives with cases — "flexible / polished / high-performance" → concrete limits and outcomes
- User-perceivable trade-offs — when comparing options in the decision log, state what the user gains or loses, then the engineering cost
- Mentoring value — decision log + Out-of-scope are mandatory; they teach judgment, not just the happy path
- One shippable slice — if the doc covers two independent products, split into two specs
Bad → good
| Bad (obscure / unteachable) | Good (user-visible / teachable) |
|---|---|
| Support pluggable auth middleware | Logged-out user hits Export → login → return and auto-continue export |
| Improve resilience | Network fail on Complete → status unchanged + retry message; no half-done state |
| Flexible batch import | Max 500 rows; row 3 bad → reject whole batch and point at row 3 |
Self-review (before user review)
- No TBD / "it depends" left as product decisions
- No contradictions between scenarios and acceptance
- No implementation plan leaked (paths, RED/GREEN, commits)
- A new hire could explain the feature from §0–§5 alone
- Every In-scope item maps to at least one scenario
Rationalization Table
| Excuse | Reality |
|---|---|
| "We'll put file paths in the spec so plan is shorter" | Spec stays stable; plan churns. Keep them apart. |
| "Architecture diagram is enough" | Diagrams don't teach when the user sees an error. |
| "Too simple for scenarios" | Tiny features hide the worst assumptions. One happy + one failure case still required. |
| "Decision log is bureaucracy" | Without it, the next person re-litigates the same choice. |
| "Board language dumbs it down" | Clear upside/cost is leadership, not dumbing down. |
Checklist
- Upstream design approved (grill or equivalent)
- Spec file written from template
- Scenarios + In/Out + decision log + acceptance present
- User reviewed (or explicitly waived)
- Ready for solid (if new boundaries) or write-plan
Hand-off
Transition gate — before the spec is passed to the next stage, ask the user (one AskUserQuestion; never auto-advance):
A) Recommended: Proceed → solid (new boundaries) / write-plan
B) Review first — run **review** on this spec (`references/spec.md`; upstream = approved grill design), then return to this gate
C) Adjust — revise the spec, then return to this gate
D) Something else (I will type it)
- New modules / ports / IO edges → solid (Gate)
- No new boundary → write-plan
- Product still open → grill (do not plan)