From a3d027d6c2ac3b5f8d105c3123fe95e33d0350c3 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Thu, 17 Sep 2026 20:58:53 -0400
Subject: [PATCH] feat(ship-check): pr-monitor sweeps the finding's class
 before each push
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Monitoring loops converged one instance per bot cycle: fix the flagged
site, push, wait for the re-review, get the sibling flagged — 121
comments on one PR. The skill handled findings as instances and never
asked for the pattern.

- Step 3 bot-thread procedure gains step 4: generalize each valid
  finding to its class, grep the changed files (doc claims: every
  sibling surface), fix all instances in the same commit, and state
  the sibling count in the reply
- "After handling all threads" now requires one full-diff re-scan
  against every class flagged on the PR so far before pushing — each
  push buys a complete re-review, so a missed sibling is next cycle's
  comments

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 plugins/ship-check/skills/pr-monitor/SKILL.md | 20 +++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/plugins/ship-check/skills/pr-monitor/SKILL.md b/plugins/ship-check/skills/pr-monitor/SKILL.md
index cee52e8..d4a056c 100644
--- a/plugins/ship-check/skills/pr-monitor/SKILL.md
+++ b/plugins/ship-check/skills/pr-monitor/SKILL.md
@@ -232,7 +232,17 @@ For each unresolved bot thread, do ALL of these in order:
    Fix anything that's reasonable effort; only escalate to the user when the fix is
    genuinely high lift.
 
-4. **Reply to the comment** -- do this BEFORE resolving, for EVERY bot comment.
+4. **Sweep the class, not just the instance.** A bot flags instances; the next pass
+   flags the sibling you left, and the point-fix loop is how a PR ends up with 100+
+   comments. Generalize each valid finding to the pattern it represents — the same
+   claim on another doc surface, the same code shape in another function, the same
+   missing guard on another entry point — then grep the PR's changed files (and for
+   doc claims, every sibling surface) for the other instances and fix them all in
+   the same commit. State the count in the reply: *"Fixed here and at N sibling
+   sites."* A class-wide fix converges the review; a point fix buys another full
+   bot cycle for each sibling.
+
+5. **Reply to the comment** -- do this BEFORE resolving, for EVERY bot comment.
 
    Since `gh` posts as the user's account, every reply MUST include an attribution
    footer. Claude runs use the family ID from system context, such as
@@ -258,7 +268,7 @@ For each unresolved bot thread, do ALL of these in order:
    - **False positive** -- reply explaining why:
      *"This is intentional -- [reasoning].\n\n---\n🔍 ship-check · pr-monitor · MODEL_ID"*
 
-5. **Resolve the thread** (AFTER replying):
+6. **Resolve the thread** (AFTER replying):
    ```
    gh api graphql -f query='mutation {
      resolveReviewThread(input: {threadId: "THREAD_ID"}) {
@@ -309,6 +319,12 @@ If the user provides a response, reply on their behalf and resolve.
 
 ### After handling all threads
 
+**Before pushing, re-scan the full diff once against every class the bot has
+flagged on this PR so far** — this cycle's and earlier cycles'. Each push
+triggers a complete re-review, so any instance the per-finding sweeps missed
+becomes next cycle's comments. The target is convergence in one or two
+cycles, not a comment-per-instance conversation.
+
 If you fixed any code: stage, commit, push. Then **go to Step 4** -- this is mandatory.
 
 If no fixes were needed and no code was pushed: **go to Step 5.**