---
requires: scratch/<slug>.md (ingested wave item)
produces: scratch/<slug>.md (elaborated design)
default_agent: claude
---
Research risks that could derail the work, then transform a wave item into a bold, well-considered design.
## Task and design
Treat the Task as the user's problem and desired experience. Explore possible
solutions before choosing one; distinguish observations, proposed mechanisms,
real constraints, and accepted decisions. The design owns architecture,
implementation sequencing, and proof. A Task need not arrive with an
implementation plan. Preserve its original problem when the solution changes.
Continue an existing design and investigate its material gaps; a newly filed
Task does not require restarting discovery. Keep accepted decisions binding
and linked, preserve draft status and open questions, and honor the selected
Flow. Launching a draft does not approve it.
## Orientation
Before starting, orient yourself in this branch:
- Read `scratch/` — design docs and notes for the current work live here
(`scratch/<branch>.md` is this PR's design; `scratch/questions.md` holds open
questions and assumptions).
- Read wave/PM context only when the seed names the exact wave, task, project,
or a concrete coordination question; never infer it or repair access as a
prerequisite.
- Read the repo's agent doc (`CLAUDE.md` / `AGENTS.md`) for conventions.
Write design artifacts, notes, and open questions under `scratch/`. Don't
re-derive what these already record.
## Workflow
1. **Understand the intent.** Read the ingested item. What problem does it solve? Who benefits?
2. **De-risk.** Before designing anything, find the things that could invalidate your approach and resolve them. Search the web, read docs, check APIs, run experiments. The job isn't to list risks — it's to come back with answers.
**Start with what's already flagged.** If the ingested item, wave `GOAL.md`, `MEMORY.md`, or current chapter KRs/metric targets call out specific risks, unknowns, or "what needs validation" — those are your first priority. Someone already thought these were dangerous enough to name. Research each one until you can confirm or refute it.
**Then scan for what was missed.** Look across technical constraints (does the API actually support this?), prior art (have others tried and failed?), ecosystem shifts (will the ground move under us?), and domain knowledge (are there papers or benchmarks that constrain the solution space?). Not every dimension applies — focus where uncertainty is highest.
The output of this step is concrete findings, not a worry list. "Linear's API doesn't support conditional assignment, so we need read-then-assign with conflict detection" — not "there might be API limitations." When two explanations remain plausible, run the smallest safe probe whose outcomes distinguish them. Preserve the observation even when it kills the attractive approach.
3. **Consider alternatives.** Develop 2-3 approaches that differ by mechanism,
not presentation. Keep them independent long enough to expose their real
strengths and exact gaps. Mark a route blocked when its remaining dependency
is as hard as the original task; elegance does not make a deferred problem
progress. If parallel agent work was explicitly authorized, assign approach
families dynamically and require concrete artifacts or counterexamples, not
status reports. Let the risks you found shape which alternatives are viable.
4. **Imagine wild success.** The feature ships and users love it. What details made it great? What surprised you about how people use it?
5. **Imagine wild failure.** Six months later, you're ripping it out. What went wrong? What did you miss?
6. **Make choices.** Given all this thinking, what's the right approach? Be bold. Commit to a direction.
7. **Name the demo.** Before writing the design, state the demo: the moment a
developer sees the win working — the command they run and what appears, the
interaction that now works. If you can't describe the demo, the slice is
usually scoped one step short — carry it to where it shows itself. The one
exception: work explicitly commissioned as infrastructure-only. Then say so
in the doc instead of inventing a demo.
8. **Write the design.** Update `scratch/<slug>.md` with a concrete, actionable
design. Treat every other scratch artifact as evidence to reconcile. It may
contain an older or poor design; do not continue it merely because it was
present first.
9. **Keep one north star.** For an indivisible change, keep the complete target
architecture, integration and deletion path, forbidden near-misses, full
proof, and ordered internal slices in this one artifact. Mark `This slice`
without replacing the rest of the design, and append evidence to a slice
ledger as work proceeds.
## Output format
Update `scratch/<slug>.md`:
```markdown
# <Title>
## Problem
<What we're solving. Who benefits. Why now.>
## The demo
<The moment that proves the win: what the developer runs and what they see.
One or two sentences, concrete enough to perform at the end of the build.>
## Approach
<The chosen direction. Be specific.>
## De-risking
| ... | ... | ... |
## Alternatives considered
| ... | ... | ... |
## Key decisions
<Choices made and why. The things someone would question.>
## Scope
- In scope: ...
- Out of scope: ...
## Done when
<Verification command or observable outcome>
## Forbidden outcomes
<Duplicate authorities, compatibility paths, or locally passing near-misses
that still violate the target architecture.>
## Internal slices
<Ordered coherent cuts. Keep the complete end state above them.>
## This slice
<The one current executable cut and its focused proof.>
## Slice ledger
<Commits, evidence, findings, and design changes without shrinking the north star.>
## Measure (if applicable)
<What to measure before and after. Command to run, baseline to capture, what "better" looks like. Skip for changes without quantitative outcomes.>
```
## Wave alignment
If `<lf:wave>` is present, check `wave/<wave>/GOAL.md` (and `MEMORY.md`) in docs:
- **Intent** — design must serve the wave's north star, stated in GOAL.md.
- **Evidence** — derive "Done when" from chapter KRs and user behavior. Use a
Wave-owned signal when the direction names one. Leave room for feature work
to reveal a better metric proposal; a substantial new UI performance path is
a strong reason to capture one for Wave sponsorship.
- **Memory** — check `MEMORY.md` for known risks and prior decisions. If this design introduces a new risk, name it.
- Scope must exclude what GOAL.md marks as out of scope.
## Principles
**Bold over safe.** If you're not sure, pick the more ambitious option. Safe designs compound into mediocrity.
**Concrete over abstract.** "Fast" means nothing. "P95 latency under 100ms" means something.
**Decisions over options.** Don't present choices—make them. The design should be implementable as-is.
**Complete over incremental.** Prefer landing an entire architectural chunk in one go. Splitting a coherent change into pieces creates backwards-compatibility adapters, dual states, and integration ambiguity. Only split when pieces are genuinely independent and each delivers something a user or developer would notice on its own.
**Comprehensive over light.** Kickoff outputs get read by reviewers evaluating the design and by implementing agents executing it. Be thorough — decisions, alternatives, "done when." This isn't a roadmap sketch; it's the spec a future session works from.
**Integrate over layer.** Map current concepts, types, authorities, writers, and
launch paths before adding another one. Name what the change reshapes and what
becomes obsolete. A Legacy/New split, v2, adapter, fallback, dual write, or
parallel store is blocking unless the design explicitly justifies and bounds
its deletion.