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