Code Review & Documentation Improvement Process

​

Purpose

1. Periodically reviewing CodeRabbit reports
2. Identifying patterns and recurring issues
3. Updating documentation (AGENTS.md, constitution.md, AI_GUIDE.md) to prevent future issues

​

Quick Start

​

5-Minute Workflow

1. Generate Latest Report:
   cr-lovable
   
2. Update Documentation:
   • AGENTS.md - Quick reference for all AI platforms
   • constitution.md - Authoritative guardrails
   • AI_GUIDE.md - Detailed process guidelines
3. Analyze Patterns:
   bash scripts/analyze-review-patterns.sh
   
4. Review Pattern Analysis:
   ls -t reports/active/pattern-analysis-*.md | head -1 | xargs cat
   
5. Get Update Recommendations:
   bash scripts/update-docs-from-review.sh
   
6. Update Documentation:
   • AGENTS.md - Quick reference rules
   • constitution.md - Engineering guardrails
   • AI_GUIDE.md - AI contribution guidelines
   • src/{core}/AGENTS.md - Module-specific patterns
7. Log the Update: Add entry to docs/archive/development/REVIEW_LOG.md

​

What to Look For

• 3+ instances of the same issue type
• Security violations (permission gates, RLS, multi-tenant)
• Architecture violations (core boundaries, imports)
• Performance issues (React.lazy, loading states)

• 2-3 instances of code quality issues
• Testing gaps (missing RLS write tests)
• Accessibility violations (touch targets, labels)

• 1-2 instances of minor issues
• Trivial suggestions (refactoring, style)

​

Daily Commands

​

CodeRabbit CLI Quick Reference

cr                  # Review all changes (default)
cr-review           # Review all changes (explicit)
cr-uncommitted      # Review only uncommitted changes
cr-plain            # Detailed feedback with suggestions
cr-quick            # Minimal output (token-efficient)

cr-report              # Full detailed report (saved to reports/)
cr-report-quick        # Quick prompt-only report (saved to reports/)
cr-report-uncommitted  # Uncommitted changes report (saved to reports/)
cr-lovable             # Generate markdown report by severity (all changes)
cr-lovable-uncommitted # Markdown report for uncommitted changes
cr-lovable-show        # Generate markdown report and show output

• Plain Text: reports/coderabbit-report-YYYYMMDD-HHMMSS.txt
• Markdown: reports/coderabbit-YYYYMMDD-HHMMSS/ (00-SUMMARY.md, 01-CRITICAL.md, etc.)

# Before Committing
cr-uncommitted

# After Feature Complete
cr-review

# With AI Assistants
cr-quick

​

Review Schedule

​

Weekly Review (Recommended)

• When: Every Monday or after major feature releases
• Scope: Review all reports from the past week
• Focus: Critical and Major issues

​

Monthly Deep Review

• When: First week of each month
• Scope: All reports from the past month
• Focus: Pattern analysis, documentation updates, process improvements

​

Quarterly Audit

• When: Beginning of each quarter
• Scope: Full codebase review + documentation accuracy check
• Focus: Major documentation updates, new patterns, deprecated practices

​

Review Workflow

​

Step 1: Generate Latest Report

# Generate fresh report
cr-lovable

# Or for specific review type
cr-lovable-uncommitted

​

Step 2: Analyze Report

1. Review Summary (00-SUMMARY.md)
   • Check total findings count
   • Review severity breakdown
   • Identify top impacted files
2. Review Critical Issues (01-CRITICAL.md)
   • Must fix before merge
   • Security, data integrity, architecture violations
3. Review Major Issues (02-MAJOR.md)
   • High priority fixes
   • Multi-tenancy, accessibility, performance
4. Review Minor/Trivial (03-MINOR.md, 04-TRIVIAL.md)
   • Look for patterns across multiple files
   • Identify documentation gaps

​

Step 3: Identify Patterns

bash scripts/analyze-review-patterns.sh

• Count issue types by category
• Identify recurring file patterns
• Suggest documentation updates
• Generate a pattern report

​

Step 4: Update Documentation

1. AGENTS.md
   • Add to “Top 11 Rules” if critical pattern
   • Add to “What AI Must NEVER Do” if prohibited pattern
   • Update quick reference sections
2. constitution.md
   • Add new guardrails if architectural pattern
   • Update database rules if schema pattern
   • Add security requirements if security pattern
3. AI_GUIDE.md
   • Add to “Pre-Flight Checklist” if common mistake
   • Update code standards if pattern found
   • Add examples if helpful
4. AGENTS.md (module-specific)
   • Update module-specific patterns
   • Add common pitfalls for that module

​

Step 5: Document Changes

• Summary of patterns found
• Documentation updates made
• Examples of issues prevented
• Version bumps for updated docs

​

Pattern Categories

​

Architecture Violations

• Direct core-to-core imports
• Missing platform integration layer usage
• Incorrect module boundaries

​

Database Issues

• Missing RLS policies
• Incorrect naming conventions
• Missing organization_id
• RLS recursion patterns

​

Security Issues

• Missing permission gates
• Hardcoded role checks
• Cross-org data leaks
• PHI/PII exposure

​

Performance Issues

• Missing React.lazy for routes
• Missing Suspense boundaries
• Incorrect QueryClient config
• Missing loading states

​

Testing Gaps

• Missing RLS write tests
• Incomplete test coverage
• Missing edge cases

​

Code Quality

• Shell script error handling
• TypeScript type safety
• Accessibility violations
• Mobile-first violations

​

Automation

​

Automation notes

​

Manual Review Checklist

• Generated latest report
• Reviewed summary and critical issues
• Ran pattern analysis script
• Ran npm run audit:component-duplication and reviewed top duplicate component clusters
• Confirmed touched duplicate/recreated components compose existing platform/shared primitives where applicable
• Identified 3+ recurring patterns
• Updated relevant documentation
• Version bumped documentation files
• Created PR with changes
• Documented patterns in review log

​

Review Log

## 2025-12-22 - Weekly Review

**Report:** coderabbit-20251222-103959
**Findings:** 59 total (10 Critical, 17 Major, 29 Minor, 3 Trivial)

### Patterns Identified
1. Missing React.lazy for route components (5 instances)
2. Missing permission gates (3 instances)
3. Incomplete RLS test coverage (4 instances)

### Documentation Updates
- Added React.lazy requirement to AGENTS.md §6
- Added permission gate pattern to AI_GUIDE.md
- Updated RLS testing requirements in constitution.md §3.3

### Version Bumps
- AGENTS.md: 3.9.0 → 3.10.0
- AI_GUIDE.md: 2.4.1 → 2.4.2

​

Best Practices

1. Don’t Over-Document
   • Only add patterns that appear 3+ times
   • Focus on preventable issues, not one-offs
2. Keep Examples Current
   • Update examples when patterns change
   • Remove deprecated patterns
3. Version Control
   • Always version bump documentation
   • Include “Last Updated” dates
4. Link to Reports
   • Reference specific reports in documentation updates
   • Keep historical context
5. Prioritize Critical
   • Focus documentation updates on critical/major issues
   • Minor/trivial can be addressed in code reviews

​

Quick Reference

cr-lovable

bash scripts/analyze-review-patterns.sh

bash scripts/find-report.sh --latest

bash scripts/find-report.sh --date 2025-12-22