The 4-file spec structure (1-description, 2-analysis, 3-solution, 4-status): what belongs in each file, the required sections, and the Tracking info fields. Use when: creating, analyzing, reviewing, implementing or archiving a spec; deciding which of the four files a piece of content belongs in. Do NOT use for: general documentation formatting (use the documentation skill), the workflow around the files (use the workflows skill).
Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Spec Structure?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/ragnarwestad-spec-structure)
---
name: spec-structure
description: >-
The 4-file spec structure (1-description, 2-analysis, 3-solution,
4-status): what belongs in each file,
the required sections, and the Tracking info fields.
Use when: creating, analyzing, reviewing, implementing or archiving a
spec; deciding which of the four files a piece of content belongs in.
Do NOT use for: general documentation formatting (use the documentation
skill), the workflow around the files (use the workflows skill).
effort: medium
---
# Spec structure
## Table of contents
- [Overview](#overview)
- [File structure](#file-structure)
- [1-description](#1-description)
- [Acceptance criteria in EARS](#acceptance-criteria-in-ears)
- [2-analysis](#2-analysis)
- [3-solution](#3-solution)
- [4-status](#4-status)
- [Separation of content](#separation-of-content)
- [Templates](#templates)
---
## Overview
Four files per spec, in `specs/<NN>-slug/` (an issue key in the title is
part of the slug):
1. **1-description.md** — the problem as reported
2. **2-analysis.md** — what the investigation found
3. **3-solution.md** — the solution and its plan, test first
4. **4-status.md** — progress, updated as the work goes
Each file is created from its template, and its headings are the
structure to fill in. A fifth file, `test-run.json`, is written by
`aide-record-test-run` and read by `aide-archive-spec`; no model writes
or reads it.
The details a step needs only in some runs — the Tracking info lines,
approach marks, the lines the runner writes, the acceptance rows in a
new round — are in the aide-analyze skill's `spec-files.md` reference.
---
## File structure
### 1-description
```markdown
# [Title] - Description
## Tracking info
- **Task:** `NN-slug/`
- **Created:** `YYYY-MM-DD`
---
## Description
[The description as given; the user may add to it by hand]
## Acceptance criteria (optional)
- **AC-1:** The system SHALL ...
- **AC-2:** WHEN ..., the system SHALL ...
## Out of scope
- [what the change must not do or touch]
```
- The description is written as given, never rewritten. It holds no
code, no files to change and no estimate: those belong in the solution
- Acceptance criteria are optional: a flat bullet list, the id in bold
(`**AC-n:**`), one sentence per id in one of the five EARS patterns
below. Ids are additive: never renumbered or reused
- An `## Out of scope` section is optional, under exactly that heading:
a flat list of what the change must not do or touch. It is the
author's own; the plan review and the review after implement hold the
change to it
- Tracking info may carry `Depends on:`, `Acceptance criteria checks:`,
`Let me choose the approach:` and `Sent back to a full analysis:` lines;
the aide-analyze skill's `spec-files.md`, section "1-description: Tracking info and acceptance criteria", says what each does
#### Acceptance criteria in EARS
Each criterion is one sentence in one of the five EARS patterns (Easy
Approach to Requirements Syntax). The condition comes first, in its own
clause, so a reader knows when the criterion holds before reading what it
asks for. A criterion with no condition is the always pattern; a condition
written after SHALL follows none of the five.
- **Always:** `The <system> SHALL <response>` — "The status file SHALL
carry one row per AC-n id."
- **Event:** `WHEN <trigger>, the <system> SHALL <response>` — "WHEN a step
ends, the runner SHALL write its result into the status file."
- **State:** `WHILE <state>, the <system> SHALL <response>` — "WHILE a job
runs on a spec, the specs list SHALL lock that spec's Run button."
- **Unwanted behaviour:**
`IF <condition>, THEN the <system> SHALL <response>` — "IF origin
refuses the push, THEN the runner SHALL keep the commit on the spec's
branch."
- **Optional feature:** `WHERE <feature>, the <system> SHALL <response>` —
"WHERE a project has a test command, /aide-implement SHALL run it before the commit."
`<system>` is whatever the criterion is about — a script, a skill, a page.
The keywords are written in capitals, as SHALL is.
---
### 2-analysis
What the investigation found: how it was done, the affected files with
`file:line`, the code, the test coverage. No solution, complexity grade,
estimate or risk: those judge the solution, and belong in 3-solution.md.
---
### 3-solution
Scope (files, complexity, estimate), Approaches with the recommended one
under its own `### Recommended: Approach X` heading, the recommended
solution with its Parts, Behavior delta, Acceptance criteria as
given/when/then scenarios, Risk analysis, the implementation plan
(RED, GREEN, VERIFY) and Testing.
- The recommended approach IS the spec: every section below it describes
that approach, and `/aide-implement` builds the plan it finds
- Each approach is a bold lead, `**Approach A: [Name] (recommended).**`,
never a heading; on a spec whose `Let me choose the approach:` line
says `yes`, every lead carries one of three marks
(the aide-analyze skill's `spec-files.md`, section "3-solution: approaches, parts and tests")
- `### Where the tests sit` names, one line per place, the public
interface where the behaviour is observed, its test file and the rules
tested there; `/aide-implement` writes its tests there
- Manual testing is a note, not a checklist: what no test covers, and why
- A small spec may have a short analysis instead (the aide-analyze skill's `spec-files.md`, section "A short analysis"): `3-solution.md` holds the grade, the two
counts, a `## Short analysis` sentence, Scope and Testing, with no plan
and no plan review
---
### 4-status
Phase tables matching 3-solution.md's plan, one row per task, the Status
cell a symbol from the file's own Notation (`⬜`, `🔄`, `✅`).
A short analysis has the template's four phase tables with one row each,
and no `## Plan review` section.
- **The runner writes these lines; never edit them:** `Workflow steps
completed:`, `Total progress:`, and each phase's `Repo`/`Model`/
`Result`/`Time spent`/`Cost` record in that phase's own file
- **No skill ever ticks a row under `## Acceptance criteria`**, and none
writes `Not verified` or `Failed`: those are the user's judgment. The
section has one row per `AC-n`, and archiving waits until every row is
ticked. A new round on a held-back or reopened spec has its own rules
(the aide-analyze skill's `spec-files.md`, section "4-status: Acceptance criteria")
---
## Separation of content
| Content | Location |
|----------------------------------------------------------------|------------------|
| Problem description | 1-description.md |
| Acceptance criteria — source (AC-n, optional) | 1-description.md |
| Out of scope — what the change must not do or touch (optional) | 1-description.md |
| Metadata | 1-description.md |
| Mapping/findings | 2-analysis.md |
| Scope (files, estimate) | 3-solution.md |
| Complexity analysis | 3-solution.md |
| Risk analysis | 3-solution.md |
| Approaches | 3-solution.md |
| Behavior delta | 3-solution.md |
| Acceptance criteria — testable scenarios | 3-solution.md |
| Before/after examples | 3-solution.md |
| Implementation plan | 3-solution.md |
| Testing strategy | 3-solution.md |
| Progress | 4-status.md |
| Acceptance criteria — tick checklist (AC-tagged, optional) | 4-status.md |
---
## Templates
The create step makes the four files from their templates; the analyze
step fills in the analysis, the solution and the status. Both run on the
board, queued with `aide create` and `aide analyze` or from the
dashboard.
**Spec files are always produced by a step on the board — never by
hand-writing or reimplementing the pattern directly with
Read/Write/Bash, even when the exact structure is already known.** A
spec created that way carries none of the commits, review or convention
the step provides, and looks identical to one that did.
Where `aide-install-spec-hook` has been run, a commit touching a spec's
files is rejected unless its message follows the
`Run /aide-<step> for <spec-folder>` convention; a hand-edit to an
existing `1-description.md` is the one exception.