> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Code Review & Documentation Improvement Process

> Version: 1.0.0 Last Updated: 2026-04-11

**Version:** 1.0.0\
**Last Updated:** 2026-04-11

## Purpose

This document defines the process for:

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:**
   ```bash theme={null}
   cr-lovable
   ```

2. **Update Documentation:**
   * AGENTS.md - Quick reference for all AI platforms
   * docs/tools/lovable/LOVABLE\_CUSTOM\_KNOWLEDGE.md - Lovable-specific guidance (if needed)
   * constitution.md - Authoritative guardrails
   * AI\_GUIDE.md - Detailed process guidelines

3. **Analyze Patterns:**
   ```bash theme={null}
   bash scripts/analyze-review-patterns.sh
   ```

4. **Review Pattern Analysis:**
   ```bash theme={null}
   ls -t reports/active/pattern-analysis-*.md | head -1 | xargs cat
   ```

5. **Get Update Recommendations:**
   ```bash theme={null}
   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

**High Priority Patterns (Update Documentation):**

* **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)

**Medium Priority Patterns:**

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

**Low Priority (Code Review Only):**

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

***

## Daily Commands

### CodeRabbit CLI Quick Reference

**Using Aliases (Recommended):**

```bash theme={null}
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)
```

**Report Generation:**

```bash theme={null}
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
```

**Report Types:**

| Command           | Output Type               | File Size      | Best For                         |
| ----------------- | ------------------------- | -------------- | -------------------------------- |
| `cr-report`       | Detailed (`--plain`)      | \~50-200 KB    | Manual review, Lovable           |
| `cr-report-quick` | Minimal (`--prompt-only`) | \~5-10 KB      | Quick checks, AI assistants      |
| `cr-lovable`      | Markdown by severity      | Multiple files | AI review, organized by priority |

**Report Locations:**

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

**Common Workflows:**

```bash theme={null}
# Before Committing
cr-uncommitted

# After Feature Complete
cr-review

# With AI Assistants
cr-quick
```

**See Also:** `CODERABBIT_GUIDE.md` for complete setup instructions and detailed workflows.

***

## 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

```bash theme={null}
# 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

Use the pattern analysis script:

```bash theme={null}
bash scripts/analyze-review-patterns.sh
```

This script will:

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

### Step 4: Update Documentation

Based on patterns found, update:

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

Create a PR with:

* 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

**Documentation Update:** `constitution.md §1`, `AGENTS.md §1`

### Database Issues

* Missing RLS policies
* Incorrect naming conventions
* Missing organization\_id
* RLS recursion patterns

**Documentation Update:** `constitution.md §5`, `AGENTS.md §3, §6`

### Security Issues

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

**Documentation Update:** `constitution.md §4`, `AI_GUIDE.md §Security`

### Performance Issues

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

**Documentation Update:** `constitution.md §6.7`, `AGENTS.md §6`

### Testing Gaps

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

**Documentation Update:** `AI_GUIDE.md §Testing`, `constitution.md §3.3`

### Code Quality

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

**Documentation Update:** `AI_GUIDE.md §Code Standards`, `AGENTS.md §11`

***

## Automation

### Automation notes

CodeRabbit runs via the **CodeRabbit GitHub App** on pull requests (see `.coderabbit.yaml` and [CODERABBIT\_GUIDE.md](CODERABBIT_GUIDE.md)). There is **no** `coderabbit-review.yml` workflow in this repository; optional scheduled reporting or issue creation would use a separate workflow if added later.

### 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

Track reviews in `docs/archive/development/REVIEW_LOG.md`:

```markdown theme={null}
## 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

**Generate Report:**

```bash theme={null}
cr-lovable
```

**Analyze Patterns:**

```bash theme={null}
bash scripts/analyze-review-patterns.sh
```

**Find Latest Report:**

```bash theme={null}
bash scripts/find-report.sh --latest
```

**Review Specific Report:**

```bash theme={null}
bash scripts/find-report.sh --date 2025-12-22
```