Write and Validate the Spec

Phase 1 left you with a backlog: units decomposed, dependencies mapped, task-comments marked ACTIVE. Every artifact so far has been cross-unit — stakeholder notes, prioritized requirements, user stories, the backlog itself. Now the work narrows. Everything from here through Phase 3 happens one unit at a time.

The first per-unit artifact is the feature spec. It turns "here is the ACTIVE unit and its stories" into a precise contract: what the feature must do, what it must not do, what the API looks like, and what counts as done. The spec is the input for architecture (next page) and — eventually — for the tests and implementation in Phase 3.

You have a backlog with the ACTIVE unit selected. Now you write the detailed specification — the document that becomes the contract for the rest of Phase 2, all of Phase 3, and for Phase 4's Ralph Loop when it builds the deferred units. This is Spec-Driven Development (SDD): write the spec first, then everything downstream follows from it.

The spec lives in docs/specs/task-comments.md — NOT in CLAUDE.md. CLAUDE.md stays focused on project-level conventions (tech stack, commands, error format, architecture constraints) and pointers to active specs. Feature specs are separate files so they can be reviewed, versioned, and eventually archived independently.

A feature spec answers five questions: What does it do? What must it NOT do? How do you know it's done? What does the API look like? What decisions are already made?

Feature spec structure

# Feature: Task Comments

## Description
2-3 sentences: what this feature does and why it matters.

## Capabilities
- MUST: [Required functionality — non-negotiable]
- SHOULD: [Important but negotiable]
- MUST NOT: [Explicit exclusions — prevent scope creep]

## Acceptance Criteria
- [ ] Specific, testable condition 1
- [ ] Specific, testable condition 2
(These become test cases in Phase 3)

## API Contract
- Endpoints affected, request/response shapes, error codes
- Error format: { error: string, details?: array }

## Scope Boundaries
- What is explicitly OUT of this unit
- "Do NOT add pagination, sorting, or filtering"

## Decisions Made
- Any technical choices already locked in
- References to relevant architecture docs

After Claude writes the initial spec, don't just review it in chat — open the file in your editor and edit it directly. Add notes, tighten vague criteria, remove things you don't want. Then tell Claude: 'I updated the spec. Please read my changes and incorporate them.'

The spec file is the source of truth, not the conversation. Anyone on your team can read it, edit it, and understand what the ACTIVE unit does — without reading through chat history. This is the file-as-contract principle in action — you will see it again in Phase 3 with the Plan-Review-Execute loop for implementation.

You have requirements/backlog.md with the ACTIVE unit selected and its user stories identified in Phase 1.

Step 1 — Generate feature spec: Ask Claude to write a detailed feature spec based on the user stories and existing codebase.

Tell Claude:

Read the user stories for the ACTIVE unit in
requirements/backlog.md and requirements/stories.md. Also read the
existing codebase to understand the current API structure.

Write a feature spec to docs/specs/task-comments.md using this structure:
- Description (what and why)
- Capabilities (MUST / SHOULD / MUST NOT)
- Acceptance Criteria (specific, testable — these become tests later)
- API Contract (affected endpoints, request/response shapes, error format)
- Scope Boundaries (what is explicitly OUT)
- Decisions Made (any technical choices locked in)

Be precise. Every acceptance criterion must be testable by a machine.

Observe: Claude produces a detailed spec. Check: Are the acceptance criteria specific enough that any developer — or any Claude session — would implement them the same way? Are scope boundaries explicit?

Step 2 (optional) — Edit and handoff: Open docs/specs/task-comments.md in your editor. Edit it directly — tighten any vague criteria, add missing edge cases, remove anything that feels like scope creep. Then tell Claude to re-read your changes. Skip this step if the spec already reads cleanly; the handoff pattern below is the point, and you can exercise it anytime a teammate edits a spec file directly.

Tell Claude:

I updated the spec in docs/specs/task-comments.md.
Please read my changes and incorporate them.
Verify that every acceptance criterion is still testable
and flag anything that became ambiguous from my edits.

Observe: Claude re-reads the spec, incorporates your edits, and flags any issues. This is the 'I updated the file' handoff in action — you edited the contract directly, and Claude adapted.

This is the document that drives the rest of Phase 2 and all of Phase 3. Every acceptance criterion becomes a test case, every scope boundary prevents over-engineering, every API contract shapes implementation.

