fraim-framework 2.0.26 → 2.0.30

package/registry/workflows/reviewer/review-implementation-vs-design-spec.md

@@ -1,632 +1,632 @@
-# Review Implementation vs Design Spec
-
-## INTENT
-To systematically verify that the implementation matches the approved technical design (RFC), ensuring all technical requirements, test cases, and validation scenarios are complete.
-
-## PRINCIPLES
-- **Design-Driven Validation**: Every requirement in the RFC must be verified
-- **Test Matrix Compliance**: All test cases from design spec must exist and pass
-- **Architecture Alignment**: Implementation must follow design decisions
-- **Evidence-Based**: All claims must be backed by actual evidence
-- **Gap Identification**: Systematically identify what's missing, not just what exists
-
-## REVIEW WORKFLOW
-
-### Step 1: Issue Identification and Evidence Loading
-- Get {issue_number} from context
-- Verify issue has `phase:impl` and `status:needs-review` labels
-- Locate RFC: `docs/rfcs/{issue}-*.md`
-- If RFC doesn't exist: ❌ BLOCKER - Cannot review without design spec. Request design phase first.
-- **Determine Issue Type**: Check if this is a bug fix or feature
-  - Check RFC title/description or issue title for "bug", "fix", "error", etc.
-  - Bug fixes require regression tests (see Step 4.4 Regression Test Verification)
-- **Load Implementation Evidence**: Read `docs/evidence/{issue}-implementation-evidence.md`
-  - If evidence doesn't exist: ❌ BLOCKER - Implementation agent must create evidence document first
-  - Review evidence for completeness and quality
-- **Check for Existing Feedback**: Check if `docs/evidence/{issue}-design-reviewer-feedback.md` exists
-  - If exists, this is an iteration (check iteration count)
-  - Track iteration number (max 3 iterations)
-
-### Step 2: RFC Analysis
-**MUST read and extract:**
-- Technical requirements (API changes, schema changes, etc.)
-- Test Matrix section (unit, integration, E2E tests required)
-- Validation Plan section (all validation scenarios)
-- Architecture decisions (service boundaries, patterns)
-- Risk mitigations (how they were addressed)
-- Observability requirements (logs, metrics, alerts)
-
-**Create a checklist mapping:**
-- List each requirement from RFC
-- List each test case from Test Matrix
-- List each validation scenario from Validation Plan
-- This becomes your review checklist
-
-### Step 3: Implementation Code Review
-**For each technical requirement in RFC:**
-- [ ] Verify requirement is implemented in code
-  - Search codebase for implementation
-  - Check file paths match design
-  - Verify code exists and is not just stubbed
-- [ ] Check code follows architecture decisions
-  - Service boundaries match design
-  - Patterns match design (e.g., spike-first, deterministic separation)
-  - No over-engineering beyond design scope
-- [ ] Verify API/schema changes match RFC exactly
-  - Check OpenAPI spec matches (if applicable)
-  - Check database schema matches (if applicable)
-  - Verify field names, types, constraints match
-- [ ] Check error handling matches design
-  - Error responses match design
-  - Error codes match design
-  - Error messages match design
-- [ ] Verify observability (logs, metrics) matches design
-  - Log statements exist where specified
-  - Metrics tracked where specified
-  - Alerts configured where specified
-
-**Document findings:**
-- Create table: Requirement | Status | Evidence Location | Notes
-
-### Step 4: Test Matrix Validation
-**For each test type in RFC Test Matrix:**
-
-#### Unit Tests
-- [ ] **Count Required**: How many unit tests does RFC specify?
-- [ ] **Count Found**: How many unit test files exist? (`test-{issue}-*.ts` or similar)
-- [ ] **Verify Existence**: Check each listed test case exists
-- [ ] **Run Tests**: Execute `npm run test test-{issue}-*.ts` (or appropriate command)
-- [ ] **Verify Exit Code**: Must be 0 (success)
-- [ ] **Check Output**: All tests must pass (not just "some tests pass")
-- [ ] **Document Results**: Include actual test output in review evidence
-
-#### Integration Tests
-- [ ] **Count Required**: How many integration tests does RFC specify?
-- [ ] **Count Found**: How many integration test files exist?
-- [ ] **Verify Existence**: Check each listed test case exists
-- [ ] **Run Tests**: Execute integration tests with proper mocks
-- [ ] **Verify Service Interactions**: Check mocks validate service calls match design
-- [ ] **Verify Exit Code**: Must be 0 (success)
-- [ ] **Document Results**: Include actual test output in review evidence
-
-#### E2E Tests
-- [ ] **Count Required**: How many E2E tests does RFC specify?
-- [ ] **Count Found**: How many E2E test files exist?
-- [ ] **Verify Existence**: Check each listed test case exists
-- [ ] **Run Tests**: Execute E2E tests (may require server running)
-- [ ] **Verify End-to-End Flow**: Complete workflow must work
-- [ ] **Verify Exit Code**: Must be 0 (success)
-- [ ] **Document Results**: Include actual test output in review evidence
-
-**If test matrix says "X test cases" but only Y exist:**
-- ❌ BLOCKER: Missing test cases
-- Must identify which tests are missing (list specific test names)
-- Cannot approve until all tests from matrix exist and pass
-
-**Document findings:**
-- Create table: Test Type | Required | Found | Passing | Evidence | Missing Tests
-
-#### Test Quality Validation (Anti-Pattern Detection)
-**🚨 CRITICAL: Verify tests validate runtime behavior, not code structure**
-
-**For each test file found (test-{issue}-*.ts):**
-- [ ] **Check for Static Analysis Anti-Pattern**: Verify tests don't use `fs.readFileSync()` for code structure checks
-  - Check: `grep -E "fs\.readFileSync|readFileSync" test-{issue}-*.ts`
-  - ❌ BLOCKER if found - tests are doing static analysis, not runtime testing
-  - Expected: Tests should execute code, not read source files
-  - Reference: `retrospectives/issue-723-weak-test-validation-anti-pattern-postmortem.md`
-- [ ] **Verify Runtime Behavior Testing**: Check tests actually execute code paths
-  - Review test code to ensure it calls actual functions/services
-  - Verify tests check observable outcomes (API responses, database state, logs)
-  - ❌ BLOCKER if tests only check code structure without execution
-- [ ] **Check for Mock Anti-Pattern**: Verify tests don't mock the core functionality being tested
-  - Check: Are mocks used for dependencies (✅) or for the thing being tested (❌)?
-  - ❌ BLOCKER if core functionality is mocked
-  - Expected: Mock dependencies, test actual implementation
-- [ ] **Verify State Validation**: Check tests validate state changes
-  - Tests should check database state, API responses, or service interactions
-  - ❌ BLOCKER if tests don't validate any state changes
-  - Expected: Tests verify before/after state or observable outcomes
-
-**Document findings:**
-- Create table: Test File | Static Analysis Check | Runtime Behavior | Mock Usage | State Validation | Status
-
-#### Regression Test Verification (For Bug Fixes)
-**If this is a bug fix (check RFC or issue description):**
-- [ ] **Identify Bug**: Understand what the bug was from RFC/issue
-- [ ] **Check for Regression Test**: Verify test file includes regression test for the bug
-  - Check test file for test case that reproduces the bug
-  - Test should be named something like "regression test for bug X" or similar
-- [ ] **Verify Test Pattern**: Regression test must follow correct pattern
-  - ❌ BLOCKER if test passes/fails regardless of bug (wrong pattern)
-  - ✅ CORRECT: Test fails with bug → Test passes with fix
-  - ❌ WRONG: Test passes with bug AND with fix (doesn't reproduce bug)
-  - ❌ WRONG: Test fails with bug AND with fix (environmental issue)
-- [ ] **Verify Test Behavior** (if possible):
-  - Ideally: Revert fix temporarily, run test → should fail
-  - Reapply fix, run test → should pass
-  - If not possible, verify test logic would fail with buggy code
-
-**Document findings:**
-- Bug Fix: ✅ Yes / ❌ No
-- Regression Test: ✅ Found / ❌ Missing
-- Test Pattern: ✅ Correct (fails with bug, passes with fix) / ❌ Wrong pattern
-- Notes: [Any issues with regression test]
-
-### Step 4.5: Common Error Pattern Checks
-**🚨 CRITICAL: Check for common test and code quality issues**
-
-#### Test Structure Validation
-**For each test file found (test-{issue}-*.ts):**
-- [ ] **BaseTestCase Extension**: Verify test cases extend `BaseTestCase` interface
-  - Check: `grep -E "extends BaseTestCase|interface.*extends BaseTestCase" test-{issue}-*.ts`
-  - ❌ BLOCKER if test cases don't extend BaseTestCase
-  - Expected pattern: `interface MyTestCase extends BaseTestCase { ... }`
-  - All test case objects must use interface that extends BaseTestCase
-- [ ] **Main Function**: Verify test file has `main()` function
-  - Check: `grep -E "async function main\(\)|function main\(\)" test-{issue}-*.ts`
-  - ❌ BLOCKER if main() function missing
-  - Expected pattern: `async function main() { ... runTests(...) }`
-  - Must have `main().catch(console.error)` at end of file
-- [ ] **runTests Usage**: Verify test file uses `runTests()` function
-  - Check: `grep "runTests" test-{issue}-*.ts`
-  - ❌ BLOCKER if runTests() not used
-  - Expected: `runTests(TEST_CASES, runMyTest, 'Test Suite Name')`
-  - Must import runTests from './test-utils' or './test-utils.ts'
-
-**Document findings:**
-- Create table: Test File | BaseTestCase | main() | runTests() | Status
-
-#### Code Quality Check
-- [ ] **Run Code Quality Check**: Execute `.ai-agents/scripts/code-quality-check.sh pre-pr`
-  - Command: `bash .ai-agents/scripts/code-quality-check.sh pre-pr`
-  - Verify exit code is 0 (success)
-  - Check for critical failures (❌) vs warnings (⚠️)
-  - ❌ BLOCKER if critical checks fail (e.g., `as any` usage, TypeScript errors)
-  - ⚠️ WARNING if warnings exist (document in feedback)
-- [ ] **Review Quality Check Output**: 
-  - Check for `as any` type bypassing in src/
-  - Check TypeScript compilation passes
-  - Check linter passes (warnings acceptable, errors are blockers)
-  - Check all test files referenced in evidence have been executed
-
-**Document findings:**
-- Code Quality Check: ✅ Passed / ❌ Failed / ⚠️ Warnings
-- Critical Issues: [list any critical failures]
-- Warnings: [list any warnings]
-
-#### Evidence File Location Validation
-- [ ] **Check Evidence Files**: Verify evidence files are ONLY in `docs/evidence/` folder
-  - Check: `find . -name "*evidence*.md" -not -path "./docs/evidence/*" -not -path "./.git/*" -not -path "./node_modules/*"`
-  - ❌ BLOCKER if evidence files found outside `docs/evidence/`
-  - Expected: All evidence files should be in `docs/evidence/{issue}-*.md`
-- [ ] **Check for Evidence in Git**: Verify evidence folder is gitignored
-  - Check: `git check-ignore docs/evidence/` should return `docs/evidence/`
-  - ⚠️ WARNING if evidence folder not in .gitignore (should be gitignored)
-- [ ] **Check PR for Evidence Files**: Verify no evidence files committed to repo
-  - Check git status for any files in docs/evidence/
-  - ❌ BLOCKER if evidence files are staged/committed
-
-**Document findings:**
-- Evidence Location Check: ✅ All in docs/evidence/ / ❌ Found outside
-- Git Ignore Check: ✅ Ignored / ⚠️ Not ignored
-- Committed Evidence: ✅ None / ❌ Found in commits
-
-**If any blockers found:**
-- ❌ BLOCKER: Must fix before approval
-- List specific files and issues
-- Cannot approve until all blockers resolved
-
-### Step 5: Validation Plan Execution
-**For each validation scenario in RFC Validation Plan:**
-- [ ] **Scenario Identified**: Map each scenario from validation plan
-- [ ] **Evidence Found**: Check PR evidence for scenario validation
-  - Look in PR comments for evidence
-  - Check for screenshots, curl outputs, test results
-  - Verify evidence shows actual execution (not just "tested")
-- [ ] **Method Verified**: Ensure validation method matches (UI, API, DB, etc.)
-  - If RFC says "API validation", check for curl/Postman results
-  - If RFC says "Browser validation", check for screenshots/recordings
-  - If RFC says "Database validation", check for DB query results
-- [ ] **Result Verified**: Ensure scenario actually passes (not just "tested")
-  - Check evidence shows success, not just attempt
-  - Verify no "pending" or "TODO" markers
-
-**If validation plan has 10 scenarios but only 7 have evidence:**
-- ❌ BLOCKER: Missing validation evidence
-- Must identify which scenarios are missing (list specific scenario names)
-- Cannot approve until all scenarios validated with evidence
-
-**Document findings:**
-- Create table: Scenario | Method | Evidence | Status | Missing Evidence
-
-### Step 6: Architecture Compliance Check
-**Verify implementation matches design:**
-- [ ] Service boundaries match design
-  - Check service files match design boundaries
-  - Verify no cross-boundary violations
-- [ ] Patterns match design (e.g., spike-first, deterministic separation)
-  - Check code follows patterns specified in RFC
-  - Verify no anti-patterns introduced
-- [ ] Dependencies match design
-  - Check package.json matches design dependencies
-  - Verify no unexpected dependencies added
-- [ ] No over-engineering beyond design scope
-  - Check code doesn't add features not in RFC
-  - Verify minimal implementation (not over-engineered)
-
-**Document findings:**
-- List any architecture deviations
-- Note if deviations are acceptable or blockers
-
-### Step 7: Risk Mitigation Verification
-**For each risk in RFC Risks & Mitigations:**
-- [ ] Verify mitigation is implemented
-  - Check code implements mitigation strategy
-  - Verify mitigation code exists and is not just commented
-- [ ] Check mitigation actually addresses the risk
-  - Verify mitigation logic matches risk description
-  - Check mitigation is complete (not partial)
-- [ ] Verify observability for risk detection
-  - Check logs/alerts exist for risk scenarios
-  - Verify monitoring is in place
-
-**Document findings:**
-- Create table: Risk | Mitigation Status | Implementation Location | Notes
-
-### Step 8: Evidence Quality Review
-**Verify PR evidence quality:**
-- [ ] All test outputs included (not just "tests pass")
-  - Check for actual test command output
-  - Verify exit codes shown
-  - Check for test case names and results
-- [ ] All validation scenarios documented with results
-  - Check each scenario has evidence
-  - Verify evidence shows actual execution
-- [ ] No "pending" items that could be validated automatically
-  - Flag any "pending" items that could be tested
-  - Check for "TODO" or "needs manual validation" markers
-- [ ] Build verification included
-  - Check for `npm run build` output
-  - Verify build succeeds
-- [ ] Quality gate results included
-  - Check for quality gate script output
-  - Verify all gates pass (or warnings documented)
-
-**Document findings:**
-- List any evidence quality issues
-- Note if evidence is sufficient or needs improvement
-
-### Step 9: Review Decision and Feedback Creation
-
-**Check Iteration Count:**
-- If `docs/evidence/{issue}-design-reviewer-feedback.md` exists, check iteration number
-- Maximum 3 iterations allowed
-- If iteration 3 and still issues: ❌ REJECT (max iterations reached)
-
-**Options:**
-- ✅ **APPROVE**: All requirements met, tests pass, evidence complete
-- ❌ **REJECT**: Missing requirements, tests fail, or evidence incomplete (after max iterations)
-- ⚠️ **REQUEST CHANGES**: Minor gaps that need addressing (iteration < 3)
-
-**If REQUEST CHANGES (iteration < 3):**
-- **Create Feedback Document**: Create `docs/evidence/{issue}-design-reviewer-feedback.md`
-  - Use template below for feedback structure
-  - List specific blockers with evidence locations
-  - Provide actionable feedback for each issue
-  - Include iteration number
-- Label issue `status:wip` (remove `status:needs-review`)
-- Add PR comment referencing feedback document
-- Implementation agent must address feedback and update evidence
-- Implementation agent re-submits by marking `status:needs-review` again
-
-**If REJECT (max iterations reached):**
-- Create final feedback document with all remaining issues
-- Label issue `status:wip` (remove `status:needs-review`)
-- Add PR comment with final rejection notice
-- Implementation agent must address all issues before re-submission
-
-**If APPROVE:**
-- **Create Summary for Feature Spec Review**: Create `docs/evidence/{issue}-design-review-summary.md`
-  - Summarize what was reviewed and approved
-  - Include key findings and evidence locations
-  - Provide context for feature spec review agent
-- Label issue `status:design-review-passed` (remove `status:needs-review`)
-- Add PR comment confirming design spec compliance
-- Issue ready for Feature Spec Review (next workflow)
-
-## FEEDBACK DOCUMENT TEMPLATE
-
-Create `docs/evidence/{issue}-design-reviewer-feedback.md`:
-
-```markdown
-# Design Review Feedback - Issue #{issue}
-
-## Iteration Information
-- Iteration Number: {1, 2, or 3}
-- Review Date: {date}
-- Reviewer: Design Spec Review Agent
-
-## Review Summary
-- RFC Location: `docs/rfcs/{issue}-*.md`
-- Evidence Reviewed: `docs/evidence/{issue}-implementation-evidence.md`
-- Overall Status: ⚠️ REQUEST CHANGES
-
-## Issues Found
-
-### Critical Blockers (Must Fix)
-1. **Issue Title**
-   - **Location**: `src/file.ts:line`
-   - **Problem**: [Specific problem description]
-   - **Expected**: [What RFC requires]
-   - **Found**: [What implementation has]
-   - **Action Required**: [Specific fix needed]
-
-2. **Issue Title**
-   - [Same structure]
-
-### Missing Requirements
-1. **Requirement Name**
-   - **RFC Section**: [Section reference]
-   - **What's Missing**: [Specific requirement]
-   - **Action Required**: [What needs to be implemented]
-
-### Test Matrix Issues
-1. **Missing Test**: Test case name
-   - **RFC Test Matrix**: [Reference]
-   - **Action Required**: Create test file `test-{issue}-*.ts` with test case
-
-### Test Structure Issues (Common Error Patterns)
-1. **Test Not Extending BaseTestCase**: `test-{issue}-*.ts`
-   - **Problem**: Test case interface doesn't extend BaseTestCase
-   - **Expected**: `interface MyTestCase extends BaseTestCase { ... }`
-   - **Action Required**: Update test case interface to extend BaseTestCase
-
-2. **Missing main() Function**: `test-{issue}-*.ts`
-   - **Problem**: Test file doesn't have main() function
-   - **Expected**: `async function main() { ... runTests(...) }` with `main().catch(console.error)`
-   - **Action Required**: Add main() function that calls runTests()
-
-3. **Not Using runTests()**: `test-{issue}-*.ts`
-   - **Problem**: Test file doesn't use runTests() function
-   - **Expected**: Import runTests from './test-utils' and call it in main()
-   - **Action Required**: Refactor to use runTests() function
-
-### Test Quality Issues (Anti-Patterns)
-1. **Static Analysis Anti-Pattern**: `test-{issue}-*.ts`
-   - **Problem**: Tests use `fs.readFileSync()` to check code structure instead of runtime behavior
-   - **Expected**: Tests should execute code and validate outcomes, not read source files
-   - **Action Required**: Rewrite tests to validate runtime behavior
-   - **Reference**: `retrospectives/issue-723-weak-test-validation-anti-pattern-postmortem.md`
-
-2. **No Runtime Behavior Validation**: `test-{issue}-*.ts`
-   - **Problem**: Tests don't execute actual code paths or validate observable outcomes
-   - **Expected**: Tests should call functions/services and check results
-   - **Action Required**: Add runtime behavior validation to tests
-
-3. **Mocking Core Functionality**: `test-{issue}-*.ts`
-   - **Problem**: Tests mock the thing being tested instead of dependencies
-   - **Expected**: Mock dependencies, test actual implementation
-   - **Action Required**: Refactor mocks to only mock dependencies
-
-4. **No State Validation**: `test-{issue}-*.ts`
-   - **Problem**: Tests don't validate state changes (database, API responses, etc.)
-   - **Expected**: Tests should verify before/after state or observable outcomes
-   - **Action Required**: Add state validation to tests
-
-### Regression Test Issues (For Bug Fixes)
-1. **Missing Regression Test**: `test-{issue}-*.ts`
-   - **Problem**: Bug fix doesn't have regression test
-   - **Expected**: Regression test that fails with bug, passes with fix
-   - **Action Required**: Add regression test following correct pattern
-
-2. **Wrong Regression Test Pattern**: `test-{issue}-*.ts`
-   - **Problem**: Test passes/fails regardless of bug (doesn't reproduce bug)
-   - **Expected**: Test fails with bug → Test passes with fix
-   - **Action Required**: Fix regression test to follow correct pattern
-   - **Reference**: `retrospectives/task-api-calendar-event-id-bug-postmortem.md`
-
-### Code Quality Issues
-1. **Code Quality Check Failed**: [Specific issue]
-   - **Problem**: [What failed - e.g., "as any" usage, TypeScript errors]
-   - **Action Required**: Fix code quality issues and re-run check
-   - **Command**: `bash .ai-agents/scripts/code-quality-check.sh pre-pr`
-
-### Evidence File Location Issues
-1. **Evidence File Outside docs/evidence/**: [File path]
-   - **Problem**: Evidence file found outside `docs/evidence/` folder
-   - **Expected**: All evidence files should be in `docs/evidence/{issue}-*.md`
-   - **Action Required**: Move evidence file to `docs/evidence/` folder
-
-### Validation Plan Issues
-1. **Missing Validation**: Scenario name
-   - **RFC Validation Plan**: [Reference]
-   - **Action Required**: Execute validation and add evidence
-
-### Evidence Quality Issues
-1. **Missing Evidence**: [What's missing]
-   - **Action Required**: [What evidence needs to be added]
-
-## Action Items for Implementation Agent
-- [ ] Fix critical blocker 1
-- [ ] Fix critical blocker 2
-- [ ] Implement missing requirement X
-- [ ] Add missing test case Y
-- [ ] Execute missing validation Z
-- [ ] Update evidence document with fixes
-
-## Next Steps
-1. Implementation agent addresses all feedback items
-2. Implementation agent updates `docs/evidence/{issue}-implementation-evidence.md`
-3. Implementation agent marks issue `status:needs-review` again
-4. Design review agent will re-review (iteration {next_number})
-```
-
-## SUMMARY DOCUMENT TEMPLATE (For Feature Spec Review)
-
-Create `docs/evidence/{issue}-design-review-summary.md` when approving:
-
-```markdown
-# Design Review Summary - Issue #{issue}
-
-## Review Outcome
-- Status: ✅ APPROVED
-- Iterations: {number} (1-3)
-- RFC Location: `docs/rfcs/{issue}-*.md`
-
-## What Was Reviewed
-- Technical Requirements: X/Y implemented ✅
-- Test Matrix: All test cases exist and pass ✅
-- Validation Plan: All scenarios validated ✅
-- Architecture: Matches design ✅
-- Risk Mitigations: All implemented ✅
-
-## Key Findings
-- All RFC requirements implemented correctly
-- All tests from test matrix exist and pass
-- All validation scenarios executed with evidence
-- Architecture follows design decisions
-- No over-engineering detected
-
-## Evidence Locations
-- Implementation Evidence: `docs/evidence/{issue}-implementation-evidence.md`
-- Test Results: [locations]
-- Validation Evidence: [locations]
-
-## Notes for Feature Spec Review
-- Technical implementation is complete and correct
-- All technical requirements met
-- Ready for functional/user experience validation
-- No technical blockers for feature spec review
-```
-
-## REVIEW EVIDENCE TEMPLATE (PR Comment)
-
-Add this as a PR comment:
-
-```markdown
-# Design Spec Review - Issue #{issue}
-
-## RFC Compliance Summary
-- RFC Location: `docs/rfcs/{issue}-*.md`
-- Technical Requirements: X/Y implemented ✅/❌
-- Test Matrix Compliance: X/Y test types complete ✅/❌
-- Validation Plan Coverage: X/Y scenarios validated ✅/❌
-- Architecture Compliance: ✅/❌
-- Risk Mitigations: X/Y implemented ✅/❌
-
-## Detailed Findings
-
-### Technical Requirements
-| Requirement | Status | Evidence Location | Notes |
-|------------|--------|-------------------|-------|
-| API endpoint X | ✅ | `src/api/...` | Matches RFC |
-| Schema change Y | ❌ | Missing | RFC requires Z field |
-
-### Test Matrix Validation
-| Test Type | Required | Found | Passing | Evidence | Missing Tests |
-|-----------|----------|-------|---------|----------|---------------|
-| Unit Tests | 5 | 5 | ✅ | `test-{issue}.ts` lines 10-50 | None |
-| Integration | 3 | 2 | ❌ | Partial | Missing test for scenario Z |
-| E2E | 1 | 0 | ❌ | Not found | E2E test not implemented |
-
-### Test Quality Validation
-| Test File | Static Analysis | Runtime Behavior | Mock Usage | State Validation | Status |
-|-----------|----------------|-------------------|------------|------------------|--------|
-| test-{issue}.ts | ✅ No fs.readFileSync | ✅ Executes code | ✅ Mocks dependencies | ✅ Validates state | ✅ Pass |
-| test-{issue}-2.ts | ❌ Uses fs.readFileSync | ❌ No execution | ❌ Mocks core | ❌ No validation | ❌ Fail |
-
-### Regression Test Verification (If Bug Fix)
-- Bug Fix: ✅ Yes / ❌ No
-- Regression Test: ✅ Found / ❌ Missing
-- Test Pattern: ✅ Correct (fails with bug, passes with fix) / ❌ Wrong pattern
-- Notes: [Any issues with regression test]
-
-### Validation Plan Coverage
-| Scenario | Method | Evidence | Status | Missing Evidence |
-|----------|--------|----------|--------|------------------|
-| Create operation | API | PR comment | ✅ | None |
-| Update operation | API | Missing | ❌ | No curl output found |
-
-### Architecture Compliance
-- Service Boundaries: ✅ Match design
-- Patterns: ✅ Follow design patterns
-- Dependencies: ⚠️ Extra dependency X added (not in RFC)
-- Over-engineering: ✅ Minimal implementation
-
-### Risk Mitigations
-| Risk | Mitigation Status | Implementation Location | Notes |
-|------|-------------------|-------------------------|-------|
-| Risk X | ✅ Implemented | `src/...` | Matches design |
-| Risk Y | ❌ Missing | N/A | Not implemented |
-
-### Common Error Pattern Checks
-- Test Structure: ✅ All tests extend BaseTestCase / ❌ Issues found
-- Main Functions: ✅ All tests have main() / ❌ Missing in some tests
-- runTests Usage: ✅ All tests use runTests() / ❌ Not used in some tests
-- Code Quality Check: ✅ Passed / ❌ Failed / ⚠️ Warnings
-- Evidence Location: ✅ All in docs/evidence/ / ❌ Found outside
-
-### Evidence Quality
-- Test Outputs: ✅ Complete (all test results included)
-- Validation Evidence: ⚠️ Partial (missing scenario Y evidence)
-- Build Verification: ✅ Included
-- Quality Gate: ✅ Passed
-
-## Decision
-✅ APPROVE / ❌ REJECT / ⚠️ REQUEST CHANGES
-
-## Feedback Document
-- Location: `docs/evidence/{issue}-design-reviewer-feedback.md`
-- Iteration: {1, 2, or 3}
-
-## Blockers (if any)
-1. Missing test case for scenario X (RFC Test Matrix requires it)
-2. Validation scenario Y not executed (RFC Validation Plan requires it)
-3. Technical requirement Z not implemented (RFC Technical Details requires it)
-
-## Next Steps (if REQUEST CHANGES)
-- [ ] Implementation agent addresses feedback in `docs/evidence/{issue}-design-reviewer-feedback.md`
-- [ ] Implementation agent updates `docs/evidence/{issue}-implementation-evidence.md`
-- [ ] Implementation agent marks `status:needs-review` for re-review
-- [ ] Design review agent will re-review (max 3 iterations)
-```
-
-## EXAMPLES
-
-### Good: Complete Review
-```
-Issue #533: Design Spec Review
-✅ RFC Compliance: 15/15 requirements implemented
-✅ Test Matrix: All 8 test cases exist and pass
-✅ Validation Plan: All 5 scenarios validated
-✅ Architecture: Matches design
-✅ Evidence: Complete with test outputs
-Decision: ✅ APPROVE
-```
-
-### Bad: Incomplete Review
-```
-Issue #533: Design Spec Review
-⚠️ RFC Compliance: 12/15 requirements (3 missing)
-❌ Test Matrix: 5/8 test cases exist (3 missing)
-⚠️ Validation Plan: 3/5 scenarios validated (2 missing)
-Decision: ❌ REJECT
-Blockers: Missing tests, missing validations
-```
-
-## INTEGRATION
-
-### Status Label Flow
-```
-phase:impl + status:needs-review
-  ↓ (Design Spec Review)
-status:design-review-passed (or status:wip if rejected)
-  ↓ (Feature Spec Review - next workflow)
-status:feature-review-passed
-```
-
-### After This Review
-- If APPROVE: Issue moves to Feature Spec Review
-- If REJECT: Issue returns to implementation (status:wip)
-- Implementation agent addresses blockers and re-submits
+# Review Implementation vs Design Spec
+
+## INTENT
+To systematically verify that the implementation matches the approved technical design (RFC), ensuring all technical requirements, test cases, and validation scenarios are complete.
+
+## PRINCIPLES
+- **Design-Driven Validation**: Every requirement in the RFC must be verified
+- **Test Matrix Compliance**: All test cases from design spec must exist and pass
+- **Architecture Alignment**: Implementation must follow design decisions
+- **Evidence-Based**: All claims must be backed by actual evidence
+- **Gap Identification**: Systematically identify what's missing, not just what exists
+
+## REVIEW WORKFLOW
+
+### Step 1: Issue Identification and Evidence Loading
+- Get {issue_number} from context
+- Verify issue has `phase:impl` and `status:needs-review` labels
+- Locate RFC: `docs/rfcs/{issue}-*.md`
+- If RFC doesn't exist: ❌ BLOCKER - Cannot review without design spec. Request design phase first.
+- **Determine Issue Type**: Check if this is a bug fix or feature
+  - Check RFC title/description or issue title for "bug", "fix", "error", etc.
+  - Bug fixes require regression tests (see Step 4.4 Regression Test Verification)
+- **Load Implementation Evidence**: Read `docs/evidence/{issue}-implementation-evidence.md`
+  - If evidence doesn't exist: ❌ BLOCKER - Implementation agent must create evidence document first
+  - Review evidence for completeness and quality
+- **Check for Existing Feedback**: Check if `docs/evidence/{issue}-design-reviewer-feedback.md` exists
+  - If exists, this is an iteration (check iteration count)
+  - Track iteration number (max 3 iterations)
+
+### Step 2: RFC Analysis
+**MUST read and extract:**
+- Technical requirements (API changes, schema changes, etc.)
+- Test Matrix section (unit, integration, E2E tests required)
+- Validation Plan section (all validation scenarios)
+- Architecture decisions (service boundaries, patterns)
+- Risk mitigations (how they were addressed)
+- Observability requirements (logs, metrics, alerts)
+
+**Create a checklist mapping:**
+- List each requirement from RFC
+- List each test case from Test Matrix
+- List each validation scenario from Validation Plan
+- This becomes your review checklist
+
+### Step 3: Implementation Code Review
+**For each technical requirement in RFC:**
+- [ ] Verify requirement is implemented in code
+  - Search codebase for implementation
+  - Check file paths match design
+  - Verify code exists and is not just stubbed
+- [ ] Check code follows architecture decisions
+  - Service boundaries match design
+  - Patterns match design (e.g., spike-first, deterministic separation)
+  - No over-engineering beyond design scope
+- [ ] Verify API/schema changes match RFC exactly
+  - Check OpenAPI spec matches (if applicable)
+  - Check database schema matches (if applicable)
+  - Verify field names, types, constraints match
+- [ ] Check error handling matches design
+  - Error responses match design
+  - Error codes match design
+  - Error messages match design
+- [ ] Verify observability (logs, metrics) matches design
+  - Log statements exist where specified
+  - Metrics tracked where specified
+  - Alerts configured where specified
+
+**Document findings:**
+- Create table: Requirement | Status | Evidence Location | Notes
+
+### Step 4: Test Matrix Validation
+**For each test type in RFC Test Matrix:**
+
+#### Unit Tests
+- [ ] **Count Required**: How many unit tests does RFC specify?
+- [ ] **Count Found**: How many unit test files exist? (`test-{issue}-*.ts` or similar)
+- [ ] **Verify Existence**: Check each listed test case exists
+- [ ] **Run Tests**: Execute `npm run test test-{issue}-*.ts` (or appropriate command)
+- [ ] **Verify Exit Code**: Must be 0 (success)
+- [ ] **Check Output**: All tests must pass (not just "some tests pass")
+- [ ] **Document Results**: Include actual test output in review evidence
+
+#### Integration Tests
+- [ ] **Count Required**: How many integration tests does RFC specify?
+- [ ] **Count Found**: How many integration test files exist?
+- [ ] **Verify Existence**: Check each listed test case exists
+- [ ] **Run Tests**: Execute integration tests with proper mocks
+- [ ] **Verify Service Interactions**: Check mocks validate service calls match design
+- [ ] **Verify Exit Code**: Must be 0 (success)
+- [ ] **Document Results**: Include actual test output in review evidence
+
+#### E2E Tests
+- [ ] **Count Required**: How many E2E tests does RFC specify?
+- [ ] **Count Found**: How many E2E test files exist?
+- [ ] **Verify Existence**: Check each listed test case exists
+- [ ] **Run Tests**: Execute E2E tests (may require server running)
+- [ ] **Verify End-to-End Flow**: Complete workflow must work
+- [ ] **Verify Exit Code**: Must be 0 (success)
+- [ ] **Document Results**: Include actual test output in review evidence
+
+**If test matrix says "X test cases" but only Y exist:**
+- ❌ BLOCKER: Missing test cases
+- Must identify which tests are missing (list specific test names)
+- Cannot approve until all tests from matrix exist and pass
+
+**Document findings:**
+- Create table: Test Type | Required | Found | Passing | Evidence | Missing Tests
+
+#### Test Quality Validation (Anti-Pattern Detection)
+**🚨 CRITICAL: Verify tests validate runtime behavior, not code structure**
+
+**For each test file found (test-{issue}-*.ts):**
+- [ ] **Check for Static Analysis Anti-Pattern**: Verify tests don't use `fs.readFileSync()` for code structure checks
+  - Check: `grep -E "fs\.readFileSync|readFileSync" test-{issue}-*.ts`
+  - ❌ BLOCKER if found - tests are doing static analysis, not runtime testing
+  - Expected: Tests should execute code, not read source files
+  - Reference: `retrospectives/issue-723-weak-test-validation-anti-pattern-postmortem.md`
+- [ ] **Verify Runtime Behavior Testing**: Check tests actually execute code paths
+  - Review test code to ensure it calls actual functions/services
+  - Verify tests check observable outcomes (API responses, database state, logs)
+  - ❌ BLOCKER if tests only check code structure without execution
+- [ ] **Check for Mock Anti-Pattern**: Verify tests don't mock the core functionality being tested
+  - Check: Are mocks used for dependencies (✅) or for the thing being tested (❌)?
+  - ❌ BLOCKER if core functionality is mocked
+  - Expected: Mock dependencies, test actual implementation
+- [ ] **Verify State Validation**: Check tests validate state changes
+  - Tests should check database state, API responses, or service interactions
+  - ❌ BLOCKER if tests don't validate any state changes
+  - Expected: Tests verify before/after state or observable outcomes
+
+**Document findings:**
+- Create table: Test File | Static Analysis Check | Runtime Behavior | Mock Usage | State Validation | Status
+
+#### Regression Test Verification (For Bug Fixes)
+**If this is a bug fix (check RFC or issue description):**
+- [ ] **Identify Bug**: Understand what the bug was from RFC/issue
+- [ ] **Check for Regression Test**: Verify test file includes regression test for the bug
+  - Check test file for test case that reproduces the bug
+  - Test should be named something like "regression test for bug X" or similar
+- [ ] **Verify Test Pattern**: Regression test must follow correct pattern
+  - ❌ BLOCKER if test passes/fails regardless of bug (wrong pattern)
+  - ✅ CORRECT: Test fails with bug → Test passes with fix
+  - ❌ WRONG: Test passes with bug AND with fix (doesn't reproduce bug)
+  - ❌ WRONG: Test fails with bug AND with fix (environmental issue)
+- [ ] **Verify Test Behavior** (if possible):
+  - Ideally: Revert fix temporarily, run test → should fail
+  - Reapply fix, run test → should pass
+  - If not possible, verify test logic would fail with buggy code
+
+**Document findings:**
+- Bug Fix: ✅ Yes / ❌ No
+- Regression Test: ✅ Found / ❌ Missing
+- Test Pattern: ✅ Correct (fails with bug, passes with fix) / ❌ Wrong pattern
+- Notes: [Any issues with regression test]
+
+### Step 4.5: Common Error Pattern Checks
+**🚨 CRITICAL: Check for common test and code quality issues**
+
+#### Test Structure Validation
+**For each test file found (test-{issue}-*.ts):**
+- [ ] **BaseTestCase Extension**: Verify test cases extend `BaseTestCase` interface
+  - Check: `grep -E "extends BaseTestCase|interface.*extends BaseTestCase" test-{issue}-*.ts`
+  - ❌ BLOCKER if test cases don't extend BaseTestCase
+  - Expected pattern: `interface MyTestCase extends BaseTestCase { ... }`
+  - All test case objects must use interface that extends BaseTestCase
+- [ ] **Main Function**: Verify test file has `main()` function
+  - Check: `grep -E "async function main\(\)|function main\(\)" test-{issue}-*.ts`
+  - ❌ BLOCKER if main() function missing
+  - Expected pattern: `async function main() { ... runTests(...) }`
+  - Must have `main().catch(console.error)` at end of file
+- [ ] **runTests Usage**: Verify test file uses `runTests()` function
+  - Check: `grep "runTests" test-{issue}-*.ts`
+  - ❌ BLOCKER if runTests() not used
+  - Expected: `runTests(TEST_CASES, runMyTest, 'Test Suite Name')`
+  - Must import runTests from './test-utils' or './test-utils.ts'
+
+**Document findings:**
+- Create table: Test File | BaseTestCase | main() | runTests() | Status
+
+#### Code Quality Check
+- [ ] **Run Code Quality Check**: Fetch and execute the code quality script ephemerally.
+  - Command: `get_fraim_file({ path: "scripts/code-quality-check.sh" })` -> save to temp -> run with argument `pre-pr`
+  - Verify exit code is 0 (success)
+  - Check for critical failures (❌) vs warnings (⚠️)
+  - ❌ BLOCKER if critical checks fail (e.g., `as any` usage, TypeScript errors)
+  - ⚠️ WARNING if warnings exist (document in feedback)
+- [ ] **Review Quality Check Output**: 
+  - Check for `as any` type bypassing in src/
+  - Check TypeScript compilation passes
+  - Check linter passes (warnings acceptable, errors are blockers)
+  - Check all test files referenced in evidence have been executed
+
+**Document findings:**
+- Code Quality Check: ✅ Passed / ❌ Failed / ⚠️ Warnings
+- Critical Issues: [list any critical failures]
+- Warnings: [list any warnings]
+
+#### Evidence File Location Validation
+- [ ] **Check Evidence Files**: Verify evidence files are ONLY in `docs/evidence/` folder
+  - Check: `find . -name "*evidence*.md" -not -path "./docs/evidence/*" -not -path "./.git/*" -not -path "./node_modules/*"`
+  - ❌ BLOCKER if evidence files found outside `docs/evidence/`
+  - Expected: All evidence files should be in `docs/evidence/{issue}-*.md`
+- [ ] **Check for Evidence in Git**: Verify evidence folder is gitignored
+  - Check: `git check-ignore docs/evidence/` should return `docs/evidence/`
+  - ⚠️ WARNING if evidence folder not in .gitignore (should be gitignored)
+- [ ] **Check PR for Evidence Files**: Verify no evidence files committed to repo
+  - Check git status for any files in docs/evidence/
+  - ❌ BLOCKER if evidence files are staged/committed
+
+**Document findings:**
+- Evidence Location Check: ✅ All in docs/evidence/ / ❌ Found outside
+- Git Ignore Check: ✅ Ignored / ⚠️ Not ignored
+- Committed Evidence: ✅ None / ❌ Found in commits
+
+**If any blockers found:**
+- ❌ BLOCKER: Must fix before approval
+- List specific files and issues
+- Cannot approve until all blockers resolved
+
+### Step 5: Validation Plan Execution
+**For each validation scenario in RFC Validation Plan:**
+- [ ] **Scenario Identified**: Map each scenario from validation plan
+- [ ] **Evidence Found**: Check PR evidence for scenario validation
+  - Look in PR comments for evidence
+  - Check for screenshots, curl outputs, test results
+  - Verify evidence shows actual execution (not just "tested")
+- [ ] **Method Verified**: Ensure validation method matches (UI, API, DB, etc.)
+  - If RFC says "API validation", check for curl/Postman results
+  - If RFC says "Browser validation", check for screenshots/recordings
+  - If RFC says "Database validation", check for DB query results
+- [ ] **Result Verified**: Ensure scenario actually passes (not just "tested")
+  - Check evidence shows success, not just attempt
+  - Verify no "pending" or "TODO" markers
+
+**If validation plan has 10 scenarios but only 7 have evidence:**
+- ❌ BLOCKER: Missing validation evidence
+- Must identify which scenarios are missing (list specific scenario names)
+- Cannot approve until all scenarios validated with evidence
+
+**Document findings:**
+- Create table: Scenario | Method | Evidence | Status | Missing Evidence
+
+### Step 6: Architecture Compliance Check
+**Verify implementation matches design:**
+- [ ] Service boundaries match design
+  - Check service files match design boundaries
+  - Verify no cross-boundary violations
+- [ ] Patterns match design (e.g., spike-first, deterministic separation)
+  - Check code follows patterns specified in RFC
+  - Verify no anti-patterns introduced
+- [ ] Dependencies match design
+  - Check package.json matches design dependencies
+  - Verify no unexpected dependencies added
+- [ ] No over-engineering beyond design scope
+  - Check code doesn't add features not in RFC
+  - Verify minimal implementation (not over-engineered)
+
+**Document findings:**
+- List any architecture deviations
+- Note if deviations are acceptable or blockers
+
+### Step 7: Risk Mitigation Verification
+**For each risk in RFC Risks & Mitigations:**
+- [ ] Verify mitigation is implemented
+  - Check code implements mitigation strategy
+  - Verify mitigation code exists and is not just commented
+- [ ] Check mitigation actually addresses the risk
+  - Verify mitigation logic matches risk description
+  - Check mitigation is complete (not partial)
+- [ ] Verify observability for risk detection
+  - Check logs/alerts exist for risk scenarios
+  - Verify monitoring is in place
+
+**Document findings:**
+- Create table: Risk | Mitigation Status | Implementation Location | Notes
+
+### Step 8: Evidence Quality Review
+**Verify PR evidence quality:**
+- [ ] All test outputs included (not just "tests pass")
+  - Check for actual test command output
+  - Verify exit codes shown
+  - Check for test case names and results
+- [ ] All validation scenarios documented with results
+  - Check each scenario has evidence
+  - Verify evidence shows actual execution
+- [ ] No "pending" items that could be validated automatically
+  - Flag any "pending" items that could be tested
+  - Check for "TODO" or "needs manual validation" markers
+- [ ] Build verification included
+  - Check for `npm run build` output
+  - Verify build succeeds
+- [ ] Quality gate results included
+  - Check for quality gate script output
+  - Verify all gates pass (or warnings documented)
+
+**Document findings:**
+- List any evidence quality issues
+- Note if evidence is sufficient or needs improvement
+
+### Step 9: Review Decision and Feedback Creation
+
+**Check Iteration Count:**
+- If `docs/evidence/{issue}-design-reviewer-feedback.md` exists, check iteration number
+- Maximum 3 iterations allowed
+- If iteration 3 and still issues: ❌ REJECT (max iterations reached)
+
+**Options:**
+- ✅ **APPROVE**: All requirements met, tests pass, evidence complete
+- ❌ **REJECT**: Missing requirements, tests fail, or evidence incomplete (after max iterations)
+- ⚠️ **REQUEST CHANGES**: Minor gaps that need addressing (iteration < 3)
+
+**If REQUEST CHANGES (iteration < 3):**
+- **Create Feedback Document**: Create `docs/evidence/{issue}-design-reviewer-feedback.md`
+  - Use template below for feedback structure
+  - List specific blockers with evidence locations
+  - Provide actionable feedback for each issue
+  - Include iteration number
+- Label issue `status:wip` (remove `status:needs-review`)
+- Add PR comment referencing feedback document
+- Implementation agent must address feedback and update evidence
+- Implementation agent re-submits by marking `status:needs-review` again
+
+**If REJECT (max iterations reached):**
+- Create final feedback document with all remaining issues
+- Label issue `status:wip` (remove `status:needs-review`)
+- Add PR comment with final rejection notice
+- Implementation agent must address all issues before re-submission
+
+**If APPROVE:**
+- **Create Summary for Feature Spec Review**: Create `docs/evidence/{issue}-design-review-summary.md`
+  - Summarize what was reviewed and approved
+  - Include key findings and evidence locations
+  - Provide context for feature spec review agent
+- Label issue `status:design-review-passed` (remove `status:needs-review`)
+- Add PR comment confirming design spec compliance
+- Issue ready for Feature Spec Review (next workflow)
+
+## FEEDBACK DOCUMENT TEMPLATE
+
+Create `docs/evidence/{issue}-design-reviewer-feedback.md`:
+
+```markdown
+# Design Review Feedback - Issue #{issue}
+
+## Iteration Information
+- Iteration Number: {1, 2, or 3}
+- Review Date: {date}
+- Reviewer: Design Spec Review Agent
+
+## Review Summary
+- RFC Location: `docs/rfcs/{issue}-*.md`
+- Evidence Reviewed: `docs/evidence/{issue}-implementation-evidence.md`
+- Overall Status: ⚠️ REQUEST CHANGES
+
+## Issues Found
+
+### Critical Blockers (Must Fix)
+1. **Issue Title**
+   - **Location**: `src/file.ts:line`
+   - **Problem**: [Specific problem description]
+   - **Expected**: [What RFC requires]
+   - **Found**: [What implementation has]
+   - **Action Required**: [Specific fix needed]
+
+2. **Issue Title**
+   - [Same structure]
+
+### Missing Requirements
+1. **Requirement Name**
+   - **RFC Section**: [Section reference]
+   - **What's Missing**: [Specific requirement]
+   - **Action Required**: [What needs to be implemented]
+
+### Test Matrix Issues
+1. **Missing Test**: Test case name
+   - **RFC Test Matrix**: [Reference]
+   - **Action Required**: Create test file `test-{issue}-*.ts` with test case
+
+### Test Structure Issues (Common Error Patterns)
+1. **Test Not Extending BaseTestCase**: `test-{issue}-*.ts`
+   - **Problem**: Test case interface doesn't extend BaseTestCase
+   - **Expected**: `interface MyTestCase extends BaseTestCase { ... }`
+   - **Action Required**: Update test case interface to extend BaseTestCase
+
+2. **Missing main() Function**: `test-{issue}-*.ts`
+   - **Problem**: Test file doesn't have main() function
+   - **Expected**: `async function main() { ... runTests(...) }` with `main().catch(console.error)`
+   - **Action Required**: Add main() function that calls runTests()
+
+3. **Not Using runTests()**: `test-{issue}-*.ts`
+   - **Problem**: Test file doesn't use runTests() function
+   - **Expected**: Import runTests from './test-utils' and call it in main()
+   - **Action Required**: Refactor to use runTests() function
+
+### Test Quality Issues (Anti-Patterns)
+1. **Static Analysis Anti-Pattern**: `test-{issue}-*.ts`
+   - **Problem**: Tests use `fs.readFileSync()` to check code structure instead of runtime behavior
+   - **Expected**: Tests should execute code and validate outcomes, not read source files
+   - **Action Required**: Rewrite tests to validate runtime behavior
+   - **Reference**: `retrospectives/issue-723-weak-test-validation-anti-pattern-postmortem.md`
+
+2. **No Runtime Behavior Validation**: `test-{issue}-*.ts`
+   - **Problem**: Tests don't execute actual code paths or validate observable outcomes
+   - **Expected**: Tests should call functions/services and check results
+   - **Action Required**: Add runtime behavior validation to tests
+
+3. **Mocking Core Functionality**: `test-{issue}-*.ts`
+   - **Problem**: Tests mock the thing being tested instead of dependencies
+   - **Expected**: Mock dependencies, test actual implementation
+   - **Action Required**: Refactor mocks to only mock dependencies
+
+4. **No State Validation**: `test-{issue}-*.ts`
+   - **Problem**: Tests don't validate state changes (database, API responses, etc.)
+   - **Expected**: Tests should verify before/after state or observable outcomes
+   - **Action Required**: Add state validation to tests
+
+### Regression Test Issues (For Bug Fixes)
+1. **Missing Regression Test**: `test-{issue}-*.ts`
+   - **Problem**: Bug fix doesn't have regression test
+   - **Expected**: Regression test that fails with bug, passes with fix
+   - **Action Required**: Add regression test following correct pattern
+
+2. **Wrong Regression Test Pattern**: `test-{issue}-*.ts`
+   - **Problem**: Test passes/fails regardless of bug (doesn't reproduce bug)
+   - **Expected**: Test fails with bug → Test passes with fix
+   - **Action Required**: Fix regression test to follow correct pattern
+   - **Reference**: `retrospectives/task-api-calendar-event-id-bug-postmortem.md`
+
+### Code Quality Issues
+1. **Code Quality Check Failed**: [Specific issue]
+   - **Problem**: [What failed - e.g., "as any" usage, TypeScript errors]
+   - **Action Required**: Fix code quality issues and re-run check
+   - **Command**: Run quality check (fetch `scripts/code-quality-check.sh` via `get_fraim_file`)
+
+### Evidence File Location Issues
+1. **Evidence File Outside docs/evidence/**: [File path]
+   - **Problem**: Evidence file found outside `docs/evidence/` folder
+   - **Expected**: All evidence files should be in `docs/evidence/{issue}-*.md`
+   - **Action Required**: Move evidence file to `docs/evidence/` folder
+
+### Validation Plan Issues
+1. **Missing Validation**: Scenario name
+   - **RFC Validation Plan**: [Reference]
+   - **Action Required**: Execute validation and add evidence
+
+### Evidence Quality Issues
+1. **Missing Evidence**: [What's missing]
+   - **Action Required**: [What evidence needs to be added]
+
+## Action Items for Implementation Agent
+- [ ] Fix critical blocker 1
+- [ ] Fix critical blocker 2
+- [ ] Implement missing requirement X
+- [ ] Add missing test case Y
+- [ ] Execute missing validation Z
+- [ ] Update evidence document with fixes
+
+## Next Steps
+1. Implementation agent addresses all feedback items
+2. Implementation agent updates `docs/evidence/{issue}-implementation-evidence.md`
+3. Implementation agent marks issue `status:needs-review` again
+4. Design review agent will re-review (iteration {next_number})
+```
+
+## SUMMARY DOCUMENT TEMPLATE (For Feature Spec Review)
+
+Create `docs/evidence/{issue}-design-review-summary.md` when approving:
+
+```markdown
+# Design Review Summary - Issue #{issue}
+
+## Review Outcome
+- Status: ✅ APPROVED
+- Iterations: {number} (1-3)
+- RFC Location: `docs/rfcs/{issue}-*.md`
+
+## What Was Reviewed
+- Technical Requirements: X/Y implemented ✅
+- Test Matrix: All test cases exist and pass ✅
+- Validation Plan: All scenarios validated ✅
+- Architecture: Matches design ✅
+- Risk Mitigations: All implemented ✅
+
+## Key Findings
+- All RFC requirements implemented correctly
+- All tests from test matrix exist and pass
+- All validation scenarios executed with evidence
+- Architecture follows design decisions
+- No over-engineering detected
+
+## Evidence Locations
+- Implementation Evidence: `docs/evidence/{issue}-implementation-evidence.md`
+- Test Results: [locations]
+- Validation Evidence: [locations]
+
+## Notes for Feature Spec Review
+- Technical implementation is complete and correct
+- All technical requirements met
+- Ready for functional/user experience validation
+- No technical blockers for feature spec review
+```
+
+## REVIEW EVIDENCE TEMPLATE (PR Comment)
+
+Add this as a PR comment:
+
+```markdown
+# Design Spec Review - Issue #{issue}
+
+## RFC Compliance Summary
+- RFC Location: `docs/rfcs/{issue}-*.md`
+- Technical Requirements: X/Y implemented ✅/❌
+- Test Matrix Compliance: X/Y test types complete ✅/❌
+- Validation Plan Coverage: X/Y scenarios validated ✅/❌
+- Architecture Compliance: ✅/❌
+- Risk Mitigations: X/Y implemented ✅/❌
+
+## Detailed Findings
+
+### Technical Requirements
+| Requirement | Status | Evidence Location | Notes |
+|------------|--------|-------------------|-------|
+| API endpoint X | ✅ | `src/api/...` | Matches RFC |
+| Schema change Y | ❌ | Missing | RFC requires Z field |
+
+### Test Matrix Validation
+| Test Type | Required | Found | Passing | Evidence | Missing Tests |
+|-----------|----------|-------|---------|----------|---------------|
+| Unit Tests | 5 | 5 | ✅ | `test-{issue}.ts` lines 10-50 | None |
+| Integration | 3 | 2 | ❌ | Partial | Missing test for scenario Z |
+| E2E | 1 | 0 | ❌ | Not found | E2E test not implemented |
+
+### Test Quality Validation
+| Test File | Static Analysis | Runtime Behavior | Mock Usage | State Validation | Status |
+|-----------|----------------|-------------------|------------|------------------|--------|
+| test-{issue}.ts | ✅ No fs.readFileSync | ✅ Executes code | ✅ Mocks dependencies | ✅ Validates state | ✅ Pass |
+| test-{issue}-2.ts | ❌ Uses fs.readFileSync | ❌ No execution | ❌ Mocks core | ❌ No validation | ❌ Fail |
+
+### Regression Test Verification (If Bug Fix)
+- Bug Fix: ✅ Yes / ❌ No
+- Regression Test: ✅ Found / ❌ Missing
+- Test Pattern: ✅ Correct (fails with bug, passes with fix) / ❌ Wrong pattern
+- Notes: [Any issues with regression test]
+
+### Validation Plan Coverage
+| Scenario | Method | Evidence | Status | Missing Evidence |
+|----------|--------|----------|--------|------------------|
+| Create operation | API | PR comment | ✅ | None |
+| Update operation | API | Missing | ❌ | No curl output found |
+
+### Architecture Compliance
+- Service Boundaries: ✅ Match design
+- Patterns: ✅ Follow design patterns
+- Dependencies: ⚠️ Extra dependency X added (not in RFC)
+- Over-engineering: ✅ Minimal implementation
+
+### Risk Mitigations
+| Risk | Mitigation Status | Implementation Location | Notes |
+|------|-------------------|-------------------------|-------|
+| Risk X | ✅ Implemented | `src/...` | Matches design |
+| Risk Y | ❌ Missing | N/A | Not implemented |
+
+### Common Error Pattern Checks
+- Test Structure: ✅ All tests extend BaseTestCase / ❌ Issues found
+- Main Functions: ✅ All tests have main() / ❌ Missing in some tests
+- runTests Usage: ✅ All tests use runTests() / ❌ Not used in some tests
+- Code Quality Check: ✅ Passed / ❌ Failed / ⚠️ Warnings
+- Evidence Location: ✅ All in docs/evidence/ / ❌ Found outside
+
+### Evidence Quality
+- Test Outputs: ✅ Complete (all test results included)
+- Validation Evidence: ⚠️ Partial (missing scenario Y evidence)
+- Build Verification: ✅ Included
+- Quality Gate: ✅ Passed
+
+## Decision
+✅ APPROVE / ❌ REJECT / ⚠️ REQUEST CHANGES
+
+## Feedback Document
+- Location: `docs/evidence/{issue}-design-reviewer-feedback.md`
+- Iteration: {1, 2, or 3}
+
+## Blockers (if any)
+1. Missing test case for scenario X (RFC Test Matrix requires it)
+2. Validation scenario Y not executed (RFC Validation Plan requires it)
+3. Technical requirement Z not implemented (RFC Technical Details requires it)
+
+## Next Steps (if REQUEST CHANGES)
+- [ ] Implementation agent addresses feedback in `docs/evidence/{issue}-design-reviewer-feedback.md`
+- [ ] Implementation agent updates `docs/evidence/{issue}-implementation-evidence.md`
+- [ ] Implementation agent marks `status:needs-review` for re-review
+- [ ] Design review agent will re-review (max 3 iterations)
+```
+
+## EXAMPLES
+
+### Good: Complete Review
+```
+Issue #533: Design Spec Review
+✅ RFC Compliance: 15/15 requirements implemented
+✅ Test Matrix: All 8 test cases exist and pass
+✅ Validation Plan: All 5 scenarios validated
+✅ Architecture: Matches design
+✅ Evidence: Complete with test outputs
+Decision: ✅ APPROVE
+```
+
+### Bad: Incomplete Review
+```
+Issue #533: Design Spec Review
+⚠️ RFC Compliance: 12/15 requirements (3 missing)
+❌ Test Matrix: 5/8 test cases exist (3 missing)
+⚠️ Validation Plan: 3/5 scenarios validated (2 missing)
+Decision: ❌ REJECT
+Blockers: Missing tests, missing validations
+```
+
+## INTEGRATION
+
+### Status Label Flow
+```
+phase:impl + status:needs-review
+  ↓ (Design Spec Review)
+status:design-review-passed (or status:wip if rejected)
+  ↓ (Feature Spec Review - next workflow)
+status:feature-review-passed
+```
+
+### After This Review
+- If APPROVE: Issue moves to Feature Spec Review
+- If REJECT: Issue returns to implementation (status:wip)
+- Implementation agent addresses blockers and re-submits