wiki-vault/Sources/Dev/a-review.md

---
created: 2026-04-27
path: Sources/Dev
project: a-review
status: active
tags:
- pbs
- claude-code
- code-review
- skill
- gemini
- ollama
type: project-plan
updated: 2026-04-27
---

# a-review — Agent Code Review Skill

A Claude Code skill that sends code changes to an independent AI agent
for review. Model-agnostic — supports Gemini CLI, Ollama, or any model
that accepts a prompt and returns text. Provides the reviewer with
project context (CLAUDE.md, session notes) alongside the diff and
touched files so it can evaluate intent vs. implementation.

## Why

A single agent writing and reviewing its own code has blind spots. The
Gemini CLI proof of concept on the Loom project caught a path traversal
vulnerability, a date formatting bug, and a performance issue — all real,
all missed by the authoring agent. a-review makes that second-opinion
workflow repeatable and model-agnostic.

This is not a replacement for zero-check. zero-check runs deterministic
validation (lint, SAST, tests) — pass/fail. a-review is subjective
evaluation from a different model — "did you miss something a linter
wouldn't catch?"

## How It Works

1. Collect the git diff (default: `HEAD~1`, option for staged changes)
2. Collect the diff with expanded context (e.g., git diff -U10 for 10 lines
of surrounding code)
3. Read CLAUDE.md for project conventions and architecture
4. Read the latest session notes entry for intent/context
5. Build a structured review prompt combining all four inputs
6. Pipe to the configured model backend
7. Save output to `reviews/a-review-YYYY-MM-DD.md` in the project
8. Surface a summary back to the user

## Context Packet

The reviewer receives a "briefing" assembled from:

- **CLAUDE.md** — architecture, key patterns, conventions (the "what
  and how" of the codebase)
- **Session notes** — latest session entry (the "what was intended"
  for this set of changes)
**Expanded diff** — diff with extra surrounding lines so the
reviewer can see the function each change lives in
- **Diff** — the actual changes to evaluate

This mirrors how a human code review works: read the PR description,
understand the project conventions, look at the changed files, then
evaluate the diff.

## Review Prompt Template

The prompt should instruct the reviewer to:

- Check for security vulnerabilities (injection, path traversal,
  auth bypass, data exposure)
- Check for bugs (logic errors, edge cases, null handling, off-by-one)
- Check for performance issues (unnecessary loops, missing caching,
  repeated I/O)
- Check for convention violations (patterns defined in CLAUDE.md)
- Compare intent (from session notes) vs. implementation (from diff)
- Rate each finding by severity: critical, warning, info
- Skip stylistic preferences — focus on correctness and safety

## Model Configuration

A config file in the project (e.g., `.a-review.yml`) specifies:

yaml
model: gemini          # gemini | ollama | (future backends)
gemini:
  command: gemini
  approval_mode: plan  # read-only, no file writes
  trust_workspace: true
ollama:
  model: codellama     # or any installed model
  host: localhost
  port: 11434


The skill reads this config to determine which backend to call and
how to call it.

## Output Format

Saved to `reviews/a-review-YYYY-MM-DD.md` (with `-N` suffix if
multiple reviews in one day). Format:

markdown
# a-review — YYYY-MM-DD

**Model:** gemini-2.5-pro (or whatever ran)
**Diff:** HEAD~1 (N files, M lines changed)
**Session:** 

## Findings

### [CRITICAL] 

**File:** 
**Line:** 

### [WARNING] 
...

### [INFO] 
...

## Summary



## Phasing

### Phase 1 — MVP with Gemini CLI
- [ ] Create SKILL.md for Claude Code
- [ ] Build the context packet assembler (CLAUDE.md + session notes +
      touched files + diff)
- [ ] Build the review prompt template
- [ ] Implement Gemini CLI backend
- [ ] Implement review output parser and markdown writer
- [ ] Save output to `reviews/` folder
- [ ] Test on Loom project

### Phase 2 — Ollama backend
- [ ] Add Ollama backend (HTTP API call)
- [ ] Add `.a-review.yml` config file support
- [ ] Test with a local model on herbys-dev

### Phase 3 — Refinement
- [ ] Tune the review prompt based on real-world results
- [ ] Add option for staged changes vs. HEAD~1
- [ ] Add collision-safe date suffix for multiple daily reviews
- [ ] Evaluate whether to auto-run after zero-check completes
- [ ] Evaluate whether full file contents are needed for large or
cross-cutting changes

## Out of Scope

- Full project review (only diff + touched files)
- Non-code review (content, config-only changes)
- Auto-fixing findings (review only, human decides)
- PR/git integration (this is a local skill, not a CI tool)

## Open Questions

- Should the review prompt be customizable per-project, or is one
  standard template enough?
- What size diff is too big? Should the skill warn or refuse above
  a threshold?
- Should findings be appended to the session notes automatically?

## Success Criteria

The skill is working when:
- It catches at least one issue per review that the authoring agent
  missed
- The findings are actionable, not noise
- Travis trusts it enough to run it after every session

## Proof of Concept

Already validated. On 2026-04-27, Gemini CLI reviewed the Loom project
diff and caught:
- Path traversal vulnerability in MCP write tools
- Date formatting bug (AttributeError on None dates)
- Performance issue (vault re-read on every MCP call)

All three were real. All three were fixed.


...sent from Jenny & Travis
-- 
...sent from Jenny & Travis