Serial Studio — /ss-plan (phase 2 of 4)
Turn the approved spec.md into a concrete technical design. This is the HOW: which files,
which subsystems, how data and threads move, and which design was chosen over which
alternatives. See doc/claude/spec-driven.md for the gate
discipline.
Preconditions
doc/claude/specs/NNNN-slug/spec.md exists and its status: is approved. If it is still
draft, stop — the spec must be approved first (/ss-spec).
Procedure
Read the spec in full. Every requirement and acceptance criterion is a target the plan
must hit.
Read the ground truth — do not design from memory. Read the relevant doc/claude/
sub-doc(s) and the actual code for the area:
- architecture.md — index into the per-subsystem
doc/claude/architecture/ files (dataflow, startup, io, project, scripting, dashboard,
export); read the file(s) for the touched subsystems in full.
- common-mistakes.md — the silent-breakage classes
this change is exposed to.
- code-style.md and
directory-map.md as needed.
- If the change touches the hotpath, invoke
ss-hotpath and read FrameBuilder /
CircularBuffer / FrameReader / Dashboard in full per the CLAUDE.md rule.
- For a new driver, follow
ss-new-driver and grep an existing BusType value to find
every registration touch-point.
Copy the template and write the plan:
cp doc/claude/specs/templates/plan.md doc/claude/specs/NNNN-slug/plan.md
Fill every section. The Hotpath & threading impact section is required — answer it
explicitly even when the answer is "none". List concrete file paths in Affected
subsystems & files, confirmed by grep, not guessed.
Diverge before you converge. Before settling on a design, sketch 2-3 named candidate
approaches in chat (a name plus one line each) — distinct named alternatives load distinct
thinking, and a design chosen against real alternatives beats the first plausible one
(doc/claude/j-space.md, named lenses). Then converge: recommend one with the one-line why.
Surface tradeoffs as decisions, up front. Where two reasonable designs diverge on
something that matters (perf vs simplicity, fidelity vs readability, scope), put the choice
in the Tradeoffs table with a recommendation and the one-line why. Recommend, do not
enumerate. Pull the deciding constraint out of the spec rather than discovering it later.
Map every acceptance criterion to a check in the Test & verification plan — pytest
files, tests/scripts/ units, --benchmark-hotpath, or a maintainer observation.
Gate
Stop after writing plan.md. Present the design — especially the tradeoffs and the hotpath
answer — for review. Do not run /ss-tasks until the maintainer approves it. A plan visible
before execution is the contract; this is where a different approach gets chosen, cheaply.
Rules
- No code yet. The plan describes the change; it does not make it.
- If planning surfaces a question that changes the spec, go back and amend
spec.md (and
re-confirm) rather than silently diverging.
- Honor the Trust Contract: the plan's file list is the lane — anything outside it must be
named in chat, not slipped in during
/ss-implement.
1---2name: ss-plan3description: Phase 2 of Serial Studio's spec-driven workflow: turn an approved spec.md into a technical design (plan.md) — files, data flow, hotpath/threading impact, tradeoffs, risks, test plan. Use after /ss-spec is approved, or "plan this spec", "design the implementation". Reads the doc/claude sub-docs and the real code; gates on human approval before /ss-tasks.4---56# Serial Studio — /ss-plan (phase 2 of 4)78Turn the approved `spec.md` into a concrete technical design. This is the **HOW**: which files,9which subsystems, how data and threads move, and which design was chosen over which10alternatives. See [doc/claude/spec-driven.md](../../../doc/claude/spec-driven.md) for the gate11discipline.1213## Preconditions1415- `doc/claude/specs/NNNN-slug/spec.md` exists and its `status:` is `approved`. If it is still16 `draft`, stop — the spec must be approved first (`/ss-spec`).1718## Procedure19201. **Read the spec in full.** Every requirement and acceptance criterion is a target the plan21 must hit.22232. **Read the ground truth — do not design from memory.** Read the relevant `doc/claude/`24 sub-doc(s) *and the actual code* for the area:25 - [architecture.md](../../../doc/claude/architecture.md) — index into the per-subsystem26 `doc/claude/architecture/` files (dataflow, startup, io, project, scripting, dashboard,27 export); read the file(s) for the touched subsystems in full.28 - [common-mistakes.md](../../../doc/claude/common-mistakes.md) — the silent-breakage classes29 this change is exposed to.30 - [code-style.md](../../../doc/claude/code-style.md) and31 [directory-map.md](../../../doc/claude/directory-map.md) as needed.32 - If the change touches the hotpath, invoke **`ss-hotpath`** and read `FrameBuilder` /33 `CircularBuffer` / `FrameReader` / `Dashboard` in full per the CLAUDE.md rule.34 - For a new driver, follow **`ss-new-driver`** and grep an existing `BusType` value to find35 every registration touch-point.36373. **Copy the template and write the plan:**3839 ```bash40 cp doc/claude/specs/templates/plan.md doc/claude/specs/NNNN-slug/plan.md41 ```4243 Fill every section. The **Hotpath & threading impact** section is required — answer it44 explicitly even when the answer is "none". List concrete file paths in **Affected45 subsystems & files**, confirmed by grep, not guessed.46474. **Diverge before you converge.** Before settling on a design, sketch 2-3 *named* candidate48 approaches in chat (a name plus one line each) — distinct named alternatives load distinct49 thinking, and a design chosen against real alternatives beats the first plausible one50 (`doc/claude/j-space.md`, named lenses). Then converge: recommend one with the one-line why.51525. **Surface tradeoffs as decisions, up front.** Where two reasonable designs diverge on53 something that matters (perf vs simplicity, fidelity vs readability, scope), put the choice54 in the Tradeoffs table with a recommendation and the one-line why. Recommend, do not55 enumerate. Pull the deciding constraint out of the spec rather than discovering it later.56576. **Map every acceptance criterion to a check** in the Test & verification plan — `pytest`58 files, `tests/scripts/` units, `--benchmark-hotpath`, or a maintainer observation.5960## Gate6162Stop after writing `plan.md`. Present the design — especially the tradeoffs and the hotpath63answer — for review. **Do not run `/ss-tasks` until the maintainer approves it.** A plan visible64before execution is the contract; this is where a different approach gets chosen, cheaply.6566## Rules6768- No code yet. The plan describes the change; it does not make it.69- If planning surfaces a question that changes the spec, go back and amend `spec.md` (and70 re-confirm) rather than silently diverging.71- Honor the Trust Contract: the plan's file list *is* the lane — anything outside it must be72 named in chat, not slipped in during `/ss-implement`.
serial-studio