design-doc.mdc4.0 KBView on GitHub ---
name: design_doc
description: Structure for design documents and the implement-next-phase workflow. Apply whenever the user asks to design, plan, or write a design doc for a feature/refactor, or says "implement next phase" / asks to execute a phased design doc.
tags:
- design
- planning
alwaysApply: false
---
# Design Doc Structure
When the user asks for a design document, a design plan, or to "design" a feature/refactor, produce a single markdown file with the exact structure below. Save it in the folder most relevant to the feature (default `docs/design/<slug>.md`).
## Before writing
1. Identify the feature/area and the user's success criteria.
2. Read every code path the design touches — open the actual files. Do not paraphrase from memory.
3. If anything material is ambiguous, ask 1–3 focused questions before writing.
## Required structure
Use these exact section headings, in this order. No extras, no renames.
```markdown
# <Feature title>
## 1) Introduction — goal, present state, future state
<One concise paragraph: what we want, what exists today, what changes. No bullets.>
## 2) Present state
### 2.1 Architecture diagram
\`\`\`text
<plaintext box-and-arrow diagram of the current high-level flow. ASCII only.>
\`\`\`
### 2.2 Step-by-step walkthrough
<Numbered list covering every function/method on the current path — do not skip any. Each step references the file with a clickable link `[file.ts:42](path/to/file.ts)`. Include a data snapshot (fenced ```json or ```ts block) at every step where data is transformed. Keep line numbers in link text and prose (not `#L` anchors) because local markdown rendering in Cursor/VSCode is inconsistent for non-markdown files. Links must be relative to the doc file location (for docs in `docs/design/`, use `./../../apps/...` and `./../../packages/...`).>
## 3) Designed state
### 3.1 Architecture diagram
\`\`\`text
<plaintext diagram of the proposed flow.>
\`\`\`
### 3.2 Step-by-step walkthrough
<Same rules as 2.2 but for the proposed flow. Every new/changed function listed with its target file path. Data snapshots at every transformation step.>
## 4) Implementation phases
<Sequential phases. Each phase is independently shippable, ends green, and fits in one commit. Use GitHub-style `- [ ]` checkboxes — the implement-design workflow ticks these.>
### Phase 1 — <name>
**Goal:** <one sentence>
- [ ] <atomic task with concrete file paths>
- [ ] <atomic task>
**Tests:**
- [ ] <test to add or update, with file path>
- [ ] <verification command>
### Phase 2 — <name>
...
```
## Style rules
- Concise. No filler, no recap, no "conclusion" section.
- Every function reference is a clickable markdown link: `[file.ts:42](path/to/file.ts)`.
- Link targets must be correct relative paths from the design doc's folder (not assumed repo-root-relative).
- Diagrams are ASCII inside ```text fences. No mermaid, no images.
- Data snapshots use ```json or ```ts, showing only the fields that matter.
- Phases are ordered so each one leaves the repo in a working state.
- Checkbox tasks are atomic — one logical change each. Avoid "refactor X" mega-tasks.
- No emojis unless explicitly asked.
## After writing
Output the saved path, phase count, and total checkbox count. Do not start implementing — this rule plans only.
## Implementing a design doc
When the user says "implement next phase" against a doc produced by this rule:
1. If there is uncommitted work unrelated to this run, commit + push it first under its own message (one phase = one commit).
2. Find the first phase containing unchecked `- [ ]` items.
3. Do each task in order. After a task is genuinely complete, edit the doc to flip `- [ ]` → `- [x]`. Never tick optimistically.
4. Run the phase's `Tests` commands. Fix root causes if red. Tick test boxes only when green.
5. Commit + push with message `<type>: <phase name> (design: <slug> phase <N>)`. Use the repo's commit conventions.
6. Stop. Wait for the next "implement next phase" before continuing.