write-design-docs

# Write Design Docs ## Core Workflow Use the design doc as a problem-solving and consensus-building tool, not as an implementation manual. 1. Decide whether a design doc is warranted. - Write one when the software design is ambiguous, complex, contentious, cross-functional, likely to benefit from senior review, or valuable as organizational memory. - Prefer a short note, issue, or direct implementation when the solution is obvious and there are no meaningful trade-offs. - Prefer a mini design doc for small but non-obvious changes. 2. Gather the minimum context needed to make the design concrete. - Identify the problem, existing landscape, constraints, stakeholders, and decision deadline. - Ask focused questions only when missing information would materially change goals, non-goals, or trade-offs. - State assumptions explicitly when proceeding with incomplete information. 3. Draft around decisions and trade-offs. - Start with objective context and scope. - Define goals and non-goals as explicit boundaries. - Present the selected design from overview to detail. - Explain why the selected design best satisfies the goals under the known constraints. - Compare realistic alternatives, including why they were not selected. - Cover cross-cutting concerns such as security, privacy, reliability, observability, migrations, and operations when relevant. 4. Keep the document readable. - Optimize for busy reviewers who need to understand the decision, not every implementation detail. - Link to detailed requirements, prototypes, schemas, code, or prior docs instead of copying them wholesale. - Include diagrams or compact API/data sketches only when they clarify the design trade-offs. - Avoid large code blocks unless explaining a novel algorithm. 5. Shape the lifecycle. - Mark the document status: draft, in review, accepted, implementing, superseded, or archived. - Suggest the smallest useful review group first, then wider review when the design is stable. - Update the doc while the system has not shipped if implementation reveals wrong assumptions or changed requirements. - Link amendments or follow-up docs when the original doc diverges from reality. ## Reference Read [references/design-doc-guidance.md](references/design-doc-guidance.md) before drafting or reviewing a substantive design doc. Use it for the article-derived template, decision checklist, section guidance, and review rubric.