Writing Design Docs

Writing Design Docs

Produce a structured design document that captures what you're building, why, and how you'll verify it works. Output: docs/plans/YYYY-MM-DD-<topic>-design.md. This skill produces the artifact and stops.

Process

digraph design_doc {
    "Explore codebase & context" [shape=box];
    "Propose 2-3 approaches" [shape=box];
    "User selects approach" [shape=diamond];
    "Draft each section" [shape=box];
    "Write EARS requirements" [shape=box];
    "Present to user for review" [shape=box];
    "User approves?" [shape=diamond];
    "Write to docs/plans/" [shape=box];
    "Done" [shape=doublecircle];

    "Explore codebase & context" -> "Propose 2-3 approaches";
    "Propose 2-3 approaches" -> "User selects approach";
    "User selects approach" -> "Propose 2-3 approaches" [label="none fit"];
    "User selects approach" -> "Draft each section" [label="selected"];
    "Draft each section" -> "Write EARS requirements";
    "Write EARS requirements" -> "Present to user for review";
    "Present to user for review" -> "User approves?";
    "User approves?" -> "Draft each section" [label="revise"];
    "User approves?" -> "Write to docs/plans/" [label="yes"];
    "Write to docs/plans/" -> "Done";
}

Proposing Approaches

Before drafting, explore the solution space. Research the codebase and relevant libraries, then propose 2-3 approaches:

• Lead with your recommendation and explain why
• For each approach: architecture summary, pros, cons, effort estimate
• Include at least one simpler/smaller and one more robust/extensible option
• Let the user select before committing to a design direction

Design Doc Template

Six sections. Scale depth to complexity — see Scaling Guide.

1. Summary

2-4 sentences. What and why. A busy engineer should understand the project from this alone.

2. Project Goals & Non-Goals

Goals: Problem being solved. Invariants that must hold. Be specific — "p99 under 200ms", not "fast".

Non-Goals: Reasonable things explicitly out of scope. Not negated goals — things you're choosing not to address.

3. Context

• Catalysts: GitHub Issues, Slack threads, or other triggers
• Codebase: Existing folders, files, and design docs relevant to this work
• External docs: URLs for third-party library documentation
• References: Blog posts, RFCs, or source materials that informed the design
• Impact area: Modules or directories that will be modified

4. System Design

• Architecture overview: How components fit together. Diagram if helpful.
• New or modified interfaces: Class/struct definitions, API boundaries. Shape, not implementation.
• Key functions: Important functions with expected behavior. Contracts and invariants.
• Alternatives considered: Why rejected approaches didn't make the cut.

5. Libraries & Utilities Required

External dependencies:

Internal modules:

Write "None" if no dependencies — don't omit the section.

6. Testing & Validation

This is the most important section. It should be the most detailed.

Acceptance Criteria

Use EARS format for every criterion. Each must be testable and unambiguous.

Edge Cases

Address relevant categories: concurrency/race conditions, dependency failures, error handling/recovery, boundary conditions, security considerations.

Verification Commands

Concrete commands to prove correctness. Include linting and formatting checks.

EARS Quick Reference

Rules: Use SHALL, never "should"/"may". Each requirement independently testable. No vague terms — use measurable criteria.

Scaling Guide

Common Mistakes

Examples

See examples/ for graduated examples:

• small-cli-flag.md — Adding a --verbose flag (minimal but complete)
• medium-api-endpoint.md — REST API with auth and rate limiting
• large-event-system.md — Distributed event pipeline with retry and DLQ