How a review plan works

A short tour of the pipeline behind Guided Review. The Chrome extension and the CLI share this engine in @guided-review/core; only the host differs (GitHub PR page vs local git + localhost UI).

Hands-on paths: Your first review (extension) · CLI. Provider setup: Configure AI provider.

Diff → plan

1. Parse — The unified diff is parsed into files, hunks, and lines. Every hunk gets a stable id (filePath#index) that the model must reference exactly.
2. Prompt — The parsed diff is rendered into LLM-readable text with hunk ids annotated.
3. Annotate — A structured review plan is streamed from your provider. On the extension that runs in the background worker; on the CLI it runs in the local server when you click Structure With AI.
4. Validate — Each unit is cleaned against real file/hunk ids; hallucinated refs are dropped.
5. Display — The overlay resolves unit refs back to the real diff for rendering.

If no API key is configured, step 3 is skipped and a local file-per-unit plan is used instead. If annotation fails mid-stream, see Troubleshooting → Plan generation fails.

Review units

A review unit is a logical step in the plan: a title, intent context, and one or more hunk references. Production changes and tests are separate units — never mixed in one step. After each feature’s production unit(s), the matching tests unit follows immediately (not a single dump of all tests at the end). Tests steps show a flask icon next to the unit name in the sidebar and diff pane.

Units aim for a consistent structure on the same diff: same hunk partition, order, and change-vs-tests kind. Titles and wording may still vary slightly across models.

On a GitHub PR, the first display step is a synthetic PR Description unit built from page context, then the plan’s units. On the CLI, the first step is Change summary (where Structure With AI lives) for the selected local scope. Overlay layout: Reading the overlay. You step through units with the footer or keyboard shortcuts.

Summaries are optional guidance — you still judge the code (FAQ).

Without a provider

If you start a review before configuring an API key, Guided Review still opens:

• The diff is parsed and shown as usual.
• The plan is one unit per changed file, in the order files appear in the diff (tests still get the flask kind when the path looks like a test file).
• Unit titles are file paths; commentary is empty so the context panel can prompt you to connect a provider instead of inventing text.
• You can still navigate and search the diff. On the extension you can also draft comments and submit once GitHub is connected. On the CLI you can leave notes and Generate Prompt.

Connecting a provider and starting again (or Structure With AI / Retry when prompted) replaces that fallback with an AI-clustered plan for the current diff.

Chunking large diffs

Large diffs are split by file into chunks (~60k characters each). A single file’s hunks are never split across chunks. Each chunk is annotated separately; unit ids are namespaced so multi-chunk plans don’t collide, then merged for the final plan.

That chunk size is why model choice still matters on big changes: each chunk is a full model call, so cost scales with diff size and model — see the FAQ on cost.

Streaming and validation

As text deltas arrive, complete units are extracted and validated. Progressive unit events update the overlay; a final done event carries the merged plan. Invalid structure or unknown hunk ids never reach the reviewer as broken links into missing code.

Line comments and CLI notes always attach to the real diff lines shown for a unit — not to model-invented code.

What the model must not invent

If a unit only references invalid hunks after cleanup, it won’t be shown. That keeps the overlay honest even when the model is imperfect.

Next. Your first review · Reading the overlay · Images & binary files · Leave line comments · Privacy & data