Design Doc
Authors and reviews software design documents — the written artifact an engineer produces before building, to think through the decisions that are expensive to get wrong. This skill is the judgment for three questions the article centers on: should this project have a doc at all, what goes in it, and how do you write it so it actually works on a reader who never spoke to you.
A design doc is not a formality or a status report. Its purpose is leverage:
A good design doc can save you years of development time. Writing a design doc forces you to think through important decisions before you waste time on the wrong implementation or paint yourself into a corner.
It is two things at once: a decision-forcing tool (writing the hard parts down surfaces the choices you'd otherwise discover mid-build, when they're costly to reverse) and a communication tool (it lets teammates, partner teams, and reviewers understand and pressure-test the plan before code exists).
The Two Ways a Design Doc Fails
Hold both failure modes in mind the entire time. Every decision in this skill is about staying between them.
- Under-writing — skipping the doc, or omitting the decisions that are hard to reverse. You discover the mistake after 200k lines of C++, when a rewrite is unrecoverable. The cure is the when-to-write test and the penalty-for-being-wrong filter.
- Over-writing — specifying every detail (button spacing, every helper). "If you specify every possible detail in a design doc, you've essentially written the implementation during the design phase. That would defeat the whole purpose of a design doc." The cure is the same penalty-for-being-wrong filter, applied to cut.
Good design-doc work is almost entirely about what to leave out. Reach for high-cost-of-error decisions; let cheap, reversible choices be discovered in code.
Phase 1 — Decide Whether to Write One
Not every project earns a doc. "Sometimes, the right amount to invest in a design doc is zero." Run the checklist — answer yes to any one and a doc is likely worth it; two or more and it almost certainly is:
- Will multiple people coordinate work to implement the design?
- Will the project take more than three months of full-time dev work?
- Will the implementation run in production for several years?
- Does the project involve cross-team collaboration?
- Are the goals and requirements ambiguous?
- Are there catastrophic risks (security, legal, data loss) you could prevent at design time?
If it clears the bar, scale the effort to the project's risks and deadlines — there is no universal "right length," just as there's no rule for how much to test. If it doesn't, say so and stop; recommending no doc is a valid, useful answer.
Phase 2 — Decide What Belongs
One question governs every inclusion decision:
What's the penalty for being wrong?
- High penalty → put it in the doc. Choices that are hard or impossible to reverse: programming language, storage backend, public interfaces, trust boundaries, data model, anything with multi-year lock-in. "Think deeply about which dependencies will be difficult to change after implementation, and don't worry so much about the ones that swap out easily." (Languages and storage backends are agony to change; the third-party email provider you can swap in an afternoon.)
- Low penalty → leave it out. Whether 1,000 articles render all at once or behind a "Load more" button costs an afternoon to change later — it does not belong in a design doc.
Then select the section subset. The catalog in references/section-catalog.md is a menu, not a mandate: "You generally don't need every single section for every doc. Choose the subset that makes sense for you." A small internal service may need only Objective, Background, Goals, Non-goals, Interfaces, and Alternatives. A multi-year platform with PII may need almost all of them.
Phase 3 — Draft the Doc
Work from references/section-catalog.md — every section the article defines, grouped, each with its purpose, the questions it answers, a good/bad example, and an "include when." The canonical clusters:
| Cluster |
Sections |
Carries |
| Front matter |
Title · Metadata · Objective · Background · Related documents · Glossary |
Orient a cold reader; one-sentence purpose; why this project exists. |
| Scope (the contract) |
Goals · Non-goals · Constraints |
Outcomes after launch, explicit out-of-scope, hard limits. |
| The design |
Scenarios · Diagrams · Interfaces · Dependencies & infrastructure |
How the built system behaves and fits together. |
| Operability |
SLOs · Monitoring & alerting · Logging · Timeline |
How you'll run it, measure it, and ship it in milestones. |
| Risk & compliance |
Security · Privacy · Legal |
Threats, sensitive data, regulatory and licensing obligations. |
| Living sections |
Open issues · Resolved issues · Alternatives considered |
Unresolved questions, their history, and the roads not taken. |
A full, imitable example doc — the RecencyBank caching layer, written right-sized and stand-alone end to end — is in references/worked-example.md. Read it before drafting; it is the target shape.
Phase 4 — Make It Stand on Its Own
A design doc is a writing artifact, and most of them fail as writing, not as engineering. The governing test:
Imagine what you'd say to a teammate or partner team before they read your design doc. Now realize that some readers will see the doc before hearing any explanation from you. Whatever they'd need to understand should be on the first page.
The craft rules that follow from this — write the Objective in plain language any stakeholder grasps; goals as outcomes not implementations; be measurable, not vague ("p50 latency ≤ 200ms," never "performant on mobile"); prefer recognizable terms and define them inline over burying them in a glossary; keep diagrams editable (Mermaid, D2, Excalidraw, draw.io — never a whiteboard photo) and link their source — live in references/writing-craft.md with before/after rewrites. Run them as a self-edit pass over every draft.
Phase 5 — Drive It Through Review
The doc exists to be pressure-tested before code does. Circulate it, gather meaningful feedback, and track what's unresolved in Open issues (each with: the problem, the options, the immediate next step) — moving them to Resolved issues with the discussion intact for posterity as they close. Write the doc before writing code, and adhere to it as you implement, while accepting that details below the cost-of-error line are settled in code, not prose. Full guidance — the when-to-write rationale, the cost-of-error framework, right-sizing, circulating for feedback, and the issue lifecycle — is in references/review-and-lifecycle.md.
Bundled Resources
| File |
When to Read |
| references/section-catalog.md |
While drafting — every section the article defines, grouped into six clusters, each with purpose, the questions it answers, a good vs bad example, and when to include it. |
| references/writing-craft.md |
During Phase 4 — the communication layer: the stand-alone test, plain-language objectives, outcome-shaped goals, measurable-not-vague, inline-over-glossary, editable diagrams, concision, naming, with before/after rewrites. |
| references/worked-example.md |
Before drafting — a complete, right-sized exemplar design doc (RecencyBank caching layer) to imitate end to end. |
| references/review-and-lifecycle.md |
During Phases 1, 2, and 5 — the when-to-write checklist and rationale, the penalty-for-being-wrong framework, right-sizing investment, driving the doc through review, gathering feedback, and the open/resolved-issue lifecycle. |
Scope Note
This skill writes the engineering/technical design document — systems, services, features, migrations, architecture. It is not the creative, visual, or brand "design" artifact. For brand identity and UI creative direction use creative-director; for logo and asset systems use logo-studio.
1---2name: design-doc3description: Expert author and reviewer of software design documents (technical design docs, engineering design proposals, architecture decision docs, internal RFCs). Use when the user asks to write, draft, outline, structure, scope, right-size, or review a design doc, tech spec, RFC, or architecture proposal for a software system, feature, service, migration, or platform change — or asks whether a project even needs one. Produces a decision-forcing, audience-ready document grounded in the practices from "Write an Effective Design Doc" in Refactoring English by Michael Lynch — deciding when to write one, what belongs (judged by the penalty for being wrong), the section-by-section template, the writing craft that makes the doc stand on its own, and how to drive it through review. This is the engineering/technical design document, not a creative, visual, or brand design spec.4---56# Design Doc78Authors and reviews **software design documents** — the written artifact an engineer produces *before* building, to think through the decisions that are expensive to get wrong. This skill is the judgment for three questions the article centers on: **should this project have a doc at all**, **what goes in it**, and **how do you write it so it actually works** on a reader who never spoke to you.910A design doc is not a formality or a status report. Its purpose is leverage:1112> A good design doc can save you years of development time. Writing a design doc forces you to think through important decisions before you waste time on the wrong implementation or paint yourself into a corner.1314It is two things at once: a **decision-forcing tool** (writing the hard parts down surfaces the choices you'd otherwise discover mid-build, when they're costly to reverse) and a **communication tool** (it lets teammates, partner teams, and reviewers understand and pressure-test the plan before code exists).1516## The Two Ways a Design Doc Fails1718Hold both failure modes in mind the entire time. Every decision in this skill is about staying between them.1920- **Under-writing** — skipping the doc, or omitting the decisions that are hard to reverse. You discover the mistake after 200k lines of C++, when a rewrite is unrecoverable. The cure is the *when-to-write* test and the *penalty-for-being-wrong* filter.21- **Over-writing** — specifying every detail (button spacing, every helper). *"If you specify every possible detail in a design doc, you've essentially written the implementation during the design phase. That would defeat the whole purpose of a design doc."* The cure is the same penalty-for-being-wrong filter, applied to cut.2223Good design-doc work is almost entirely about **what to leave out**. Reach for high-cost-of-error decisions; let cheap, reversible choices be discovered in code.2425## Phase 1 — Decide Whether to Write One2627Not every project earns a doc. *"Sometimes, the right amount to invest in a design doc is zero."* Run the checklist — answer **yes** to any one and a doc is likely worth it; **two or more** and it almost certainly is:28291. Will **multiple people** coordinate work to implement the design?302. Will the project take **more than three months** of full-time dev work?313. Will the implementation run **in production for several years**?324. Does the project involve **cross-team collaboration**?335. Are the **goals and requirements ambiguous**?346. Are there **catastrophic risks** (security, legal, data loss) you could prevent at design time?3536If it clears the bar, scale the effort to the project's risks and deadlines — there is no universal "right length," just as there's no rule for how much to test. If it doesn't, say so and stop; recommending *no doc* is a valid, useful answer.3738## Phase 2 — Decide What Belongs3940One question governs every inclusion decision:4142> **What's the penalty for being wrong?**4344- **High penalty → put it in the doc.** Choices that are hard or impossible to reverse: programming language, storage backend, public interfaces, trust boundaries, data model, anything with multi-year lock-in. *"Think deeply about which dependencies will be difficult to change after implementation, and don't worry so much about the ones that swap out easily."* (Languages and storage backends are agony to change; the third-party email provider you can swap in an afternoon.)45- **Low penalty → leave it out.** Whether 1,000 articles render all at once or behind a "Load more" button costs an afternoon to change later — it does not belong in a design doc.4647Then **select the section subset.** The catalog in [references/section-catalog.md](references/section-catalog.md) is a menu, not a mandate: *"You generally don't need every single section for every doc. Choose the subset that makes sense for you."* A small internal service may need only Objective, Background, Goals, Non-goals, Interfaces, and Alternatives. A multi-year platform with PII may need almost all of them.4849## Phase 3 — Draft the Doc5051Work from [references/section-catalog.md](references/section-catalog.md) — every section the article defines, grouped, each with its purpose, the questions it answers, a good/bad example, and an "include when." The canonical clusters:5253| Cluster | Sections | Carries |54|---------|----------|---------|55| **Front matter** | Title · Metadata · Objective · Background · Related documents · Glossary | Orient a cold reader; one-sentence purpose; why this project exists. |56| **Scope (the contract)** | Goals · Non-goals · Constraints | Outcomes after launch, explicit out-of-scope, hard limits. |57| **The design** | Scenarios · Diagrams · Interfaces · Dependencies & infrastructure | How the built system behaves and fits together. |58| **Operability** | SLOs · Monitoring & alerting · Logging · Timeline | How you'll run it, measure it, and ship it in milestones. |59| **Risk & compliance** | Security · Privacy · Legal | Threats, sensitive data, regulatory and licensing obligations. |60| **Living sections** | Open issues · Resolved issues · Alternatives considered | Unresolved questions, their history, and the roads not taken. |6162A full, imitable example doc — the **RecencyBank** caching layer, written right-sized and stand-alone end to end — is in [references/worked-example.md](references/worked-example.md). Read it before drafting; it is the target shape.6364## Phase 4 — Make It Stand on Its Own6566A design doc is a **writing** artifact, and most of them fail as writing, not as engineering. The governing test:6768> Imagine what you'd say to a teammate or partner team before they read your design doc. Now realize that **some readers will see the doc before hearing any explanation from you.** Whatever they'd need to understand should be on the first page.6970The craft rules that follow from this — write the Objective in plain language any stakeholder grasps; goals as *outcomes* not implementations; be **measurable, not vague** ("p50 latency ≤ 200ms," never "performant on mobile"); prefer recognizable terms and define them **inline** over burying them in a glossary; keep diagrams **editable** (Mermaid, D2, Excalidraw, draw.io — never a whiteboard photo) and link their source — live in [references/writing-craft.md](references/writing-craft.md) with before/after rewrites. Run them as a self-edit pass over every draft.7172## Phase 5 — Drive It Through Review7374The doc exists to be pressure-tested before code does. Circulate it, gather meaningful feedback, and track what's unresolved in **Open issues** (each with: the problem, the options, the immediate next step) — moving them to **Resolved issues** with the discussion intact for posterity as they close. Write the doc before writing code, and adhere to it as you implement, while accepting that details below the cost-of-error line are settled in code, not prose. Full guidance — the when-to-write rationale, the cost-of-error framework, right-sizing, circulating for feedback, and the issue lifecycle — is in [references/review-and-lifecycle.md](references/review-and-lifecycle.md).7576## Bundled Resources7778| File | When to Read |79|------|--------------|80| [references/section-catalog.md](references/section-catalog.md) | While drafting — every section the article defines, grouped into six clusters, each with purpose, the questions it answers, a good vs bad example, and when to include it. |81| [references/writing-craft.md](references/writing-craft.md) | During Phase 4 — the communication layer: the stand-alone test, plain-language objectives, outcome-shaped goals, measurable-not-vague, inline-over-glossary, editable diagrams, concision, naming, with before/after rewrites. |82| [references/worked-example.md](references/worked-example.md) | Before drafting — a complete, right-sized exemplar design doc (RecencyBank caching layer) to imitate end to end. |83| [references/review-and-lifecycle.md](references/review-and-lifecycle.md) | During Phases 1, 2, and 5 — the when-to-write checklist and rationale, the penalty-for-being-wrong framework, right-sizing investment, driving the doc through review, gathering feedback, and the open/resolved-issue lifecycle. |8485## Scope Note8687This skill writes the **engineering/technical** design document — systems, services, features, migrations, architecture. It is not the creative, visual, or brand "design" artifact. For brand identity and UI creative direction use `creative-director`; for logo and asset systems use `logo-studio`.
thatjuan