Impacting PRs

3. Analyse each hit

For every PR with hits, read the surrounding diff ($OUT/diffs/<n>.diff) and decide:

• False positive? Drop it: moved/renamed lines, comments, changesets, fixtures, generated files, code that was already there, or a usage the matrix explicitly allows.
• Which layer the file belongs to → which row of the matrix applies → severity.
• What the author must do, in one sentence, referring to their own file paths and symbols.
• The exact line to comment on, from hits.tsv — every surviving hit becomes an inline comment, not a paragraph in a wall of text.
• Is the replacement mechanical? Then attach a ```suggestion block the author can commit in one click. Only when you can write the exact resulting line(s) — a wrong suggestion is worse than none, and a suggestion is a claim we are sure, so keep the hedging in the prose around it.

The strongest suggestion you can write is one copied from the PR's own neighbours: if sibling files in the same directory already import the symbol the new way on origin/<base>, quote that and the fix becomes indisputable.

Then look past hits.tsv. It only sees added lines containing the pattern, so it structurally misses a PR that edits a file the migration deletes — the added line (+ newField?: string;) never names the package. Those are the expensive cases: guaranteed rebase conflicts, and often the author already made the same change in the right place and just left a stale duplicate. Check every PR with hits, and cheaply check the others:

grep -lE '^\+\+\+ b/(<deleted-path-1>|<deleted-path-2>)' "$OUT"/diffs/*.diff

Keep a table: PR · author · what it is about · files · severity · required action. Verify a couple of the target APIs really exist before recommending them — git grep on origin/<base> in 🟠/🔴 mode, on the migration PR's branch in 🔍 study mode (gh pr diff <migration-pr>), since on develop they do not exist yet. Recommending a symbol that does not exist destroys the credibility of the whole batch.

4. 🔍 Study mode: one report, zero pings

Only when the replacement is not on develop — re-read the mode table before landing here, since an unmerged migration PR is usually still 🟠. The impacted authors cannot act yet, so nothing is posted on their PRs. Deliver the blast radius to the person doing the migration instead — steps 5 to 7 do not apply:

• They have a PR for the migration → one comment on their own PR, updated in place on later runs (gh pr comment <migration-pr> --body-file report.md --edit-last).
• They don't → just answer in the conversation. Nothing is posted anywhere.

The report is for sizing the work, not for shaming anyone — group by required action, not by PR, since that is what tells the author whether they need a codemod, a migration guide, or a compat shim:

🔍 Impact study for `<artifact>` (this PR, not on `develop` yet) — 6 open PRs affected

**Mechanical import swap (4)** — #20204 (57 files, wallet-api refactor) · #19581 · #19191 · #20045
**Needs the coin-framework accessor (1)** — #20018 (coin-vechain, no access to the new store)
**Unclear, worth a chat (1)** — #20221 (adds a new dependency on the dropped path)

Scanned N open PRs targeting `develop`; skipped M conflicting + K other-base.
Rerun once this lands to notify them, or say the word and I'll draft the heads-up now.

Two things this makes visible early, which is the point of the mode: PRs so large the migration should wait for them to land, and layers with no replacement yet.

5. Draft and get approval

One comment per PR, from the templates in references/comment-templates.md. Tone: 🤖 On behalf of @<author> in the summary body only — never repeat the attribution in each inline comment, it reads like a robot signing every line. Hedged ("it looks like", "you may need to") — we are never 100% sure, the PR author knows their code better. In English, nice, short, actionable, open to being wrong.

Show all drafts to the user in one message, grouped by severity, and wait. Expect the user to correct the expected code change — fold their corrections back into the matrix and re-check the other drafts against it.

6. Post (🟠 / 🔴 only)

Default form: one review carrying a short summary body + one inline comment per hit (with a suggestion block where relevant). Anchored comments land next to the offending line, so the author sees the impact in their own code instead of in a wall of text — see references/comment-templates.md for the payload.

# event: REQUEST_CHANGES for 🔴 blocking, COMMENT for 🟠 heads-up (does not block)
gh api repos/$GH_REPO/pulls/<n>/reviews --input payload.json --jq .html_url

Sequentially, out of the sandbox, capturing each returned URL. Fallbacks:

• 422 line must be part of the diff → the hit is outside the PR's own hunks; drop that inline comment (keep it in the body) rather than retrying on another line.
• REQUEST_CHANGES on your own PR is rejected by GitHub → post with event: COMMENT and say in the body that it would otherwise be blocking.
• No inline anchor at all (nothing mechanical, or all 422s) → gh pr comment <n> --body-file draft.md.

State drifts between the scan and the posting, so right before each post re-check that the PR is still open, still MERGEABLE and still free of the marker — the scan's exclusions are only as fresh as the scan:

gh pr view <n> --json state,mergeable --jq '"\(.state) \(.mergeable)"'   # expect: OPEN MERGEABLE

7. Recap

Report back a copy-pasteable summary, grouped by severity, each line linking the posted comment (the URL returned above, e.g. #issuecomment-… / #pullrequestreview-…) plus a 2-4 word label of what the PR is about:

:red_circle: Blocking (@x/dropped removed from develop)
- #19806 (<comment url>) — Kaspa coin tester
- #19645 (<comment url>) — Readiness + Tezos

:large_orange_circle: Deprecated (@x/deprecated-types)
- #20034 (<comment url>) — Polkadot

List separately what was skipped and why (conflicting, other base, false positive) so the user can double-check the blind spots.