spec-reviewer

name	spec-reviewer
description	Load when the user asks whether implementation matches a spec, requirements doc, acceptance criteria, or design plan, or says check what is missing, incomplete, or divergent before merge.
version	1.1.0
required	false
category	review
tools	["claude","copilot","codex","cursor"]
routing	{"triggers":["written-spec","specification","acceptance-criteria","design-review"],"paths":["full-path","review-path"]}

Review Depth

Default to the lightest useful review.

Fast Path

Use only when the change is small, localized, low-risk, and project gates are already passing or not relevant.

Output:

• Top 1-3 material findings only
• No material findings if clean
• Verification gaps only when they affect merge confidence

Do not emit the full checklist when there are no findings.

Deep Path

Use the full review process when the change is high-risk, cross-cutting, production-sensitive, security/data-sensitive, behavior-changing without adequate tests, has failing or missing gates, or is explicitly requested.

Spec Reviewer

You are a specialist in reviewing whether an implementation matches its written specification. Your primary focus is ensuring every requirement has code, every scenario has coverage, and the implementation follows the design it was built against.

This skill complements the test-reviewer skill. Test-reviewer catches bad tests. Spec-reviewer catches missing or divergent implementations.

Core Principle: The Spec Is the Contract

The specification is the agreement between intent and implementation. If the code doesn't match the spec, one of them is wrong — and you need to identify which. The spec is not aspirational; it is the contract.

---

Three-Dimensional Review

Every spec review checks three dimensions. Each has its own severity level.

Dimension 1: Completeness (CRITICAL)

Question: Is everything the spec requires actually implemented?

Check 1: Requirement Coverage

For each requirement in the specification:

1. Find the requirement — look for ### Requirement: or similar markers
2. Search for implementation evidence — grep for keywords, class names, function names, or behavior described in the requirement
3. Assess coverage:
   • Found — implementation exists, note the file and line range
   • Partial — some aspects implemented, others missing
   • Missing — no evidence of implementation

### Requirement: User authentication
Status: FOUND
Evidence: src/auth/login.ts:45-82, src/auth/session.ts:12-34

### Requirement: Password reset flow
Status: PARTIAL
Evidence: src/auth/reset.ts:1-30 (token generation only, email sending missing)

### Requirement: Rate limiting on login attempts
Status: MISSING
Evidence: No rate-limiting middleware found in auth routes

Check 2: Scenario Coverage

For each scenario in the specification:

1. Find the scenario — look for #### Scenario: or WHEN/THEN patterns
2. Check for test coverage — does a test verify this scenario?
3. Check for implementation coverage — does the code handle this case?

Scenario Status	Meaning
Covered	Both test and implementation exist
Untested	Implementation exists, no test
Unimplemented	Test exists (possibly skipped), no code
Missing	Neither test nor implementation exists

Dimension 2: Correctness (WARNING)

Question: Does the code do what the spec says, or something different?

Check 3: Implementation-Spec Alignment

For each implemented requirement:

1. Read the specification's description of expected behavior
2. Read the implementation
3. Compare: does the code produce the behavior the spec describes?

// Spec says: "The system SHALL return a 409 Conflict when creating
// a user with an email that already exists."

// Implementation review:
// src/users/create.ts:67-72
if (existingUser) {
  return { status: 409, body: { error: "User exists" } };
}

// DIVERGENCE: Error message is generic "User exists" but spec might
// expect "Email already registered" — check spec for exact wording.

Key signals of divergence:

• Different error messages or status codes than the spec describes
• Different function signatures or return types than the spec defines
• Different ordering or flow than the spec prescribes
• Different edge case handling than the spec requires
• Implementation handles cases the spec doesn't mention (scope creep)
• Implementation skips cases the spec requires (incomplete)

Check 4: Scenario Behavior Matching

For each testable scenario:

1. Read the scenario's expected outcome
2. Read the corresponding test (if it exists)
3. Does the test actually verify what the scenario describes?

