Write Design Doc

Scope

Treat $ARGUMENTS as the thing being designed — a feature, a subsystem, or a structural change (move sessions from cookies to Redis, add multi-tenant billing, replace the polling sync with webhooks). Restate it in one sentence to confirm scope before designing.

If $ARGUMENTS is empty, ask one focused question: "What feature or system change should I design?" Do not invent a problem to solve.

Step 1 — Frame the problem

Before any solution, pin down what you're solving and why now.

• What is broken, missing, or about to break? Why is this worth doing now rather than later?
• Who is affected — end users, a specific team, on-call, future maintainers? What do they feel today?
• What does "done" look like as observable behavior, and what is explicitly not in scope for this change?

Step 2 — Ground the design in the real code

A design that ignores the existing structure invents a system that doesn't match the one you're changing. Use Read, Grep, and Glob (no shell) to map reality first:

• Orient: Read README.md, package.json, and CLAUDE.md for stack, conventions, and the patterns the team already commits to. Glob (e.g. src/**/*.ts, **/migrations/**, **/*.config.*) to see how the tree and its boundaries are laid out.
• Find the blast radius: Grep for terms from $ARGUMENTS to locate every module, route, model, and config the change touches. Trace the data flow and the layers it crosses — a design that only names the happy-path file underestimates the work.
• Find the pattern to extend or break from: Read the closest existing subsystem end to end. Decide deliberately whether your design follows that pattern (cite it) or departs from it (justify the departure in Trade-offs). Note real constraints you discover: a schema you must migrate, an interface other code depends on, a queue/cache/auth boundary you can't move freely.

Step 3 — Write the design doc

Output the doc in this structure. Keep it skimmable and decision-oriented — cite real file paths and symbols from Step 2, not placeholders. Cut anything that isn't a decision or a constraint.

## Design — <one-line summary of the change>
 
### Context & problem
<Why this, why now, who's affected. The state today, with real references
(`path/to/module.ts`, the current flow). 2-4 tight paragraphs, no preamble.>
 
### Goals
- <observable outcome this change must achieve>
 
### Non-goals
- <explicitly out of scope — the boundaries that keep this shippable>
 
### Proposed design
<The approach. Data model / flow changes, key interfaces and signatures,
and exactly how it fits (or deliberately departs from) existing patterns
in `path/to/...`. Diagrams-in-prose are fine; be concrete about what code
lives where.>
 
### Alternatives considered
- **<Alternative A>** — <how it would work> — **Rejected because** <reason>.
- **<Alternative B>** — <how it would work> — **Rejected because** <reason>.
 
### Trade-offs & risks
- <what this design costs: complexity, perf, coupling, ops burden>
- <what could break, and the failure mode if it does>
 
### Rollout & migration
- <how it ships: flag, phased rollout, backfill/migration order, rollback path>
 
### Observability
- <metrics, logs, alerts that prove it works in prod and catch regressions>
 
### Open questions
- <each unresolved decision that needs an owner / a call>

Report

Deliver the design doc as your message — it is the whole deliverable. Verify it has real alternatives with reasons, honest trade-offs, and a rollout plan that names a rollback path; if any of those is hand-waved, it isn't done. End with the Open questions — the specific decisions that need a human call before implementation can start. No files were changed; this is a doc to align on, not the change itself.