spec-step-review

Review code changes against spec requirements with production-ready rigor.

Input

Before starting, you need:

• Spec file path - what was supposed to be implemented
• Progress file path (if exists) - context on what steps were completed
• Research file path (if exists) - contains objective, defined terms, findings, decisions
• Git range (optional) - defaults to uncommitted changes

Process

1. Gather Context

Read project docs:

• README.md - project overview, conventions, setup
• AGENTS.md (if exists) - agent guidelines, project rules
• Any other relevant project documentation

Read the spec docs:

• Spec file: understand what was supposed to be implemented
• Progress file: what steps are marked complete
• Research file: defined terms, architectural decisions, constraints

Get the changes to review:

# Default: uncommitted changes (staged + unstaged)
git diff HEAD

# If specific range provided:
git diff {BASE_SHA}..{HEAD_SHA}

2. Review Against Spec

For each requirement in the spec, verify the implementation:

3. Code Quality Review

Project Standards:

• Follows conventions from README/AGENTS.md?
• Matches existing codebase patterns?
• Adheres to documented project rules?

Architecture:

• Sound design decisions?
• Matches patterns in research/spec?
• Scalability considerations?
• Security concerns?

Code Quality:

• Clean separation of concerns?
• Proper error handling?
• Type safety (if applicable)?
• DRY principle followed?
• Edge cases handled?
• Linter passes with no new errors/warnings? (run per project docs)
• Tests pass? (run per project docs)

Third-Party Libraries:

• Check library docs/source for correct API usage (use Context7 or web search)
• Verify against the EXACT version in package.json/requirements.txt/etc.
• APIs change between versions - don't assume patterns from other versions work

Testing:

• Tests actually test logic (not just mocks)?
• Edge cases covered?
• Integration tests where needed?
• All tests passing?

Production Readiness:

• Breaking changes documented?
• Backward compatibility considered?
• No obvious bugs?

Side Effects:

• Search for usages of modified functions/classes/interfaces
• Check callers weren't broken by signature or behavior changes
• Verify no unintended impact on code outside the change scope

4. Categorize Issues

Critical (Must Fix)

• Bugs, security issues, data loss risks
• Broken functionality
• Spec requirements not met

Important (Should Fix)

• Architecture problems
• Missing error handling
• Test gaps
• Partial spec compliance

Minor (Nice to Have)

• Code style
• Optimization opportunities
• Documentation improvements

For each issue, include:

• File:line reference
• What's wrong
• Why it matters (link to spec if applicable)
• How to fix (if not obvious)

5. Return Result

Return exactly one of:

APPROVED

Result: APPROVED
Spec: [spec file path]
Changes: [uncommitted / git range]

### Checklist
- [x] Project docs read (README, AGENTS.md)
- [x] All spec requirements verified
- [x] Project standards followed
- [x] Architecture sound
- [x] Code quality acceptable
- [x] Third-party libs verified against exact versions
- [x] Linter passes
- [x] Tests pass
- [x] No unintended side effects on code outside scope

### Strengths
[What's well done - be specific with file:line references]

### Assessment
All spec requirements verified. Code is production-ready.

APPROVED_WITH_RECOMMENDATIONS

Use when implementation is correct but you have suggestions or observations worth discussing (edge cases not covered by spec, potential improvements, patterns that could be documented).

Result: APPROVED_WITH_RECOMMENDATIONS
Spec: [spec file path]
Changes: [uncommitted / git range]

### Checklist
- [x] Project docs read (README, AGENTS.md)
- [x] All spec requirements verified
- [x] Project standards followed
- [x] Architecture sound
- [x] Code quality acceptable
- [x] Third-party libs verified against exact versions
- [x] Linter passes
- [x] Tests pass
- [x] No unintended side effects on code outside scope

### Strengths
[What's well done - be specific with file:line references]

### Assessment
All spec requirements verified. Code is production-ready.

### Recommendations
[Suggestions, observations, edge cases not in spec - each as a bullet point]

NEEDS_FIXES

Result: NEEDS_FIXES
Spec: [spec file path]
Changes: [uncommitted / git range]

### Checklist
- [x] Project docs read (README, AGENTS.md)
- [ ] All spec requirements verified
- [x] Project standards followed
- [x] Architecture sound
- [ ] Code quality acceptable
- [x] Third-party libs verified against exact versions
- [x] Linter passes
- [ ] Tests pass
- [x] No unintended side effects on code outside scope
(mark [x] what passed, [ ] what failed or has issues)

### Issues

#### Critical (Must Fix)
[List with file:line, issue, spec reference, fix suggestion]

#### Important (Should Fix)
[List with file:line, issue, why it matters, fix suggestion]

#### Minor (Nice to Have)
[List - optional, only if noteworthy]

### Strengths
[What's well done - be specific]

### Assessment
[1-2 sentences: what needs to happen before approval]

GAP

Result: GAP
Spec: [spec file path]
Gap: [what the spec doesn't define that blocks review]
Context: [what you were trying to verify]
Recommendation: [what needs clarification in spec]

Rules

• Always read project docs (README, AGENTS.md) before reviewing
• Verify third-party library usage against docs for the exact installed version
• Review against spec FIRST - spec compliance is primary
• Verify compliance with project standards from docs
• Never say "looks good" without verifying each spec requirement
• Be specific - always include file:line references
• Categorize by actual severity - not everything is Critical
• Acknowledge strengths - don't just list problems
• Give clear verdict - APPROVED, APPROVED_WITH_RECOMMENDATIONS, or NEEDS_FIXES, never ambiguous
• If spec is unclear on what to verify, return GAP
• Don't nitpick style unless it violates project standards