Entry/Exit
- Entry: Completed functional code, the PR about to be merged, the corresponding spec document
- Exit: Spec compliance review report (pass/fail + list of omissions)
- Points to: Pass →
verify-quality-code-quality; Fail → return to build to fill in missing functionality - Preloading: CANON.md
- Output path:
docs/features/YYYYMMDD-<name>/04-review.md(compliance part) → verify-quality-code-quality (when passing) or build-workflow-execute (when failing, return to fill in gaps) - Auxiliary reference:
references/spec-compliance-examples.md(requirement extraction examples, verification marking examples, full fictional report, boundary judgment explanation)
When not to use
- Code changes without a corresponding spec document (cannot verify functional completeness)
- Code is still under development and not claimed complete (should not enter the review stage)
Iron Law
Core anchor
Traceability Matrix
Every spec requirement must establish a traceable chain of spec line number → code implementation → test.
Execution rules:
- Requirements are extracted in four categories: functional requirements ("the system should"), boundary conditions ("when…"), error scenarios ("on failure"), acceptance criteria ("verify… ensure…")
- Each requirement is marked with
[spec:LXX]+ implementation file path + test file path - See the full example in
references/spec-compliance-examples.md§1-2
Coverage-Gated Review
100% coverage is the only criterion for passing. Any gap = fail.
Execution rules:
- Missing functional requirement → Critical, must be fixed
- Missing boundary condition → Critical, must be fixed
- Missing error scenario → Important, strongly recommended to fix
- Acceptance criteria lacking tests → Critical, must be fixed
- On failure, return to build, provide the list of omissions and fix recommendations, and do not proceed to code quality
Scope Creep Detection
Any user-visible functionality implemented in code but not mentioned in the spec = scope creep.
Execution rules:
- Inspection scope: new API endpoints, UI components, database tables/fields, configuration options
- Reasonable extension (internal utility functions, auxiliary types) → mark as pass
- Scope Creep (user-visible functionality) → require the human partner to judge: if necessary, modify the spec to include it; if unnecessary, remove it
Spec-Code Boundary
Explicitly required by the spec = Spec Compliance (this skill); not mentioned in the spec but should be present = Code Quality (verify-quality-code-quality）。
Execution rules:
- "The function does not handle null" → the spec requires handling null = Spec Compliance; not mentioned in the spec = Code Quality
- Gray areas (implementation differs from the spec but the effect is the same, the spec description is ambiguous) → mark the difference and let the human partner judge
Process
Step 1: Locate the spec document
Standard path:docs/features/YYYYMMDD-<name>/01-spec.md; Bug fix:docs/bugs/<name>/01-root-cause.md + 02-fix-plan.md. When the spec cannot be found, ask the user or require that a spec be created first.
Checkpoint: spec document located.
Step 2: Extract the requirement list (Traceability Matrix)
Read the spec line by line, extract all requirements by the four categories, and mark each one with [spec:LXX]。
Checkpoint: All functional requirements, boundary conditions, error scenarios, and acceptance criteria have been extracted with no omissions.
Step 3: Verify the implementation item by item
For each requirement, find the corresponding implementation in the code. For functional requirements, search for functions/components/APIs; for boundary conditions, check if/guard; for error scenarios, check try/catch; for acceptance criteria, check tests.
Checkpoint: Each requirement has been marked with an implementation path + test path.
Step 4: Scope Creep check
Check the code for user-visible features not mentioned in the spec.
Checkpoint: Each scope creep item has been marked + rationale provided.
Step 5: Generate report + verdict
Summarize coverage and determine pass/fail according to Coverage-Gated Review.
Checkpoint: The report has been generated, the verdict is clear, and if it fails, there is an omission list and remediation suggestions.
Common excuses
| Excuse | Reality | Consequence |
|---|---|---|
| "The functionality is basically implemented; details can be filled in later" | "Basically implemented" = incomplete. The spec is a contract. | "Fill in later" on average = never; when users encounter missing functionality, the cost of emergency fixes is 10x |
| "Boundary cases are rare and can be left unhandled" | Boundary conditions are explicitly required by the spec. | "Rare" boundary cases erupt at the worst moments (demos, releases) |
| "Tests can be added later; merge the code first" | No tests = correctness cannot be verified. | 90% of code with "tests added later" will never have tests |
| "It wasn't written in the spec, but users definitely need it" | Unapproved functionality = scope creep. | It may conflict with the product direction; the cost of removing it after merge is far higher than discussing it before merge |
Red flags — STOP
Handling verification failures
| Failure scenario | Handling method |
|---|---|
| Functional requirement coverage < 100% | Return to build and provide an omission list and remediation suggestions |
| Missing boundary conditions | Critical — must be implemented before merging |
| Acceptance criteria lack tests | Critical — can only pass after tests are added |
| Scope Creep unexplained | human partner decides: incorporate into the spec or remove the code |
| Spec description is ambiguous and cannot be verified | Pause the review and continue only after the spec is clarified |
| Implementation approach is inconsistent with the spec | Mark the discrepancy; human partner decides |
Good and bad examples
Good — structured compliance checklist + spec→code mapping
Extract spec requirements one by one, and annotate each item with the spec line number, code implementation location, and test location. Pass only at 100% coverage; omitted items have remediation suggestions and impact explanations.
Bad — "as long as the code runs"
Skip the item-by-item comparison and claim that "the functionality is basically implemented" while there are actually omissions. No spec→code mapping, no coverage calculation, and the omitted boundary conditions and acceptance criteria erupt as bugs in production.
See the complete fictional report example at references/spec-compliance-examples.md §4。
Output template
### Spec Compliance — <feature-name>
**Spec**: [01-spec.md 路径] | **时间**: [YYYY-MM-DD] | **结果**: PASS / FAIL
**覆盖率**: 功能 [X/Y] | 边界 [X/Y] | 错误 [X/Y] | 验收 [X/Y] | **总 [X/Y]**
**遗漏（Critical）**:
| # | spec 行号 | 需求 | 状态 | 影响 | 建议 |
|---|----------|------|------|------|------|
| 1 | [L12] | [需求] | [缺失] | [影响] | [建议] |
**Scope Creep**: [列表 / 无] | **测试缺口**: [列表 / 无]
**下一步**: [通过 → code quality / 不通过 → 回 build 补齐]
Verification checklist
- Spec document has been located
- All requirements (functional/boundary/error/acceptance) have been extracted and line numbers marked
- Each requirement has been verified for code implementation and tests
- Scope Creep checked and judged
- Coverage calculated (target 100%)
- Compliance report generated
- Pass/fail determined; when fail, an omission list and remediation suggestions have been provided