OpenParable
Skip to content
← Back to skills

Ss Spec

Productivity
ss-spec

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

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-spec/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/ss-spec, 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-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. 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.