Ss spec new

Spec New

Draft a language-agnostic service/system specification — the kind a second team could re-implement from scratch in a different language.

When to use this skill

Use this when the artifact needs to:

• Define a contract that multiple implementations could conform to
• Survive porting (no language/framework details bleed into normative text)
• Make conformance auditable (reviewers can answer "does this implementation comply?" point by point)

If the user just wants a design doc, ADR, or PRD, suggest creating a simpler context document or PRD instead — those have lower ceremony.

The shape of a good spec

Symphony's SPEC.md is the reference. The 10 sections below are the simplified core. Drop sections that don't apply (e.g., omit the state-machine section for stateless components), but keep their order — readers learn the system top-down.

1. Header — title, status (Draft v1, Stable v2), one-sentence purpose
2. Normative language — RFC 2119 boilerplate + Implementation-defined
3. Problem statement & scope boundaries — what it solves; what's explicitly not its job
4. Goals / Non-goals — parallel bulleted lists
5. System overview — components + abstraction layers
6. Domain model — entities, fields, types, normalization rules
7. Configuration contract — schema, defaults, validation, dynamic reload
8. State machine & lifecycle — states, transition triggers (skip if stateless)
9. Failure model — failure classes → recovery behavior
10. Reference algorithms — language-agnostic pseudocode for non-obvious flows
11. Conformance checklist — REQUIRED vs RECOMMENDED, split by extension

Optional appendix: extensions (HTTP API, alternative transports, etc.). Each extension owns its own top-level config key and conformance section.

Procedure

Phase 1 — Decide if a spec is the right artifact

Before writing anything, confirm with the user:

• Will multiple teams or implementations need to conform to this?
• Is the system stable enough that an RFC-style document won't be obsolete in a week?
• Does someone need to audit conformance later?

If "no" to all three, recommend a lighter format (PRD, ADR, design doc) and stop.

Phase 2 — Gather raw material

Before drafting, extract from the user (or existing code/docs):

• Purpose: one sentence. "X is a Y that does Z."
• Boundaries: what's in scope, what's out. Symphony's example: "scheduler/runner and tracker reader; ticket writes are out of scope".
• Components: list the major moving parts and what each owns.
• External dependencies: trackers, agents, filesystems, APIs.
• Domain entities: nouns the system reasons about (Issue, Workspace, RunAttempt, etc.).
• Configuration surface: what knobs operators turn.
• State machine: if there's stateful orchestration, list states + transition triggers.
• Failure modes: ways things go wrong and how the system recovers.

If the user can't answer one of these, that section either gets omitted or marked Implementation-defined.

Phase 3 — Draft from the template

Copy references/TEMPLATE.md to the working directory (default name SPEC.md) and fill it in section by section. The template has comments <!-- ... --> explaining each section's intent — strip them once filled.

Phase 4 — Apply the rules

Walk the draft against the rules below before showing it to the user.

---

Writing rules

These are the rules that make Symphony's spec sharp. Apply them aggressively.

Use RFC 2119 keywords correctly

• MUST / MUST NOT — absolute requirement; non-conformant if violated
• SHOULD / SHOULD NOT — strong recommendation; valid reasons to deviate exist but must be understood
• MAY / OPTIONAL — purely permissive; either choice conforms

Don't use these words casually. If you write "the system MUST log errors", that becomes a conformance test. If logging is just a good idea, write "SHOULD" or rephrase.

Use "Implementation-defined" deliberately

When a real choice exists but you don't want to mandate one, write Implementation-defined and require the implementation to document its choice. Symphony does this for approval policy, sandboxing, and user-input handling. This keeps the spec portable without leaving behavior undefined.

Make scope boundaries explicit

Every spec needs a "what this is NOT" paragraph. Symphony's:

Symphony is a scheduler/runner and tracker reader. Ticket writes are typically performed by the coding agent.

This single sentence prevents endless scope-creep arguments later.

Every entity gets a field schema

For each domain entity, list fields with:

• name
• type (string, integer, list of strings, timestamp or null)
• nullability/optionality
• normalization rule (e.g., "labels normalized to lowercase")

If a field is derived, say from where (e.g., "workspace_key derived from issue.identifier by replacing [^A-Za-z0-9._-] with _").

Every config field gets: name, type, default, required-ness

- `polling.interval_ms` (integer)
  - Default: `30000`
  - Changes SHOULD be re-applied at runtime without restart.

If something is REQUIRED, say so on the field. If it has a default, give the default. If $VAR indirection is supported, mention it.

Every failure class gets a recovery behavior

Don't just list failures — pair each with what the system does. Symphony's pattern:

Tracker candidate-fetch failure: log and skip dispatch for this tick.
Reconciliation state-refresh failure: log and keep workers running.

Pseudocode is for non-obvious flows only

Reference algorithms are valuable when the order of operations matters (poll-tick sequence, retry handling, reconciliation). They are noise when the flow is "call this function, then return". Include 3–6 small pseudocode blocks max. Use text code blocks, not a real language.

Conformance checklist is the audit surface

Every MUST in the body should have a corresponding bullet in the conformance checklist. Split into:

• Core conformance — what every implementation must do
• Extension conformance — only required if the extension is implemented
• Integration profile — environment-dependent smoke tests (often skipped in CI)

If you can't write a yes/no test for a checklist item, the requirement is too vague — go fix it in the body.

Extensions are first-class but isolated

Optional features (HTTP server, alternative trackers) live in appendices. Each appendix:

• Owns a top-level config key (e.g., server.*, worker.*)
• States that core conformance does not require it
• Has its own mini-conformance section

This lets implementations stay small without making the spec lie about what's required.

---

Common mistakes to avoid

• Mixing prescription and description. The spec says what implementations must do, not what this implementation does. If you find yourself writing "the Python code uses asyncio", lift it to a normative requirement ("the runtime MUST process events concurrently") or move it to an implementation note.
• Burying requirements in prose. Numbered lists, bullets, and bold keywords make conformance auditable. Prose paragraphs hide MUSTs.
• Skipping the failure model. Specs that only describe the happy path produce implementations that disagree about error behavior. Always include Section 9.
• Letting examples become normative. If you show a JSON shape, mark it Suggested response shape: not Required response shape: unless the field set really is required.
• Versioning the spec implicitly. Put a Status: Draft v1 line at the top. When you make a breaking change, bump the version and note it.

---

Output

Default output path: SPEC.md in the user's working directory (or wherever they specify). After writing, point out:

• Which sections you filled vs. left as TODO or Implementation-defined
• The conformance checklist size — if it's under ~10 items the spec is probably too thin; if it's over 100 the spec is probably too prescriptive

Then offer to review the spec and stress-test it to find weak spots before it ships.