Ss Plan
Productivityss-planSs Plan is an Agent Skill for productivity published in the Serial-Studio/Serial-Studio repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Serial-Studio/Serial-Studio/blob/HEAD/.claude/skills/ss-plan/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/ss-plan, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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.mdexists and itsstatus:isapproved. If it is stilldraft, 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-hotpathand readFrameBuilder/CircularBuffer/FrameReader/Dashboardin full per the CLAUDE.md rule. - For a new driver, follow
ss-new-driverand grep an existingBusTypevalue to find every registration touch-point.
- architecture.md — index into the per-subsystem
-
Copy the template and write the plan:
cp doc/claude/specs/templates/plan.md doc/claude/specs/NNNN-slug/plan.mdFill 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 —
pytestfiles,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.