fraim-framework 2.0.67 → 2.0.69

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

@@ -1,734 +0,0 @@
-# Review Implementation vs Feature Spec
-
-## INTENT
-To systematically verify that the implementation solves the customer problem and delivers the user experience described in the feature spec, ensuring **completeness**, **correctness**, and **quality** of functional requirements and user value.
-
-## PRINCIPLES
-- **Completeness First**: Verify ALL feature spec components are implemented before checking correctness
-- **User-Centric Validation**: Every user scenario must work as specified
-- **Problem-Solution Fit**: Implementation must solve the customer problem
-- **Experience Fidelity**: UI/UX must match feature spec and mocks
-- **Validation Plan Execution**: All validation methods must be executed
-- **End-to-End Testing**: Complete user workflows must be validated with authentication
-- **Quality Standards**: User experience must meet quality, usability, and documentation standards
-
-{{include:orchestration/independent-reviewer-guidance.md}}
-
-## REVIEW WORKFLOW
-
-### Step 1: Issue Identification and Evidence Loading
-- Get {issue_number} from context
-
-- Verify issue has `status:design-review-passed` label
-- Locate feature spec: `docs/feature specs/{issue}-*.md`
-- If feature spec doesn't exist: ⚠️ Check if this is a bug fix (may not have feature spec). If feature, BLOCKER - request spec phase first.
-- **Load Design Review Summary**: Read `docs/evidence/{issue}-design-review-summary.md`
-  - If summary doesn't exist: ❌ BLOCKER - Design review must complete first
-  - Review summary to understand what was approved in design review
-- **Load Implementation Evidence**: Read `docs/evidence/{issue}-implementation-evidence.md`
-  - Review evidence for functional/user experience aspects
-- **Check for Existing Feedback**: Check if `docs/evidence/{issue}-feature-reviewer-feedback.md` exists
-  - If exists, this is an iteration (check iteration count)
-  - Track iteration number (max 3 iterations)
-
-### Step 2: Feature Spec Completeness Check
-
-**CRITICAL**: Before checking functional correctness, verify ALL feature spec components are addressed.
-
-#### 2.1: Extract Full Feature Spec Scope
-**Read the ENTIRE feature spec and extract**:
-- All user experience workflow steps
-- All UI components/screens described
-- All user interactions specified
-- All validation methods from Validation Plan
-- All UI mocks (if applicable)
-- All acceptance criteria
-- All alternatives considered (verify chosen approach implemented)
-
-#### 2.2: Create Completeness Checklist
-**Format**:
-```markdown
-## Feature Spec Completeness Checklist
-
-### User Experience Workflow
-- [ ] Step 1: [description from spec] - [UI/interaction]
-- [ ] Step 2: [description from spec] - [UI/interaction]
-- [ ] Step 3: [description from spec] - [UI/interaction]
-
-### UI Components (if applicable)
-- [ ] Screen/Component: [name] - [description from spec]
-- [ ] Screen/Component: [name] - [description from spec]
-
-### Validation Methods
-- [ ] Method 1: [description from Validation Plan]
-- [ ] Method 2: [description from Validation Plan]
-
-### Acceptance Criteria
-- [ ] Criterion 1: [description]
-- [ ] Criterion 2: [description]
-
-**Total Items**: X
-```
-
-#### 2.3: Verify Each Item
-**For each checklist item**:
-- ✅ **Implemented**: Point to code/UI/test files that implement it
-- ⏸️ **Deferred**: Check if follow-up issue exists and is documented
-- ❌ **Missing**: BLOCKER - must be implemented or explicitly deferred
-
-#### 2.4: Calculate Completeness
-```
-Implemented: X/Y items (Z%)
-Deferred: A items (with follow-up issues #123, #456)
-Missing: B items (BLOCKER if >0 without follow-up issues)
-```
-
-**If completeness <100%**:
-- ❌ REQUEST CHANGES - List all missing items
-- Require either implementation or explicit deferral with follow-up issues
-- Do NOT proceed to correctness checks until completeness is 100%
-
-### Step 3: Feature Spec Analysis (Correctness Check)
-
-**ONLY proceed here if Step 2 shows 100% completeness**
-
-**MUST read and extract:**
-- Customer problem statement
-- Customer's desired outcome
-- User experience workflow (step-by-step)
-- Validation Plan (all validation methods)
-- UI mocks (if applicable): `docs/feature specs/mocks/{issue}-*.png` (or similar)
-- Alternatives considered (verify chosen approach)
-
-**Create a correctness checklist mapping:**
-- List each step in user experience workflow
-- List each validation method from Validation Plan
-- List each UI mock element (if applicable)
-- This becomes your correctness review checklist
-
-### Step 4: Customer Problem Verification (Correctness Check)
-**Verify implementation solves the problem:**
-- [ ] Read customer problem statement from spec
-- [ ] Understand desired outcome from spec
-- [ ] Verify implementation addresses the problem
-  - Check code solves the stated problem
-  - Verify solution matches desired outcome
-- [ ] Check if solution matches chosen alternative (if alternatives documented)
-  - Review alternatives table in spec
-  - Verify implementation matches chosen approach
-  - Note if different approach was used (and why)
-
-**Document findings:**
-- Problem Statement: [from spec]
-- Desired Outcome: [from spec]
-- Solution Status: ✅ Addresses problem / ❌ Doesn't address problem
-- Notes: [any concerns or deviations]
-
-### Step 3.5: Authentication Setup for End-to-End Testing
-**🚨 CRITICAL: Set up authentication before testing user workflows**
-
-**Determine if authentication is needed:**
-- [ ] Check if user experience workflow requires authentication
-- [ ] Check if validation plan includes browser/UI validation
-- [ ] Check if feature requires logged-in user state
-
-**If authentication is needed, choose one approach:**
-
-#### Option A: Request Credentials (if applicable)
-- [ ] **When to use**: If OAuth/SSO automation is not possible or if testing requires specific test accounts
-- [ ] Ask user: "I need credentials to test the end-to-end user workflow. Please provide:"
-  - Username/email
-  - Password (or test account credentials)
-  - Any additional auth requirements (2FA, etc.)
-- [ ] Store credentials securely (do not commit to repo)
-- [ ] Use credentials to authenticate during testing
-- [ ] Document: "Using provided credentials for end-to-end testing"
-
-#### Option B: Cookie-Driven Browser Session (preferred for UI features)
-- [ ] **When to use**: For UI features that require authentication - this is the preferred method
-- [ ] Ask user: "I need to test the end-to-end user workflow. Please log in to the application in a browser session I can access, so I can validate the complete user experience. Once you're logged in, I'll use that session for all my validations."
-- [ ] **Wait for user confirmation**: User logs in manually (complies with OAuth ToS, avoids bot detection)
-- [ ] **Verify login state**: 
-  - Navigate to application URL
-  - Check for authenticated state (user menu, profile icon, etc.)
-  - Take snapshot to verify login succeeded
-- [ ] **Session persistence**: 
-  - Browser MCP tools automatically maintain cookies between invocations
-  - Or use Playwright with `storageState` to save/load auth state
-  - Session persists for all subsequent validations
-- [ ] Document: "Using cookie-driven browser session for end-to-end testing (user logged in manually)"
-
-**Browser Session Setup (if using Option B):**
-
-**Using Browser MCP Tools (if available):**
-- Browser MCP tools (like `browser_navigate`, `browser_snapshot`) automatically maintain session state
-- Cookies persist between browser invocations
-- User logs in once, agent can reuse session for all validations
-- Reference: Read `workflows/customer-development/linkedin-outreach.md` (via `get_fraim_file`) to see this pattern
-- **Process**:
-  1. Use `browser_navigate` to open application
-  2. Use `browser_snapshot` to check if already logged in
-  3. If not logged in, ask user to log in manually
-  4. Use `browser_wait_for` to detect login success (e.g., wait for "Dashboard" text)
-  5. Verify with `browser_snapshot` - should see authenticated UI elements
-  6. Session automatically persists for future browser operations
-
-**Using Playwright (if MCP tools not available):**
-- Use Playwright with `storageState` to save/load authentication
-- Reference: Look for authentication setup and Playwright configuration in the project's test files.
-- **Process**:
-  1. Launch browser: `chromium.launch()`
-  2. Create context: `browser.newContext()`
-  3. Navigate to application
-  4. Ask user to log in manually in the browser window
-  5. Wait for login success (check URL or UI elements)
-  6. Save auth state: `context.storageState({ path: 'auth-state.json' })`
-  7. Reuse auth state in future: `browser.newContext({ storageState: 'auth-state.json' })`
-
-**Setup Steps (General):**
-1. Ask user: "I need to test the end-to-end user workflow. Please log in to the application now. I'll wait for you to complete the login."
-2. Wait for user confirmation that login is complete
-3. Verify login: Navigate to authenticated page, check for user menu/profile/authenticated UI
-4. Document: "Using authenticated browser session for end-to-end validation (user logged in manually)"
-5. Reuse session for all subsequent workflow validations
-6. Take screenshots at key validation points to show authenticated state
-
-**Verification:**
-- [ ] Test authentication works: Navigate to protected page
-- [ ] Verify user is logged in (check for user menu, profile, etc.)
-- [ ] Confirm session persists across multiple page navigations
-- [ ] Document authentication method used in review evidence
-
-**If authentication setup fails:**
-- [ ] Document what prevented authentication
-- [ ] Ask user for alternative approach
-- [ ] Note in review: "End-to-end testing limited due to authentication setup"
-- [ ] Proceed with available validation methods
-
-### Step 4: User Experience Validation
-**For each step in the user experience workflow:**
-
-- [ ] **Step Identified**: Map each workflow step from spec
-- [ ] **Implementation Verified**: Check code implements the step
-  - Search codebase for relevant code
-  - Verify UI components exist (if UI feature)
-  - Verify API endpoints exist (if API feature)
-- [ ] **Functionality Tested**: Actually test the step (browser, API, etc.)
-  - Use authenticated browser session (from Step 3.5)
-  - Navigate through workflow step-by-step
-  - Verify each step works as described
-- [ ] **Result Verified**: Ensure step works as described
-  - Check actual behavior matches spec description
-  - Verify data appears correctly (not just UI renders)
-  - Take screenshots at key points
-
-**Example for UI feature (with authentication):**
-- Step: "User clicks on tab X"
-  - [ ] Verify tab X exists in UI code
-  - [ ] **Use authenticated browser session** (from Step 3.5)
-  - [ ] Navigate to page, click tab X
-  - [ ] Verify tab X actually works (not just exists)
-  - [ ] Take screenshot for evidence
-- Step: "User sees list Y"
-  - [ ] Verify list Y is rendered
-  - [ ] **Use authenticated browser session** to check list Y
-  - [ ] Check list Y shows correct data (verify data matches expected)
-  - [ ] Verify list Y matches spec description
-  - [ ] Take screenshot showing list Y with data
-
-**Example for API feature:**
-- Step: "Call API A with params X, Y, Z"
-  - [ ] Verify API endpoint exists
-  - [ ] Test with curl: `curl -X POST /api/a -d '{"x":..., "y":..., "z":...}'`
-  - [ ] Verify response matches expected outcome
-  - [ ] Include curl output in evidence
-
-**Document findings:**
-- Create table: Step | Description | Status | Evidence | Notes
-
-### Step 5: UI Mock Compliance (if applicable)
-**If feature spec includes UI mocks:**
-- [ ] Locate mocks: `docs/feature specs/mocks/{issue}-*.png` (or similar)
-- [ ] Compare implementation to mocks
-  - Open implementation in browser (with authentication)
-  - Compare layout to mock
-  - Compare components to mock
-  - Compare interactions to mock
-- [ ] Verify layout matches
-  - Check positioning, spacing, colors
-  - Verify responsive behavior (if specified)
-- [ ] Verify components match
-  - Check all components from mock exist
-  - Verify component styling matches
-- [ ] Verify interactions match
-  - Test interactions described in spec
-  - Verify behavior matches mock expectations
-- [ ] Document any intentional deviations with rationale
-  - Note if deviations are acceptable
-  - Explain why deviations exist
-
-**Document findings:**
-- Create table: Mock Element | Spec | Implementation | Match | Notes
-
-### Step 6: Validation Plan Execution
-**For each validation method in feature spec Validation Plan:**
-- [ ] **Method Identified**: Map each validation method from spec
-- [ ] **Execution Verified**: Check evidence shows method was executed
-  - Look in PR evidence for validation results
-  - Check for screenshots, curl outputs, test results
-- [ ] **Result Verified**: Ensure validation actually passed
-  - Check evidence shows success, not just attempt
-  - Verify no "pending" or "TODO" markers
-- [ ] **Evidence Quality**: Verify evidence is complete (screenshots, curl output, etc.)
-  - Screenshots for UI validation
-  - Curl outputs for API validation
-  - Database queries for data validation
-
-**Validation methods typically include:**
-- Browser validation (UI testing) - **REQUIRES authentication if feature needs login**
-- API validation (curl/Postman) - May require auth tokens
-- Database validation (check data state)
-- User workflow validation (end-to-end) - **REQUIRES full authentication setup**
-
-**For browser/UI validation with authentication:**
-- [ ] Use authenticated browser session from Step 3.5
-- [ ] Navigate through complete user workflow
-- [ ] Verify each step works as described in spec
-- [ ] Take screenshots at key points
-- [ ] Verify data appears correctly (not just UI renders)
-- [ ] Test error states if applicable
-- [ ] Document any issues found during end-to-end testing
-
-**Document findings:**
-- Create table: Validation Method | Required | Executed | Result | Evidence | Auth Status
-
-### Step 7: Edge Cases, Negative Cases, and Error Handling
-**🚨 CRITICAL: Validate both positive and negative scenarios**
-
-#### Positive Case Validation (Already in Step 4)
-- [ ] All user workflow steps work (from Step 4)
-- [ ] Success states work correctly
-
-#### Negative Case Validation (What Shouldn't Work)
-**For each user workflow step, test negative scenarios:**
-- [ ] **Invalid Input Handling**: Test with invalid/malformed inputs
-  - Example: Empty fields, wrong data types, out-of-range values
-  - Verify feature rejects invalid inputs gracefully
-  - Verify error messages are clear and actionable
-- [ ] **Unauthorized Access**: Test with wrong permissions/authentication
-  - Example: Try to access feature without login (if required)
-  - Example: Try to access another user's data
-  - Verify proper error handling (401, 403, etc.)
-- [ ] **Missing Data Scenarios**: Test with missing required data
-  - Example: Required fields not provided
-  - Example: Dependencies not set up
-  - Verify feature handles missing data gracefully
-- [ ] **Boundary Conditions**: Test at limits/edges
-  - Example: Maximum/minimum values, empty lists, null states
-  - Verify feature handles boundaries correctly
-- [ ] **Concurrent Operations**: Test simultaneous actions (if applicable)
-  - Example: Multiple users accessing same resource
-  - Verify no race conditions or data corruption
-
-**Document findings:**
-- Create table: Negative Scenario | Tested | Result | Error Handling | Notes
-
-#### Edge Cases from Spec
-- [ ] Review alternatives considered in spec
-  - Read alternatives table from spec
-  - Understand why chosen approach was selected
-- [ ] Verify chosen approach is implemented
-  - Check code matches chosen alternative
-  - Verify not using discarded alternatives
-- [ ] Check if edge cases from spec are handled
-  - Review spec for edge case mentions
-  - Verify edge cases are handled in code
-  - Test each edge case explicitly
-
-**Document findings:**
-- Create table: Edge Case | From Spec | Tested | Result | Notes
-
-#### Error Handling Validation
-- [ ] **Error Messages**: Verify error messages are user-friendly
-  - Test error scenarios and check messages
-  - Verify messages explain what went wrong
-  - Verify messages suggest how to fix (if applicable)
-- [ ] **Error States**: Verify error states match spec descriptions
-  - Check UI shows appropriate error states
-  - Verify error states don't break the UI
-  - Verify users can recover from errors
-- [ ] **Error Logging**: Verify errors are logged appropriately
-  - Check server logs for error details
-  - Verify errors don't expose sensitive information
-  - Verify errors are actionable for debugging
-
-**Document findings:**
-- Error Handling: ✅ User-friendly / ❌ Confusing
-- Error States: ✅ Match spec / ❌ Don't match
-- Error Logging: ✅ Appropriate / ❌ Missing or excessive
-
-### Step 8: Functional Completeness Check
-**Verify feature is functionally complete:**
-- [ ] All user workflow steps work
-  - Test complete workflow end-to-end
-  - Verify no broken steps
-- [ ] No broken links or missing functionality
-  - Check all links work
-  - Verify no 404s or missing pages
-- [ ] **Positive Cases Work**: Success scenarios function correctly
-  - Test all success paths
-  - Verify success feedback is clear
-  - Verify data is saved/updated correctly
-- [ ] **Negative Cases Handled**: Invalid inputs rejected gracefully
-  - Test invalid inputs (from Step 7)
-  - Verify proper error handling
-  - Verify no crashes or data corruption
-- [ ] **Edge Cases Handled**: Boundary conditions work correctly
-  - Test edge cases (from Step 7)
-  - Verify feature handles limits correctly
-  - Verify no unexpected behavior at boundaries
-- [ ] **Error Recovery**: Users can recover from errors
-  - Test error scenarios
-  - Verify users can retry or fix issues
-  - Verify no dead-end error states
-
-**Document findings:**
-- Positive Cases: ✅ All working / ❌ Some broken
-- Negative Cases: ✅ Handled gracefully / ❌ Not handled
-- Edge Cases: ✅ Handled / ❌ Issues found
-- Error Recovery: ✅ Users can recover / ❌ Dead-ends found
-
-### Step 9: Evidence Quality Review
-**Verify validation evidence quality:**
-- [ ] All validation methods have evidence
-  - Check each method from validation plan has evidence
-  - Verify evidence is complete
-- [ ] Evidence shows actual execution (not just "tested")
-  - Check for screenshots, curl outputs, test results
-  - Verify evidence shows real execution
-- [ ] Screenshots/recordings for UI features
-  - Check screenshots show actual UI
-  - Verify screenshots show authenticated state (if applicable)
-- [ ] API outputs for API features
-  - Check curl outputs are included
-  - Verify responses match expected
-- [ ] Database state for data features
-  - Check database queries/results included
-  - Verify data state matches expected
-
-**Document findings:**
-- List any missing evidence
-- Note if evidence quality is sufficient
-
-### Step 10: Review Decision and Feedback Creation
-
-**Check Iteration Count:**
-- If `docs/evidence/{issue}-feature-reviewer-feedback.md` exists, check iteration number
-- Maximum 3 iterations allowed
-- If iteration 3 and still issues: ❌ REJECT (max iterations reached)
-
-**Options:**
-- ✅ **APPROVE**: All user scenarios work, problem solved, evidence complete
-- ❌ **REJECT**: User scenarios broken, problem not solved, or evidence incomplete (after max iterations)
-- ⚠️ **REQUEST CHANGES**: Minor UX issues or missing validations (iteration < 3)
-
-**If REQUEST CHANGES (iteration < 3):**
-- **Create Feedback Document**: Create `docs/evidence/{issue}-feature-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:design-review-passed`)
-- Add PR comment referencing feedback document
-- Implementation agent must address feedback and update evidence
-- Implementation agent re-submits by marking `status:design-review-passed` again
-
-**If REJECT (max iterations reached):**
-- Create final feedback document with all remaining issues
-- Label issue `status:wip` (remove `status:design-review-passed`)
-- Add PR comment with final rejection notice
-- Implementation agent must address all issues before re-submission
-
-**If APPROVE:**
-- **Create Final Summary**: Create `docs/evidence/{issue}-feature-review-summary.md`
-  - Summarize what was reviewed and approved
-  - Include key findings and evidence locations
-  - Confirm feature is ready for merge
-- Label issue `status:feature-review-passed` (remove `status:design-review-passed`)
-- Add PR comment confirming feature spec compliance
-- Issue ready for final approval/merge
-
-## FEEDBACK DOCUMENT TEMPLATE
-
-Create `docs/evidence/{issue}-feature-reviewer-feedback.md`:
-
-```markdown
-# Feature Review Feedback - Issue #{issue}
-
-## Iteration Information
-- Iteration Number: {1, 2, or 3}
-- Review Date: {date}
-- Reviewer: Feature Spec Review Agent
-
-## Review Summary
-- Feature Spec Location: `docs/feature specs/{issue}-*.md`
-- Design Review Summary: `docs/evidence/{issue}-design-review-summary.md`
-- Evidence Reviewed: `docs/evidence/{issue}-implementation-evidence.md`
-- Overall Status: ⚠️ REQUEST CHANGES
-
-## Issues Found
-
-### Critical Blockers (Must Fix)
-1. **Issue Title**
-   - **Location**: [UI component, API endpoint, or workflow step]
-   - **Problem**: [Specific problem description]
-   - **Expected**: [What feature spec requires]
-   - **Found**: [What implementation has]
-   - **Action Required**: [Specific fix needed]
-
-2. **Issue Title**
-   - [Same structure]
-
-### User Experience Issues
-1. **Workflow Step**: Step name
-   - **Feature Spec Section**: [Section reference]
-   - **Problem**: [What doesn't work]
-   - **Action Required**: [What needs to be fixed]
-
-### UI Mock Compliance Issues
-1. **Mock Element**: Element name
-   - **Mock Location**: `docs/feature specs/mocks/{issue}-*.png`
-   - **Problem**: [What doesn't match]
-   - **Action Required**: [What needs to be updated]
-
-### Validation Plan Issues
-1. **Missing Validation**: Method name
-   - **Feature Spec Validation Plan**: [Reference]
-   - **Action Required**: [What validation needs to be executed]
-
-### Customer Problem Issues
-1. **Problem Not Solved**: [Description]
-   - **Feature Spec Problem**: [Reference]
-   - **Action Required**: [What needs to be fixed]
-
-### Negative Case Issues
-1. **Invalid Input Not Handled**: [Scenario]
-   - **Problem**: Feature doesn't reject invalid inputs gracefully
-   - **Expected**: Clear error message, no crashes
-   - **Action Required**: Add input validation and error handling
-
-2. **Unauthorized Access Not Blocked**: [Scenario]
-   - **Problem**: Feature allows unauthorized access
-   - **Expected**: Proper 401/403 errors
-   - **Action Required**: Add authorization checks
-
-3. **Missing Data Not Handled**: [Scenario]
-   - **Problem**: Feature crashes or behaves incorrectly with missing data
-   - **Expected**: Graceful handling with clear error messages
-   - **Action Required**: Add null/undefined checks
-
-### Edge Case Issues
-1. **Edge Case Not Handled**: [Edge case from spec]
-   - **Feature Spec Section**: [Reference]
-   - **Problem**: [What doesn't work]
-   - **Action Required**: [What needs to be fixed]
-
-### Error Handling Issues
-1. **Error Messages Not User-Friendly**: [Error scenario]
-   - **Problem**: Error messages are technical or confusing
-   - **Expected**: Clear, actionable error messages
-   - **Action Required**: Improve error messages
-
-2. **Error Recovery Not Possible**: [Error scenario]
-   - **Problem**: Users can't recover from errors (dead-end)
-   - **Expected**: Users can retry or fix issues
-   - **Action Required**: Add error recovery paths
-
-## Action Items for Implementation Agent
-- [ ] Fix critical blocker 1
-- [ ] Fix critical blocker 2
-- [ ] Fix user experience issue X
-- [ ] Update UI to match mock 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:design-review-passed` again
-4. Feature review agent will re-review (iteration {next_number})
-```
-
-## FINAL SUMMARY TEMPLATE (When Approving)
-
-Create `docs/evidence/{issue}-feature-review-summary.md` when approving:
-
-```markdown
-# Feature Review Summary - Issue #{issue}
-
-## Review Outcome
-- Status: ✅ APPROVED
-- Iterations: {number} (1-3)
-- Feature Spec Location: `docs/feature specs/{issue}-*.md`
-
-## What Was Reviewed
-- Customer Problem: ✅ Solved
-- User Experience: All X steps working ✅
-- Validation Plan: All Y methods executed ✅
-- UI Mocks: Match ✅ (if applicable)
-- Authentication: Set up and working ✅
-
-## Key Findings
-- Customer problem is solved
-- All user workflow steps work correctly
-- All validation methods executed with evidence
-- UI matches mocks (if applicable)
-- End-to-end testing completed with authentication
-
-## Evidence Locations
-- Implementation Evidence: `docs/evidence/{issue}-implementation-evidence.md`
-- Design Review Summary: `docs/evidence/{issue}-design-review-summary.md`
-- Validation Evidence: [locations]
-- Screenshots: [locations]
-
-## Final Status
-- Technical Review: ✅ Passed (from design review)
-- Functional Review: ✅ Passed (this review)
-- Ready for merge: ✅ Yes
-```
-
-## REVIEW EVIDENCE TEMPLATE (PR Comment)
-
-Add this as a PR comment:
-
-```markdown
-# Feature Spec Review - Issue #{issue}
-
-## Feature Spec Compliance Summary
-- Feature Spec Location: `docs/feature specs/{issue}-*.md`
-- Customer Problem: Solved ✅/❌
-- User Experience: Complete X/Y steps ✅/❌
-- Validation Plan: X/Y methods executed ✅/❌
-- UI Mocks: Match ✅/❌ (if applicable)
-
-## Detailed Findings
-
-### Customer Problem Verification
-- Problem Statement: [from spec]
-- Desired Outcome: [from spec]
-- Solution Status: ✅ Addresses problem / ❌ Doesn't address problem
-- Notes: [any concerns]
-
-### Authentication Setup
-- Method Used: [Credentials provided / Cookie-driven browser session]
-- Status: ✅ Authenticated / ❌ Failed / ⚠️ Partial
-- Notes: [Any authentication issues encountered]
-
-### User Experience Workflow Validation
-| Step | Description | Status | Evidence | Notes |
-|------|-------------|--------|----------|-------|
-| 1 | User clicks tab X | ✅ | Screenshot | Works correctly (tested with auth) |
-| 2 | User sees list Y | ❌ | Missing | List not rendering (tested with auth) |
-| 3 | User approves item Z | ⚠️ | Partial | Works but slow (tested with auth) |
-
-### UI Mock Compliance (if applicable)
-| Mock Element | Spec | Implementation | Match | Notes |
-|--------------|------|----------------|-------|-------|
-| Layout | [description] | [description] | ✅ | Matches |
-| Component X | [description] | [description] | ❌ | Missing feature Y |
-
-### Validation Plan Execution
-| Validation Method | Required | Executed | Result | Evidence | Auth Status |
-|------------------|----------|----------|--------|----------|-------------|
-| Browser validation | Yes | ✅ | Pass | Screenshot in PR | ✅ Authenticated |
-| API validation | Yes | ❌ | Missing | No curl output | ⚠️ Auth token missing |
-| Database validation | Yes | ✅ | Pass | DB query results | N/A |
-| End-to-end workflow | Yes | ✅ | Pass | Full workflow screenshots | ✅ Cookie session |
-
-### Edge Cases, Negative Cases, and Error Handling
-- Alternatives Considered: ✅ Matches chosen approach
-- Edge Cases: ✅ All tested / ⚠️ Some not tested / ❌ Issues found
-- Negative Cases: ✅ All tested / ⚠️ Some not tested / ❌ Issues found
-- Error Handling: ✅ User-friendly / ❌ Confusing
-- Error Recovery: ✅ Users can recover / ❌ Dead-ends found
-
-### Functional Completeness
-- All Workflow Steps: ✅ Working
-- Broken Links: ✅ None found
-- Positive Cases: ✅ All working
-- Negative Cases: ✅ Handled gracefully / ❌ Not handled
-- Edge Cases: ✅ Handled / ❌ Issues found
-- Error States: ✅ Handled gracefully
-- Error Recovery: ✅ Users can recover / ❌ Dead-ends found
-- Success States: ✅ Work correctly
-
-### Evidence Quality
-- Validation Evidence: ✅ Complete
-- Screenshots: ✅ Included for UI features
-- API Outputs: ⚠️ Missing for some endpoints
-- Database State: ✅ Included
-
-## Decision
-✅ APPROVE / ❌ REJECT / ⚠️ REQUEST CHANGES
-
-## Feedback Document
-- Location: `docs/evidence/{issue}-feature-reviewer-feedback.md`
-- Iteration: {1, 2, or 3}
-
-## Blockers (if any)
-1. User workflow step X doesn't work (tested with authentication)
-2. Validation method Y not executed
-3. UI doesn't match mock Z
-4. Customer problem not actually solved
-
-## Next Steps (if REQUEST CHANGES)
-- [ ] Implementation agent addresses feedback in `docs/evidence/{issue}-feature-reviewer-feedback.md`
-- [ ] Implementation agent updates `docs/evidence/{issue}-implementation-evidence.md`
-- [ ] Implementation agent marks `status:design-review-passed` for re-review
-- [ ] Feature review agent will re-review (max 3 iterations)
-```
-
-## EXAMPLES
-
-### Good: Complete Review
-```
-Issue #533: Feature Spec Review
-✅ Customer Problem: Solved
-✅ User Experience: 5/5 steps working
-✅ Validation Plan: 4/4 methods executed
-✅ UI Mocks: Match
-✅ Authentication: Cookie session working
-Decision: ✅ APPROVE
-```
-
-### Bad: Incomplete Review
-```
-Issue #533: Feature Spec Review
-❌ Customer Problem: Not fully addressed
-⚠️ User Experience: 3/5 steps working (2 broken)
-❌ Validation Plan: 2/4 methods executed (2 missing)
-❌ UI Mocks: Don't match
-Decision: ❌ REJECT
-Blockers: Broken workflow steps, missing validations
-```
-
-## INTEGRATION
-
-### Status Label Flow
-```
-status:design-review-passed
-  ↓ (Feature Spec Review)
-status:feature-review-passed (or status:wip if rejected)
-  ↓ (Final approval)
-Ready for merge
-```
-
-### After This Review
-- If APPROVE: Issue ready for final approval/merge
-- If REJECT: Issue returns to implementation (status:wip)
-- Implementation agent addresses blockers and re-submits
-
-### Relationship to Design Spec Review
-- Design Spec Review validates technical correctness
-- Feature Spec Review validates user value and experience
-- Both must pass for issue to be complete