Review pipeline

The review pipeline analyzes a pull request and posts a code review comment. Three stages, all read-only. The agent never writes files or runs git commands.

developer review assistant 42
developer review https://github.com/gregology/assistant/pull/42
developer review assistant 42 --dry-run

Flow

flowchart TD
    A[analyze] --> B[review_findings]
    B --> C[draft]
    C --> C1([post comment])
    C1 --> STOP[STOP]

Straightforward. No branching, no loops.

Stages

analyze

Reads the PR diff and explores the surrounding codebase to understand what changed and why. Returns an AnalysisResult with a summary of the changes. This stage has read-only tools (Read, Glob, Grep).

The point of separating analysis from review is that understanding should happen before judgment. When the agent tries to do both in one pass, it starts generating findings before it fully understands the context.

review_findings

Resumes the analysis session and generates findings. Each finding has a severity level, a file/line reference, and an explanation. Returns a ReviewResult with a list of ReviewComment objects.

draft

Resumes the review session. Formats the findings into a markdown comment. This stage has no tools at all -- it's pure text generation from the findings already in context.

Python posts the formatted comment on the PR. With --dry-run, it prints to stdout instead.

Why three stages?

This costs roughly 3x the tokens of a single-pass review. The tradeoff is better findings. Separating "understand the code" from "find problems" from "write the review" produces more thoughtful reviews with fewer false positives. The analysis stage builds context that the review stage draws on, and the draft stage can reference both.

Session continuity means nothing is lost between stages. The draft stage has access to everything the analysis stage discovered.