| name | review-spec |
| description | Spec adherence review skill. Evaluates implementation against functional requirements, success criteria, and acceptance scenarios from the specification. Verifies SHALL obligations, preconditions, postconditions, error paths, edge cases, data models, and API contracts. |
| argument-hint | Invoked by Review Coordinator - do not call directly |
review-spec - Spec Adherence Review Skill
This skill is invoked by the Review Coordinator as a subagent. It receives a WP identifier and spec path, discovers and reads all implementation code relevant to the WP, evaluates each functional requirement against the code, and writes structured findings to the specified output path.
Input contract (received via subagent prompt):
- Read this SKILL.md file for review instructions.
- Read the specification file to extract functional requirements.
- Discover and read all implementation code relevant to this WP.
- Evaluate each checklist item below against the discovered code.
- Write structured findings to the specified output path.
- Return a brief summary (counts of PASS/WARN/FAIL/N/A).
Constraint: Do NOT modify any source code, the WP file, or the spec file. Only write to the specified output path.
1. Identify In-Scope FRs
- Read the WP file and locate the
Spec References section.
- For each spec section referenced, identify the functional requirements (FR-XXX) that fall within those sections.
- Also read the WP's task descriptions to identify any additional FRs mentioned.
- Build a list of all FRs that this WP is responsible for implementing.
2. FR Classification Checklist
For each in-scope FR, classify implementation adherence as one of:
| Classification | Definition | Severity |
|---|
| Compliant | The FR is fully implemented exactly as specified. All obligations, preconditions, postconditions, and error paths are satisfied. | PASS |
| Partial | Some aspects of the FR are implemented but others are missing or incomplete. | FAIL |
| Deviating | The FR is implemented but behaves differently from the specification. | FAIL |
| Missing | The FR is not implemented at all. | FAIL |
Detailed verification per FR
For each FR, check all of the following:
- SHALL/SHALL NOT obligation: Is the exact obligation stated in the FR satisfied? Look for the specific behavior described.
- Preconditions enforced: Are the preconditions listed in the FR checked before the main logic executes?
- Postconditions produced: Does the code produce the outputs/state changes described as postconditions?
- Error paths handled: Are all error conditions listed in the FR (under "Error:" bullets) handled with the specified behavior?
- Edge cases covered: Are edge cases from the spec's acceptance scenarios (Section 5, Section 11.2) addressed in the implementation?
- Data model match: Do data model fields, types, and validation rules match the spec's Section 7?
- API contract match: Do API request/response schemas match the spec's Section 8?
- Error codes match: Do returned error codes match the spec's error taxonomy?
For each checklist item that fails, cite the specific evidence: the code that deviates, the spec text that defines the expected behavior, and the file/line where the deviation occurs.
3. Stub Detection
The following patterns indicate stub implementations. Classify these as Missing (not Partial):
pass as the sole statement in a function body (Python)raise NotImplementedError or raise NotImplementedError(...) (Python)... (ellipsis) as function body (Python)# TODO, # FIXME, # HACK as the only meaningful content in a function- Empty function bodies:
{} with no logic (JavaScript/TypeScript)
throw new Error("Not implemented") or similar placeholder throws- Any function body with fewer than 3 meaningful lines (excluding comments and whitespace) that does not perform the FR's specified behavior
When a stub is detected:
- Classification: Missing
- Finding severity: FAIL
- Evidence: show the stub code and the FR it should implement
4. Success Criteria Verification
For each success criterion (SC-XXX) referenced by the WP:
- Locate evidence: Look for passing tests, observable behavior, or measurable metrics that demonstrate the SC is met.
- Verify evidence is genuine: Confirm the claimed test file actually exists and its assertions are not vacuous (no
assert True, no empty test bodies, no fully mocked subjects).
- Handle unverifiable SCs: If an SC cannot be verified at this stage (e.g., requires runtime behavior not yet available), document it as N/A with justification: "Deferred verification: ".
| Evidence status | Severity |
|---|
| Genuine evidence exists | PASS |
| Evidence is fabricated (test does not exist or is vacuous) | FAIL |
| No evidence provided for a verifiable SC | FAIL |
| SC cannot be verified at this stage | N/A (with justification) |
5. Severity Rules
| Finding type | Severity | Notes |
|---|
| FR classified as Compliant | PASS | All 8 checklist items verified |
| FR classified as Partial | FAIL | List which items are missing |
| FR classified as Deviating | FAIL | Describe the deviation |
| FR classified as Missing | FAIL | Note if stub detected |
| SC-XXX with genuine evidence | PASS | |
| SC-XXX with missing/fabricated evidence | FAIL | |
| SC-XXX not verifiable at this stage | N/A | Include justification |
| FR not applicable to this WP | N/A | Include justification |
There is no WARN level for spec adherence. Spec compliance is binary: either the requirement is fully met or it is not.
Every N/A finding MUST include a justification field explaining why the item does not apply. Do NOT produce findings for checklist items that are not applicable -- record them as N/A with justification instead.
6. Output Format
Write findings to the specified output path using this exact format:
YAML Frontmatter
---
skill: review-spec
wp: <WP-id>
spec: <spec_path>
reviewed_at: <ISO 8601 timestamp>
status: completed
finding_counts:
pass: <count>
warn: 0
fail: <count>
na: <count>
files_reviewed:
- <file1>
- <file2>
---
Findings Body
# review-spec Findings for <WP-id>
## Summary
<Brief overview of scope and overall assessment. List total FRs evaluated, how many Compliant vs Partial/Deviating/Missing.>
## Findings
### SPEC-001 [PASS]
- **Checklist item**: FR classification - SHALL obligation
- **Requirement**: FR-001
- **File**: <file_path>
- **Description**: <What was verified and found correct>
### SPEC-002 [FAIL]
- **Checklist item**: FR classification - SHALL obligation
- **Requirement**: FR-012
- **File**: <file_path>#L<start>-L<end>
- **Description**: <What was found wrong or missing>
- **Expected**: <What the spec requires>
- **Evidence**:
```
SPEC-003 [N/A]
- Checklist item: API contract match
- Justification: No API endpoints in this WP - all artifacts are markdown files.
### Rules
- Finding IDs use prefix `SPEC-` and are sequential: SPEC-001, SPEC-002, etc. No gaps.
- Every FAIL finding MUST include: Checklist item, Requirement, File (with line range), Description, Expected, Evidence.
- Every PASS finding MUST include: Checklist item, Requirement, File, Description.
- Every N/A finding MUST include: Checklist item, Justification.
- `finding_counts` MUST accurately reflect the actual findings in the file.
- `files_reviewed` MUST list every file that was read and evaluated during this review.
- `warn` count is always 0 for this skill (spec adherence has no WARN level).
