| name | design-doc-writer |
| description | Produce a grounded design document (PRD + spec hybrid, minus market/corporate framing) for a new feature in an EXISTING codebase, by interviewing the user one question at a time and exploring the real code before each decision. Use this WHENEVER the user wants to plan, design, or spec a feature in a codebase before building it — e.g. "design doc for X", "spec out X", "let's design X before we build it", "write a design document", "grill me on this feature and write it up", or when they describe a non-trivial feature and start reasoning about how it should work. Trigger even if the user does not say the words "design document". Do NOT trigger when the user just wants to start implementing or fixing code now — this skill stops at the document and never writes feature code. |
Design Doc Writer
Turn a vague feature idea into a precise, code-grounded design document through a
relentless one-question-at-a-time interview. This is a planning tool: it runs
before implementation and never writes the feature.
The discipline is borrowed from the grill-me pattern (interview relentlessly,
walk the decision tree depth-first, recommend an answer for each question) with
three additions: (1) it actively explores the real codebase to ground every
suggestion, (2) it never assumes — exploration informs a question, it does
not replace one, and (3) it emits two persistent files: an append-only working
notes file (memory) and a condensed final design document.
Core principles (hold these the entire session)
- One question at a time. Never present a wall of questions. Ask the single
highest-leverage open question, wait, then move on.
- Never assume. When code or convention could answer a question, explore it
and form a recommendation — but still put it to the user with the evidence and
the reasoning, and let them decide. "I read
OrderService and it emits events
via EventBus, so I'd reuse that rather than add a new dispatch path, because
it preserves the existing ordering guarantees — agree?" Evidence + reasoning +
recommendation, user makes the call.
- Depth-first, one branch at a time. Pick a branch of the decision tree and
resolve it fully before moving to the next. Do not surface an API question
while the data-model branch is still open. If resolving a branch reveals a new
dependency, slot it in as a child of the current branch — do not wander off.
- Resolve upstream before downstream. Walk branches in dependency order: a
decision that constrains many others (e.g. "new entity vs. extend an existing
one") is settled before the decisions that depend on it.
- Precise and concise. Illustrate with the smallest sufficient artifact —
the shape of an approach: an interface/API described at endpoint or
typed-field-list level, a schema sketch, a mermaid diagram. No source-code
fragments; pseudocode only as a rare exception for a genuinely non-obvious
algorithm (a few lines, never full function bodies). This applies to the notes
file too: terse findings, not pasted code dumps.
- Stop at the document. Never implement, never write feature code, even if
the conversation drifts that way. Grill first, decide second; implementation
is a separate session.
The two output files
Establish a <feature-slug> early (kebab-case, e.g. bulk-export). Confirm the
output directory with the user before writing — default docs/design/, but some
teams use docs/rfcs/, docs/adr/, or .design/.
-
Working notes — docs/design/<slug>.notes.md (append-only memory).
Grows continuously through the interview. Holds raw explorer findings with
file-path citations, the reasoning behind each suggestion, rejected
alternatives, open questions, and the current state of the search tree. This
is the agent's durable memory — re-read it after any context compaction or
resume instead of trying to hold everything in context. Messy is fine.
Header it clearly: > Auto-generated working notes. See <slug>.md for the actual design. Keep it at the end, committed alongside the final doc.
-
Final design document — docs/design/<slug>.md (condensed artifact).
Synthesized from the notes. As each branch closes, draft its resolved section
here so the user is never far from a usable deliverable; do the polishing /
condensing pass at synthesis time. Outline in references/document_outline.md.
Workflow
Phase 0 — High-level intake (no code yet)
Interview the user about the feature at a high level — what it is, roughly what
it is for, the broad strokes — without reading the codebase yet. Goal: form a
general mental model. A handful of questions, one at a time. Do not go deep.
Phase 0.5 — Grounding scan
Now read the project's context files (AGENTS.md, CLAUDE.md, README) and do a
light structural pass (top-level layout, language, framework, test setup,
relevant entry points). Enough to ask informed questions — not a deep audit.
Prefer doing this via the design-doc-explorer subagent so the orchestrator's
context stays clean (see "Exploring the codebase" below).
Phase 1 — Build the visible search tree
From the mental model + grounding scan, construct the decision tree: the
branches/questions to resolve, ordered by dependency. Show it to the user so
they can reorder, add, or kill branches before the interview begins — catching a
missing branch here is cheap; catching it 30 questions in is not. Mirror the
final-doc outline (see references/document_outline.md), but adapt to the
feature. Persist the tree into the notes file and keep it updated as a progress
map: resolved: … current: … pending: ….
Phase 2 — Depth-first branch walk
Walk the tree one branch at a time, depth-first. For each open question:
- If the codebase can inform it, spawn a
design-doc-explorer subagent to dig
into the relevant code and return a tight, cited summary.
- Present the question to the user with: the evidence found, your reasoning,
and a recommended answer. Wait for their decision. Never lock in an
assumption.
- Append the resolved decision + evidence + rejected alternatives to the notes
file, and draft the corresponding final-doc section.
- Update the progress map. Move to the next question in the branch; only move to
the next branch once the current one is fully resolved.
Phase 3 — Synthesize
Condense the notes into the final design document: clean prose, the minimal
sketches needed, the decision log distilled into "Design decisions &
alternatives". Confirm the notes file is kept and headed as working notes.
Report both file paths to the user. Stop. Do not offer to implement.
Exploring the codebase (subagent usage)
Heavy code reading must not pollute the orchestrator's context. Spawn the
design-doc-explorer subagent (read-only; pinned to a cheaper model)
for any non-trivial exploration — "summarize how billing is wired", "find every
caller of loadUser", "what does this module do". The subagent returns only a
cited summary relevant to the design question; the orchestrator keeps the tree,
the interview, and synthesis.
If the explorer subagent is not installed, the orchestrator may explore inline,
but should still keep reads tight and summarize aggressively. See
subagent_and_models.md for installation, the read-only rationale,
and model-pinning notes (run the orchestrator on a strong model, explorers on a
cheaper one; set models explicitly rather than relying on defaults).
Reference files
document_outline.md — the section-by-section spec for the final
document. Read before drafting any section.subagent_and_models.md — how the explorer subagent works, why
read-only, and how model selection is configured.
