One Fix One Pr Then Coordinate

One fix, one PR — then coordinate the cluster

Purpose

A real investigation rarely produces exactly one fix. You go in after one bug, read the subsystem, and come out with three — developed together, on one branch, touching the same files. The path of least resistance is to ship that branch: "here's my graceful-shutdown work." That forces a reviewer to evaluate unrelated changes as a unit, couples their merge and revert, and destroys the one thing a PR must answer — what does this change do?

So the packaging is a separate act from the fixing: split by issue, prove each stands alone, then coordinate. Coordination is the half people skip. Three PRs appearing at once from a stranger reads as a dump; the same three, with the live PR answered first and one hub comment mapping the web, reads as someone who did a piece of work and made it navigable. The hub comment is the highest-value artifact in the whole cluster — it is the only place a maintainer can see the shape without reconstructing it.

When to use

• One thread of work yielded fixes for two or more filed issues.
• You developed several fixes on one branch and now have to decide what to open.
• A cluster is already open and nothing ties it together for a maintainer.

When NOT to use

The fixes are genuinely interdependent — B doesn't work without A — then one PR is correct, and say so in the body. Also skip when it's one fix for one issue: there is no cluster to coordinate, and a hub comment for a single PR is noise.

The practice (checklist)

1. SPLIT — one issue per PR, independence proven not assumed

• Prove each fix stands alone before splitting: on a clean base, does this fix resolve its issue without the others? Done when each fix has been built and its issue's tests run on a base that contains none of the sibling fixes.
• Don't cherry-pick commits when the fixes share files — cross-contamination is near-certain. Instead, per issue: branch off base, git checkout <final-commit> -- <files> to take the fully-fixed files, then strip the other issues' hunks by matching text, not line numbers.
• Clean up what the strip orphaned — now-unused imports, dead locals.
• Done when each branch is one commit off base, its own tests are green, and the other issues' code and tests are verifiably absent. Check, don't assume: the strip is exactly where a stray hunk survives.

2. COORDINATE — the order matters more than the speed

• Answer the live PR's open concerns FIRST. The already-reviewed PR is the cluster's main door and where maintainers already look. Reply, thank, resolve — before anything new appears.
• Open the spin-off PRs, each naming its own issue.
• Comment on each spin-off's ISSUE, and credit the reporter's own dig — if they pinpointed the line, say so before presenting your fix. Offer-don't-grab tone extends to acknowledging prior work, not just to avoiding surprise PRs.
• Post ONE hub comment linking the whole web — every issue and PR, one line each on how they relate.
• Put the hub on the neutral root ISSUE, not on a contested PR. These are two different rules and conflating them costs you the hub entirely: "don't bump a contested PR" bans the cross-link on that PR; it does not ban a hub in the cluster. The root issue is where cluster-watchers look and pings nobody.
• If a spin-off's issue is assigned, this is offer-dont-grab — wait for the nod or frame the PR explicitly as the offered fix.

Rationalizations

RECEIPT

SOURCING-receipt — two independent applications, six PRs, one issue and one commit each. Verified via gh 2026-07-26.

jetty (2026-07-23) — one graceful-shutdown dig produced three fixes. #13569 and #13602 were developed on one branch, mixed across 5 commits touching the same two files, and were split per-issue rather than shipped as "my graceful-shutdown work":

The hub landed on the root issue #15368, verbatim:

"While digging this one I found two related graceful-shutdown issues on the server side, now with fixes up: #13569 — connector.shutdown() doesn't send a GOAWAY, so HTTP/2 keeps accepting new streams (PR #15472) · #13602 — connector.shutdown() future never completes if stop() follows…"

Sequencing was load-bearing: #13569 is assigned to the same reviewer who had an open concern on #15435, so the concern was answered there first, then the spin-offs opened, then the hub posted on the neutral issue — with the #15435-side cross-link held.

apache/solr-orbit + OpenSearch Benchmark (2026-07-25) — the same packaging applied to a different cluster: 3 aggregate defects → #58 / #59 / #60 and #1096 / #1097 / #1098 — six PRs, one commit each, one issue each, every artifact cross-referencing its counterpart. The numbering was kept parallel (#55↔#1093, #56↔#1094, #57↔#1095) so the cross-references read at a glance.

Lifecycle

• Signals it worked: no reviewer asks "why are these together?" or "how do these relate?"; the PRs merge or revert independently; a maintainer uses your hub comment's framing when discussing the cluster.
• What to log on a misfire: a split that turned out not to be independent (a PR that failed without its sibling), a hub comment that read as bumping a contested thread, or a bundle a reviewer asked you to split after the fact. Record it in LEDGER.md.
• Death criterion: retire for a house that explicitly prefers batched changes — some do, and the house wins (read-the-houses-agent-file-first).
• Relates to: the packaging sibling of no-force-push-a-reviewed-pr — that one is how to commit on a PR under review, this one is how to shape the PRs before they exist. Clusters come from follow-the-thread and use-the-tool-for-its-purpose; the independence proof is verify-before-a-committer-comment applied to your own split; the assigned-issue case is offer-dont-grab.