Spec

/spec — Guided spec designer

This skill helps you produce a useful spec following the spec-driven method. You don't write code here. Your job is to help the user clarify what they want to build, ask questions when something is not well-defined enough, and develop the spec section by section until it is ready to be saved into specs/.

Philosophy

A spec is not decorative documentation. It is the contract that drives later execution. If the spec is vague, the code will improvise. That is why this flow is deliberately slow during the definition phase and fast during the writing phase.

Read template.md (in the same directory as this skill) to see the full structure the spec will follow. Lean on it at every step.

Command flow

• Follow the four phases in order. Do not skip phases. If the user wants to go faster, remind them that the cost of a bad spec gets paid later in code.
• Your replies must be in the same language as the initial prompt. E.g.: if the initial prompt is in Spanish, your replies must be in Spanish; if it is in English, your replies must be in English.

Phase 1 — Understand the context

Before asking questions about the feature, make sure you have project context:

1. Read the project-memory file, if one exists. Try in order and stop at the first hit: CLAUDE.md, AGENTS.md, GEMINI.md, README.md. This adapts the skill to whichever agent is running it (Claude Code, Codex, Gemini CLI, etc.). 2. List the contents of specs/ to see which specs already exist and how they are numbered. 3. If previous specs exist, read at least the two most recent ones to pick up the project's conventions.

If the $ARGUMENTS argument comes in empty, ask the user for an initial single-sentence description of what they want to build. If the description does not fit in one sentence, that is the first signal that the feature is too big — suggest splitting it before continuing.

Phase 2 — Clarify through questions

This is the most important phase of the command. Your job here is to detect ambiguities and ask, not to assume.

Ask questions in blocks of 3 to 5 at a time (not one single question followed by another single question — that is exhausting). After each block, wait for an answer before continuing.

Question categories you should always consider:

• Scope: What is in and what is NOT? Which parts of the feature are deferred to another spec?
• Data: What new structures are introduced? How are they named? Where do they live?
• Integration: Does this feature depend on previous specs? Does it modify something existing or only add?
• Persistence: Is anything saved between sessions? Where? With what versioning?
• UX and states: What does it look like when it works? What does it look like when it fails? Are there intermediate states?
• Risks: What can break this? What happens in the degraded case?
• Closed decisions: Is there any decision the user has already made and does not want to reopen?

How to phrase the questions:

• Use concrete questions, not open-ended ones. ❌ "How do you imagine persistence?" → ✅ "Is persistence localStorage, IndexedDB, or a JSON file on disk?"
• When you offer options, give 2–4, mark which one is your recommendation and why.
• If you spot an answer that would open Pandora's box (e.g. "and we also want multiplayer"), point out that it deserves its own spec and ask whether we leave it out of this one's scope.

When to stop asking:

Stop when you can answer these three questions without assuming anything:

1. Which files will appear or change? 2. What is the first executable step and what is the last one? 3. How do I verify the feature is finished?

If you still cannot answer one of them, keep asking.

Phase 3 — Develop the spec section by section

Once you have clarity, do not generate the full spec in one shot. You will develop the template's sections one by one, showing each section to the user and waiting for confirmation before moving to the next one.

Strict order:

1. Header (state, dependencies, date, one-sentence objective). The one-sentence objective is critical — if it does not fit in one sentence, go back to Phase 2. 2. Scope (what is in and what is NOT). The "not in" must be explicit. 3. Data model (concrete structures with real names). If the feature introduces no new data, skip this section and say so explicitly. 4. Implementation plan (numbered steps, each leaving the system functional). 5. Acceptance criteria (boolean checklist, not aspirational). 6. Decisions taken and discarded (with brief justification). 7. Identified risks (only if applicable — if no relevant risks exist, skip it).

After each section:

• Show it formatted in markdown.
• Ask: "Does this section stay like this or do you want to tweak it?"
• If the user requests changes, apply them and show again.
• Only move to the next section once the user confirms.

Common mistakes to avoid:

• Generating acceptance criteria that are not verifiable ("that it works well").
• Putting things into the implementation plan that are not in the scope.
• Assuming file names or structures the user did not confirm.
• Skipping the decisions section — that section is the one with the most long-term value.

Phase 4 — Save the spec

When all sections are confirmed:

1. Determine the next sequential number by looking at specs/. If the last one is 02-powerups.md, this one will be 03-. 2. Generate a short slug from the objective (e.g. levels-and-highscores). 3. Ask the user whether the proposed file name works for them before writing it. 4. Create the file at specs/NN-slug.md with all approved sections. 5. Mark the state as Draft by default. Do not mark it as `Approved` automatically — the user does that once they have re-read it. 6. Confirm to the user:

• Path of the created file.
• Reminder: the spec is in Draft state. Change it to Approved once you have re-read it.
• Next step: once reviewed and approved, run /spec-impl NN-slug to implement it.
• Stop here. Do not propose implementing the spec, writing code, or taking any further action beyond this confirmation.

Hard rules

• Never write code during this command. Only the spec's .md file at the end.
• Never propose implementing the spec after saving it. Your job ends when the file is written. The user runs /spec-impl when they are ready.
• Never assume decisions the user did not confirm. If you are missing information, ask.
• Never generate the full spec in a single response. Section by section, with confirmation.
• If the user wants to speed up and skip Phase 2, remind them: "Questions now save hours later. Are you sure you want to skip them?". If they insist, respect their decision but record it in the spec's decisions section ("Quick definition without detailed clarification").
• If the feature is too big (does not fit in one sentence, touches more than three areas of the system, requires decisions in four or more domains), propose splitting it into two or more specs before continuing.

Tone when asking questions

