Travis Herbranson 86797abb99 Initial a-review skill: model-agnostic independent code review

Skill that sends git diffs to an independent AI model (Gemini CLI, Ollama)
for security, bug, performance, and convention review. Assembles a context
packet from CLAUDE.md + session notes + expanded diff so the reviewer
evaluates intent vs. implementation.

Includes context assembler script, structured review prompt template,
and review-ready CLAUDE.md with key patterns documented.

2026-04-27 20:32:56 -04:00

3.2 KiB

Raw Permalink Blame History

a-review Skill — Session Notes

Session log for the a-review-skill project. Each session is a dated heading with a list of changes. Each change has a label, narrative, and four structured fields (What, Why, How, Touches).

Session — 2026-04-27

SKILL.md Definition

Wrote the skill definition with trigger description, five-step workflow (collect diff, assemble context, send to reviewer, save output, surface findings), and reference file pointers. Triggers automatically after coding sessions and on manual requests. Supports Gemini CLI and Ollama backends with examples for both.

What: SKILL.md with model-agnostic review workflow
Why: Need a reusable skill that runs independent code review from any AI backend, not just Gemini CLI one-offs
How: Five-step workflow: git diff, assemble_context.py, pipe to backend with review-prompt.md, save to reviews/ folder, summarize findings. Backend selection via .a-review.yml config or default to Gemini CLI.
Touches: a-review/SKILL.md (new)

Review Prompt Template

Wrote the structured prompt sent to the reviewer model. Covers five review areas (security, bugs, performance, conventions, intent-vs- implementation) with severity levels and output format guidance. Explicitly tells the reviewer to skip stylistic preferences and not manufacture findings.

What: Review prompt template at references/review-prompt.md
Why: Structured prompt produces consistent, actionable findings across different models
How: Markdown document with numbered review areas, severity definitions ([CRITICAL], [WARNING], [INFO]), and output format template. Includes instruction to compare session notes intent against diff implementation.
Touches: a-review/references/review-prompt.md (new)

Context Packet Assembler

Python script that collects CLAUDE.md, latest session notes, expanded diff (with surrounding context), and diff stat from the current git repo. Outputs a structured markdown document to stdout for piping to the reviewer.

What: assemble_context.py CLI script with --staged and --context options
Why: Reviewer needs project context alongside the diff to produce meaningful findings — a naked diff review misses convention violations and intent mismatches
How: Uses subprocess to call git commands. Finds project root via git rev-parse --show-toplevel. Reads CLAUDE.md and latest session entry from sessions/ directory. Builds markdown document with labeled sections. Supports --staged for uncommitted changes and --context N for surrounding line count (default 10).
Touches: a-review/scripts/assemble_context.py (new)

Project Documentation

Added CLAUDE.md with key patterns documenting the context packet approach, model-agnostic backend design, read-only reviewer constraint, and the complementary relationship with zero-check.

What: CLAUDE.md with architecture and key patterns
Why: Future sessions need to understand design decisions, especially the separation between context assembly, prompt template, and backend
How: Follows the review-ready CLAUDE.md convention with file tree, key patterns, dev workflow, and session notes pointer.
Touches: CLAUDE.md (new)

3.2 KiB Raw Permalink Blame History