pbs-projects/Tech/Projects/a-review.md

project	type	status	path	tags	created	updated
a-review	project-plan	active	Tech/Projects	pbs claude-code code-review skill gemini ollama	2026-04-27	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