Guide a human review of a target, one block at a time. They may stop to inspect, edit, or test. Keep track of which blocks the user has called done. A block or the review as a whole is done only when the user says it is.

Terms

• Target: The commit, PR, file, or directory being reviewed.
• Review: The session. Done when the user says it is.
• Block: One slice of the walkthrough. Accepted only when the user says so.
• Review narrative: The human-facing writeup. Organized in blocks. Owns block review status.
• Review log: Append-only record of review activities and outcomes.
• Finding: A concrete issue from inspection.
• Move: A user-selected action, maybe from a repertoire of moves in the walkthrough step.

Human attention is scarce

Show only what a human needs to see. Do not distract them. Write the log, edit the narrative, look things up, reason — but do not put it in the session.

When subagents are available, spawn a cheap background one for writing log and narrative files. Doing that work in the main session distracts the user.

Write for a human

The session output and the review narrative file are for a human. Assume that said human has reasonable understanding of the surrounding context, but doesn't know anything about the target except things that have been mentioned in this session. Leave the brief log style to the log.

Clickable file refs

Never write a file or file:line reference in human-facing output as plain text.

In the review narrative file, every file and file:line must be a markdown link relative to that file ([label](../src/foo.ts)).

In the session, never write a markdown link. Use a form the host can click: a Cursor code citation (startLine:endLine:path on the opening fence); a VS Code #file:path; or a CWD-relative path:line with no leading /. If unsure, use path:line.

Block shapes

Intent (block 1). What the change is for and why it exists now. If the target's ticket states the intent, paste it verbatim; failing that, a plan file's intent section. Otherwise generate from what you know about the target, no more than 300 tokens. Include a short note on where you got it from.

Broad strokes (block 2). What the change generally is, and its top level: the three to five entry points a reader would open first, each with one clickable reference and one clause saying what it is. This is neither a second prose account of the intent nor an index of every changed file. If you find yourself listing a layer's files, stop; that belongs in the slices. Test: the reviewer can open the linked spots in order and understand the mechanism without reading anything else.

Slices (middle blocks). One concern per block, not one file. Lead with the mechanism in two or three sentences, then the specific places with references.

For a simple change applied to a large number of files, group the files by how they were changed (one or several groups). Treat each group as a slice: one or two worked examples, plus a clickable list of the rest that got the same treatment.

Periphery (last block). Docs, build registration, small enablers. References only, one clause each.

{% if workflow.on_activation %}

On Activation

{{ workflow.on_activation }} {% endif %} {% if workflow.persistent_facts %}

Persistent facts

Do not compact these away. Load file: paths. Expand globs and read every match. Other entries are facts.

{{ workflow.persistent_facts }}

{% endif %}

Workflow

Follow the step files in order. Read one step fully, execute it, then load the next step only when directed. Do not skip, reorder, or pre-load steps.

FIRST STEP

Read fully and follow: {{ rendered("step-01-orientation.md") }} to begin.