diff --git a/Tech/Projects/a-review.md b/Tech/Projects/a-review.md new file mode 100644 index 0000000..1d64582 --- /dev/null +++ b/Tech/Projects/a-review.md @@ -0,0 +1,188 @@ +--- +project: a-review +type: project-plan +status: active +path: Tech/Projects +tags: + - pbs + - claude-code + - code-review + - skill + - gemini + - ollama +created: 2026-04-27 +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 \ No newline at end of file