fraim-framework 2.0.27 → 2.0.30

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

@@ -1,669 +1,669 @@
-# 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 functional completeness and user value.
-
-## PRINCIPLES
-- **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
-
-## 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 Analysis
-**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 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 review checklist
-
-### Step 3: Customer Problem Verification
-**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: `.ai-agents/workflows/customer-development/linkedin-outreach.md` shows 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: `tests/auth-setup.ts` and `tests/playwright.config.ts`
-- **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: 'tests/auth-state.json' })`
-  7. Reuse auth state in future: `browser.newContext({ storageState: 'tests/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
+# 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 functional completeness and user value.
+
+## PRINCIPLES
+- **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
+
+## 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 Analysis
+**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 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 review checklist
+
+### Step 3: Customer Problem Verification
+**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