Review code against spec compliance - checks implementation matches spec requirements, identifies deviations, reports compliance score, triggers evolution if needed
From spexnpx claudepluginhub rhuss/cc-spex --plugin spexThis skill uses the workspace's default tool permissions.
Review code implementation against specification to ensure compliance.
Key Difference from Standard Code Review:
/speckit.implement)If no spec is specified, discover available specs:
# List all specs in the project
fd -t f "spec.md" specs/ 2>/dev/null | head -20
If specs found: Present list and ask user to select one using AskUserQuestion.
Example:
Found 2 specs in this project:
1. specs/0001-user-auth/spec.md
2. specs/0002-api-gateway/spec.md
Which spec should I review code against?
If no specs found: Inform user:
No specs found in specs/ directory.
Code review against spec requires a spec to compare against.
Use `spex:brainstorm` or `/speckit.specify` to create one first.
Read specification:
cat specs/features/[feature-name].md
Identify implementation files:
# From implementation plan or code exploration
ls -la [implementation-files]
For each functional requirement in spec:
Create compliance matrix:
Requirement 1: [Spec text]
Implementation: [file:line]
Status: ✓ Compliant | ✗ Deviation | ? Missing
Notes: [If deviation, explain]
Requirement 2: [Spec text]
...
For each error case in spec:
Error handling compliance:
Error Case 1: [From spec]
Implemented: Yes/No
Location: [file:line]
Response: [What code returns]
Spec Expected: [What spec says]
Status: ✓ / ✗
For each edge case in spec:
Identify code features NOT in spec:
For each extra feature:
Formula:
Compliance % = (Compliant Requirements / Total Requirements) × 100
Include:
Example:
Functional: 8/8 = 100%
Error Cases: 3/4 = 75%
Edge Cases: 2/3 = 67%
Non-Functional: 3/3 = 100%
Overall: 16/18 = 89%
Report structure:
# Code Review: [Feature Name]
**Spec:** specs/features/[feature].md
**Date:** YYYY-MM-DD
**Reviewer:** Claude (spex:review-code)
## Compliance Summary
**Overall Score: XX%**
- Functional Requirements: X/X (XX%)
- Error Handling: X/X (XX%)
- Edge Cases: X/X (XX%)
- Non-Functional: X/X (XX%)
## Detailed Review
### Functional Requirements
#### ✓ Requirement 1: [Spec text]
**Implementation:** src/[file]:line
**Status:** Compliant
**Notes:** Correctly implemented as specified
#### ✗ Requirement 2: [Spec text]
**Implementation:** src/[file]:line
**Status:** Deviation
**Issue:** [What differs from spec]
**Impact:** [Minor/Major]
**Recommendation:** [Update spec / Fix code]
### Error Handling
[Similar format for each error case]
### Edge Cases
[Similar format for each edge case]
### Extra Features (Not in Spec)
#### [Feature name]
**Location:** src/[file]:line
**Description:** [What it does]
**Assessment:** [Helpful / Scope creep]
**Recommendation:** [Add to spec / Remove]
## Code Quality Notes
[Secondary observations about code quality, patterns, etc.]
## Recommendations
### Critical (Must Fix)
- [ ] [Issue requiring immediate attention]
### Spec Evolution Candidates
- [ ] [Deviation that might warrant spec update]
### Optional Improvements
- [ ] [Nice-to-have suggestions]
## Conclusion
[Overall assessment]
**Next Steps:**
- If compliance < 100%: Use `spex:evolve` to reconcile deviations
- If compliance = 100%: Proceed to verification
After generating the compliance report (step 7), append or update a Code Review Guide section in the existing REVIEWERS.md. This section helps human reviewers focus their code review in 30 minutes, using the same structure as the Spec Review Guide.
If REVIEWERS.md does not exist, create it with just the Code Review Guide section.
If a Code Review Guide section already exists (from a prior implementation phase), append a new dated subsection under it rather than replacing it. Incremental PRs build up the review guide over time, and reviewers need context from all phases.
CRITICAL: This follows the exact same philosophy as the Spec Review Guide: time-boxed, question-driven, honest about uncertainty, focused on high-level questions that need human judgment. Do NOT dump compliance scores, requirement checklists, or verification results into REVIEWERS.md. Those belong in the console report (step 7).
Append the following to REVIEWERS.md:
---
## Code Review Guide (30 minutes)
> [If this is the first code review entry, use this intro:]
> This section guides a code reviewer through the implementation changes,
> focusing on high-level questions that need human judgment.
>
> [If appending to an existing code review guide, add a dated subsection:]
> ### Phase N: [brief description] (YYYY-MM-DD)
**Changed files:** [N files changed, summary of which areas: e.g. "3 source files,
2 config files, 1 script"]
### Understanding the changes (8 min)
[Point the reviewer to the 1-2 files that form the core of the change.
Explain the reading order. Frame as questions.]
- Start with `[main-file]`: [Why this is the entry point for understanding]
- Then `[second-file]`: [What it does in relation to the first]
- Question: [High-level question about the overall approach, e.g. "Does this
decomposition make sense, or would a single module be clearer?"]
### Key decisions that need your eyes (12 min)
[For each notable implementation decision, point to the code and frame as a
question. Mirror the spec review structure: decision title, brief context,
question for the reviewer. Only include decisions where human expertise or
domain knowledge could change the outcome.]
**[Decision 1 title]** (`path/to/file:line`, relates to [FR-NNN](spec.md#anchor))
[1-2 sentences on what was decided and what alternatives existed.]
- Question: [e.g. "Is this the right data structure given our expected scale?"]
**[Decision 2 title]** (`path/to/file:line`)
[Same pattern. Focus on decisions where reviewer input adds value.]
### Areas where I'm less certain (5 min)
[Be honest about implementation areas where the AI's interpretation may be
wrong, the approach may not be idiomatic, or edge cases may not be covered.
Link to relevant spec sections where the requirement was ambiguous.]
- `[file:line]` ([spec context](spec.md#anchor)): [What's uncertain and why]
- `[file:line]`: [Another area of uncertainty]
### Deviations and risks (5 min)
[List deviations from [plan.md](plan.md) and open risks, framed as questions.
If there are no deviations, state explicitly: "No deviations from
[plan.md](plan.md) were identified."]
- `[file:line]`: [What differs from [plan section](plan.md#anchor), and why.
Question: "Is this deviation acceptable?"]
- [Risk framed as question with spec reference]
Constraints for the Code Review Guide:
### Phase 2: API endpoints (2026-03-29)) rather than replacing the existing content. Each phase adds context for the reviewer.[FR-003](spec.md#fr-003), [Phase 2](plan.md#phase-2)). Never use bare backtick references without a link.Note: When deep review runs and produces fixes, re-evaluate the Code Review Guide (step 8) and update it if the fixes changed the areas of concern.
First, parse flags from the invocation arguments:
When /spex:review-code is invoked with arguments, extract flags before treating the remainder as hint text:
--no-external: disable all external tools--no-coderabbit: disable CodeRabbit only--no-copilot: disable Copilot only--external: enable all external tools--coderabbit: enable CodeRabbit only--copilot: enable Copilot onlyFlags are consumed and removed from the argument string. The remaining text (if any) becomes the hint text.
Example: /spex:review-code --no-copilot check mutation safety results in:
Resolve external tool settings (defaults + flag overrides):
# 1. Read defaults from config (all default to true if key is missing)
DEFAULT_ENABLED=$(jq -r '.external_tools.enabled // true' .specify/spex-traits.json 2>/dev/null)
DEFAULT_CODERABBIT=$(jq -r '.external_tools.coderabbit // true' .specify/spex-traits.json 2>/dev/null)
DEFAULT_COPILOT=$(jq -r '.external_tools.copilot // true' .specify/spex-traits.json 2>/dev/null)
# 2. If global "enabled" is false, individual tools default to false too
# (unless individually overridden to true in config)
Resolution logic:
1. Start with config defaults:
coderabbit = DEFAULT_ENABLED && DEFAULT_CODERABBIT
copilot = DEFAULT_ENABLED && DEFAULT_COPILOT
2. Apply flag overrides (flags always win over defaults):
--external → coderabbit = true, copilot = true
--no-external → coderabbit = false, copilot = false
--coderabbit → coderabbit = true
--no-coderabbit → coderabbit = false
--copilot → copilot = true
--no-copilot → copilot = false
3. Flags are applied in order. Later flags override earlier ones:
--external --no-copilot → coderabbit = true, copilot = false
--no-external --coderabbit → coderabbit = true, copilot = false
After spec compliance is calculated, check for the deep-review trait:
# Check if deep-review trait is enabled
jq -r '.traits["deep-review"] // false' .specify/spex-traits.json 2>/dev/null
If deep-review is enabled AND spec compliance >= 95% (or no spec exists):
{Skill: spex:deep-review} with:
superpowers if called from quality gate, manual if called directly{coderabbit: true/false, copilot: true/false} (resolved from defaults + flags)review-findings.md generationIf deep-review is enabled AND spec compliance < 95%:
If deep-review is NOT enabled:
If deviations found (standard review path, no deep-review):
spex:evolveIf 100% compliant (standard review path):
spex:verification-before-completionUse TodoWrite to track:
# Code Review: User Profile Update API
**Spec:** specs/features/user-profile-api.md
**Date:** 2025-11-10
**Reviewer:** Claude (spex:review-code)
## Compliance Summary
**Overall Score: 94%**
- Functional Requirements: 6/6 (100%)
- Error Handling: 4/4 (100%)
- Edge Cases: 3/3 (100%)
- Non-Functional: 2/3 (67%)
## Detailed Review
### Functional Requirements
#### ✓ Requirement 1: PUT endpoint accepts requests
**Implementation:** src/api/users/profile.ts:12
**Status:** Compliant
**Notes:** Route correctly configured at PUT /api/users/:id/profile
#### ✓ Requirement 2: Validates request body
**Implementation:** src/middleware/validation/profile.ts:5
**Status:** Compliant
**Notes:** All validations match spec (name 2-50, bio max 500, avatar_url URL)
[... all ✓ ...]
### Error Handling
#### ✓ Error: Missing/Invalid JWT
**Implementation:** src/middleware/auth.ts:22
**Status:** Compliant
**Spec Expected:** 401 with "Authentication required"
**Actual:** 401 with "Authentication required" ✓
[... all ✓ ...]
### Non-Functional Requirements
#### ✗ Performance: Response time < 200ms
**Status:** Not Verified
**Issue:** No performance testing implemented
**Impact:** Minor (likely meets requirement but unverified)
**Recommendation:** Add performance test or update spec to remove specific timing
### Extra Features (Not in Spec)
#### Updated timestamp in response
**Location:** src/api/users/profile.ts:45
**Description:** Adds `updated_at` timestamp to response object
**Assessment:** Helpful - standard practice for update endpoints
**Recommendation:** Add to spec (minor addition)
## Recommendations
### Spec Evolution Candidates
- [ ] Add `updated_at` field to response spec (minor addition)
- [ ] Remove specific performance timing or add perf tests
## Conclusion
Code implementation is 94% compliant with spec. All functional requirements and error handling correctly implemented. One non-functional requirement unverified and one helpful feature added beyond spec.
**Next Steps:**
Use `spex:evolve` to update spec with:
1. `updated_at` field (minor addition)
2. Clarify performance requirement (remove specific timing or add test)
After spec evolution, compliance will be 100%.
DO NOT skip checking ANY requirement. Each spec requirement must be verified against code. Not "spot checking." Not "seems fine." Every. Single. One.
DO NOT assume compliance. "It looks right" is not compliance. "I think it matches" is not compliance. Show the code location. Compare the behavior. Document the status.
DO NOT hide deviations. A deviation is not a failure; it's information. Hiding deviations breaks the feedback loop. Report every deviation, even minor ones.
DO NOT proceed with deviations unresolved. 89% compliance is NOT ready for verification. 99% compliance is NOT ready for verification. Only 100% compliance proceeds to verification.
DO NOT rationalize scope creep. "But this feature is useful!" is not justification for unspecified code. Either add it to the spec (via evolution) or remove it. Undocumented features are invisible bugs.
DO NOT conflate code quality with spec compliance. Code can be beautiful AND non-compliant. Code can be ugly AND compliant. Check both, report both, but never confuse them.
Spec compliance is primary concern.
This is not just code quality review; it's spec validation.
100% compliance is the goal.
Deviations trigger evolution.
spex:evolve to reconcileThe code and spec must tell the same story.
Evidence before assertions. Always.