SIGN IN SIGN UP

docs(agents): bound bot review loops with convergence rules (#1964)

* docs(agents): bound bot review loops with convergence rules

The PR #1944-#1958 cycle ran eleven-plus response rounds because every bot
finding was fixed every round. Reproducible findings converged - defects
are finite - but prose findings did not, and several rounds' findings
targeted the previous round's fix while one skill was restructured four
times, oscillating narrow-wide-narrow.

The gh-ai-review-triage skill gains a Convergence section: split findings
by evidence class and fix only what reproduces or self-contradicts; never
restructure in response to bot review - file an issue instead; treat a
finding that targets the previous response as the signal to stop
forward-fixing; and stop editing after two response rounds, declining the
remainder with evidence.

Lesson LRN-20260822-bound-bot-review-loops records the provenance,
including that the triage skill sat unused through the entire cycle - the
rules only work if the skill is loaded when bot feedback arrives.

* docs(agents): the convergence rules must not override the triage rules

All six review findings identified genuine contradictions between the new
Convergence section and the skill it extends, and this commit is the
section applied to itself: contradictions fixed, no structure added.

- The restructuring ban and the stop-loss now bind subjective findings
  only. A verified Required defect is fixed in any round, including one
  whose necessary fix changes structure - the ban is on reshaping to
  satisfy taste, not on repairing defects.
- The reproducible class includes deterministic guidance failures
  (validator errors, broken links, invalid frontmatter), not only code.
- An oscillating finding is verified like any other before freezing,
  since a response can introduce a real regression.
- Thread resolution stays behind Step 6's explicit-authorization gate;
  the stop-loss no longer instructs an unauthorized write.

The lesson mirrors the same corrections.

* docs(agents): end review iteration on a sufficiency verdict

Maintainer direction: the convergence rules bound the loop but only
negatively - round limits and freeze signals say when to stop, nothing
says when the change is done. The missing piece is a positive termination
condition: shippability.

The triage skill gains a Sufficiency Judgment gate. Processing a round's
valid findings means deciding fix, decline, or file-an-issue for each,
with reasoning - processing is not fixing. The change as a whole then gets
one of three verdicts: SUFFICIENT (purpose achieved, nothing remaining
justifies blocking the merge), INSUFFICIENT (a correctness, safety, or
acceptance problem remains), or UNCERTAIN (a human decides). Sufficient
does not mean zero findings; it means the required conditions hold and
additional fixing now costs more than it returns.

The anchor question is "what concretely breaks if this merges now?" - a
finding that cannot answer it does not block, however reasonable it
sounds. The stop-loss becomes the backstop for rounds that keep ending
without a verdict, and the output format carries the verdict with its
rationale. The lesson records the same shift: from chasing "could be
better" to judging "is it shippable".

* docs(agents): reviewer commands feed the loop too

Maintainer policy: @coderabbitai review is not a routine step - it starts
a full re-review over unchanged code, which is fuel for the loop - and is
reserved for pushes that genuinely change direction or scope. After a
SUFFICIENT verdict, a stale CHANGES_REQUESTED is cleared with
@coderabbitai approve, which updates the verdict without inviting another
pass. Approval is the outcome of the judgment, never the goal; the command
must not bypass an INSUFFICIENT state.
S
shm committed
fdb84c890ad53985ebaee0380819f0ce09142aae
Parent: b85c569
Committed by GitHub <noreply@github.com> on 8/22/2026, 3:56:24 AM