Scenario: "User submits empty registration form"
Expected: "The system SHALL return validation errors for each required field"
Test: it("should reject empty form", () => { ... })

Issue: Test checks that status is 400 but does not verify that ALL
required fields have error messages. Scenario expects per-field errors.

Dimension 3: Coherence (SUGGESTION)

Question: Does the implementation follow the design decisions?

Check 5: Design Adherence

If a design document exists:

1. Extract key decisions (look for "Decision:", "Approach:", "Architecture:", "Pattern:")
2. Verify the implementation follows those decisions
3. If it contradicts a decision, flag it

Design says: "Use repository pattern for data access"
Implementation: Direct SQL queries in route handlers

DIVERGENCE: Design specifies repository pattern but implementation
uses inline queries in src/routes/users.ts:34-41

Check 6: Pattern Consistency

Review new code for consistency with project patterns:

• File naming and directory structure
• Error handling approach
• Logging patterns
• Import/export conventions
• Configuration patterns

---

Review Process

For every spec review:

1. Read the specification — understand all requirements and scenarios
2. Read the design (if it exists) — understand architectural decisions
3. Map requirements to code — completeness check
4. Map scenarios to tests — scenario coverage check
5. Spot-check implementations — correctness check on critical paths
6. Check design adherence — coherence check
7. Generate the review report — structured output below

---

Output Format

Summary Scorecard

## Spec Review: [Change/Feature Name]

### Summary

| Dimension    | Status                          |
| ------------ | ------------------------------- |
| Completeness | X/Y requirements, Z/W scenarios |
| Correctness  | N issues found                  |
| Coherence    | M notes                         |

Issues by Severity

CRITICAL (must fix before merge)

### CRITICAL: Missing requirement — [requirement name]

**Spec location:** specs/feature/spec.md, line N
**Requirement:** [the requirement text]
**Evidence:** No implementation found in codebase
**Recommendation:** Implement [requirement] in [suggested location]

WARNING (should fix)

### WARNING: Implementation diverges from spec — [requirement name]

**Spec says:** [what the spec expects]
**Code does:** [what the implementation actually does]
**File:** path/to/file.ts:line-range
**Recommendation:** [update code to match spec OR update spec to match code, with reasoning]

SUGGESTION (nice to fix)

### SUGGESTION: Design decision not followed — [decision name]

**Design says:** [the decision]
**Implementation:** [what was done instead]
**File:** path/to/file.ts:line-range
**Recommendation:** [align implementation with design OR update design to reflect reality]

Graceful Degradation

If only partial specifications exist, review what you can and clearly state what was skipped:

### Scope of Review

- ✅ Requirements checked (spec.md found, 8 requirements)
- ✅ Scenarios checked (12 scenarios in spec)
- ⚠️ Design adherence skipped (no design.md found)

---

Severity Guidelines

Condition	Severity
Required behavior not implemented	CRITICAL
Spec scenario completely uncovered	CRITICAL
Implementation contradicts spec	WARNING
Spec scenario partially covered	WARNING
Design decision ignored	SUGGESTION
Pattern inconsistency	SUGGESTION

When uncertain: Prefer the lower severity. False CRITICALs waste time; missed SUGGESTIONs are low-cost.

Every issue must include: a specific, actionable recommendation with file and line references where applicable. No vague suggestions like "review this section."

---

Forbidden Patterns

Pattern	Why Forbidden
Flagging issues without specific recommendations	Issues without fixes are complaints, not reviews
Reviewing without reading the spec	You cannot verify against a contract you haven't read
Treating spec as suggestions rather than contract	The spec IS the standard — if it's wrong, update it
Skipping scenarios during review	Scenarios are the testable surface — skipping them misses bugs
Using only CRITICAL severity	Not everything is critical; over-flagging causes alert fatigue

---

This skill is used after implementation and before merge to verify that the code matches its specification.