Skip to main content
Transforms a conversation, idea, or raw description into a complete, structured technical specification saved to spec-[slug].md in the current working directory. Covers the full spec surface: problem statement, goals, non-goals, API/interface design, data model, failure modes, and measurable success criteria. Use this skill when the user asks to write a spec, technical spec, design doc, RFC, API design, or implementation spec — or says “spec this out”, “turn this into a spec”, or “document this”.

​
Invocation

/spec [feature or system to specify]

​
Workflow

1

Extract the core idea

Identify what system, feature, or API is being specified from the conversation or argument. If the input is a long discussion thread, extract the core intent rather than summarising every message.
2

Ask clarifying questions if needed

If the problem, scale, or constraints are unclear, ask at most 3 targeted questions before proceeding. Prefer stating assumptions and moving forward over interrogating the user.
If you have enough to write a reasonable Problem Statement and Goals, start there. You can resolve remaining open questions in the Open Questions section.
3

Draft problem statement and goals

Write the Problem Statement (3–6 sentences of prose — no bullet points) and Goals / Non-Goals sections first. Do not proceed to design until these are agreed.Goals must be concrete and measurable — not “improve performance” but “p99 latency < 500ms”. Non-Goals must have at least 2 items. They define the boundary of the work.
4

Design the API / interface surface

Specify the public interface: functions, endpoints, decorators, or CLI commands. Use code blocks for every interface definition.
def process_batch(
    items: list[Item],
    *,
    timeout_ms: int = 5000,
    max_retries: int = 3,
) -> BatchResult: ...
5

Design the data model

Define key data structures, schemas, and artifact shapes. Use code blocks. Never describe a data model in prose when a type definition or schema is clearer.
6

Identify failure modes

Enumerate what can go wrong and how each is mitigated. The Failure Modes section is mandatory — a spec without it is incomplete. Format as a table:
FailureProbabilityImpactMitigation
Worker crash mid-batchMediumHighCheckpoint after each item; resume from last checkpoint
7

Write the full spec

Assemble all sections in the standard output format from FORMAT.md. Print the full spec to the conversation and save it to spec-[slug].md in the current working directory.

​
Self-review checklist

Before delivering, verify all of the following:
  • Problem Statement is 3–6 sentences of prose — no bullet points
  • Goals are concrete and measurable (numbers, percentages, latency targets)
  • Non-Goals section present with at least 2 items
  • API/Interface section contains actual code blocks — not prose descriptions of code
  • Data Model section contains actual code blocks — not prose descriptions
  • Failure Modes table present with Failure, Probability, Impact, and Mitigation columns
  • Success Metrics are measurable (numbers, percentages, latency targets)
  • Open Questions section present — even if empty, the section must appear
  • File saved as spec-[slug].md in the current working directory
  • No section contains “TBD” — unknowns go in Open Questions instead

​
Golden rules

Always write the Problem Statement and Goals before designing anything. A design without a problem statement will be wrong.
Never skip the Non-Goals section. It defines the boundary of the work and is as important as Goals.
A spec with no Failure Modes table is incomplete. Happy-path-only specs fail in production.
Without measurable criteria there is no definition of done. Vague metrics such as “users are happy” are rejected — replace with numbers.
If the design is unknown, write the open question in the Open Questions section. The spec body must contain actual designs, not placeholders.
Print to conversation AND write spec-[slug].md. Specs that exist only in the conversation are lost.
If the problem is truly ambiguous, ask — but never more than 3 at once. Prefer proceeding with stated assumptions over interrogating the user.

​
Reference files

FileContents
FORMAT.mdComplete spec template, section-by-section writing guidance, good vs bad examples, and an abbreviated example spec
DESIGN.mdHow to extract design from conversation, API-first design principle, handling ambiguity, making key decisions explicit