lucasilverentand/write-design-doc

Write a Design Doc

Assembles a system design into a structured document that engineers and LLMs can understand, implement from, and maintain. This skill is about the DOCUMENT — structure, sections, writing quality, completeness. The intellectual work of decomposing systems, analyzing trade-offs, modeling data, and designing APIs happens in other skills; this skill pulls their outputs together into a coherent, readable artifact.

Current context

• Existing architecture artifacts: !ls .context/architecture/ 2>/dev/null || echo "none yet"

Decision tree

• What does the user need?
  • Writing a full design doc for a new system → follow the full process below
  • Updating an existing design doc → read the current doc, apply changes, preserve the existing structure
  • Quick informal sketch → talk through it in chat, offer to formalize into a doc later
  • User hasn't done the design thinking yet → hand off to systems-design:architecture first when available, come back here when the thinking is done
  • User wants to review an existing doc → hand off to systems-design:design-review when available

Document structure

Every design doc has these 10 sections. Each one has content or an explicit "N/A — reason."

1. Summary

2-3 sentences: what is being built, who it's for, why now. A reader should know whether this doc is relevant to them after reading this paragraph alone.

2. Requirements

Functional and non-functional. If requirements were gathered with the project:requirements skill, link to that output rather than duplicating. Otherwise, capture them inline. Non-functional requirements need concrete targets: "p99 latency < 200ms" not "fast."

3. High-level architecture

Components and how they communicate. Include a Mermaid diagram — delegate to documentation:c4-diagrams if the system has more than 4-5 components. Name concrete technology for each component: "Orders Worker (Cloudflare Workers, Hono)" not "Orders Service."

4. Data model

Entities, relationships, ownership, storage engine. If the model is detailed, link to the systems-design:data-modeling output rather than duplicating the full schema here. At minimum, show the core entities and their relationships.

5. Key flows

Walk 2-4 important request paths end-to-end. At least one happy path and one failure/error path. Use numbered steps, not prose paragraphs:

1. Client sends POST /orders with cart_id
2. Orders Worker validates the cart exists (D1 lookup)
3. ...

6. API surface

Main endpoints or operations. If the API is substantial (>5 endpoints), delegate to systems-design:api-design and link to its output in .context/architecture/api/. Here, show only the most important operations with their signatures.

7. Non-functional story

How the design meets EACH non-functional requirement from section 2. Be specific and tie back to concrete mechanisms: "handles 5k req/s because Workers auto-scale per-isolate and D1 read replicas serve reads from edge" — not "scales well."

8. Trade-offs

|Decision|Chose|Rejected|Why| |---|---|---|---| |...|...|...|...|

Every non-obvious choice gets a row. Give rejected options their real best case — strawman comparisons are useless.

9. Open questions

What's unclear, what needs input from others, what was deliberately punted. Mark each with who needs to answer and a rough deadline if applicable.

10. Next steps

Concrete first actions to de-risk the design. Not "implement the system" but "set up the D1 schema and seed test data to validate the query patterns."

Writing principles

These are non-negotiable. A design doc that violates these is worse than no doc at all.

• Write for a junior engineer or a weaker LLM model. The next reader may not have been in the room when the design was discussed. They need to understand the system from the doc alone.
• Explain jargon the first time you use it. "the outbox pattern (write events to a DB table in the same transaction as the state change, then a worker publishes them)" — not just "the outbox pattern."
• State the WHY next to every choice. Not "uses Postgres" but "uses Postgres because transactional writes across orders and line_items must be atomic." Every technology, pattern, and boundary needs a reason.
• Be concrete. Name files, services, cloud resources, paths. "Orders Worker owns orders and line_items in D1 (orders-db)" beats "Orders service handles order data."
• Mark uncertainty. Write "TBD: expected write/read ratio" — not a made-up number. Fake precision is worse than an honest gap.
• Prefer trade-offs over recommendations. "Chose KV over D1 for sessions because lookups are single-key and KV is 10x cheaper at this access pattern, giving up SQL queryability" is more useful than "uses KV."
• Add a Glossary section when the doc uses 5+ specialized terms. Place it at the end, keep it alphabetical and skimmable.

Output

Write the finished doc to .context/architecture/<name>.md. After writing:

1. If .context/overview.md exists, add a pointer to the new doc from it
2. If major decisions were made during the writing, suggest capturing them individually as ADRs via documentation:write-adr
3. If the user will build next, suggest concrete first implementation steps

Verification checklist

Before considering the doc done, verify:

• [ ] Does every section have content or an explicit "N/A — reason"?
• [ ] Do NFR targets in the doc match the architecture's actual capabilities?
• [ ] Are all trade-offs documented, not just the obvious ones?
• [ ] Is there a glossary for specialized terms (if 5+ are used)?
• [ ] Do diagrams match the prose — same component names, same data flows?
• [ ] Can a reader who missed all design discussions implement from this doc?

Cross-references

|When|Use| |---|---| |Need to gather requirements first|project:requirements if installed| |Need to do architecture thinking|systems-design:architecture if installed| |Need a data model|systems-design:data-modeling if installed| |API surface is substantial|systems-design:api-design if installed| |Need a diagram|documentation:c4-diagrams| |Decisions deserve individual records|documentation:write-adr| |Want to review the finished doc|systems-design:design-review if installed|

Key references

|File|Covers| |---|---| |references/design-template.md|Filled-in example of the design doc structure|