Friction notes from scheduled agent runs#1822

Friction notes: dispatch cycle

1. The implementer was told to save its pull request description in a shared folder, but its sandbox refused to write there, so it saved it elsewhere and copied it across.
2. The implementer's sandbox refused two multi-step commands as too complex to check, so it had to split and re-run them.

Each note in full

#	from	kind	anchor	cost	fix
1	implementer	friction	dispatch prompt (".dispatch/ path is preferred" for the PR body)	wrote and linted the body under /tmp, then copied it with a plain cp	allow .dispatch/ writes in the worktree isolation guard, or name /tmp as the body path in the dispatch prompt
2	implementer	friction	worktree isolation guard on Bash	two re-runs: a python3 heredoc chained with prettier and pnpm test, and a teardown.sh close --artefacts; ...; git status chain, split into single commands and Edit calls	unknown

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/38192015303 Commit: def735d8346e4fe93c75c5fc00ea8e7e7fcf6d06 Date: 2026-10-12

Friction notes: dispatch cycle

1. The implementer had to split several combined file-writing and saving steps into separate steps, because a safety check refused them together.
2. The dispatcher had a comment refused because a safety check mistook it for a change to the pull request description.

Each note in full

#	from	kind	anchor	cost	fix
1	implementer	friction	worktree-isolation guard on the Bash tool	refused compound commands that combined a heredoc or python3 file edit with git add; re-split into Write/Edit calls plus separate git commands three times	unknown
2	dispatcher	friction	.claude/skills/post-pr-body/scripts/check.sh PreToolUse hook	a command that read pulls/1844 and then posted the verdict to issues/1844/comments --input was linted as a PR body and refused; re-run as two calls	match the hook on the write command's endpoint, not on any pulls/ path in the command text

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/38221876490 Commit: 6724907dc2f5c043b7cb49c6672120f19b2268ee Date: 2026-10-12

Friction notes: PR review

1. The reviewer had to work out the real diff of a stacked pull request by hand, because the review step compares against main and so pulls in the parent pull request's files.
2. The CI wait script listed every check as ignored and none as passed, so the session had to read the check runs directly to learn that CI had passed.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	re-derived	.claude/agents/birdbrain-reviewer.md (Review passes, step 1)	read the base ref, re-diffed against the base sha, ran the evidence-path match twice	diff against the pull request's base sha when its base ref is not main
2	pr-review	confusing	.github/scripts/dispatch/checks.sh	three extra API reads of workflow runs and check runs at the pinned sha	unknown

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/38330518034 Commit: b0a1a5107947c93767049a58a76a2b83fe9a1cb6 Date: 2026-10-13

Friction notes: PR review

1. The reviewer ran its full set of checks and tests on a commit the pull request had already moved past, because it only re-reads the latest commit after those checks finish.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	friction	.claude/agents/birdbrain-reviewer.md#review-passes	a full verify loop (about 5 minutes of coverage) on a sha the PR had already moved past	re-read the head sha just before pnpm test:coverage as well as before reporting

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/38338228935 Commit: 273ecd2de3c591722fa9135089d927e81079e550 Date: 2026-10-13

Friction notes: PR review

1. The comment check rejected the reviewer's report because it named the co-author trailer it had checked for, even inside the collapsed block.
2. The reviewer's agent file asks for the report as its own file, while the session forbids report files, so the reviewer had to choose.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	friction	.claude/skills/post-comment/scripts/check.sh	one rewrite and re-run of the comment	let the linter skip that string inside the details block, or have the agent file say to describe the trailer without naming it
2	reviewer	confusing	.claude/agents/birdbrain-reviewer.md Reporting section	the reviewer kept the report only inside the comment file	unknown

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/38377024107 Commit: 273ecd2de3c591722fa9135089d927e81079e550 Date: 2026-10-13

Friction notes: PR review

1. The reviewer's instructions show the collapsed report heading on one line, but the comment checker rejects that form, so the reviewer had to rewrite its comment.
2. The comment checker treats any mention of the co-author trailer name inside the collapsed report as a real trailer, so a review that reports "no trailer found" fails the check.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	confusing	.claude/agents/birdbrain-reviewer.md Reporting section	one failed check.sh run and a rewrite of the comment file	show the two-line <details> then <summary> form in the agent file
2	pr-review	friction	.claude/skills/post-comment/scripts/check.sh trailer rule	one failed check.sh run and a rewording of the completion-controls line	match the trailer only at the start of a line with a colon and an address

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/38492635540 Commit: 38615d14f0f2cee3028bcaf9de467b5ce1d8955a Date: 2026-10-14

