Code Review

Code Review Skill

Purpose: Enforce automated code reviews as a mandatory guardrail before every commit and deployment. Choose between Claude, OpenAI Codex, Google Gemini, or multiple engines for comprehensive analysis.

Sub-skills:

• adr-gate.md — Pre-review ADR and spec enforcement

---

Pre-Review: ADR Gate (Mandatory)

Before any review engine runs, the ADR gate executes automatically:

1. Classify — trivial changes (typos, deps, tests-only) skip the gate 2. Discover — scan docs/adr/, _project_specs/, iCPG ReasonNodes, git history for linked ADRs and specs 3. Enforce — if no ADRs found for non-trivial changes:

• Interactive (default): draft ADR from git history, ask user to confirm
• Unattended (CI): write as Status: proposed, proceed
• Strict: block review until ADR exists

4. Inject — feed discovered ADRs + specs into the review prompt as architectural context

ADR Compliance Review Dimension

Added to the standard 7 review categories:

See adr-gate.md for full protocol, reverse-engineering rules, and configuration.

---

Review Engine Choice

When running /code-review, users can choose their preferred review engine:

┌─────────────────────────────────────────────────────────────────┐
│  CODE REVIEW - Choose Your Engine                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ○ Claude (default)                                             │
│    Built-in, no extra setup, full conversation context          │
│                                                                 │
│  ○ OpenAI Codex CLI                                             │
│    GPT-5.2-Codex specialized for code review, 88% detection     │
│    Requires: npm install -g @openai/codex                       │
│                                                                 │
│  ○ Google Gemini CLI                                            │
│    Gemini 2.5 Pro with 1M token context, free tier available    │
│    Requires: npm install -g @google/gemini-cli                  │
│                                                                 │
│  ○ Dual Engine (any two)                                        │
│    Run two engines, compare findings, catch more issues         │
│                                                                 │
│  ○ All Three (maximum coverage)                                 │
│    Run Claude + Codex + Gemini for critical/security code       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Engine Comparison

Set Default Engine

# ~/.claude/settings.toml or project CLAUDE.md
[code-review]
default_engine = "claude"  # Options: claude, codex, gemini, dual, all

Usage Examples

# Use default engine
/code-review

# Explicitly choose engine
/code-review --engine claude
/code-review --engine codex
/code-review --engine gemini

# Dual engine (pick any two)
/code-review --engine claude,codex
/code-review --engine claude,gemini
/code-review --engine codex,gemini

# All three engines
/code-review --engine all

# Quick shortcuts
/code-review              # Uses default
/code-review --codex      # Use Codex
/code-review --gemini     # Use Gemini
/code-review --all        # All three engines

---

Multi-Engine Output

When using multiple engines, findings are compared and deduplicated:

Dual Engine Example

┌─────────────────────────────────────────────────────────────────┐
│  CODE REVIEW RESULTS - DUAL ENGINE (Claude + Codex)             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ✅ AGREED (Found by both):                                     │
│  🔴 SQL injection in auth.ts:45                                 │
│  🟡 Missing error handling in api.ts:112                        │
│                                                                 │
│  🔷 CLAUDE ONLY:                                                │
│  🟠 Potential race condition in worker.ts:89                    │
│  🟢 Consider extracting helper function                         │
│                                                                 │
│  🔶 CODEX ONLY:                                                 │
│  🟠 Memory leak - unclosed stream in upload.ts:34               │
│  🟡 N+1 query pattern in orders.ts:156                          │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│  SUMMARY                                                        │
│  Agreed: 2 | Claude only: 2 | Codex only: 2                     │
│  Critical: 1 | High: 2 | Medium: 2 | Low: 1                     │
│  Status: ❌ BLOCKED - Fix critical/high issues                  │
└─────────────────────────────────────────────────────────────────┘

Triple Engine Example (All Three)

