OpenParable
Skip to content
← Back to skills

Ss Plan

Productivity
ss-plan

Ss 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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.md exists and its status: is approved. If it is still draft, stop — the spec must be approved first (/ss-spec).

Procedure

  1. Read the spec in full. Every requirement and acceptance criterion is a target the plan must hit.

  2. 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.
  3. 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.

  4. 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.

  5. 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.

  6. 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.