Skip to content

docs: document how deep-review findings route to the loop's verify job #595

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
allxsmith merged 5 commits into from
Aug 29, 2026
Merged

docs: document how deep-review findings route to the loop's verify job #595

Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ba4f39e
docs: document how deep-review findings route to the loop's verify job
allxsmith Aug 29, 2026
145d7fe
docs: cover the refutation path and scope the absent-verify claim
allxsmith Aug 29, 2026
790c3ae
docs: note that verify reads the PR's whole unresolved-thread set
allxsmith Aug 29, 2026
315793a
docs: separate the iteration cap from the paused state for verify
allxsmith Aug 29, 2026
234fc0f
docs: unambiguous zero-blocking phrasing, bound the thread-set claim
allxsmith Aug 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions docs/docs/guides/getting-started/ai-development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,26 @@ re-verify their own findings against the pushed code (nothing is closed on the f
alone) → after at most 4 fix rounds, the PR either converges (CI green, all review threads
resolved) or is handed to a human with the open disagreements listed.

**How deep-review findings reach the fixer.** The deep review posts on two channels, and which
one a finding takes decides whether the loop acts on it. Blocking findings (🔴 Critical, 🟠
Major, 🟡 Minor) are filed as **inline review comments** on the lines they concern, and those
threads are the fix agent's work items. It answers each either with `Fixed in <sha>` when it
makes the fix, or with a refutation when it judges the finding wrong — and in neither case does
it resolve the thread. The reviewer picks it up from there in its `verify` pass: it re-checks a
`Fixed in` claim and resolves only what is genuinely fixed, and answers a refutation with one
rebuttal-or-concede round before a human rules. 🔵 Advisory findings never go inline: they
appear only as rows in the summary review (the one carrying the `<!-- claude-deep-review -->`
marker), because an inline thread is an actionable work item and advisories must not spin the
loop.

One consequence is worth knowing before reading a run's job list: **a deep review that reports
`0 blocking` creates no threads, so the `verify` pass has nothing to check.** Most reviews do
land at zero blocking, which makes this the usual reason `verify` is absent from a run — but it
Comment thread
allxsmith marked this conversation as resolved.
Resolved
is not the only one. The gate picks a single mode per run, and red or pending CI and threads
still awaiting the fixer all outrank `verify`; a capped or paused loop stops before it too. So
an absent `verify` is normal rather than a stalled loop, and the gate's decision line (it logs
`fail=`, `pend=`, `actionable=`, `verify=` and `rebut=` counts) says which case applied.

**Screenshots at handoff.** When the loop flips a PR to `needs-human-review` it also
dispatches a screenshot pass (`story-screenshots.yml`): Playwright captures the Storybook
stories affected by the PR's changed files — once light, once dark — and posts them to the PR
Expand Down
Loading