Write Spec
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>
## 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
Hand-off
- New modules / ports / IO edges → solid (Gate)
- No new boundary → write-plan
- Product still open → grill (do not plan)
1---2name: write-spec3description: Use after design alignment (grill), or when the user asks for a design/spec/PRD doc, or when locking scope before an implementation plan, or when handing work off to someone who was not in the design discussion.4---56# Write Spec78## Overview910Turn an **approved design** into a durable **product spec** that a new teammate (or future you) can understand without the meeting recording.1112**Spec = what & why.** **Plan = how & in what order.** Do not mix them.1314**REQUIRED UPSTREAM:** **grill** (or an already-approved design the user points at). Do not invent product decisions while writing the spec.1516**Announce:** "Using write-spec to …"1718## When to Use1920- After grill approval, before **write-plan**21- User asks for a design doc / spec / PRD-lite22- Handing work to another person or agent who was not in the grill2324**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**.2526## The Iron Law2728```29A SPEC NO NEWCOMER CAN ACT FROM IS THEATER.30Write in plain language. Drive with user-visible scenarios.31Every "should" must become a concrete case someone can demo or test.32No file paths, TDD steps, or commit lists — those belong in write-plan.33```3435## Voice: builder who lives in their own product3637Write for one reader who is both the engineer and a daily user of what they build:3839- **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 code40- Lead with **perceivable upside / downside / cost**, but never drop the mechanism into vague "user speak"41- Prefer "what the user sees + the mechanism that delivers it" over "the system should have pluggable…"42- Name the **trade-off you chose** and what you **explicitly skip** this round43- Scenarios carry the product story (§2); "How we'll build it" (§7) carries the precise tech — keep them distinct, keep both honest4445## Spec vs Plan (do not blur)4647| | Spec (`write-spec`) | Plan (`write-plan`) |48|--|---------------------|---------------------|49| Question | What should the product do, and why? | Which files, in what order, how do we verify? |50| Reader | Product owner, new hire, future you | Implementer / coding agent |51| Content | Scenarios, scope, trade-offs, acceptance | Paths, interfaces, RED→GREEN→commit |52| Bad smell | File lists, "Task 3", pytest commands | "Maybe we should also support X" undecided |5354## Workflow55561. **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 state572. **Pick path** — default `docs/creed/specs/YYYY-MM-DD-<topic>-design.md` (user path overrides)583. **Write the spec** — use the template below; scale length to complexity594. **Self-review** — checklist at bottom605. **User gate** — ask them to skim before planning616. **Hand off** — if the slice adds modules / ports / IO edges → **solid** (Gate); else → **write-plan** → **tdd**6263## Spec template (required sections)6465```markdown66# <Feature> Spec6768**Status:** Draft | Approved69**Date:** YYYY-MM-DD70**Owner:** <who decides product calls>7172## 0. Current state (from explore) — refactor/legacy only7374When explore produced a fact checklist (the task modified existing code), open the75spec with it so a newcomer doesn't re-read the repo. Skip this section for greenfield.7677- **Anchors:** <methods/classes/tables read, current behavior>78- **Assertion check:** <user's claims → ✓/✗ with evidence>79- **Conflicts:** <constraint vs repo reality, resolved by the decisions below>8081## 1. One-liner (board slide)8283<One sentence: who gets what benefit, and the main cost/risk we accept.>8485## 2. User scenarios (source of truth)8687### Happy path88- **Who:** …89- **When:** …90- **Does:** …91- **Sees:** …9293### Failure / edge94- **Who:** …95- **When:** … (timeout, empty, permission, conflict, …)96- **Sees / system does:** …9798(Add more scenarios until a newcomer can role-play the feature.)99100## 3. Scope101102**In:**103- …104105**Out (this round):**106- … — why skipped: …107108## 4. Decision log (mentoring)109110| Decision | Chose | Rejected | Why (user/business impact) |111|----------|-------|----------|----------------------------|112| … | A | B | Users get …; we accept … |113114## 5. Acceptance (demo / test language)115116- [ ] Scenario: … → observable result …117- [ ] Scenario: … → observable result …118119## 6. Constraints120121- Platforms / versions / naming / perf floors (quantify if it matters to users)122123## 7. How we'll build it (short)124125<2–5 sentences: main components and boundaries. No task list.>126127## 8. Open risks128129- … → mitigation / accept130```131132## Writing rules1331341. **Scenario before mechanism** — if you cannot write a Who/When/Does/Sees case, you do not understand the requirement yet → **grill**1352. **Replace adjectives with cases** — "flexible / polished / high-performance" → concrete limits and outcomes1363. **User-perceivable trade-offs** — when comparing options in the decision log, state what the *user* gains or loses, then the engineering cost1374. **Mentoring value** — decision log + Out-of-scope are mandatory; they teach judgment, not just the happy path1385. **One shippable slice** — if the doc covers two independent products, split into two specs139140### Bad → good141142| Bad (obscure / unteachable) | Good (user-visible / teachable) |143|-----------------------------|----------------------------------|144| Support pluggable auth middleware | Logged-out user hits Export → login → return and auto-continue export |145| Improve resilience | Network fail on Complete → status unchanged + retry message; no half-done state |146| Flexible batch import | Max 500 rows; row 3 bad → reject whole batch and point at row 3 |147148## Self-review (before user review)1491501. No TBD / "it depends" left as product decisions1512. No contradictions between scenarios and acceptance1523. No implementation plan leaked (paths, RED/GREEN, commits)1534. A new hire could explain the feature from §0–§5 alone1545. Every In-scope item maps to at least one scenario155156## Rationalization Table157158| Excuse | Reality |159|--------|---------|160| "We'll put file paths in the spec so plan is shorter" | Spec stays stable; plan churns. Keep them apart. |161| "Architecture diagram is enough" | Diagrams don't teach *when* the user sees an error. |162| "Too simple for scenarios" | Tiny features hide the worst assumptions. One happy + one failure case still required. |163| "Decision log is bureaucracy" | Without it, the next person re-litigates the same choice. |164| "Board language dumbs it down" | Clear upside/cost is leadership, not dumbing down. |165166## Checklist167168- [ ] Upstream design approved (grill or equivalent)169- [ ] Spec file written from template170- [ ] Scenarios + In/Out + decision log + acceptance present171- [ ] User reviewed (or explicitly waived)172- [ ] Ready for **solid** (if new boundaries) or **write-plan**173174## Hand-off175176- New modules / ports / IO edges → **solid** (Gate)177- No new boundary → **write-plan**178- Product still open → **grill** (do not plan)
Gusen1453