writing-technical-design-docs

Writing Technical Design Docs

• A design doc is a decision artifact, not a specification.
• Its job is to align people on a direction with enough rigor that work can start and enough humility that the plan can change.
• Aim for directionally correct, not perfect: a 60% draft circulated now gets better feedback than a 95% draft circulated in three weeks.
• If the doc takes longer to write than the first slice of implementation, it is over-engineered.

Principles

• Decide the one-way doors; default the two-way doors. A one-way door is hard to reverse (data model, public API, persistence format, identity scheme): argue it out. A two-way door is cheap to reverse (timeouts, retry counts, internal module boundaries, log format): name the default, say it is revisable, and move on. A two-way door debated for more than a paragraph gets cut. When unsure what a wrong call would cost to change, treat it as one-way.
• Name unknowns; never fabricate numbers. Write "QPS unknown, will measure in week 1", not "approximately 500 QPS". Reviewers can challenge an unknown; a made-up number costs the doc its credibility.
• Pick a direction and state one alternative. Name the chosen approach, one alternative considered, and a one-line reason it lost: "Using Postgres LISTEN/NOTIFY. Considered Kafka; rejected for ops complexity at our scale." Do not lay out an option buffet; a reviewer who prefers another option will raise it.
• Concrete but incomplete. Write the load-bearing scenario end to end with its key edge cases, and mark the rest "follows the same pattern" or "TBD in implementation".
• Write down what only you know. Reviewers and later readers see the doc and the files it links, never this conversation. So each requirement, constraint, and decision from the conversation goes into the doc, or into a file the doc links.

Shape

A default to adapt; fold it into the team's own template where one exists.

1. Status banner first: Status: Draft v0.1 (seeking [direction | implementation | rollout] feedback). It tells reviewers not to send line edits.
2. Lead with the decision: right after the problem statement, the chosen approach in 3 to 5 sentences. Everything else is justification or detail.
3. Mark depth: [deep] on sections that warrant rigor, [sketch] on sections deliberately light, so reviewers know where to push.
4. Open Questions: numbered, each with an owner and the calendar date its answer is needed. Five honest open questions beat zero. An owner is an assignment, not an unknown fact: when no person can be named, name the owning team, the role, or the author, and propose the date from the doc's date. Never write TBD for either.
5. Close with a Reversibility table: each major decision rated one-way or two-way. No section follows it.

Review

• This session is the producer: it holds the conversation, so it never judges its own draft. Follow the independent review rules.
• Before returning the draft, call the Skill tool with reviewing-design-docs on it for an adversarial review.
• If it is not installed or cannot run here (for example, it cannot save the draft to a file), then below a separator after the doc, say that no independent review was done, why, and the next step: save the draft to a file, then run /reviewing-design-docs <path>.
• Return the draft, then the review output verbatim below a separator, including the prompt-only line when present. Do not revise the draft to answer findings. The user decides which to act on.
• Without a Skill tool, follow the skill call rules.

When not to use this skill

• Compliance, legal, or safety-critical specs: these need precision, not direction. Write a complete, exhaustive spec.
• Public API contracts shipped to external customers: a one-way door by default; optimize for thoroughness.
• Post-mortems and incident reports: backward-looking and factual.
• Final sign-off architecture docs: the direction is already set.