From 55c3d748b85b699dbe3caedda5d9e1ccf9db8bb1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20S=C3=A4nger?=
 <20968534+dsnger@users.noreply.github.com>
Date: Mon, 27 Jul 2026 21:03:17 +0200
Subject: [PATCH] Make the re-trigger an optional note, not a verification step
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Resolves the Minor collected on #19: the file said `@coderabbitai review` is
a no-op while automatic reviews are active, then instructed operators to run
it anyway inside the deterministic merge-verification procedure. Described
twice, once imperatively and once as "expect nothing".

The imperative is gone from the procedure, which now ends at the `DISMISSED`
filter and describes the step exactly once — as an explicitly optional note
beside the human-exception clause it precedes, and therefore for Wait-for
bots only.

Facts kept, and one boundary made explicit: the no-op behaviour with its #17
source; that #14 and #17 both moved nothing; that nothing here claims a
re-trigger cannot work, only that this account has never seen one work; and
that `full review` must not be claimed to work unless a run of it is actually
observed here, which as of #19 it has not.

Gate B: N/A — single explanatory documentation path per §5's prose rule.
Battery green: shellcheck (6 files), hook tests, invariant tests + check
(123 assertions), version-bump tests + check (36 assertions),
`claude plugin validate . --strict`.
---
 docs/pr-review-bots.md | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/docs/pr-review-bots.md b/docs/pr-review-bots.md
index 38c6c89..d3c185a 100644
--- a/docs/pr-review-bots.md
+++ b/docs/pr-review-bots.md
@@ -129,9 +129,7 @@ nothing" here:** `@coderabbitai review` is a no-op while automatic reviews are a
 `--paginate` matters: without it only page one is read, so a qualifying review can sit on
 page two and be read as absent. `jq -s` is what slurps the pages — `gh api --slurp` cannot
 do it here, being rejected outright when combined with `--jq`. `DISMISSED` is excluded — a dismissed review is not
-a review of that head. If no qualifying record exists, re-trigger once (expect nothing —
-`@coderabbitai review` is a no-op while automatic reviews are active, so the attempt
-costs a wait and is kept only because it is cheap and has not been observed to hurt).
+a review of that head.
 
 **Then the two facts separate, and only one of them still binds.**
 
@@ -152,6 +150,16 @@ kept, not retired: promote a bot back and it reactivates unchanged, for that bot
 live — they document a real requirement under the routing of their time, not a
 requirement suspended in the abstract.
 
+**Optional, not a step: the re-trigger.** Before invoking the human-exception clause —
+so, for a **Wait for** bot only — a re-trigger may be attempted. It is not part of the
+verification above, which is why the procedure no longer contains it: `@coderabbitai
+review` is a **no-op while automatic reviews are active** (the bot's own message on #17),
+so it cannot be expected to move the count, and on #14 and #17 it moved nothing. Nothing
+here says a re-trigger cannot work — only that this account has never seen one work.
+CodeRabbit documents other invocations; **do not claim `full review` works unless a run
+of it has actually been observed here**, which as of #19 it has not. Attempting one costs
+a wait and has not been observed to hurt; that is the whole case for it.
+
 What was actually measured, stated exactly: the rate-limit warning appeared in the **issue
 comment**, while the review record was an earlier completed review of an earlier commit.
 So the demonstrated failure is a *missing* review for the final head — which the