Reviewer Skill

This skill compares implementation output against the original specification and produces a comprehensive, human-readable HTML compliance report.

When to Use This Skill

• User has completed implementation and wants to verify spec compliance
• User asks to "review", "verify", "audit", or "check" implementation against spec
• User needs a compliance report comparing code to requirements
• User wants a quality gate assessment before shipping

Review Process

Step 1: Gather Inputs

Required:

1. The specification file (spec.md or equivalent)
2. The project directory (implemented code)

Optional but helpful: 3. tasks.md (implementation task tracker) 4. Completion report from the implementer 5. Deviation log from the implementer

Step 2: Systematic Audit

Perform EACH of these audits:

A. User Story Coverage

For EACH story in the spec:

Score: ✅ PASS / ⚠️ PARTIAL / ❌ FAIL / ⬜ MISSING

B. Functional Requirements Coverage

For EACH FR-XXX:

• Find the code that implements it (file + line)
• Verify correctness against the spec wording
• Check if a test covers it

Score: ✅ IMPLEMENTED / ⚠️ PARTIAL / ❌ INCORRECT / ⬜ MISSING

C. Non-Functional Requirements

For EACH NFR:

• Find evidence in code (caching, validation, error handling, etc.)
• Assess whether it's measurably met

Score: ✅ MET / ⚠️ PARTIALLY / ❌ NOT MET / ⬜ NOT ADDRESSED

D. Success Criteria

For EACH SC-XXX:

• Is it verifiable with the current implementation?
• What evidence supports it?

Score: ✅ VERIFIABLE / ⚠️ LIKELY / ❌ UNLIKELY / ⬜ NOT ADDRESSED

E. Edge Cases

For EACH edge case in the spec:

• Is it handled in code? (find the handler)
• Is the handling correct?

Score: ✅ HANDLED / ⚠️ PARTIAL / ❌ UNHANDLED

Step 3: Calculate Scores

Per-item scoring:

• ✅ = 1.0 points
• ⚠️ = 0.5 points
• ❌ = 0.0 points
• ⬜ = 0.0 points

Overall compliance = (total points / total possible) × 100%

Verdict:

• 95-100%: APPROVED — Ship it
• 80-94%: APPROVED WITH CONDITIONS — Minor fixes needed
• 60-79%: NEEDS REVISION — Significant gaps
• Below 60%: REJECTED — Major rework required

Step 4: Generate HTML Report

Use the template at templates/report-template.html as the base.

The report MUST include:

1. Executive Summary — Score, verdict, key stats
2. User Story Matrix — Visual coverage table
3. Requirements Traceability — FR → Code → Test mapping
4. Success Criteria Dashboard — Visual status indicators
5. Findings — Categorized by severity:
   • 🔴 Critical: Feature broken, security issue, data loss risk
   • 🟠 Major: Requirement not implemented, test failing
   • 🟡 Minor: Partial implementation, missing edge case
   • 🔵 Info: Suggestion, pattern recommendation
6. Deviations — Analysis of any implementation deviations
7. Verdict & Recommendations — Overall assessment

Step 5: Save & Report

1. Save HTML report as review-report.html in the project root
2. Present summary to user:
   • Overall compliance percentage
   • Verdict (APPROVED / NEEDS REVISION / etc.)
   • Critical findings count
   • Top 3 issues to address (if any)

Rules

DO:

• Check EVERY requirement — no sampling
• Include file paths and line numbers as evidence
• Credit good patterns alongside issues
• Be specific and actionable in recommendations
• Generate a self-contained HTML file (inline CSS, no external deps)

DON'T:

• Be vague ("some issues found" — name them)
• Penalize for spec issues (that's spec-writer's domain)
• Include opinions not grounded in the spec
• Skip non-functional or edge case checks
• Generate report without reading ALL code