/verify

name: "Specs: Verify"
description: Verify implementation matches change artifacts before archiving
category: Workflow
tags: [workflow, verify, experimental]

Verify that an implementation matches the change artifacts (design, tasks).

**Input**: Optionally specify a conversation_id after `/specs:verify`. If omitted, use the current conversation's UUID. If vague or ambiguous, list conversations that have specs directories.

**UUID Enforcement**: The conversation_id MUST be a UUID (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`). NEVER use descriptive names.

**Steps**

1. **Locate the specs directory**

Use the current conversation's UUID or the provided one to find: `.scaffolding/conversations/{conversation_id}/specs/`

If no specs directory exists, inform the user and suggest `/specs:new`.

2. **Load artifacts**

Read all available spec files:

• `proposal.md` - Why and what
• `design.md` - How (scenarios, decisions, risks)
• `tasks.md` - Implementation checklist

3. **Initialize verification report structure**

Create a report structure with three dimensions:

• **Completeness**: Track tasks and requirement coverage
• **Correctness**: Track requirement implementation and scenario coverage
• **Coherence**: Track design adherence and pattern consistency

Each dimension can have CRITICAL, WARNING, or SUGGESTION issues.

4. **Verify Completeness**

**Task Completion**:

• If tasks.md exists, read it
• Parse checkboxes: `- [ ]` (incomplete) vs `- [x]` (complete)
• Count complete vs total tasks
• If incomplete tasks exist:
• Add CRITICAL issue for each incomplete task
• Recommendation: "Complete task: <description>" or "Mark as done if already implemented"

**Requirement Coverage**:

• If design.md exists:
• Extract all requirements and scenarios
• For each requirement:
• Search codebase for keywords related to the requirement
• Assess if implementation likely exists
• If requirements appear unimplemented:
• Add CRITICAL issue: "Requirement not found: <requirement name>"
• Recommendation: "Implement requirement X: <description>"

5. **Verify Correctness**

**Requirement Implementation Mapping**:

• For each requirement from design.md:
• Search codebase for implementation evidence
• If found, note file paths and line ranges
• Assess if implementation matches requirement intent
• If divergence detected:
• Add WARNING: "Implementation may diverge from spec: <details>"
• Recommendation: "Review <file>:<lines> against requirement X"

**Scenario Coverage**:

• For each scenario in design.md (Given/When/Then):
• Check if conditions are handled in code
• Check if tests exist covering the scenario
• If scenario appears uncovered:
• Add WARNING: "Scenario not covered: <scenario name>"
• Recommendation: "Add test or implementation for scenario: <description>"

6. **Verify Coherence**

**Design Adherence**:

• If design.md exists:
• Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
• Verify implementation follows those decisions
• If contradiction detected:
• Add WARNING: "Design decision not followed: <decision>"
• Recommendation: "Update implementation or revise design.md to match reality"
• If no design.md: Skip design adherence check, note "No design.md to verify against"

**Code Pattern Consistency**:

• Review new code for consistency with project patterns
• Check file naming, directory structure, coding style
• If significant deviations found:
• Add SUGGESTION: "Code pattern deviation: <details>"
• Recommendation: "Consider following project pattern: <example>"

7. **Generate Verification Report**

**Summary Scorecard**:

   ## Verification Report: <conversation_id>

   ### Summary
   | Dimension    | Status           |
   |--------------|------------------|
   | Completeness | X/Y tasks, N reqs|
   | Correctness  | M/N reqs covered |
   | Coherence    | Followed/Issues  |

**Issues by Priority**:

1. **CRITICAL** (Must fix before archive):

• Incomplete tasks
• Missing requirement implementations
• Each with specific, actionable recommendation

2. **WARNING** (Should fix):

• Design divergences
• Missing scenario coverage
• Each with specific recommendation

3. **SUGGESTION** (Nice to fix):

• Pattern inconsistencies
• Minor improvements
• Each with specific recommendation

**Final Assessment**:

• If CRITICAL issues: "X critical issue(s) found. Fix before archiving."
• If only warnings: "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."
• If all clear: "All checks passed. Ready for archive."

**Verification Heuristics**

• **Completeness**: Focus on objective checklist items (checkboxes, requirements list)
• **Correctness**: Use keyword search, file path analysis, reasonable inference - don't require perfect certainty
• **Coherence**: Look for glaring inconsistencies, don't nitpick style
• **False Positives**: When uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL
• **Actionability**: Every issue must have a specific recommendation with file/line references where applicable

**Graceful Degradation**

• If only tasks.md exists: verify task completion only, skip design checks
• If tasks + design exist: verify completeness and correctness
• If full artifacts: verify all three dimensions
• Always note which checks were skipped and why

**Output Format**

Use clear markdown with:

• Table for summary scorecard
• Grouped lists for issues (CRITICAL/WARNING/SUGGESTION)
• Code references in format: `file.ts:123`
• Specific, actionable recommendations
• No vague suggestions like "consider reviewing"