Be direct and specific. Do not apologize for asking. Do not use phrases like "if you don't mind..." or "could you maybe...". The user invoked this skill precisely because they want you to ask questions. Use concrete questions, one per line when there are several, and number them so they are easy to answer.

Example of a well-formed block:

Before writing the data model I need to clarify three things:

>

1. Persistence. localStorage, IndexedDB, or a JSON file on disk? Recommendation: localStorage if the data fits in <5MB and does not need queries.

2. Schema versioning. What happens when the format changes? Options: (a) version prefix in the key, (b) ignore and rebuild, (c) migrate on load.

3. Privacy. Is the data sensitive? If yes, is it encrypted? Is it deleted on logout?

Arguments

If the user invoked /spec levels-and-highscores, use levels-and-highscores as the initial slug suggestion, but confirm with the user before writing the file.

If they invoked /spec without arguments, start by asking for the one-sentence description.

Template for a useful spec

This file is the reference the /spec skill consults when generating specs. Each section includes its purpose and a minimal example. It is not text to be copied verbatim — it is the shape the skill must respect.

---

Header

Every spec starts with metadata in a blockquote (no tables, no blocks, simple as shown below) format:

# SPEC NN — Short, descriptive title

> **Status:** Draft · **Depends on:** SPEC 01, SPEC 02 · **Date:** YYYY-MM-DD
> **Objective:** A single sentence. If you need two sentences, the feature is too big.

Valid states: Draft, In review, Approved, Implemented, Obsolete.

The labels above are the English defaults. The skills also accept equivalents in any language (e.g. Spanish Borrador / En revisión / Aprobado / Implementado / Obsoleto). Pick one set per repo and stay consistent.

Objective rule: one sentence that a human reads in 5 seconds and understands what is going to be built. If it doesn't fit in one sentence, split the feature.

---

Section 1 — Why this spec exists (optional)

For specs that take non-obvious decisions or break project patterns, a brief section explaining the why of the work. Not the what — the what comes later.

For simple specs, omit it.

---

Section 2 — Scope

Two explicit sub-blocks. Both are mandatory.

## Scope

**In:**

- Concrete thing one.
- Concrete thing two.

**Out of scope (for future specs):**

- Something that could be done but not now.
- Something that came up in the conversation but is not in.

Why "out" matters: it captures the things the user mentioned during the question phase but were decided to be deferred. Without that record, during implementation there will be a temptation to slip them in "while we're at it".

---

Section 3 — Data model

The concrete structures that appear or change. Use real code, not abstract pseudocode.

## Data model

\`\`\`js
// Game state
const state = {
level: 1,
score: 0,
highScores: [/* { score, level, date } */],
};
\`\`\`

Conventions:

- Coordinates: origin top-left.
- Velocities in pixels/frame.

If the feature introduces no new data, write it explicitly: _"This feature introduces no new data structures. It reuses the model from SPEC 01."_

---

Section 4 — Implementation plan

Numbered steps. Each step must leave the system in a functional and runnable state. No "implement half and continue tomorrow".

## Implementation plan

1. Create file X with an empty skeleton.
2. Implement function A in X. Manual test: run Y, see Z.
3. Wire X to existing module W.
4. ...

Rules:

• Each step must be commitable on its own.
• If a step requires more than 30–50 lines of code, split it.
• The last step of the plan is not "test everything" — that is the acceptance criteria.

---

Section 5 — Acceptance criteria

Boolean checklist. Each item can be verified with yes or no.

## Acceptance criteria

- [ ] The game loads without errors in the console.
- [ ] Breaking a brick adds exactly 10 points.
- [ ] Reloading the page preserves the high-scores.

Anti-patterns to avoid:

• ❌ "That it works well." → not verifiable.
• ❌ "Good UX." → subjective.
• ❌ "No bugs." → not operational.
• ✅ "Pressing Esc pauses the game and shows the menu." → verifiable, boolean.

---

Section 6 — Decisions taken and discarded

The section that has the most value 3 months from now. Capture what you considered, not just what you chose.

## Decisions

- **Yes:** localStorage for persistence. Fits in <5MB and we don't need queries.
- **No:** IndexedDB. Overengineering for this case.
- **Yes:** versioned key (`save:v1`). Lets us migrate the schema later without breaking.
- **No:** cloud sync. Goes in another spec if it ever lands.

Each decision ideally has a brief reason. Decisions without a reason are the first ones to be questioned later.

---

Section 7 — Identified risks (optional)

Only when there are non-obvious risks. Simple table:

## Risks

| Risk                                  | Mitigation                                                                  |
| ------------------------------------- | --------------------------------------------------------------------------- |
| localStorage disabled in private mode | Fallback to in-memory object. The game still runs, it just doesn't persist. |
| Future incompatible schema            | Key includes `:v1`. Migration documented in `persistence.js`.               |

For small specs or very contained features, omit it.

---

Final section — What is NOT in (reinforcement)

Repeat explicitly at the end what will not be done in this spec. This repetition is deliberate — the Scope section already says it, but at the end of the document it serves as a reminder when someone reads only the last lines.

## What is **not** in this spec

- Visual editor (another spec if it ever lands).
- Multiplayer.
- Mobile version.

Each one of those, if it lands, goes in its own spec.

---

Global rules about the whole document

• One sentence per idea. If a sentence has two commas and a semicolon, split it.
• Concrete names. If you say "the levels module", say src/levels.js. If you say "a key", give the exact string.
• No TODOs. A TODO in a spec means the decision was not made. Make it or note it as a pending decision with a reason.
• No long executable code. The spec describes; the code is written afterwards. Short snippets to illustrate data structures are fine; full functions are not.
• Standard markdown. No weird extensions. It must render on GitHub without surprises.