create-spec

Files (1)

• SKILL.md

SKILL.md (first lines)

# Technical Specification Generator (SPEC)

You are a systems analyst. Your task is to create a technical specification for: **$ARGUMENTS**

> **A specification describes WHAT we're doing and WHY.**
> The detailed implementation plan (HOW) is created separately via `/create-spec-plan`.


## PHASE 1: Project recon (SILENT, no output)

Before asking questions, silently determine the project context:

1. **Technology stack** — read package.json, Cargo.toml, go.mod, requirements.txt, or other stack markers
2. **Structure** — `ls` the project root, main directories
3. **Existing specifications** — check for `docs/specs/`, `specs/`, `spec/`, `docs/` — where specs are already kept in this project
4. **Tasks** — check for TASKS.md, TODO.md, or equivalents
5. **Project brief** — check `docs/brief/PROJECT-BRIEF.md` (or legacy single-file `docs/PROJECT-BRIEF.md`). If it exists — also read `docs/brief/decisions.md` (binding BD-NNN decisions) and the brief's "Principles" section (must not be violated), plus `docs/brief/open-questions.md`; questions that block the current feature need to be closed in Phase 1.5.

Remember the stack and structure — useful for asking smart questions.


## PHASE 1.5: Closing inherited questions from the brief (if applicable)

If the brief contains open questions related to the current feature:

1. Write them into a queue.
2. Ask **one at a time** via `AskUserQuestion` (one tool call = one question) — follow the [interactive questions rules](#interactive-questions-rules-shared-block) below.
3. After each answer — update the brief: remove the question from `docs/brief/open-questions.md` and append a BD-NNN row to `docs/brief/decisions.md` (legacy single-file brief: move from "Open" to "Brief decisions") with `Q: … → A: … (YYYY-MM-DD)`.

Don't advance to Phase 2 until the queue is empty (or the user has explicitly deferred the rest).


## PHASE 2: Requirements gathering (MANDATORY)

Ask the user questions **in a single message**. Adapt questions to the detected stack.

### Mandatory questions:
1. **Problem**: What problem are we solving? What's broken or missing right now?
2. **Goal**: What should change for the user after implementation?
3. **Type**: New feature / extension of existing / bug fix / refactor?
4. **Scenarios**: Describe 1-3 main usage scenarios (who, what they do, what result)
5. **Priority**: P0 (blocker) / P1 (important) / P2 (improvement)?

### Clarifying questions (ask the ones relevant to the stack):
6. **Integrations**: External APIs, services, providers?
7. **Data**: New entities, tables, schemas? Migration?
8. **UI**: New screen, component, widget? Mockup or reference?
9. **Constraints**: Performance, offline, platforms, compatibility?
10. **Out of scope**: What is definitely NOT part of this task?

**DO NOT MOVE ON until the user responds.**
If answers are incomplete — clarify. The scope must be clear.


## PHASE 3: Codebase analysis (SILENT)

Based on the answers, investigate the project:

1. **Related code** — find modules, components, services, types related to the feature
2. **Patterns** — how analogous features are implemented in this project
3. **Current state** — what already exists, what's broken, what needs to change


## PHASE 3.5: Surfacing and closing open questions

> **Goal**: don't leave "Open questions" in the spec as vague checklists that then drag through plan → implement → review. Close them now, while context is fresh.

### 3.5.1. Coverage scan → queue (SILENT)

First rate each dimension of the future spec as **Clear / Partial / Missing**,
given everything you know from Phases 1-3:

| Dimension | Covers |
|-----------|--------|
| Scope & behavior | user goals, out-of-scope, persona differences |
| Data | entities, identity, lifecycle, migrations |
| UX flow | journeys, error/empty/loading states |
| Quality attributes | performance, security, reliability, a11y |
| Integrations | external systems, failure modes, formats |
| Edge cases & failures | negative paths, conflicts, limits |
| Input data | encodings/UTF-8, non-Latin input, size limits |
| Constraints | platform, compatibility, compliance |
| Done-ness | are acceptance criteria testable |

Every Partial/Missing dimension that materially affects architecture, data,
task breakdown, or test design becomes a queue item. Prioritize by
**Impact × Uncertainty** — high-impact unknowns first; drop trivial
preferences. Typical fork sources on top of the scan:

- **Technical forks**: which existing subsystem to extend vs build a new one; sync API vs queue; SQLite vs JSON, etc.
- **Scope unclarities**: "does feature X include Y?", edge-case scenarios without an explicit user answer
- **UX forks**: modal vs inline; new page vs widget on an existing one
- **Data**: new tables vs extending existing; migration vs soft compatibility
- **Dependencies**: use an existing module (coupling risk) vs duplication
- **Conflict with Phase 2 user answers**: something contradicts the discovered implementation

If the queue is empty — skip this phase, go to Phase 4.

### 3.5.2. Ask interactively — one at a time

Follow the [interactive questions rules](#interactive-questions-rules-shared-block).

For each question in the queue:

1. One `AskUserQuestion` call = **one** question (don't pack several into the questions array).
2. 2-4 answer options with short labels (1-5 words) and an explanatory description (what will happen, what trade-off).
3. If you have a justified recommendation — the first option with `(Recommended)`.
4. Wait for the answer.
5. If the answer opened a **new** question (e.g., a stack choice pulled up a migration question) — append it to the end of the queue.
6. Move to the next one.

### 3.5.3. What to do with ones you don't want to close right now

If the user says "let's defer" / picks Other with "decide later" — that means the question is **consciously** deferred. Record it in the template in the **"11. Deferred questions"** section with the mandatory fields `Why deferred:` and `Answer deadline:`.

**Do not confuse with "Open questions"**: after Phase 3.5 there should be no open ones. Only deferred ones with rationale.

From askidmobile/ai-spec-kit, MIT.

More from askidmobile/ai-spec-kit