software-design-docs

name

software-design-docs

description

Use when drafting, reviewing, restructuring, or updating software design documents, RFCs, engineering proposals, architecture proposals, implementation plans, or technical decision documents before or during a software project. Helps decide whether a design doc is warranted, choose the right level of detail, document high-cost decisions and tradeoffs, prepare docs for review, and identify missing goals, non-goals, scenarios, interfaces, dependencies, risks, open issues, and alternatives.

Software Design Docs

Use this skill to produce design docs that expose the hard decisions before a team commits to an implementation path.

Install

npx skills add shenli/dev-skills@software-design-docs -g

Workflow

1. Decide whether the work deserves a design doc. Favor writing one when the project is risky, ambiguous, long-lived, cross-team, security-sensitive, legally sensitive, or likely to take months. Keep the doc lightweight when the cost of a wrong choice is low.
2. Define the reader and review goal. Capture the author, status, created date, authoritative URL if known, target reviewers, and the decisions that need feedback.
3. Start with context that lets the doc stand alone: objective, background, related docs, goals, and non-goals.
4. Document the expensive-to-change design choices. Prioritize decisions whose reversal would require rewrites, migrations, protocol changes, operational churn, user disruption, security exposure, or contractual risk.
5. Add only the sections that matter for this project. Do not pad the doc with irrelevant headings.
6. Keep unresolved design work visible. Record open issues with options and a concrete next step, and move settled issues to resolved issues with the decision and rationale.
7. Before calling the doc ready, review it for missing tradeoffs, vague claims, unstated assumptions, and reviewer questions that are predictable enough to answer in the doc.

Section Guide

Use this as a menu, not a mandatory template:

Section	Include when it helps answer
Title	What short, distinctive name should people use for this project?
Metadata	Who owns the doc, what status is it in, and where is the canonical copy?
Objective	What is the one-sentence purpose in stakeholder-readable language?
Background	Why now, what problem exists, and what prior attempts or constraints matter?
Related docs	Which specs, plans, designs, tickets, or prior decisions frame this work?
Goals	What user, team, product, reliability, cost, or business outcomes should change?
Non-goals	What plausible expectations are explicitly out of scope?
Scenarios	How will users, operators, clients, or systems experience the design?
Diagrams	How do components, data flow, protocols, trust boundaries, or dependencies relate?
Glossary	Which terms, internal names, or domain concepts might readers not know?
Constraints	What budget, platform, client, infrastructure, compliance, or compatibility limits shape the design?
SLOs	What measurable availability, latency, throughput, scale, durability, or correctness targets matter?
Monitoring / alerting	How will the team know the design is healthy or failing in production?
Timeline	What milestones produce useful artifacts or reviewable increments?
Interfaces	What UI, API, CLI, file format, event, schema, or protocol contracts change?
Dependencies / infrastructure	Which languages, stores, services, vendors, libraries, hardware, or deployment choices are hard to reverse?
Security	What threats, attack surfaces, trust boundaries, and access controls matter?
Privacy	What sensitive data exists, who can access it, how long it is retained, and how it is protected?
Legal considerations	What licenses, contracts, regulations, or customer obligations constrain the design?
Logging	What events are logged, where logs live, who can read them, and what data must not appear?
Open issues	What problem remains, what options exist, and what is the immediate next step?
Resolved issues	What decision was made, why, and what discussion should be preserved?
Alternatives considered	Which strong alternatives are reviewers likely to ask about, and why were they rejected?

Drafting Rules

• Make the first page useful without a meeting or hallway explanation.
• Write goals as outcomes, not implementation tasks. Prefer "reduce deploy outages" over "add Kubernetes."
• Make non-goals explicit when a reader could reasonably assume the work is in scope.
• Use concrete scenarios for user-visible behavior, operator workflows, failure handling, migrations, and cross-system interactions.
• Keep diagrams editable and link to the source diagram or diagram code when possible.
• Quantify claims about scale, reliability, latency, cost, data retention, and operational load. If a number is unknown, state the measurement needed.
• Explain why the chosen dependency, language, storage layer, API shape, or deployment model is acceptable despite its tradeoffs.
• Keep alternatives brief unless a rejected option was genuinely plausible, controversial, or expensive to evaluate.
• Avoid specifying reversible implementation details that reviewers can safely leave to the implementation phase.

Reviewing Existing Docs

When auditing or revising a design doc:

1. Identify the project stage: sketch, ready for review, approved, superseded, partially implemented, or stale.
2. Check whether the doc distinguishes current behavior from proposed behavior.
3. Look for major decisions whose rationale is missing, especially interfaces, data storage, dependencies, security boundaries, privacy handling, rollout, migration, and failure modes.
4. Flag vague objectives, implementation-shaped goals, missing non-goals, unmeasurable SLOs, unowned open issues, and alternatives that reviewers will predictably ask about.
5. Preserve useful unresolved discussion. Do not delete an open issue simply because it is awkward; make the next step concrete.

Closeout

When done, report:

Design doc:
- Created/updated: <path>
- Key decisions documented: <short list>
- Open issues: <count or none>
- Validation: <commands or checks run>

This skill is based on the design-doc guidance and example published by Refactoring English:

• https://refactoringenglish.com/excerpts/write-an-effective-design-doc/
• https://refactoringenglish.com/excerpts/write-an-effective-design-doc/little-moments-design-doc/