┌─────────────────────────────────────────────────────────────────┐
│  CODE REVIEW RESULTS - TRIPLE ENGINE                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ✅ UNANIMOUS (All 3 found):                                    │
│  🔴 SQL injection in auth.ts:45                                 │
│                                                                 │
│  ✅ MAJORITY (2 of 3 found):                                    │
│  🟠 Memory leak - unclosed stream in upload.ts:34 (Codex+Gemini)│
│  🟡 Missing error handling in api.ts:112 (Claude+Codex)         │
│                                                                 │
│  🔷 CLAUDE ONLY:                                                │
│  🟠 Potential race condition in worker.ts:89                    │
│                                                                 │
│  🔶 CODEX ONLY:                                                 │
│  🟡 N+1 query pattern in orders.ts:156                          │
│                                                                 │
│  🟢 GEMINI ONLY:                                                │
│  🟡 Consider using batch API for better performance             │
│  🟢 Type could be more specific in types.ts:23                  │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│  SUMMARY                                                        │
│  Unanimous: 1 | Majority: 2 | Single: 5                         │
│  Critical: 1 | High: 2 | Medium: 3 | Low: 2                     │
│  Status: ❌ BLOCKED - Fix critical/high issues                  │
└─────────────────────────────────────────────────────────────────┘

When to Use Each Mode

---

Core Philosophy

┌─────────────────────────────────────────────────────────────────┐
│  CODE REVIEW IS NON-NEGOTIABLE                                  │
│  ─────────────────────────────────────────────────────────────  │
│                                                                 │
│  Every commit must pass code review.                            │
│  Every PR must be reviewed before merge.                        │
│  Every deployment must include review sign-off.                 │
│                                                                 │
│  AI catches what humans miss. Humans catch what AI misses.      │
│  Together: fewer bugs, cleaner code, better security.           │
├─────────────────────────────────────────────────────────────────┤
│  INVOKE: /code-review                                           │
│  PLUGIN: code-review@claude-plugins-official                    │
└─────────────────────────────────────────────────────────────────┘

---

When to Run Code Review

Mandatory Review Points

Automatic Integration

Run code review automatically before every commit:

┌─────────────────────────────────────────────────────────────────┐
│  COMMIT WORKFLOW                                                │
│  ─────────────────────────────────────────────────────────────  │
│                                                                 │
│  1. Write code                                                  │
│  2. Run tests (TDD - must pass)                                 │
│  3. Run /code-review  ← MANDATORY                               │
│  4. Address critical/high issues                                │
│  5. Commit                                                      │
│  6. Push                                                        │
│                                                                 │
│  Skip step 3? ❌ NO COMMIT ALLOWED                              │
└─────────────────────────────────────────────────────────────────┘

---

Using the Code Review Plugin

Basic Usage

# Review current changes
/code-review