Friction notes: PR review

1. Commands piped into the run-birdbrain driver run concurrently, so a piped launch followed by quit exits before the launch reports anything.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	confusing	.claude/skills/run-birdbrain/driver.mjs	one wasted driver run, then the commands were re-fed through a subshell with sleep	state in SKILL.md that piped input needs delays between commands, or make the driver run commands one at a time

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/38495950885 Commit: f7bfc5458d142ad62e93233f0252438c655f78c5 Date: 2026-10-14

Friction notes: PR review

1. The setup script for a new working copy exited with a failure for a missing prose checker after dependencies had installed, so the reviewer read the install log to confirm the copy was usable.
2. The comment style check rejected the review comment for naming the co-author trailer inside prose, which cost two rounds of edits.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	friction	scripts/setup-worktree.sh	read the install log to confirm the tree could be used before running the verify loop	report a missing Vale as a warning and exit 0 when only the prose hook is affected
2	reviewer	friction	.claude/skills/post-comment/scripts/check.sh	two edit-and-lint rounds to reword one completion-controls line	match only a trailer at the start of a line, not the phrase inside prose or code spans

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/38506316876 Commit: f7bfc5458d142ad62e93233f0252438c655f78c5 Date: 2026-10-14

Friction notes: PR review

1. The reviewer lost a probe run because a log statement in a single-file test printed nothing and the output was buried under image-library warnings.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	friction	docs/agents/testing.md (pnpm test <path>)	one wasted probe run before writing results to a file instead	unknown

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/38665933505 Commit: 0c5ee8fc148d1b5a179086243ad919599b7c3177 Date: 2026-10-15

Friction notes: PR review

1. Console output from a one-off test file never showed when the reviewer ran that single file, so the first reproduction printed nothing.
2. The reviewer's verdict draft put extra text on the reviewed-commit line, which the post step refuses, and the comment style check still passed it.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	re-derived	CLAUDE.md#commands	one extra rerun after switching to writing results into a file under /tmp	unknown
2	pr-review	confusing	.claude/skills/post-comment/scripts/check.sh	one rewrite of the verdict file before it could be posted	have check.sh require the line to be exactly Reviewed commit: <40-character sha>

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/38671433505 Commit: 0c5ee8fc148d1b5a179086243ad919599b7c3177 Date: 2026-10-15

Friction notes: PR review

1. The reviewer had to redo its verdict draft because the comment checker rejects a summary tag on the same line as its details tag, and the template does not say so.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	confusing	.claude/skills/post-comment/template.md#pre-pass-verdict-10-lines-at-most-5-numbered-findings-full-report-collapsed	one extra edit-and-lint round on the verdict draft; the trailer check also matched the trailer name inside a findings sentence	state in the template that the summary tag sits on its own line and that the trailer check matches the text anywhere in the comment

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/38726823708 Commit: 0c5ee8fc148d1b5a179086243ad919599b7c3177 Date: 2026-10-15

Friction notes: PR review

1. The reviewer had to read the merge-gate job log before it could approve, because its rule that a PR red in CI cannot be approved does not set apart the sign-off gate every evidence-affecting PR waits on.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	confusing	.claude/agents/birdbrain-reviewer.md Review passes, 4. Verification	read the merge-gate job log to classify the red check	exempt merge-gate when it is blocked only on sign-off at head

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/38840827033 Commit: 03b3ededeadb46f017cae65def9fe7fe89380649 Date: 2026-10-16

Friction notes: PR review

1. The reviewer's instructions ask it to report the commit-trailer check, but the comment style check rejects the trailer phrase anywhere in the comment, including the collapsed report.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	friction	.claude/skills/post-comment/scripts/check.sh	one failed lint and a rewrite of the completion-controls line	let the linter ignore the phrase inside <details>, or tell the reviewer to describe the trailer check without quoting the trailer

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/38845567955 Commit: 03b3ededeadb46f017cae65def9fe7fe89380649 Date: 2026-10-16

Friction notes: PR review

1. The comment style check rejected the review because the report named the co-author trailer while saying no such trailer existed.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	confusing	.claude/skills/post-comment/scripts/check.sh	one extra rewrite-and-lint round	tell reviewers to describe the trailer check without the literal trailer string, or match only trailer-shaped lines

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/38901396910 Commit: 03b3ededeadb46f017cae65def9fe7fe89380649 Date: 2026-10-16

