---
name: a-review
description: >
  Run an independent AI code review after coding sessions. Sends the git diff,
  CLAUDE.md, and session notes to a second model (Gemini CLI, Ollama, or any
  text-in/text-out backend) for security, bug, performance, and convention
  review. Use this skill after completing code changes, after zero-check passes,
  when the user asks for a review, or when you want a second opinion on code
  quality. Also triggers on "review my changes", "get a second opinion",
  "run a-review", or "check this with gemini/ollama".
---

# a-review — Agent Code Review

Send code changes to an independent AI for review. The reviewer gets project
context (architecture, conventions, intent) alongside the diff so it can
evaluate what was done against what was intended.

This is not a linter or SAST tool — that's what zero-check does. This is a
subjective second opinion from a different model: "did you miss something
a linter wouldn't catch?"

## When to Run

- After a coding session with substantive changes
- After zero-check passes (review complements validation)
- When the user asks for a review or second opinion
- Before committing changes to a shared branch

Do not run on trivial changes (typo fixes, comment edits, formatting-only).

## Workflow

### Step 1: Collect the diff

```bash
# Default: changes since last commit
git diff HEAD~1

# Or staged changes if nothing committed yet
git diff --cached

# Expanded context for reviewer (10 lines surrounding each change)
git diff -U10 HEAD~1
```

Use `HEAD~1` by default. If the user says "review staged changes" or
there are no commits yet, use `--cached`.

### Step 2: Assemble the context packet

The reviewer needs four things:

1. **CLAUDE.md** — read from the project root. This gives the reviewer
   the architecture, key patterns, and conventions to review against.
   If CLAUDE.md doesn't exist, skip this and note it in the output.

2. **Session notes** — read the latest session entry from
   `sessions/<project-slug>.md`. This tells the reviewer what was
   intended, so it can compare intent vs. implementation.
   If no session notes exist, skip this.

3. **Expanded diff** — `git diff -U10 HEAD~1` so the reviewer sees
   each change in its surrounding context (the function it lives in,
   the class it belongs to).

4. **Diff stat** — `git diff --stat HEAD~1` for a quick summary of
   what files changed and how much.

Run the assembler script to combine these:

```bash
python scripts/assemble_context.py
```

This reads the project, builds the context packet, and prints it to
stdout. Pipe it to the reviewer.

### Step 3: Send to the reviewer

Check for a `.a-review.yml` config file in the project root. If it
exists, use the configured backend. If not, default to Gemini CLI.

**Gemini CLI:**
```bash
python scripts/assemble_context.py | \
  GEMINI_CLI_TRUST_WORKSPACE=true \
  gemini -p "$(cat references/review-prompt.md)" \
  --approval-mode plan
```

**Ollama:**
```bash
CONTEXT=$(python scripts/assemble_context.py)
curl -s http://localhost:11434/api/generate \
  -d "{\"model\": \"codellama\", \"prompt\": \"$(cat references/review-prompt.md)\n\n$CONTEXT\", \"stream\": false}" \
  | jq -r '.response'
```

The `--approval-mode plan` flag for Gemini is important — it keeps
the reviewer in read-only mode so it can't modify files.

### Step 4: Save the output

Save the review to `reviews/a-review-YYYY-MM-DD.md` in the project.
Create the `reviews/` directory if it doesn't exist.

If a review already exists for today, suffix with `-2`, `-3`, etc.

Add a header to the saved file:

```markdown
# a-review — YYYY-MM-DD

**Model:** <model name/version>
**Diff:** HEAD~1 (N files, M lines changed)
**Context:** CLAUDE.md + session notes included

---

<reviewer output here>
```

### Step 5: Surface findings

Read the saved review and summarize the findings for the user. Group
by severity if the reviewer used severity labels. Highlight anything
marked critical or security-related.

If the reviewer found actionable issues, offer to fix them.

## Reference Files

| File | Purpose |
|------|---------|
| `references/review-prompt.md` | The prompt template sent to the reviewer |
| `scripts/assemble_context.py` | Builds the context packet from project files |

Load `references/review-prompt.md` when building the review command.
Load `scripts/assemble_context.py` when you need to understand or
modify the context assembly logic.