spec-review

OpenSpec Verification

Guide for verifying that implementation matches spec artifacts.

Input Files

File	Required	Purpose
{specs_path}/design.md	Yes	Requirements and scenarios to verify
{specs_path}/tasks.md	Yes	Completion checklist
{specs_path}/proposal.md	Optional	Original intent reference

Path Enforcement: The specs_path MUST be .scaffolding/conversations/{UUID}/specs/ where {UUID} is a valid UUID (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). NEVER use descriptive folder names.

Three Verification Dimensions

1. Completeness

Question: Are all tasks done and all requirements covered?

Check	Method	Issue Level
All checkboxes marked [x]	Parse tasks.md	CRITICAL if incomplete
All requirements have code	Search codebase for keywords	CRITICAL if missing
All new files exist	Verify file paths from tasks	CRITICAL if missing

2. Correctness

Question: Does the code do what the spec says?

Check	Method	Issue Level
GIVEN/WHEN/THEN satisfied	Trace scenario through code	WARNING if divergent
Tests cover scenarios	Match test names to scenarios	WARNING if uncovered
Edge cases handled	Check error paths in code	WARNING if missing
Validation commands pass	Run pytest / npm run validate	CRITICAL if failing

3. Coherence

Question: Does the code match design decisions?

Check	Method	Issue Level
Design decisions followed	Compare Decisions section to code	WARNING if violated
Patterns consistent	Check naming, structure, style	SUGGESTION
No undocumented changes	Diff scope vs design scope	WARNING if extra
No design deviations	Cross-reference architecture	WARNING if different

Verification Process

1. Load artifacts - Read design.md, tasks.md, proposal.md
2. Check completeness - Parse checkboxes, search for requirement implementations
3. Check correctness - Trace each scenario through code, verify test coverage
4. Check coherence - Compare decisions to implementation, check patterns
5. Generate report - Summarize findings with issue levels

Report Format

## Verification Report

### Summary
| Dimension    | Status              |
|--------------|---------------------|
| Completeness | X/Y tasks, N reqs   |
| Correctness  | M/N scenarios pass   |
| Coherence    | Followed / N issues  |

### Critical Issues
| # | Dimension | Issue | File | Recommendation |
|---|-----------|-------|------|----------------|
| 1 | Completeness | Task 2.3 incomplete | - | Complete or mark blocked |

### Warnings
| # | Dimension | Issue | File | Recommendation |
|---|-----------|-------|------|----------------|
| 1 | Correctness | Scenario X not tested | test_foo.py | Add test case |

### Suggestions
- [Pattern deviation details with file reference]

### Assessment
[CRITICAL: N issues | WARNINGS: N | Ready for archive: Yes/No]

Graceful Degradation

Available Artifacts	Checks Performed
tasks.md only	Completeness (checkboxes) only
tasks.md + design.md	Completeness + Correctness
All three	All three dimensions

Always note which checks were skipped and why.

Verification Heuristics

• Completeness: Focus on objective items (checkboxes, requirement lists)
• Correctness: Use keyword search + file path analysis; don't require certainty
• Coherence: Look for glaring inconsistencies, don't nitpick style
• False positives: Prefer SUGGESTION over WARNING, WARNING over CRITICAL when uncertain
• Actionability: Every issue must have a specific recommendation with file references