Spec Review

Validate that the implementation conforms to its spec-kit artifacts.

[!IMPORTANT] Consult REFERENCE.md in this skill directory for the expected output format and level of detail.

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Argument Parsing

Parse $ARGUMENTS for:

• •Path: Optional path to focus the review (default: entire repo)
• •Spec folder name: If provided (e.g., 001-user-auth), use that spec instead of deriving from branch
• •--create-beads: Create beads for findings (default: report only)

Outline

1. Validate Prerequisites

Run prerequisite checks:

./.specify/scripts/bash/check-prerequisites.sh --json

Parse the JSON response to get FEATURE_DIR.

Then verify beads is initialized:

bd info

[!CAUTION] ERROR if beads is not initialized. Instruct user to run bd onboard first. ERROR if spec.md is missing. Instruct user to run /speckit.spec first.

If a spec folder name was provided in arguments, override FEATURE_DIR to specs/<folder-name>.

2. Load Context Documents

Read from FEATURE_DIR:

• •Required: spec.md
• •Optional: plan.md, .specify/memory/constitution.md

Note which optional documents are present — validation criteria are gated on document availability.

3. Read Implementation Code

If a path argument was provided, scope to that path. Otherwise, read the project's source code (excluding vendor, node_modules, build output, and other generated directories).

Build a working understanding of the implementation: files, modules, public APIs, imports, configuration, and test files.

4. Validation

Run each applicable validation section below. Skip sections whose required documents are not present.

Status Definitions (use consistently throughout):

• •✅ PASS: Fully implemented as specified
• •⚠️ PARTIAL: Implemented but with minor deviations from spec
• •❌ GAP: Missing or significantly divergent

Evidence Format: file:line only (or — if no specific location). Detailed explanations go in Findings section.

Table Output: Only show non-passing items (⚠️ PARTIAL and ❌ GAP). End each table with "N passed, not shown."

4.1 Specification Conformance (requires spec.md)

Evaluate ALL functional requirements and acceptance criteria from spec.md.

Functional Requirements: Scan spec.md for all FR-xxx identifiers or numbered requirements. For each:

• •Compare the implementation against the requirement
• •Evaluate: behavior coverage, edge case handling, constraint enforcement, API surface match
• •Record status and evidence for non-passing items

Acceptance Criteria: Scan spec.md for all user stories (USx-x format) and their scenarios. For each scenario:

• •Verify the described behavior is implemented
• •Record status and evidence for non-passing items

4.2 Architecture Consistency (requires plan.md)

Extract ALL architectural declarations from plan.md. This includes:

• •Module/package structure
• •Naming conventions
• •Technology choices (frameworks, libraries, databases)
• •Configuration patterns
• •External integrations

Evaluate each declaration:

• •Does the code use the declared frameworks/libraries? (check imports, config files, dependency manifests)
• •Is code organized per the declared directory structure?
• •Do external service integrations match the plan?
• •Does the data layer match (database driver, ORM, migration tool)?

4.3 Constitution Alignment (requires constitution.md)

For EACH numbered principle in constitution.md, create a table row and evaluate whether the code adheres to it. Common principle categories:

• •API design standards
• •Security requirements
• •Infrastructure-as-code requirements
• •Testing standards
• •Code organization conventions

Only flag cases where code clearly contradicts a stated principle. Do not flag ambiguous or inapplicable cases.

5. Deduplication

Before creating beads, check for existing ones:

• •Run bd list --status=open to see all open issues
• •Compare findings against existing bead titles and descriptions
• •Skip creating beads for issues that already have matching open beads

6. Report Format (Mandatory)

You MUST produce a report following the exact structure shown in REFERENCE.md. This format is required for every review—do not deviate.

Key rules:

• •Only show non-passing items (⚠️ PARTIAL, ❌ GAP) in validation tables—end each with "N passed, not shown."
• •Evidence column is just file:line (or —)—detailed explanations go in Findings
• •Use H3 headers for Findings section (see REFERENCE.md for format)
• •No Summary table—Findings section already lists issues
• •Skip sections (4.2, 4.3) if their required documents are not present
• •Include Findings section only if there are non-passing items
• •End with "To create beads..." footer unless --create-beads was used

7. Bead Creation (--create-beads mode)

When --create-beads is specified, create beads for each finding:

bd create --type=bug --priority=<1-3> \
  --title="Spec: <issue>" \
  --description="**Source**: <spec.md|plan.md|constitution.md>
**Violated**: <quote from source>
**Code**: <file:line>
<explanation>"

Priority mapping:

• •Missing core behavior from spec: P1
• •Architecture divergence from plan: P2
• •Constitution violations: P2

After creating beads, append to the report:

## Beads Created

- <bead-id>: "<title>"
- ...

Omit the "To create beads..." footer when beads have been created.

Error Handling

• •If bd commands fail, report the error and continue with remaining findings
• •If spec.md cannot be read, abort (it is the only hard requirement)
• •Missing optional documents skip their corresponding validation sections silently

Design Principles

• •Spec-aware: This command reads and understands spec-kit artifacts, unlike the generic review commands
• •Code-level validation: Evaluates actual code against specs, not just file existence or build output
• •Gated sections: Each validation section is gated on its required document being present
• •Non-destructive: Creates bug beads for findings, never modifies source code or spec artifacts
• •Focused scope: Validates spec conformance only — use review-code, review-tests, review-docs for generic quality
• •Stable numbering: When recommending removal of a numbered item (FR-xxx, USx-x, principles), never delete it. Mark it as "Removed" in place to preserve stable identifiers and avoid breaking cross-references