Skip to content

Rule 10: a PR goes Open when the rounds stop, whoever calls the stop - #22

Merged
Peeja merged 1 commit into
mainfrom
claude/rule-10-open-on-done
Sep 22, 2026
Merged

Peeja merged 1 commit into
mainfrom
claude/rule-10-open-on-done

Conversation

@Peeja

@Peeja Peeja commented Sep 22, 2026

Copy link
Copy Markdown
Contributor

Checks a reviewer can merge without waiting for

All of them. One file, AGENTS.md, markdown only — nothing compiles, parses or executes it. Every reference to it in the tree is a prose mention inside a comment:

$ git diff --stat origin/main HEAD
 AGENTS.md | 33 +++++++++++++++++++++++++-------

$ grep -rn 'AGENTS\.md' --include='*.yml' --include='*.yaml' --include='*.sh' \
      --include='*.go' --include='Makefile' .
./.github/scripts/finish-subtree-pull.sh:43,344,670
./.github/scripts/check-assert-released-version.sh:12
./.github/scripts/resolve-rewrite-conflicts.sh:58

What it costs if that is wrong: the ignored checks still run, and a red one after merge leaves main red.


Two clauses of rule 10 became false when Petra decided a pull request should go Open as soon as the rounds are done. It said a PR "goes Open once a round comes back satisfied" and that "the flip is the human's to make, not the agent's". The trigger is the rounds ending, and a human calling enough ends them as surely as a satisfied round does.

Both places said it — the rule's one-line form in the numbered list, and the two-signals bullet in the section below — so the enumeration ran before committing rather than after. Nothing else in the tree repeats it:

$ grep -rn "flip is the human\|comes back satisfied\|until one comes back" \
      AGENTS.md MONOREPO_TODO.md .github/scripts/*.sh .github/workflows/*.yml
(no output)

Why a satisfied round cannot be the only way they end

This is the part worth reading; the wording change follows from it.

Measured across #18 and #19, which ran five rounds each:

#19 #18
round 1 3 behaviour, 1 claim, 1 wrong premise 5 behaviour, 1 claim
round 2 2 behaviour, 1 claim 4 behaviour, 1 claim
rounds 3–5 0 behaviour, 9 claims 0 behaviour, 10 claims

Fourteen findings about behaviour in the first two rounds, none in the last three — which still produced nineteen findings, every one about a claim: a comment, a count, a pull request body.

Those sustain themselves, because each fix to a comment is a new comment the next round finds slightly off. One number could not converge at all: the run that measured plan's duration always postdated the sentence quoting it, so a single figure was the slowest sample, the range that replaced it was stale by its own next push, and only deleting the number fixed it.

The cause is structural rather than anyone's carelessness. release.yml's diff on #19 was ~305 changed lines and nearly all of it comments, so the rounds reviewed the commentary — and a reviewer briefed to verify every factual claim against the tree will always find something in that much prose.

Two instructions follow, and are now written down:

  • scope each round to what changed since the last one, and
  • skip the round when that is comments only.

Deliberately no review round on this one

By the rule it adds. This is a prose-only change to a prose file — precisely the case where the rounds have been shown not to converge — so running one would be the behaviour this pull request exists to stop. Flagging it rather than doing it quietly.


🤖 Generated with Claude Code

https://claude.ai/code/session_01CGAGAib517Ae1kg8SCdcEt


Generated by Claude Code

Petra's decision, and it makes two clauses of rule 10 false. It said a PR "goes
Open once a round comes back satisfied" and that "the flip is the human's to
make, not the agent's". Neither holds: the trigger is the rounds ENDING, and a
human calling enough ends them as surely as a satisfied round does.

Both places said it -- the rule's headline at the top of the file and the
two-signals bullet below -- which is rule 5's enumerate-the-class, run before
committing rather than after. Nothing else in the tree repeats it.

The substance behind the change is worth more than the wording. Measured across
the two pull requests that ran five rounds each: fourteen findings about
behaviour in rounds one and two, NONE in rounds three to five, which produced
nineteen findings between them, every one about a claim rather than about what
the code does. Those sustain themselves, because each fix to a comment is a new
comment the next round finds slightly off -- and one number could not converge
at all, since the run measuring it always postdated the sentence quoting it.

The cause is structural. When most of a diff is commentary -- one of those two
was ~305 changed lines of a workflow, nearly all comments -- the rounds review
the commentary, and a reviewer told to verify every factual claim will always
find something in that much prose. So the satisfied sentence is not always
reachable, which is exactly why it cannot be the only way the rounds end.

Two instructions follow and are written down: scope each round to what changed
since the last one, and skip the round when that is comments only.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CGAGAib517Ae1kg8SCdcEt
@Peeja
Peeja merged commit 4611cbc into main Sep 22, 2026
26 checks passed
@Peeja
Peeja deleted the claude/rule-10-open-on-done branch September 22, 2026 21:43
Peeja pushed a commit that referenced this pull request Sep 22, 2026
…n main

Petra's reframing settled the schedule question and it was better than my
answer. I argued for keeping a nightly so an upstream release could not silently
break us; her point is that the question worth asking is whether the release in
THIS pull request breaks compat, and that answer goes stale on its own. A
schedule on main answers a different question badly, since main is not deployed
and a red there has no decision attached.

compat.yml now triggers on a release/* pull request and carries no schedule.
compat-refresh.yml carries the schedule and re-runs each open release PR's own
compat run -- re-running rather than dispatching, because a re-run stays
attached to the pull request and so puts the fresh answer where the merge
decision is made.

One bug caught by testing rather than reading, and the same class as the
|| true removed from compat-window.sh: mapfile < <(gh ...) discards the
subshell's status, so an unreachable API read as "nothing to refresh" and went
green.

#22 merged as 4611cbc, so rule 10 now says a PR goes Open when the rounds stop
whoever calls the stop, and a round is skipped when the push was comments only.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CGAGAib517Ae1kg8SCdcEt
Peeja pushed a commit that referenced this pull request Sep 22, 2026
Two findings, both a correct piece of code defended by a false premise --
the refresher's concurrency group ("it only ever runs from the default
branch": only `schedule:` is) and the age diagnosis ("the refusal whose
cause the API error never names": GitHub names it, and gh forwards the
message on the whole-run path). Neither changed behaviour; both would have
misled whoever touched the code next.

The fixing push is comments only, which is rule 10's skip condition as #22
amended it, so seven is the last round. #18 stays Open on 1691b59.

Also records what made rounds six and seven productive after five that had
stopped finding things: each was scoped to a single push rather than the
whole PR, and each push contained shell that was executed rather than read.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CGAGAib517Ae1kg8SCdcEt
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants