Telling Technology · Learning in public
All episodes
EP.125 — MERGE PREFLIGHT
One button, checked first

My merge button failed 44 times out of 65. Now it tells me why before I press it.

My AI agents do their work on branches, and one button merges it to main. For two weeks that button died half way more often than not. Now a read-only preflight checks first, names the blocker in one line, and the boring failures repair themselves.

A big glowing green Merge button on a dark desk with a small checklist floating above it: branch, worktree, unsaved edits, clash with main, each with a teal tick, and one line in coral
✓ 1 read-only preflight · 1 Fix line per stop · 44 of 65 failed before · 4 of 4 merged since
why the press kept dying half way
01 The pain

One button, five ways to die half way

My agents pick up tickets, work in their own branch and stop at verify (the ticket that worked itself). Then I press Merge: rebase onto main, run the tests, fast-forward, push, mark the ticket done, restart the dashboard. Between 27 September and 10 October I pressed it 65 times and 44 times it died half way. No branch to merge. Unsaved edits in the main folder. A clash with main. A red test. Or everything worked, and then a cleanup step after the push hung and the run said FAILED anyway. Every failure meant opening a log to find out which one it was.

claude code — desktop
> The merge button failed again. Read every merge log since it shipped and tell me why each press died.
65 presses, 44 failed. 11 reached verify with no ticket branch at all, so there was nothing to merge. Most of the rest were a clash on rebase or unsaved edits in the main folder. Almost all of them were knowable before the press. (paraphrased; the counts are from the ticket and the merge logs)
A dark log viewer listing merge runs from 27 September to 10 October, most rows ending in a red FAILED at check, rebase or cleanup, with a counter in the corner reading 44 of 65 failed
44 of 65 failed
Most of these were knowable before anyone pressed anything.
02 The preflight

Ask first, touch nothing

Now the ticket drawer asks a read-only question before the button is live: GET /api/tickets/merge?id=. It checks that there is exactly one tix/<id>-* branch, that it has commits main lacks, that the ticket’s worktree is clean, whether unsaved edits in the main folder touch this ticket’s files, whether another merge is running, and whether the branch clashes with main. The clash check is git merge-tree --write-tree: a dry merge that writes nothing to any working folder. Each line comes back ok, warn or block, and every block carries its fix. A block greys out Approve, and the POST that really merges refuses the same thing, so the button is not the only guard.

claude code — desktop
> Before I press Merge, tell me if it will work. Read-only, touch nothing.
Preflight: 1 blocker. The branch clashes with main in components/TicketDrawer.tsx. Fix: Send it back so the agent rebases on main and resolves the clash. Approve stays disabled. (paraphrased; the check and fix text are verbatim from lib/merge-readiness.ts, the file name is an example)
A ticket drawer in dark mode with a Merge readiness list: one branch ahead of main, worktree clean, two unsaved edits that do not touch this ticket as a warning, and one coral blocker, the branch clashes with main, with its fix line underneath and a greyed-out Approve button
ok · warn · block
The drawer says it first. The server refuses it anyway.
03 The gate, the repairs, the honest part

Stop it earlier, repair what is boring, say what to do next

The cheapest failure is the one that never reaches the button. A ticket now cannot move from wip to verify unless exactly one branch is ahead of main; --force still works, and it is logged. The merge script got four repairs. Unsaved edits in the main folder only block when they touch the ticket’s own files; the rest become a warning. A clash or a red test or type check sends the ticket back to spec for the worker, tagged golive-conflict or golive-red; a second bounce tags needs-jacob and takes the agent off it. A second press on a merged ticket is a no-op. Trouble after the push is a warning, not FAILED. And every stop prints a Fix line.

claude code — desktop
> Press Merge on a ticket whose branch has a red test.
Merge stopped at test. Sent back to spec for the worker, tagged golive-red and golive-bounced. Fix: Nothing for you unless it bounces twice: the worker fixes the tests, then it comes back to verify. (paraphrased; the Fix line is verbatim from scripts/tix-merge.ps1)
A terminal showing a merge run that stops at the test step, sends the ticket back to spec with the tags golive-red and golive-bounced, and ends on a highlighted line starting with Fix:
every stop has a Fix line
A refusal that says what to do next is half a repair.
⚠️

Four clean merges is not a rate yet

Since the fix shipped on 10 October at 21:14, the tally counts 4 presses · 4 merged · 0 failed. Four is a small sample. The ticket’s own done-when is under 1 in 10 presses fail, and I will only call it done when the tally says so over a few weeks. Forced moves past the verify gate are still possible; they are logged, not prevented.

04 Gallery

Four failures that became one-line answers

Each card is one way the button used to die, and what it says now. Typographic cards built from the merge script and the board, not screenshots. Tap any image to enlarge it and read the exact prompt that drew it.

MEASURED, NOT FELT

The fix was not a smarter agent. It was a refusal that says what to do next.

“Almost never fails” is a number now. A small read-only script, merge-tally, reads the merge logs, counts presses against clean merges, groups the failures by reason and logs why a restart failed. Before: 44 of 65 presses failed. Since the fix: 4 of 4 merged. The bar it has to clear: under 1 in 10.

A bold typographic card with the merge-tally output: a large coral 44 of 65 failed for the two weeks before the fix, and next to it a large teal 4 of 4 merged since, with the target under 1 in 10 underneath
node scripts/merge-tally.mjs · read-only · done-when: under 1 in 10 presses fail
06 Steal this

Steal the preflight pattern

The dashboard is private, so this is the pattern, not the repo: a read-only preflight, the same refusal on the server, a gate before verify, a Fix line on every stop and a tally that reads your own logs. Everything in this episode is free and open — clone it, run it, make it yours.

skill merge-readiness checklist cmd git merge-tree dry merge template Stop-Run with a Fix line assets merge-tally.mjs
run it # pattern soon. Try the dry merge now (writes nothing to your folder): git merge-tree --write-tree --name-only --no-messages main my-branch

No GitHub? Comment PREFLIGHT on the post and the bot DMs you the link.

Next episode

I had 102 things going and no single place that listed them

Tests, learning pages, projects: swept from five places, folded into one page, and the first count surprised me.

A dark overview table of initiatives with a large count of 102 at the top and rows grouped into tests, learning pages and projects
drops soon · follow so you don’t miss it