Friction notes: PR review

1. When main has a failing test, the coverage run writes no coverage file, so the reviewer had to run the whole suite a second time to measure test coverage of the changed lines.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	friction	.claude/agents/birdbrain-reviewer.md#review-passes	pnpm coverage:diff stopped with "Missing coverage-final.json", and re-running the full suite with --coverage.reportOnFailure took about 10 minutes	tell the reviewer to pass --coverage.reportOnFailure when a known red test on main is expected

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/39199676919 Commit: afd786dacfb773397f97cdb0bf1c25dbe139fc52 Date: 2026-10-19

Friction notes: PR review

1. The reviewer wrote the two collapsible-block tags on one line, and the comment style check rejected it with five cascading errors.
2. The CI reader listed the end-to-end job as failing because it counts an older CI run at the same commit, although a newer run there passed every job.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	friction	.claude/agents/birdbrain-reviewer.md#reporting	one extra edit and linter re-run	show the two-line <details> / <summary> form in the Reporting section
2	pr-review	confusing	.github/scripts/dispatch/checks.sh#read_checks	four extra API reads to tell a superseded run from a real red, and without main's own e2e red it would have forced a request-changes verdict on a green head	count only the newest run per workflow at the head sha

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/39217335079 Commit: afd786dacfb773397f97cdb0bf1c25dbe139fc52 Date: 2026-10-19

Friction notes: PR review

1. The review was skipped for an end-to-end test that also failed on four of the main branch's last five runs, because the exception only looks at the single most recent main run.

Each note in full

#	from	kind	anchor	cost	fix
1	pr-review	friction	.claude/skills/pr-review/SKILL.md#2-read-ci	one scheduled review fire spent on a request-changes verdict for e2e/extraction-burst.spec.ts, which also passed in a second CI run at the same commit	let the main-branch exception count a spec that failed on any of main's last few runs, or prefer the newest passing run of a job at the same commit

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/39323991163 Commit: 4f22ec10bad196bfc11e130e5f4e303e7670fa7c Date: 2026-10-19

Friction notes: PR review

1. The comment style check rejected a verdict that reported a missing commit trailer, because it matches the trailer's name anywhere in the text.
2. The CI reader listed the cancelled jobs of a superseded run as failing, though a newer run at the same commit had passed all of them.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	friction	.claude/skills/post-comment/scripts/check.sh	one rewrite and a re-run of the check, and the same rule rejected the first draft of this note	match only a line that starts with the trailer key and a colon, not the bare phrase
2	pr-review	friction	.github/scripts/dispatch/checks.sh	four extra API reads to separate the cancelled CI run from the real failure before spawning the reviewer	drop a cancelled job when a later run of the same workflow at the same commit has a conclusion for it

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/39517438647 Commit: 0d999707fabe611e79112947a8ef9dff47584f49 Date: 2026-10-21

Friction notes: PR review

1. The working copy setup script installed dependencies and then exited with an error only because the prose style check was missing, so the reviewer had to check the Electron install by hand.
2. The scheduled review ran a full coverage pass and two reproductions on a commit that already had a request-changes verdict and was replaced by eight new commits before the review ended.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	friction	scripts/setup-worktree.sh	checked node_modules/electron/dist by hand before trusting the tree	report a missing vale as a warning when only dependencies are needed
2	reviewer	friction	.claude/skills/pr-review/SKILL.md#1-pin-the-commit	one full coverage run and two scratch worktrees for a verdict on a commit that was no longer head	skip a pinned sha that already has an agent/pre-pass verdict, or re-read the head before the coverage run

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/39623143312 Commit: 5509cff8941aaa30e4c783d1a9891c24340caeda Date: 2026-10-21

Friction notes: PR review

1. The reviewer could not judge scope against the 22 October ruling, because its text is recorded on neither the issue nor the PR.
2. The script that sets up a working copy stopped on a missing Vale in the Actions runner, so the reviewer could not run the changed-docs prose check.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	re-derived	birdbrain-reviewer agent file, Scope pass	searched the branch's commit messages and found two readings of the ruling (ef1af578, 467ff2ee), so scope stayed unverified	require the ruling text to be quoted on the issue before a review judges against it
2	reviewer	friction	scripts/setup-worktree.sh	the Vale check on changed docs could not run, and the review relied on CI hunks and the PR's preflight block instead	unknown

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/39760358789 Commit: e943c66a15fab3a084876e50fc7dc181c2f8122e Date: 2026-10-22

