Make the re-trigger an optional note, not a verification step

[dsnger]

Resolves the 🟡 Minor collected on #19. Single docs path, 11 insertions / 3 deletions.

The inconsistency. The file established that @coderabbitai review is a no-op while automatic reviews are active, and then instructed operators to run it anyway — inside the deterministic merge-verification procedure. The step was described twice, once imperatively ("re-trigger once") and once as a parenthetical undercutting it ("expect nothing… kept only because it is cheap"). That is what CodeRabbit objected to, and it was right.

The fix. The imperative is out of the procedure, which now ends at the DISMISSED filter. The step survives once, as an explicitly optional note placed beside the human-exception clause it precedes — which also scopes it correctly: the clause binds Wait for bots only, so the re-trigger belongs to that path and not to the general verification every merge runs.

Facts kept, plus one boundary made explicit:

• the no-op behaviour, with its The rate-limit message is noise; the review count is signal #17 source (the bot's own message);
• that Ship the §5 companion files, the deferred template sync, and 0.6.0 #14 and The rate-limit message is noise; the review count is signal #17 both produced nothing;
• that nothing here claims a re-trigger cannot work — only that this account has never seen one work. The evidence is two observations, which is not a proof of impossibility, and the note says so rather than hardening a small sample into a law;
• that full review must not be claimed to work unless a run of it has actually been observed here — as of Move CodeRabbit to opportunistic; disambiguate the CLAUDE.md rows #19 it has not. CodeRabbit documents other invocations; documenting one as effective without running it would break this repo's own rule against documenting a command nobody ran.

Gate B: N/A — single explanatory documentation path per §5's prose rule. Battery green before commit: shellcheck (6 files), hook tests, invariant tests + check (123 assertions), version-bump tests + check (36 assertions), claude plugin validate . --strict.

Summary by CodeRabbit

• Documentation
  • Clarified PR-review workflow guidance for handling CodeRabbit rate limits and review-count verification.
  • Moved re-trigger instructions into an optional section and limited them to applicable waiting scenarios.
  • Documented that manual review requests may have no effect while automatic reviews are active.
  • Added a caution that full-review behavior has not been confirmed for the referenced account.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e50d5bc2-a027-4fe4-98aa-78d866dbbe8e

📥 Commits

Reviewing files that changed from the base of the PR and between 286c55f and 55c3d74.

📒 Files selected for processing (1)

• docs/pr-review-bots.md

---

📝 Walkthrough

Walkthrough

The PR updates docs/pr-review-bots.md to separate optional CodeRabbit re-trigger guidance from the core review-count verification procedure and scope it to Wait for bots.

Changes

CodeRabbit review workflow

Layer / File(s)	Summary
Optional re-trigger guidance docs/pr-review-bots.md	Removes the inline re-trigger instruction and adds an optional section describing its scope, the no-op behavior of @coderabbitai review during automatic reviews, and the unobserved “full review” behavior.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• dsnger/dev-workflow-kit#5: Updates the same document’s bot review completion and finding-handling guidance.
• dsnger/dev-workflow-kit#19: Refines the document’s bot routing, review-count verification, and retry exception rules.

Poem

A rabbit read the review bot’s note,
“Wait for” guides now clearly float.
Retriggers hop to optional ground,
While review-count truths stay tightly bound.
Sniff, sniff—no-op commands make no sound!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the PR’s main change: re-triggering is documented as optional guidance instead of a required verification step.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

Clarifies that re-triggering CodeRabbit is optional rather than part of deterministic merge verification.

• Removes the imperative re-trigger step from the verification procedure.
• Limits the optional re-trigger note to Wait for bots before invoking the human-exception clause.
• Documents the observed no-op behavior and avoids claiming that full review works without repository-specific evidence.

Confidence Score: 5/5

The documentation-only change appears safe to merge.

The updated text removes contradictory procedural guidance while preserving the observed behavior, scope, and evidence boundaries of the optional re-trigger note.

Important Files Changed

Filename	Overview
docs/pr-review-bots.md	The revised guidance consistently separates deterministic verification from the optional, evidence-qualified re-trigger attempt.

_{Reviews (1): Last reviewed commit: "Make the re-trigger an optional note, no..." | Re-trigger Greptile}

[dsnger]

Per-head count, run as a diagnostic before merge.

head  = 55c3d748b85b699dbe3caedda5d9e1ccf9db8bb1
count = 0

A 0 blocks nothing here — CodeRabbit is opportunistic, Wait for is empty, and no human-exception clause applies. That is the routing from #19 working as intended.

But this 0 is not the 0 the rule describes, and that matters more than the merge.

CodeRabbit posted an issue comment on this PR reading "No actionable comments were generated in the recent review 🎉", naming the exact range it reviewed: 286c55f..55c3d74 — the live head. So the head was reviewed. It produced zero findings, and a zero-finding review apparently posts no review record, so the query counts nothing.

The count therefore conflates two different states:

State	count	Reality
Head never reviewed (#17)	0	dangerous — merging ships an unreviewed head
Head reviewed, nothing found (this PR)	0	fine — the reviewer looked and had nothing to say

docs/pr-review-bots.md currently says a 0 "means the head was not reviewed". On this evidence that is wrong in one direction, and it is the benign direction — the rule over-reports unreviewed heads rather than under-reporting them, so it has never caused a bad merge. It did cause a wasted three-minute wait on #15 and a re-trigger on #17. The file already contains the adjacent insight for blocking ("a bot that finds nothing can finish without posting at all"); the count rule never absorbed it.

Not fixed here — this PR is the re-trigger cleanup and shouldn't grow. Filed as the next follow-up.

Second observation, unrelated to this diff: CodeRabbit's run configuration on this PR reports Plan: Pro Plus. #19 recorded the plan as Free on your say-so and dismissed the earlier "Pro Plus" as a stale PR #1 observation. The bot's own current output disagrees. Worth resolving — the plan is the stated cause of the review-limit behaviour that drove the whole routing change.

Greptile (opportunistic, read at pass start): summary posted, Confidence 5/5, no findings — it read the change as consistent. No inline comments. Cursor Bugbot: disabled, as documented.