Writing Designs

Takes definition.md from docs/issues/YYYY-MM-DD-<slug>/ as input. Produces a design document grounded in research, not speculation.

Does NOT implement code, create PRs, or make architectural changes. Output is a design document only.

NO DESIGN DECISION WITHOUT A CITED REFERENCE

Workflow

- [ ] Step 1: Load Issue Definition
- [ ] Step 2: Research
- [ ] Step 3: Industry Baseline
- [ ] Step 4: Research Summary
- [ ] Step 5: Design Goals & Non-Goals
- [ ] Step 6: Proposed Design
- [ ] Step 7: Validate

Step 1: Load Issue Definition

Read definition.md from the issue folder.

If no folder is specified, list available folders and ask
Extract: background, issue statement, current state, non-goals, open questions
Note open questions that affect design decisions

Step 2: Research

Web search: Engineering blogs, technical articles, documentation
GitHub: Open-source implementations, issues, PRs showing patterns

Prioritize primary sources from companies that have solved this at scale. Use at least 3 distinct search queries.

Rules:

At least 5 references, each with a URL you actually visited
Verify each URL loads via WebFetch before including
Do NOT fabricate URLs

Step 3: Industry Baseline

Common/default solution and widely adopted patterns
Trade-offs and known limitations
Cite references by title

Step 4: Research Summary

Key patterns across sources
Which approaches fit the current issue and codebase
What research suggests about the issue's open questions

Step 5: Design Goals & Non-Goals

Design Goals — derive from issue statement, order by priority. Each must be verifiable: a measurable metric or testable assertion.

Non-Goals — inherit all from issue definition, add any discovered during research.

Step 6: Proposed Design

Reference specific files/modules from issue definition's current state
Explain key decisions and why alternatives were rejected (cite research)
Include interface definitions or data flows where helpful
Every decision traces to a design goal
Pseudocode acceptable; implementation code is not

Step 7: Validate

Check	Criteria
References	5+ entries with verified URLs via `WebFetch`
Industry Baseline	Cites references by title, no speculation
Design Goals	Verifiable, trace to issue statement
Non-Goals	All inherited items from issue definition included
Proposed Design	Every decision traces to a goal, no implementation code

If any check fails, return to the failing step and revise.

Output

Save to docs/issues/YYYY-MM-DD-<slug>/design.md in the same folder as definition.md.

## References

## Industry Baseline

## Research Summary

## Design Goals

## Non-Goals

## Proposed Design

Missing any section invalidates the output.

Anti-patterns

❌ "Most apps probably use X" → ✓ "PDF.js uses X (PR #7793)"
❌ Atomic goal + best-effort design → ✓ reconcile goals and design
❌ keys.filter(k => ...) → ✓ "Collect keys ending with suffix"
❌ Unverified URLs → ✓ every URL visited via WebFetch
❌ Features not traced to goals → ✓ every decision references a goal

writing-designs