You have a feature spec. One critical step remains before architecture design: validation. Catching gaps now — while they are five-minute spec edits — prevents hours of rework in design, implementation, and testing.

This is what AIDLC calls the 'loss function' checkpoint: a systematic review that catches errors before they propagate downstream.

Here is the prompt that runs the five-dimension check against a spec:

Read docs/specs/task-comments.md and the requirements in requirements/.
Validate against these five dimensions:

1. Completeness — any acceptance criteria that aren't specific and testable?
2. Consistency — any contradictions or inconsistent terminology?
3. Feasibility — anything conflicting with our tech stack (Express.js, JSON file storage)?
4. Traceability — any spec item without a clear user story?
5. Risk — rate each capability as low/medium/high complexity

Report findings. Fix any issues you find in the spec.

You could paste this into Claude right now and get a validation report. But you will run this same check on every future spec — and Phase 4's Ralph Loop will run it on every deferred unit automatically. Rather than copy-paste it each time, package it as a skill once and invoke it with a slash command from then on.

The principle from the Extensions section applies here: if a prompt is worth running more than twice, turn it into a skill. A skill is a markdown file in .claude/skills/ that becomes a slash command. Type /validate-spec in any project that has your .claude/ directory and the five-dimension check runs automatically — no copy-pasting, no remembering the format.

.claude/skills/validate-spec/SKILL.md

---
name: validate-spec
description: Validate a feature spec against five quality dimensions: completeness, consistency, feasibility, traceability, and risk. Use before handing off to architecture design.
disable-model-invocation: true
argument-hint: [path to spec file]
---

Validate the spec at $ARGUMENTS against these five dimensions:

1. Completeness — are all acceptance criteria specific and testable? No 'TBD' placeholders.
2. Consistency — do any requirements contradict each other? Is terminology consistent?
3. Feasibility — does anything conflict with our tech stack (Express.js, JSON file storage)?
4. Traceability — does every spec item link to a user story? No orphan requirements.
5. Risk — rate each capability as low/medium/high complexity.

For each dimension:
- PASS if no issues found
- FAIL with specific issue and line/section if problems exist

Fix any FAIL issues in the spec file directly. Report what you changed.

You are in the taskflow folder with the ACTIVE unit's spec written. Create the skill directly from the shell, then start a fresh session and run it to validate the spec.

Step 1 — Exit Claude: A skill is just a file on disk. You do not need Claude to write it — drop to the shell and create it directly. Exit the session first.

Run in terminal:

1
/exit

Step 2 — Write the skill file: Create .claude/skills/validate-spec/SKILL.md with the frontmatter and body below. The $ARGUMENTS placeholder is replaced at runtime with whatever you pass after /validate-spec.

Run in terminal:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
mkdir -p .claude/skills/validate-spec && cat > .claude/skills/validate-spec/SKILL.md << 'EOF'
---
name: validate-spec
description: Validate a feature spec against five quality dimensions (completeness, consistency, feasibility, traceability, risk) before architecture design.
disable-model-invocation: true
argument-hint: [path to spec file]
---

Read the spec at $ARGUMENTS and the requirements in requirements/.
Validate against these five dimensions:

1. Completeness — any acceptance criteria that aren't specific and testable? No 'TBD' placeholders.
2. Consistency — any contradictions or inconsistent terminology?
3. Feasibility — anything conflicting with the tech stack (Express.js, JSON file storage)?
4. Traceability — any spec item without a clear user story? No orphan requirements.
5. Risk — rate each capability as low/medium/high complexity.

For each dimension:
- PASS if no issues found
- FAIL with the specific issue and line/section if problems exist

Fix any FAIL issues in the spec file directly. Report what you changed.
EOF

Observe: The skill file now exists on disk. Nothing about this required an LLM — that is the point. Skills are plain text contracts that Claude reads when you invoke them.

Step 3 — Start a new session: Skills are discovered at session start, so the next claude invocation will pick it up.

Run in terminal:

1
claude

Step 4 — Run the skill to validate the spec: Invoke the skill against the spec you just wrote. This is the validation gate the earlier section described — you just run it through the skill instead of pasting the prompt.

Tell Claude:

/validate-spec docs/specs/task-comments.md

Observe: Claude runs the five-dimension check scoped to the spec file you passed. The $ARGUMENTS placeholder gets replaced with docs/specs/task-comments.md. Expect 1-3 findings — a vague acceptance criterion, a missing error code, an unstated constraint. If it finds issues, tell Claude to fix them in the spec file directly.