# Review specific files
/code-review src/auth/*.ts

# Review a PR
/code-review --pr 123

# Review with specific focus
/code-review --focus security
/code-review --focus performance
/code-review --focus architecture

Review Categories

The code review plugin analyzes:

Severity Levels

---

Pre-Commit Hook Integration

Install Pre-Commit Hook

#!/bin/bash
# .git/hooks/pre-commit

echo "🔍 Running code review..."

# Run Claude code review on staged files
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx|py|go|rs)$')

if [ -n "$STAGED_FILES" ]; then
    # Invoke code review (requires claude CLI)
    claude --print "/code-review $STAGED_FILES" > /tmp/code-review-result.txt 2>&1

    # Check for critical/high issues
    if grep -q "🔴\|Critical\|🟠\|High" /tmp/code-review-result.txt; then
        echo "❌ Code review found critical/high issues:"
        cat /tmp/code-review-result.txt
        echo ""
        echo "Fix these issues before committing."
        exit 1
    fi

    echo "✅ Code review passed"
fi

exit 0

Make Hook Executable

chmod +x .git/hooks/pre-commit

---

Codex CLI Setup (For Codex/Both Modes)

If you want to use Codex or Both modes, install the Codex CLI:

# Prerequisites: Node.js 22+
node --version  # Must be 22+

# Install Codex CLI
npm install -g @openai/codex

# Authenticate (choose one):
# Option 1: ChatGPT subscription (Plus, Pro, Team, Enterprise)
codex  # Follow prompts to sign in

# Option 2: API key
export OPENAI_API_KEY=sk-proj-...

Verify Installation

# Check Codex is installed
codex --version

# Test review
codex
> /review

See codex-review.md skill for full Codex documentation.

---

Gemini CLI Setup (For Gemini/Multi-Engine Modes)

If you want to use Gemini or multi-engine modes, install the Gemini CLI:

# Prerequisites: Node.js 20+
node --version  # Must be 20+

# Install Gemini CLI
npm install -g @google/gemini-cli

# Or via Homebrew (macOS)
brew install gemini-cli

# Install Code Review extension
gemini extensions install https://github.com/gemini-cli-extensions/code-review

Authenticate

# Option 1: Google Account (recommended, 1000 req/day free)
gemini  # Follow browser login prompts

# Option 2: API key (100 req/day free)
export GEMINI_API_KEY="your-key-from-aistudio.google.com"

Verify Installation

# Check Gemini is installed
gemini --version

# List extensions
gemini extensions list

# Test review
gemini
> /code-review

See gemini-review.md skill for full Gemini documentation.

---

CI/CD Integration

GitHub Actions - Claude Only

# .github/workflows/code-review.yml
name: Code Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  code-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get changed files
        id: changed-files
        run: |
          echo "files=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | tr '\n' ' ')" >> $GITHUB_OUTPUT

      - name: Run Claude Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npx @anthropic-ai/claude-code --print "/code-review ${{ steps.changed-files.outputs.files }}" > review.md

      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.md', 'utf8');

            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `## 🔍 Claude Code Review\n\n${review}`
            });

      - name: Check for Critical Issues
        run: |
          if grep -q "Critical\|🔴" review.md; then
            echo "❌ Critical issues found"
            exit 1
          fi

GitHub Actions - Codex Only

# .github/workflows/codex-review.yml
name: Codex Code Review

on:
  pull_request:

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Codex Review
        uses: openai/codex-action@main
        with:
          openai_api_key: ${{ secrets.OPENAI_API_KEY }}
          model: gpt-5.2-codex
          safety_strategy: drop-sudo

GitHub Actions - Both Engines

# .github/workflows/dual-review.yml
name: Dual Code Review

on:
  pull_request:

jobs:
  claude-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Claude Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npx @anthropic-ai/claude-code --print "/code-review" > claude-review.md

      - uses: actions/upload-artifact@v4
        with:
          name: claude-review
          path: claude-review.md

  codex-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install Codex
        run: npm install -g @openai/codex

      - name: Codex Review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          codex exec --full-auto --sandbox read-only \
            --output-last-message codex-review.md \
            "Review this code for bugs, security issues, and quality problems"

      - uses: actions/upload-artifact@v4
        with:
          name: codex-review
          path: codex-review.md

  combine-reviews:
    needs: [claude-review, codex-review]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4

      - name: Combine Reviews
        run: |
          echo "## 🔍 Dual Code Review Results" > combined-review.md
          echo "" >> combined-review.md
          echo "### Claude Findings" >> combined-review.md
          cat claude-review/claude-review.md >> combined-review.md
          echo "" >> combined-review.md
          echo "### Codex Findings" >> combined-review.md
          cat codex-review/codex-review.md >> combined-review.md

      - name: Post Combined Review
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('combined-review.md', 'utf8');
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: review
            });

GitHub Actions - Gemini Only

# .github/workflows/gemini-review.yml
name: Gemini Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Gemini CLI
        run: npm install -g @google/gemini-cli

      - name: Run Review
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        run: |
          # Get diff
          git diff origin/${{ github.base_ref }}...HEAD > diff.txt

          # Run Gemini review
          gemini -p "Review this pull request diff for bugs, security issues, and code quality problems. Be specific about file names and line numbers.

          $(cat diff.txt)" > review.md

      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.md', 'utf8');
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `## 🤖 Gemini Code Review\n\n${review}`
            });

      - name: Check for Critical Issues
        run: |
          if grep -qi "critical\|security vulnerability\|injection" review.md; then
            echo "❌ Critical issues found"
            exit 1
          fi

GitHub Actions - All Three Engines

# .github/workflows/triple-review.yml
name: Triple Engine Code Review

on:
  pull_request:

jobs:
  claude-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Claude Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npx @anthropic-ai/claude-code --print "/code-review" > claude-review.md

      - uses: actions/upload-artifact@v4
        with:
          name: claude-review
          path: claude-review.md

  codex-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install Codex
        run: npm install -g @openai/codex

      - name: Codex Review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          codex exec --full-auto --sandbox read-only \
            --output-last-message codex-review.md \
            "Review this code for bugs, security issues, and quality problems"

      - uses: actions/upload-artifact@v4
        with:
          name: codex-review
          path: codex-review.md

  gemini-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Gemini CLI
        run: npm install -g @google/gemini-cli

      - name: Gemini Review
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        run: |
          git diff origin/${{ github.base_ref }}...HEAD > diff.txt
          gemini -p "Review this code diff for bugs, security, and quality issues:
          $(cat diff.txt)" > gemini-review.md

      - uses: actions/upload-artifact@v4
        with:
          name: gemini-review
          path: gemini-review.md

  combine-reviews:
    needs: [claude-review, codex-review, gemini-review]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4

      - name: Combine Reviews
        run: |
          echo "## 🔍 Triple Engine Code Review Results" > combined-review.md
          echo "" >> combined-review.md
          echo "### 🟣 Claude Findings" >> combined-review.md
          cat claude-review/claude-review.md >> combined-review.md
          echo "" >> combined-review.md
          echo "---" >> combined-review.md
          echo "### 🟢 Codex Findings" >> combined-review.md
          cat codex-review/codex-review.md >> combined-review.md
          echo "" >> combined-review.md
          echo "---" >> combined-review.md
          echo "### 🔵 Gemini Findings" >> combined-review.md
          cat gemini-review/gemini-review.md >> combined-review.md

      - name: Post Combined Review
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('combined-review.md', 'utf8');
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: review
            });

      - name: Check Critical Issues
        run: |
          # Fail if any engine found critical issues
          if grep -qi "critical\|🔴" combined-review.md; then
            echo "❌ Critical issues found by at least one engine"
            exit 1
          fi

---

Review Checklist

Before Every Commit

• [ ] Run /code-review on staged changes
• [ ] No critical (🔴) issues
• [ ] No high (🟠) issues
• [ ] Security concerns addressed
• [ ] Performance issues considered

Before Every PR

• [ ] Full code review of all changes
• [ ] All critical/high issues resolved
• [ ] Tests added for new functionality
• [ ] Documentation updated if needed

Before Every Deployment

• [ ] Final review of deployment diff
• [ ] Security scan passed
• [ ] No new vulnerabilities introduced
• [ ] Rollback plan documented

---

Common Review Findings

Security Issues (Always Fix)

Performance Issues (Should Fix)

Code Quality (Nice to Fix)

---

Post-Review: Decision Extraction

After review completes, extract architectural decisions automatically:

1. If review flagged new architectural choices → prompt to create ADR in docs/adr/ 2. If review approved a new pattern → log to _project_specs/session/decisions.md 3. If review found ADR drift → flag the ADR for update or supersede

### Auto-Log Entry (decisions.md)
- [YYYY-MM-DD] **[Review Finding]**: Brief description
  - Source: Code review of [PR/commit]
  - ADR: Created/Updated ADR-NNNN
  - Impact: What changed

---

Integration with TDD Workflow

┌─────────────────────────────────────────────────────────────────┐
│  TDD + CODE REVIEW WORKFLOW                                     │
│  ─────────────────────────────────────────────────────────────  │
│                                                                 │
│  1. RED: Write failing tests                                    │
│  2. GREEN: Write code to pass tests                             │
│  3. REFACTOR: Clean up code                                     │
│  4. REVIEW: Run /code-review  ← NEW STEP                        │
│  5. FIX: Address critical/high issues                           │
│  6. VALIDATE: Lint + TypeCheck + Coverage                       │
│  7. COMMIT: Only after review passes                            │
│                                                                 │
│  Review catches what tests miss:                                │
│  - Security vulnerabilities                                     │
│  - Performance issues                                           │
│  - Architecture problems                                        │
│  - Code maintainability                                         │
└─────────────────────────────────────────────────────────────────┘

---

Review Response Template

When code review finds issues, respond with:

## Code Review Results

### 🔴 Critical Issues (Must Fix)
1. **SQL Injection in userController.ts:45**
   - Issue: User input directly interpolated into query
   - Fix: Use parameterized query
   - Code: `db.query('SELECT * FROM users WHERE id = $1', [userId])`

### 🟠 High Issues (Should Fix)
1. **Missing authentication on /api/admin endpoints**
   - Issue: Admin routes accessible without auth
   - Fix: Add auth middleware

### 🟡 Medium Issues (Fix Soon)
1. **N+1 query in getOrders function**
   - Consider eager loading or batch query

### 🟢 Low Issues (Nice to Have)
1. **Consider extracting validation logic to separate file**

### ✅ Strengths
- Good test coverage
- Clear function names
- Proper error handling

### 📊 Summary
- Critical: 1 | High: 1 | Medium: 1 | Low: 1
- **Status: ❌ BLOCKED** - Fix critical/high issues before commit

---

Claude Instructions

When to Invoke Code Review

Claude should automatically suggest or run code review:

1. After completing a feature → "Let me run a code review before we commit" 2. Before creating a PR → "Running code review on all changes" 3. When user says "commit" → "First, let me review the changes" 4. After fixing bugs → "Reviewing the fix for any issues"

Review Focus Areas

Prioritize review based on change type:

---

Quick Reference

Commands

# Basic review
/code-review

# Review specific files
/code-review src/auth.ts src/users.ts

# Review with focus
/code-review --focus security

# Review PR
/code-review --pr 123

Severity Actions

🔴 Critical → STOP. Fix now. No commit.
🟠 High     → STOP. Fix now. No commit.
🟡 Medium   → Note it. Fix soon. Can commit.
🟢 Low      → Optional. Nice to have.
ℹ️ Info     → FYI only.

Workflow

Code → Test → Review → Fix → Commit → Push → PR → Review → Merge → Deploy
              ↑                              ↑                    ↑
           /code-review                /code-review          /code-review

ADR Gate — Pre-Review Spec Enforcement

Every code review must have architectural context. This gate runs before review engines and ensures changes are linked to ADRs (Architecture Decision Records) and specs.

---

Gate Protocol

Before any review engine runs, execute this sequence:

Changed files detected
      |
      v
[1. Classify change scope]
      |
      v
  Trivial? ──YES──> Skip gate, proceed to review
      |
      NO
      v
[2. Discover linked ADRs + specs]
      |
      v
  Found? ──YES──> Inject into review context
      |
      NO
      v
[3. Reverse-engineer ADR draft]
      |
      v
[4. Present draft to user OR auto-tag as "proposed"]
      |
      v
[5. Proceed to review with ADR context]

---

Step 1: Classify Change Scope

Exempt trivial changes from ADR requirements:

Trivial (Skip Gate)

• Typo fixes, comment edits, whitespace
• Dependency version bumps (patch/minor)
• Test-only changes that don't alter behavior
• Config value changes (not structural)
• Changelog/README updates

Detection

# If ALL changed files match trivial patterns, skip gate
TRIVIAL_PATTERNS="CHANGELOG|README|\.lock$|\.md$|__snapshots__|\.test\.|\.spec\."

Non-Trivial (Gate Applies)

• New files or deleted files
• Changes to API routes, models, schemas
• Security-related files (auth, crypto, permissions)
• Architecture changes (new services, new patterns)
• Database migrations

---

Step 2: Discover ADRs + Specs

Search in order — stop when context is sufficient:

2a. Check docs/adr/ directory

# List existing ADRs
ls docs/adr/*.md 2>/dev/null

# Search ADR content for references to changed files/modules
grep -rl "module_name\|feature_name" docs/adr/ 2>/dev/null

2b. Query iCPG (if indexed)

search_graph(name_pattern="*", label="ReasonNode")

Match ReasonNodes to changed file paths. If iCPG is not available, skip — this step is optional.

2c. Check _project_specs/

# Search specs for references to the changed area
grep -rl "feature_name\|module_name" _project_specs/ 2>/dev/null

2d. Check git history for decision context

# Get commit messages that explain WHY for changed files
git log --oneline -10 -- <changed_files>
git log --grep="decision\|chose\|instead of\|trade-off" -5

2e. Check issue tracker references

# Look for ticket references in recent commits
git log --oneline -20 | grep -oE "(#[0-9]+|[A-Z]+-[0-9]+)"

# Check PR description if in PR context
gh pr view --json body -q .body 2>/dev/null

Discovery Output

Produce an ADR context block:

## ADR Context for Review

### Linked ADRs
- ADR-0003: Use Zustand for state management (accepted)
- ADR-0007: Atomic file writes for editor (accepted)

### Linked Specs
- _project_specs/phase-08-editor.md
- GitHub Issue #25: In-browser file editor

### Relevant Decisions (from git history)
- "Chose atomic write via temp+rename over direct write" (commit abc123)

### Coverage
- 3/5 changed files have ADR linkage
- 2 files have no documented decision context

---

Step 3: Reverse-Engineer ADR Draft

When ADRs are missing for non-trivial changes, draft one:

Input Sources

1. git log --follow -5 <file> — commit messages for intent 2. git diff — what actually changed 3. File content — module structure, imports, patterns 4. PR description (if available)

Draft Template

# NNNN - [Auto-generated title from change description]

**Status:** proposed
**Date:** [today]
**Spec:** [discovered spec or "none — needs linking"]
**Deciders:** [git author]

## Context
[Extracted from commit messages and PR description]

## Decision
[Inferred from the code changes — what pattern/library/approach was chosen]

## Consequences
[Inferred trade-offs from the implementation]

## Alternatives Considered
[If git history shows rejected approaches, include them]

---

Step 4: Present or Auto-Tag

Interactive Mode (default when user is present)

Present the draft ADR:

No ADR found for changes to src/services/editor.ts.
Here's a draft based on git history and code:

  # 0008 - Atomic file writes for editor API
  Status: proposed
  Decision: Use temp file + os.rename for atomic saves
  Context: Editor needs crash-safe writes...

Accept this ADR? [Y/edit/skip]

Unattended Mode (CI/CD, headless)

• Write ADR draft as docs/adr/NNNN-draft-TITLE.md with Status: proposed
• Log warning: "ADR auto-generated as proposed — needs human review"
• Do NOT mark as "accepted" — only humans accept ADRs
• Review proceeds with the proposed ADR as context

Configuration

Set in project CLAUDE.md or .claude/settings.json:

[adr-gate]
mode = "interactive"   # interactive | unattended | strict
# interactive: ask user to confirm ADR drafts
# unattended: auto-write as proposed, proceed
# strict: block review until ADR exists (not auto-generated)

---

Step 5: Inject into Review Context

Prepend this block to the review prompt sent to any engine:

## Architectural Context (ADR Gate)

### Active ADRs for This Change
[List of relevant ADRs with status and summary]

### Linked Specifications
[List of specs/tickets with key requirements]

### Review Against ADRs
In addition to standard review categories, verify:
1. Does this change conform to the linked ADRs?
2. Does it introduce decisions not captured in any ADR?
3. Should any existing ADR be updated or superseded?
4. Are there spec requirements not addressed by this change?

---

New Review Dimension: ADR Compliance

Added to the standard review categories:

Severity for ADR Issues

---

Post-Review: Decision Extraction

After review completes, extract new decisions:

1. If review flagged architectural choices → prompt to create ADR 2. If review approved a new pattern → log to _project_specs/session/decisions.md 3. If review found ADR drift → flag ADR for update

Auto-Log Format (decisions.md)

- [YYYY-MM-DD] **[Review Finding]**: Brief description
  - Source: Code review of [PR/commit]
  - ADR: Created/Updated ADR-NNNN
  - Impact: [What changed]

---

ADR Numbering

ADRs use sequential 4-digit numbers: 0001, 0002, etc.

Auto-Number Logic

# Find next ADR number
LAST=$(ls docs/adr/*.md 2>/dev/null | sort -t- -k1 -n | tail -1 | grep -oE '[0-9]{4}' | head -1)
NEXT=$(printf "%04d" $((${LAST:-0} + 1)))

---

Project Init Integration

When a project is initialized via claude-bootstrap: 1. Create docs/adr/ directory 2. Write docs/adr/0001-project-init.md with tech stack decisions 3. Add docs/adr/ to the file structure documentation 4. Register ADR pattern in session decisions.md

---

Quick Reference

/code-review          → ADR gate runs automatically before review
docs/adr/NNNN-*.md   → ADR storage location
_project_specs/       → Spec storage (phases, roadmap)
decisions.md          → Session decision log (auto-appended)

ADR statuses: proposed → accepted → deprecated/superseded
Gate modes:   interactive | unattended | strict