/stdd:plan — Sketch → roadmap + backlog

/stdd:plan — Sketch → roadmap + backlog

Input: $ARGUMENTS

stdd is deliberately silent on how to plan, but a greenfield project still needs a bridge from a big sketch to the one-spec-per-slice loop. This command builds that bridge once, as a blessed artifact, so you don't reinvent it (and don't invent a convention, like roadmap-indexed spec names, that fights the guard or the self-containment rule).

It produces a roadmap and a backlog. It does not write specs. Specs are written just-in-time with /stdd:spec <name> immediately before /stdd:tdd <name>, one slice at a time.

Task

1. Read the inputs

Read the sketch named in $ARGUMENTS (a file path, or a pasted description), plus any existing docs/decisions/ ADRs and docs/ material. For a large sketch, delegate the read to a subagent (Task tool) that returns a structured digest: the candidate slices, the cross-cutting decisions, and the open questions. That keeps the synthesis below from consuming your main context.

2. Fog check: is the sketch decomposable yet?

Before decomposing, decide whether you can. Decomposition assumes the roadmap's shape is knowable now. Sometimes it isn't: the number and boundaries of the slices depend on questions you can't yet answer (does SSO force a separate identity service, is the tenant boundary in the DB or the app, does the ORM even support the isolation model). These are blocking unknowns: they gate planning itself, not a slice's finish. Guessing past them produces a roadmap that reality invalidates on slice 2.

Distinguish a blocking unknown from an ordinary empirical bet (step 6). A bet is settled by running a slice you've already committed to build, and only decides whether that slice ships as planned; the roadmap around it stands. A blocking unknown decides what the slices are: you cannot order the backlog until it resolves.

If blocking unknowns dominate (you can't name a stable first few slices without guessing), enter fog mode instead of forcing a roadmap:

1. Write the blocking unknowns to docs/open-questions.md (step 6's template), each with *Kind*: blocking and *Gate*: planning, so they resolve before the roadmap can be drawn, not before a slice finishes. State each item's Resolution mechanism: a spike, a code/doc read, or a decision the user must make.
2. Write only the slices you can already name stably (often the tracer, or none). Leave the rest as a short "not yet decomposable, blocked on OQ-N" note under the backlog. Do not emit guessed slices to look complete.
3. Tell the user which blocking questions to resolve first, and that resolving them (a spike's finding, an ADR, an answered fork) graduates the fog into real slices. Then they re-run /stdd:plan and the frontier is smaller.

Fog mode is the same loop the rest of stdd runs, one level up: resolve an unknown, let it clear the next stretch of the map, repeat until the sketch decomposes. Most sketches are not foggy; decompose them directly and skip this. Reach for fog mode only when naming the slices would mean guessing.

3. Decompose into vertical slices

A slice is the smallest end-to-end increment that ships real value and proves its own wiring (a tracer through the stack), not a horizontal layer. Order them so each builds on the last; the first slice is the tracer bullet for the whole system.

For each slice decide its domain-nested spec path, mirroring src/: src/auth/login.ts → docs/specs/auth/login.md. Name by domain, never by roadmap position (auth/login, not slice-3): roadmap-indexed names break the guard's spec↔file mapping and force you to fork specs (slice-3.5) when reality inserts work between items. The roadmap absorbs ordering and insertions; the specs stay domain-stable.

4. Separate decisions from slices

Anything cross-cutting that applies across slices (validation library, error model, timestamp format, auth strategy) is an ADR in docs/decisions/, not a slice and not repeated in each spec. Note any the sketch implies that aren't captured yet, but do not bulk-write ADRs you don't need yet.

5. Capture deliberate non-goals as out-of-scope notes

A slice you don't build is silent; a slice you decided not to build should be written down, or someone re-proposes it cold. If the sketch raises directions you consciously reject (a feature deferred, a simpler alternative chosen over a richer one, a whole capability ruled out), write docs/out-of-scope.md from the stdd template (read ${CLAUDE_PLUGIN_ROOT}/templates/out-of-scope.md): one stable OOS-N item each, with the reason and the date. Do not invent non-goals to fill the file. A plan that draws no boundaries doesn't get one. It is a peer of docs/decisions/, not part of any spec.

6. Capture empirical bets as open questions

An ADR records a decision you've made; an open question records an assumption you're betting on but can't verify until code runs: does the driver's dialect cover our SQL, does the SDK behave the same headless, does this library run on our runtime. These are the cheap-to-discover-early, expensive-to-discover-late risks that decide whether a slice ships as planned.

If the sketch carries any, write docs/open-questions.md from the stdd template (read ${CLAUDE_PLUGIN_ROOT}/templates/open-questions.md): one stable OQ-N item each, phrased as a question, with a Gate naming the slice that must resolve it and a Resolution mechanism (the probe that settles it, plus the on-ship / on-miss branch). Do not invent questions to fill the file. A project with no empirical bets doesn't get one. The file is a peer of docs/decisions/, not part of any spec; /stdd:tdd resolves a slice's gating question at its Finish.

7. Write docs/roadmap.md

# Roadmap

How this project is built: an ordered backlog of vertical slices. Each is
implemented just-in-time — run `/stdd:spec <name>` then `/stdd:tdd <name>` for
the next unstarted slice. This roadmap is an *input* to specs, not a reference
they link back to; specs stay self-contained.

## Conventions
- Specs are named by domain (mirroring `src/`), one per vertical slice.
- Edit a spec in place when behaviour changes; retire it when removed. Never
  fork to `-v2` or to a roadmap index.
- Cross-cutting decisions live in `docs/decisions/` (ADRs), not in the roadmap.
- A slice resting on an empirical bet cites its `OQ-N` from
  [`open-questions.md`](open-questions.md); that question resolves before the
  slice finishes.

## Backlog

| # | Slice (spec path) | Intent | Depends on | Independent? |
|---|-------------------|--------|------------|--------------|
| 1 | `<domain/name>` (tracer) | <one line> | — | — |
| 2 | `<domain/name>` | <one line> | 1 | yes |
| … | … | … | … | … |

## Out of scope
Deliberate non-goals this plan drew live in
[`out-of-scope.md`](out-of-scope.md), each a stable `OOS-N`. Omit this section
(and the file) when the plan drew no boundaries worth recording.

## Open questions
Empirical bets this plan rests on live in
[`open-questions.md`](open-questions.md), each gated to the slice that must
resolve it. Omit this section (and the file) when the sketch carries no such
bets.

Fill Independent? with yes only for slices that touch a disjoint set of src/ files from the in-flight work. Those are the only ones safe to run in parallel git worktrees. Most slices touch shared modules; mark them —.

8. Confirm

Roadmap written to docs/roadmap.md — N slices[, K open questions to docs/open-questions.md][, J non-goals to docs/out-of-scope.md]. No specs drafted (that's deliberate). Start the first slice with /stdd:spec <slice-1-name>.

In fog mode, confirm differently: name the blocking questions and stop short of a full roadmap.

The sketch isn't decomposable yet — K blocking questions in docs/open-questions.md gate the shape of the plan. Resolve them (a spike, a read, a decision), then re-run /stdd:plan. Wrote N slices I could name stably; the rest waits on those answers.

Do not create empty spec stubs and do not draft specs ahead. The next slice's spec is written when you reach it.