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
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).
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).
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).
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.
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.
1---2name: ss-spec3description: Phase 1 of Serial Studio's spec-driven workflow: capture WHAT a feature must do and WHY, with no implementation detail. Use to start any non-trivial or multi-file feature — "spec this out", "write a spec", "start a feature", "let's spec-drive X". Produces doc/claude/specs/NNNN-slug/spec.md and gates on human approval before /ss-plan.4---56# Serial Studio — /ss-spec (phase 1 of 4)78Capture the **WHAT** and the **WHY**. No file paths, class names, signal wiring, or algorithm9choices — those belong to `/ss-plan`. A spec that leaks implementation pre-commits the design10before it has been reviewed. See [doc/claude/spec-driven.md](../../../doc/claude/spec-driven.md)11for the full workflow and the gate discipline.1213## Procedure14151. **Pick the number and slug.** The next number is `max(existing) + 1`, zero-padded to four16 digits:1718 ```bash19 ls -d doc/claude/specs/[0-9][0-9][0-9][0-9]-* 2>/dev/null \20 | sed -E 's#.*/([0-9]{4}).*#\1#' | sort -n | tail -121 ```2223 If that prints nothing, start at `0001`. Choose a short kebab-case slug from the feature24 name (`0007-canbus-filter`).25262. **Ground yourself first.** Skim the relevant `doc/claude/` sub-doc(s) for the area so the27 spec's claims about current behavior are true — but keep the spec implementation-free.28 Ground in real behavior (a report, a screenshot, a measured limit), not a hypothesis.29 Then state the problem and the one deciding constraint in a single chat sentence *before*30 drafting sections — a problem you can name is one the requirements will actually serve31 (`doc/claude/j-space.md`, verbalize-to-load).32333. **Create the directory and copy the template:**3435 ```bash36 mkdir -p doc/claude/specs/NNNN-slug37 cp doc/claude/specs/templates/spec.md doc/claude/specs/NNNN-slug/spec.md38 ```3940 Fill in the frontmatter (`spec`, `title`, `created`, `author: Alex Spataru`, `status:41 draft`).42434. **Write the spec** into every section: Problem/Motivation, Goals, Non-Goals, Requirements44 (numbered + testable), Acceptance Criteria (tied to a real check), Constraints & Invariants,45 Open Questions.46475. **Resolve ambiguity before finishing.** Where a requirement is genuinely the maintainer's48 call (scope, tier gating, UX shape), use `AskUserQuestion` with a recommendation — do not49 guess and bury the assumption. Unresolved items stay in Open Questions.5051## Gate5253Stop after writing `spec.md`. Present it for review and **do not run `/ss-plan` until the54maintainer approves it** (set `status: approved`). The spec is the contract every later phase55is measured against; an unreviewed spec poisons the plan and the build.5657## Rules5859- WHAT/WHY only. The first reviewer should be able to read it without seeing the codebase.60- Acceptance criteria must be verifiable — prefer ones that map to `pytest`, `tests/scripts/`,61 `--benchmark-hotpath`, or a concrete in-app observation.62- This file is the only thing you create. No code, no plan, no scaffolding yet.
serial-studio