Friction notes: PR review

1. The reviewer's test count differed from the PR's by 20 skips, because the built-binary verifier tests skip unless the binary exists and CI never builds it.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	re-derived	.claude/agents/birdbrain-reviewer.md#review-passes	traced the skip gate, then ran pnpm build:verifier and binary.test.ts separately	tell the reviewer to run pnpm build:verifier before coverage when src/shared/verify/** or src/verifier/** changes

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/40325561676 Commit: 50966b79b438c90b2031f82f6b19a77b6f834617 Date: 2026-10-26

Friction notes: PR review

1. The reviewer's first throwaway test run printed nothing, because running a single test file silences console output and the testing guide does not say so.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	confusing	docs/agents/testing.md (single-file pnpm test)	one extra test run, then results written to a file instead	say in the testing guide that console output is silenced and how to see it

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/40384701558 Commit: 50966b79b438c90b2031f82f6b19a77b6f834617 Date: 2026-10-26

Friction notes: PR review

1. The CI reader ignores every check on a pull request stacked on another branch, so a red check there would read as no failures.
2. The setup script for a new working copy exits with failure when Vale is missing, even after the install and the Electron fetch succeed.

Each note in full

#	from	kind	anchor	cost	fix
1	pr-review	confusing	.github/scripts/dispatch/checks.sh	its workflow-run filter keeps only runs with base.ref == "main", so on PR 1980 (base feat/1904-capture-engine-verifier) every check was ignored and the CI result had to be read again by hand from the workflow runs and check runs at the sha	match runs on the PR number and head sha whatever the base branch
2	reviewer	friction	scripts/setup-worktree.sh	read the install log to confirm Electron was in place before running tests	report a missing Vale as a warning, not a failure, when only tests and builds are needed

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/40417455901 Commit: 50966b79b438c90b2031f82f6b19a77b6f834617 Date: 2026-10-26

Friction notes: PR review

1. On a stacked pull request the reviewer had to find out by reading the script that the step measuring test coverage of the changed lines compares against main unless given another base.
2. The CI check script listed every check on this stacked draft pull request as not part of the latest runs, with nothing passed, so CI had to be confirmed by hand.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	re-derived	.claude/agents/birdbrain-reviewer.md Verification step, pnpm coverage:diff	read scripts/diff-coverage.mjs to find --base and reran it against the stacked base	add "on a stacked PR, pass --base origin/<base branch>" to that step
2	pr-review	confusing	.github/scripts/dispatch/checks.sh	two extra API reads of CI run 40309369713 and its jobs to confirm seven successful jobs	unknown

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/40435884622 Commit: 50966b79b438c90b2031f82f6b19a77b6f834617 Date: 2026-10-27

Friction notes: PR review

1. Five test files that use the sharp image library crashed on this runner, although the testing guide says CI on Ubuntu is not affected.
2. The check reader script put every check on this stacked pull request in its ignored list, so it reported nothing passed and nothing failing.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	confusing	docs/agents/testing.md sharp under Electron on Linux	re-read the testing guide, checked for a system libvips, and relied on the CI test job for five files	unknown: install libvips on the runner, or say in the guide that agent runners are affected
2	pr-review	confusing	.github/scripts/dispatch/checks.sh	read the check runs directly from the commit to confirm CI was green before spawning the reviewer	unknown: likely the latest-run match misses pull requests whose base is not main

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/40520525345 Commit: 50966b79b438c90b2031f82f6b19a77b6f834617 Date: 2026-10-27

Friction notes: PR review

1. The reviewer had to simulate a merge with main to find the PR's own diff, because its stack base had already been squash-merged and the prescribed three-dot diff showed other PRs' changes.

Each note in full

#	from	kind	anchor	cost	fix
1	reviewer	re-derived	.claude/agents/birdbrain-reviewer.md "Review passes" step 1	built a scratch merge with git merge-tree, then typechecked and tested that tree separately; coverage:diff used a stale merge base	when mergeable_state is dirty or the stack base has squash-merged, review against a simulated merge with origin/main

Where these came from

Run: https://github.com/thebristolsound/birdbrain/actions/runs/40620613276 Commit: aa87bd36bbc662fb00bb39304900103d7d20283c Date: 2026-10-28