fraim-framework 2.0.55 → 2.0.56

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

@@ -0,0 +1,675 @@
+# 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
+
+**GitHub Repository Context**: Before using GitHub MCP tools, read the local `.fraim/config.json` file to get the repository context:
+- Use `git.repoOwner` for the GitHub repository owner
+- Use `git.repoName` for the GitHub repository name
+- These values are required for GitHub MCP API calls (owner/repo parameters)
+
+- 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