Serial Studio — /ss-spec (phase 1 of 4)

Capture the WHAT and the WHY. No file paths, class names, signal wiring, or algorithm choices — those belong to /ss-plan. A spec that leaks implementation pre-commits the design before it has been reviewed. See doc/claude/spec-driven.md for the full workflow and the gate discipline.

Procedure

1. Pick the number and slug. The next number is max(existing) + 1, zero-padded to four digits:

   ls -d doc/claude/specs/[0-9][0-9][0-9][0-9]-* 2>/dev/null \
     | sed -E 's#.*/([0-9]{4}).*#\1#' | sort -n | tail -1
   

   If that prints nothing, start at 0001. Choose a short kebab-case slug from the feature name (0007-canbus-filter).

2. Ground yourself first. Skim the relevant doc/claude/ sub-doc(s) for the area so the spec's claims about current behavior are true — but keep the spec implementation-free. Ground in real behavior (a report, a screenshot, a measured limit), not a hypothesis. Then state the problem and the one deciding constraint in a single chat sentence before drafting sections — a problem you can name is one the requirements will actually serve (doc/claude/j-space.md, verbalize-to-load).

3. Create the directory and copy the template:

   mkdir -p doc/claude/specs/NNNN-slug
   cp doc/claude/specs/templates/spec.md doc/claude/specs/NNNN-slug/spec.md
   

   Fill in the frontmatter (spec, title, created, author: Alex Spataru, status: draft).

4. Write the spec into every section: Problem/Motivation, Goals, Non-Goals, Requirements (numbered + testable), Acceptance Criteria (tied to a real check), Constraints & Invariants, Open Questions.

5. Run the premise check. Name the one measurement that would kill the spec (the coupling figure that retired spec 0069, the local benchmark that would have stopped spec 0090 before eleven commits), run it time-boxed to about an hour in the scratchpad or against the running app, and record the question, the number and the verdict in the spec's Premise Check section. If the premise cannot be measured, say so there in one sentence; the maintainer decides whether to proceed on reasoning alone.

6. Resolve ambiguity before finishing. Where a requirement is genuinely the maintainer's call (scope, tier gating, UX shape), use AskUserQuestion with a recommendation — do not guess and bury the assumption. Unresolved items stay in Open Questions.

Gate

Stop after writing spec.md. Present it for review and do not run /ss-plan until the maintainer approves it (set status: approved). The spec is the contract every later phase is measured against; an unreviewed spec poisons the plan and the build.

Rules

• WHAT/WHY only. The first reviewer should be able to read it without seeing the codebase.
• Acceptance criteria must be verifiable — prefer ones that map to pytest, tests/scripts/, --benchmark-hotpath, or a concrete in-app observation.
• This file is the only thing you create. No code, no plan, no scaffolding yet.
• The Premise Check section never keeps its template text: /ss-plan refuses a spec without a recorded measurement or an explicit one-sentence "unmeasurable" verdict.
• When the maintainer asks for a commit, the spec directory goes in its own docs(spec): commit before any implementation; scripts/commit-shape.py refuses the mix.