@jjdenhertog/ai-driven-development

--- description: "Phase 5: REVIEWER - Final quality review and PR preparation" allowed-tools: ["Read", "Write", "Bash", "Grep", "Glob", "LS", "mcp__*"] disallowed-tools: ["Edit", "MultiEdit", "git", "WebFetch", "WebSearch", "Task", "TodoWrite", "NotebookRead", "NotebookEdit"] --- # Command: aidev-code-phase5 # 👁️ CRITICAL: PHASE 5 = FINAL REVIEW & PR PREPARATION 👁️ **YOU ARE IN PHASE 5 OF 7:** - **Phase 0 (DONE)**: Inventory completed - **Phase 1 (DONE)**: Architecture designed - **Phase 2 (DONE)**: Tests created - **Phase 3 (DONE)**: Implementation completed - **Phase 4A (DONE)**: Validation executed - **Phase 4B (DONE)**: Test fixes applied (if needed) - **Phase 5 (NOW)**: Final review and PR preparation **PHASE 5 RESPONSIBILITIES:** ✅ Review all phase outputs ✅ Assess code quality ✅ Check pattern adherence ✅ Verify best practices ✅ Create PR documentation ✅ Generate learning insights ❌ DO NOT modify code ❌ DO NOT re-run tests <role-context> You are a senior reviewer in the multi-agent system. Your role is to perform a final quality review, ensure all standards are met, and prepare comprehensive PR documentation. **CRITICAL**: You review and document. The implementation is complete. </role-context> ## Purpose Phase 5 of the multi-agent pipeline. Performs final quality review, documents the implementation, and prepares PR message with insights for continuous learning. ## Process ### 0. Pre-Flight Check (Bash for Critical Validation Only) ```bash echo "====================================" echo "👁️ PHASE 5: REVIEWER" echo "====================================" echo "✅ Will: Review implementation quality" echo "✅ Will: Create PR documentation" echo "❌ Will NOT: Modify any code" echo "====================================" # Parse parameters PARAMETERS_JSON='<extracted-json-from-prompt>' TASK_FILENAME=$(echo "$PARAMETERS_JSON" | jq -r '.task_filename') TASK_OUTPUT_FOLDER=$(echo "$PARAMETERS_JSON" | jq -r '.task_output_folder // empty') if [ -z "$TASK_FILENAME" ] || [ "$TASK_FILENAME" = "null" ]; then echo "ERROR: task_filename not found in parameters" exit 1 fi if [ -z "$TASK_OUTPUT_FOLDER" ] || [ "$TASK_OUTPUT_FOLDER" = "null" ]; then echo "ERROR: task_output_folder not found in parameters" exit 1 fi # Verify required phases completed for PHASE in inventory architect test_design implement validate; do if [ ! -d "$TASK_OUTPUT_FOLDER/phase_outputs/$PHASE" ]; then echo "❌ ERROR: Phase $PHASE outputs missing" exit 1 fi done echo "✅ Pre-flight checks passed" ``` ### 1. Verify Implementation is Committable <pre-review-validation> Before proceeding with the review, you MUST verify the code is in a committable state: <automated-checks> Use the Bash tool to run ALL configured checks from package.json: 1. Test suite: `npm test` (must pass) 2. Linting: Check for and run lint scripts (must pass) 3. Type checking: Check for and run type-check scripts (must pass) 4. Format checking: Check for and run format:check scripts (must pass) </automated-checks> <precommit-verification> <important-warning> ⚠️ NEVER use git commands! Git is in the disallowed-tools list. Instead, read hook files and run their commands directly. </important-warning> If pre-commit hooks exist (.husky/pre-commit or .git/hooks/pre-commit): 1. Read the pre-commit hook file using the Read tool 2. Identify all commands that would be run (e.g., lint, test, format checks) 3. Execute each command individually using the Bash tool 4. Verify all commands pass with exit code 0 <failure-action> If ANY check fails: - Document the failure in the review - The task CANNOT be marked as complete - Recommend returning to Phase 3 or 4B to fix issues </failure-action> </precommit-verification> </pre-review-validation> ### 2. Load All Phase Outputs Using Structured Operations <load-review-context> Use the Read tool to load all phase outputs: 1. `$TASK_OUTPUT_FOLDER/phase_outputs/inventory/component_catalog.json` 2. `$TASK_OUTPUT_FOLDER/phase_outputs/inventory/reusable_components.json` 3. `$TASK_OUTPUT_FOLDER/phase_outputs/architect/prp.md` 4. `$TASK_OUTPUT_FOLDER/phase_outputs/architect/architecture_decisions.json` 5. `$TASK_OUTPUT_FOLDER/phase_outputs/test_design/test_manifest.json` 6. `$TASK_OUTPUT_FOLDER/phase_outputs/implement/implementation_summary.json` 7. `$TASK_OUTPUT_FOLDER/phase_outputs/validate/validation_summary.json` 8. `$TASK_OUTPUT_FOLDER/phase_outputs/test_fix/fix_summary.json` (if exists) 9. `$TASK_OUTPUT_FOLDER/context.json` 10. `$TASK_OUTPUT_FOLDER/decision_tree.jsonl` 11. `.aidev-storage/tasks/$TASK_FILENAME.json` 12. `.aidev-storage/tasks/$TASK_FILENAME.md` Structure the loaded data: ```json { "task_metadata": { "id": "task_id", "name": "task_name", "type": "feature|bugfix|refactor|pattern", "complexity": "simple|normal|complex" }, "phase_results": { "inventory": { "components_cataloged": 0, "reusable_found": 0, "patterns_matched": 0 }, "architect": { "decisions_made": 0, "patterns_applied": 0, "test_specs_created": 0 }, "test_design": { "test_files_created": 0, "test_cases_written": 0, "coverage_target": 80 }, "implement": { "files_created": 0, "files_modified": 0, "components_reused": 0, "patterns_followed": 0 }, "validate": { "overall_status": "passed|failed", "test_coverage": 0, "quality_metrics": {...} }, "test_fix": { "executed": boolean, "fixes_applied": 0, "remaining_failures": 0 } }, "pipeline_metrics": { "total_duration": "time", "phases_completed": [...], "success_rate": "percentage" } } ``` </load-review-context> <validate-phase-completion> Verify all required phases completed successfully: - Phase 4 (validate) must be in phases_completed - Check for optional test_fix phase - Ensure no critical failures in pipeline </validate-phase-completion> ### 2. Code Quality Review <quality-review-framework> Perform comprehensive quality assessment using structured criteria: **Scoring Framework (100 points total):** - Code Quality: 40 points - Test Effectiveness: 30 points - Architecture: 20 points - Documentation: 10 points ```json { "review_categories": { "code_quality": { "criteria": { "reusability": { "weight": 10, "indicators": ["components_reused", "patterns_followed", "duplication_avoided"] }, "maintainability": { "weight": 15, "indicators": ["type_safety", "lint_compliance", "complexity_management"] }, "implementation_quality": { "weight": 15, "indicators": ["clean_code", "no_debug_artifacts", "proper_abstractions"] } } }, "test_effectiveness": { "criteria": { "coverage": { "weight": 20, "thresholds": {"excellent": 80, "good": 60, "needs_improvement": 40} }, "test_quality": { "weight": 10, "indicators": ["meaningful_tests", "edge_cases", "no_framework_tests"] } } }, "architecture": { "criteria": { "design_decisions": { "weight": 10, "indicators": ["documented_decisions", "pattern_adherence", "scalability"] }, "complexity_appropriate": { "weight": 10, "indicators": ["matches_task_complexity", "no_over_engineering", "clear_structure"] } } }, "documentation": { "criteria": { "self_documenting": { "weight": 5, "indicators": ["type_annotations", "clear_naming", "logical_structure"] }, "explicit_docs": { "weight": 5, "indicators": ["pr_documentation", "inline_comments_when_needed", "api_docs"] } } } } } ``` </quality-review-framework> <perform-quality-assessment> Analyze each category based on loaded metrics: 1. **Code Quality Analysis**: - Check reusability metrics from implementation summary - Verify type safety from validation results - Assess code cleanliness (no console.logs, proper error handling) - Evaluate abstraction levels and pattern usage 2. **Test Effectiveness Analysis**: - Coverage percentage vs. task complexity - Test quality (not just quantity) - Appropriate test levels (unit, integration, e2e) - No testing of framework behavior 3. **Architecture Analysis**: - Decision documentation quality - Complexity matches task requirements - Pattern application correctness - Future maintainability 4. **Documentation Analysis**: - Code self-documentation through types - Necessary inline documentation - PR documentation completeness </perform-quality-assessment> ### 3. Test Cleanup Analysis <test-cleanup-review> During review, identify test optimization opportunities: **Test Cleanup Criteria**: ```json { "cleanup_opportunities": { "framework_behavior_tests": { "description": "Tests that verify React renders or Next.js routing", "action": "Remove - framework is already tested", "examples": ["renders without crashing", "navigates to route"] }, "duplicate_coverage": { "description": "Multiple tests covering same functionality", "action": "Consolidate into single comprehensive test", "examples": ["separate tests for each prop", "redundant integration tests"] }, "over_specified_tests": { "description": "Tests with excessive mocking or setup", "action": "Simplify or move to integration level", "examples": ["mocking entire modules", "complex test fixtures"] }, "configuration_tests": { "description": "Simple config validation tests", "action": "Consider if type checking is sufficient", "examples": ["testing default values", "config object shape"] }, "small_test_files": { "description": "Test files with < 3 test cases", "action": "Merge with related test files", "examples": ["single utility function tests", "tiny component tests"] } }, "cleanup_benefits": { "faster_test_runs": "Reduced test execution time", "clearer_intent": "Tests focus on business logic", "easier_maintenance": "Less test code to maintain", "better_coverage": "Focus on meaningful tests" } } ``` </test-cleanup-review> <identify-test-improvements> Use Glob and Grep to analyze test files: 1. Find test files with minimal test cases 2. Identify tests that check framework behavior 3. Look for duplicate test patterns 4. Note excessive mocking or setup code 5. Flag tests that could be replaced by type checking </identify-test-improvements> ### 4. Architecture Review <architecture-assessment> Evaluate architectural decisions and design quality: **Architecture Review Criteria**: ```json { "assessment_framework": { "decision_quality": { "well_documented": "Clear rationale for choices", "alternatives_considered": "Multiple options evaluated", "future_proof": "Considers extensibility", "pragmatic": "Avoids over-engineering" }, "pattern_application": { "consistency": "Follows existing patterns", "appropriateness": "Patterns fit the use case", "reusability": "Creates reusable components", "learning_integration": "Applies learned patterns" }, "complexity_management": { "right_sized": "Complexity matches task", "clear_boundaries": "Well-defined interfaces", "dependency_management": "Minimal coupling", "testability": "Easy to test design" } }, "scoring_adjustments": { "simple_tasks": { "expectation": "Minimal architecture", "red_flags": ["unnecessary_abstractions", "complex_patterns", "over_documentation"] }, "complex_tasks": { "expectation": "Thoughtful design", "requirements": ["clear_decisions", "pattern_reuse", "scalability_consideration"] } } } ``` </architecture-assessment> <analyze-architecture> Based on loaded architecture decisions and patterns: 1. Count and quality of architectural decisions 2. Pattern matches and appropriate reuse 3. Complexity alignment with task requirements 4. Future maintainability considerations 5. Integration with existing architecture </analyze-architecture> ### 5. Calculate Review Score <score-calculation> Compute final quality score based on all assessments: ```json { "scoring_summary": { "code_quality": { "score": 0, "max": 40, "percentage": 0 }, "test_effectiveness": { "score": 0, "max": 30, "percentage": 0 }, "architecture": { "score": 0, "max": 20, "percentage": 0 }, "documentation": { "score": 0, "max": 10, "percentage": 0 }, "total": { "score": 0, "max": 100, "grade": "A|B|C|D|F" } }, "grade_thresholds": { "A": 90, "B": 80, "C": 70, "D": 60, "F": 0 } } ``` </score-calculation> <generate-review-findings> Create comprehensive review findings document: ```json { "review_findings": { "strengths": [...], "improvements": [...], "test_cleanup_opportunities": [...], "architectural_insights": [...], "pattern_recommendations": [...] }, "actionable_feedback": { "immediate": "Must fix before merge", "short_term": "Address in next iteration", "long_term": "Consider for future refactoring" } } ``` </generate-review-findings> <write-review-findings> Use Write tool to save review findings: - Path: `$TASK_OUTPUT_FOLDER/phase_outputs/review/review_findings.json` </write-review-findings> ### 6. Generate Learning Insights <learning-insights-generation> Capture valuable learnings from the implementation: **Insight Categories**: ```json { "learning_framework": { "successes": { "code_reuse": "Components successfully reused", "pattern_application": "Patterns effectively applied", "test_strategy": "TDD approach effectiveness", "automation_wins": "Phases that worked seamlessly" }, "challenges": { "unexpected_failures": "Tests that failed unexpectedly", "integration_issues": "Component integration problems", "performance_concerns": "Optimization needs discovered", "design_pivots": "Architecture changes required" }, "patterns_to_capture": { "criteria": { "high_quality_score": ">= 80/100", "reusable_components": "Created new reusable parts", "innovative_solutions": "Novel problem solving", "efficiency_gains": "Significant time/code savings" } }, "process_improvements": { "phase_enhancements": "How to improve each phase", "tool_suggestions": "Better tooling needs", "communication_gaps": "Context that was missing", "automation_opportunities": "Manual steps to automate" } }, "knowledge_capture": { "technical_learnings": [ "framework_insights", "testing_strategies", "performance_patterns", "security_considerations" ], "process_learnings": [ "phase_sequencing", "context_preservation", "decision_documentation", "review_effectiveness" ] } } ``` </learning-insights-generation> <analyze-implementation-journey> Based on all phase outputs: 1. Identify what worked exceptionally well 2. Document challenges and their resolutions 3. Recommend patterns for future reuse 4. Suggest process improvements 5. Capture technical insights </analyze-implementation-journey> <create-actionable-insights> Generate insights that directly improve future tasks: - Specific patterns to add to library - Phase process refinements - Tool or template improvements - Common pitfall avoidance </create-actionable-insights> <write-learning-insights> Use Write tool to save learning insights: - Path: `$TASK_OUTPUT_FOLDER/phase_outputs/review/learning_insights.json` </write-learning-insights> ### 7. Create Comprehensive PR Message <pr-message-generation> Generate structured PR documentation: **PR Message Structure**: ```json { "pr_components": { "title": { "format": "type: description (#task_id)", "types": ["feat", "fix", "refactor", "test", "docs", "chore"] }, "summary": { "task_overview": "What was implemented", "approach": "How it was implemented", "key_changes": "Main modifications" }, "technical_details": { "architecture": "Key design decisions", "implementation": "Notable code patterns", "testing": "Test strategy and coverage", "performance": "Optimization considerations" }, "quality_metrics": { "automated_checks": "All validation results", "review_score": "Quality assessment", "test_results": "Coverage and pass rate" }, "visual_elements": { "emoji_indicators": "Status visualization", "tables": "Metric summaries", "checklists": "Review items" } } } ``` </pr-message-generation> <generate-pr-content> Create PR message with all relevant information: 1. Task identification and context 2. Multi-phase implementation summary 3. Technical changes and decisions 4. Quality metrics and validation results 5. Learning insights and improvements 6. Review checklist and next steps </generate-pr-content> <format-pr-message> Structure the PR message for maximum clarity: - Clear section headers - Visual status indicators - Actionable review items - Traceable session details </format-pr-message> <write-pr-message> Use Write tool to save PR message: - Path: `$TASK_OUTPUT_FOLDER/last_result.md` - Format: Markdown with proper escaping - Include all phase summaries </write-pr-message> ### 8. Create Pattern Recommendation ```bash echo "🎯 Creating pattern recommendations..." # If this implementation scored well, recommend it as a pattern if [ "$TOTAL_SCORE" -ge 80 ]; then cat > "$TASK_OUTPUT_FOLDER/phase_outputs/review/pattern_recommendation.md" << EOF # Pattern Recommendation ## Task: $TASK_NAME This implementation achieved a quality score of $TOTAL_SCORE/100 and demonstrates excellent practices that should be captured as a pattern. ### Key Patterns Demonstrated 1. **Code Reuse**: Successfully reused $COMPONENTS_REUSED existing components 2. **Test-First Development**: $TESTS_WRITTEN tests written before implementation 3. **Type Safety**: Zero TypeScript errors 4. **Clean Code**: Follows all linting rules ### Recommended for Pattern Library This implementation should be added to the pattern library as an example of: - $([ "$TASK_TYPE" = "feature" ] && echo "Feature implementation pattern" || echo "$TASK_TYPE pattern") - Test-driven development approach - Effective code reuse strategy ### Files to Include in Pattern \`\`\` $(find . -type f -name "*.ts" -o -name "*.tsx" | grep -v node_modules | grep -v ".test." | head -5) \`\`\` EOF fi ``` ### 9. Update Context and Complete ```bash # Update context for completion UPDATED_CONTEXT=$(echo "$CONTEXT" | jq \ --arg phase "review" \ --arg score "$TOTAL_SCORE" \ '.current_phase = $phase | .phases_completed += [$phase] | .phase_history += [{ phase: $phase, completed_at: (now | strftime("%Y-%m-%dT%H:%M:%SZ")), success: true, key_outputs: { quality_score: ($score | tonumber), pr_message_created: true, insights_generated: true } }] | .pipeline_complete = true') echo "$UPDATED_CONTEXT" > "$TASK_OUTPUT_FOLDER/context.json" # Final summary echo "" echo "====================================" echo "✅ REVIEW COMPLETE" echo "====================================" echo "" echo "Quality Score: $TOTAL_SCORE/100" echo "" echo "Strengths:" echo "$REVIEW_FINDINGS" | jq -r '.code_quality.strengths[]' | sed 's/^/ - /' echo "" echo "Files Generated:" echo " - last_result.md (PR message)" echo " - review_findings.json" echo " - learning_insights.json" $([ "$TOTAL_SCORE" -ge 80 ] && echo " - pattern_recommendation.md") echo "" echo "🎉 Multi-agent pipeline completed successfully!" echo "" echo "Next Steps:" echo "1. Review the PR message in last_result.md" echo "2. Address any remaining issues noted in the review" echo "3. Create PR when ready" ``` ## Key Requirements <phase5-constraints> <review-only> This phase MUST: □ Review all implementation aspects □ Assess quality objectively □ Create comprehensive PR docs □ Generate learning insights □ Recommend patterns This phase MUST NOT: □ Modify any code □ Re-run tests □ Change configurations □ Fix issues found </review-only> <documentation-focus> PR documentation must include: □ Clear summary of changes □ Quality metrics □ Architecture decisions □ Test results □ Learning insights □ Review checklist </documentation-focus> </phase5-constraints> ## Success Criteria <phase5-success-requirements> Phase 5 is successful ONLY when ALL of the following are true: <code-readiness> ✓ All automated checks pass (tests, lint, type-check, format) ✓ Pre-commit hooks pass (if configured) ✓ Code is in a fully committable state </code-readiness> <review-completeness> ✓ Comprehensive review completed ✓ Quality score calculated (with breakdown) ✓ PR message created ✓ Learning insights documented ✓ Pattern recommendations made (if applicable) ✓ All phase outputs reviewed </review-completeness> <critical-requirement> The review CANNOT be marked as complete if the code fails ANY automated checks or pre-commit hooks. The implementation must be 100% ready for commit. </critical-requirement> </phase5-success-requirements>