Lanes
A multi-PR effort runs as one coordinator session, which writes no code, and several
lane sessions, each owning a slice of the PRs. Sessions die, get renamed and get
compacted; files outlive them. The whole method: decide in a file, then act.
When it applies
Many PRs across several code areas that can move in parallel. It pays off most when the
work outlives any single session, and when one maintainer reviews PRs in batches.
One area worked in sequence fits one session. A bounded task whose answer fits a
paragraph fits a subagent.
The user decides
The coordinator runs supervised through preparation and lane start. It proposes each
decision there and acts on it after the user's go-ahead. A proposal is a few lines: what,
why, and the alternative weighed. Then the coordinator stops and waits. A go-ahead covers
the decision it was given for; the next decision is asked again. Writing an approved
decision into the plan file needs no second go-ahead. When unsure whether something is a
decision, ask.
Decisions include:
- each plan section: the inventory buckets, the spec, the PR map, the lane cut, batches
and merge order, the review process;
- per lane: its model, its placement and name, the full text of its brief before it is
sent.
Lanes run at their usual pace; their briefs add no extra stops.
1. Preparation
Done when the plan file has every section below in place. The plan file sits next to the
code and is kept out of git.
- Inventory. One row per change the effort must land (a hunk, a finding, a
requirement), sorted into buckets.
- Spec. What done means: a spec the PRs are measured against.
- PR map. Inventory row → PR → branch → commit, the commit filled in from the
lane's report. Each PR's branch name follows the repo's convention, and its base is
the base branch (e.g.
origin/main) or the PR it builds on. Each PR carries its open
questions for the maintainer or the developer. Every row lands in a PR or states why
it does not.
- Lanes. Cut by code area and merge order, with overlap checked at function level:
two lanes may share a file when they edit different functions. When the changes
already exist as patches, check with
git apply onto the base branch, in plan order and
with each pair of lanes swapped; otherwise compare the lanes' function lists. A
function two lanes both edit fixes an order: the later PR rebases onto the earlier
one. The lanes table names each lane's functions, PR order, worktrees, session model
(as approved) and, once the lane reports, its tab id.
- Merge order, and batches when the maintainer reviews in batches. Batch 1: every PR
that stands on the base branch by itself. Batch n+1: PRs that build on a batch-n PR,
started after the maintainer's pass on batch n so they take in the remarks. Before
asking the maintainer to review a batch, the coordinator runs the trial build (section 3).
- Review process. Agreed with the client, if any, and the maintainer before the
first PR: who reviews, who merges, who requests reviews.
- "After a merge, do" (section 4) and Status, empty at the start.
2. Starting a lane
- Model, per lane and per task. The strongest model for the lane session itself when it
touches money, consensus, keys or judgement calls. Inside a lane, each subagent call names
its model and gets the cheapest one that fits: the strongest for the first grade of
judgement items (tests, mutations, money logic) and for fact-checking a review text with
technical claims; a cheaper one for mechanical checks, re-grades after a small fix, trial
builds and fact-checking a short text (a one-line closing comment). Effort stays at the
default. The coordinator stays on the strongest model: it catches errors across PRs, and
it saves by taking fewer, shorter turns, not by a cheaper model.
- Worktree. One worktree per PR, on the branch and base the PR map names.
- Placement. One session per lane, in a terminal multiplexer if you use one (e.g.
Herdr, tmux), in the repo's workspace or session. The tab is named
<lane> · <session name>:
the lane first, because sidebars cut names from the end (b · 6c; the coordinator
coord · da). The tab gets the last segment of the session name once the session
runs; cross-session messages go to the full name. The workspace already says the repo.
The lane label names the code area loosely; the plan's PR list stays the authority. A
security or embargoed lane gets a neutral label (sec), never what it fixes. When a
lane's report arrives from a new session name, the coordinator renames the tab. It
finds the tab by the tab id the lane states in its first report and in its first
report after a restart. A resumed session does not notice a restart by itself: the
coordinator asks for the report when a lane's session name changes in the session list.
- First prompt. Filled in from
brief.md.
Per-PR steps, in the lane:
- Branch as above; read the PR's inventory rows.
- TDD where the change alters behaviour: a test that fails without the change, then
the change.
- Run your review pipeline, plus every domain auditor whose area the diff touches.
- Run your pre-PR check and write its result to the pre-PR results file. Before handing
the check to its grader, the author walks the check's mutation categories itself, so the
grader confirms rather than finds. A commit made after the check gets its diff read for
leftovers (debug output, stray files) before the push.
- Publish per the brief's "Who publishes": push and open the PR in one command
(
git push … && gh pr create …). Where a hook asks before a push or a post, its prompt
is the user's word: say in two or three lines what goes out (branch, head, PR or post),
then run the command, with no dialog of your own. Without such a hook, ask for it (and
for any other outward step: a post to the code host, a message) through the
AskUserQuestion dialog, with options like "push and open" / "not yet", not as a
question in the reply text, where it gets lost in long output. A PR body states what a
test checks and what the pre-PR check needs, not reasoning about edge modes; text for
the code host goes through the review pipeline once, after the code has settled. A
branch in the embargo ledger waits for the go the ledger names.
- Report to the coordinator: the PR and its commit, the inventory rows it covers, any
step due after a merge.
A gap in tests the user has accepted on one PR may be accepted on a like PR without asking
again; the lane names it in its report.
Scale the pipeline by risk. The plan assigns each PR a tier; the brief names it.
- Comments, docs or tests only: the review pipeline once; from the pre-PR check only the
items that need no mutations (stand-alone, consequences, overlap); no live run.
- Logic without money, consensus or keys: the full review pipeline and the full pre-PR
check; no live run unless sync or restart behaviour changes.
- Money, consensus or keys: everything: the full review pipeline, the full pre-PR check,
every domain auditor, the live run.
Below the top tier, one combined review agent replaces the separate review agents: they
read the same diff and mostly overlap.
3. The coordinator
Writes no code. It:
- keeps the plan file: statuses and the "After a merge, do" table, from lane reports;
- routes briefs to lanes and answers between them, taking branch names and heads for a
brief from git or the code host, never from memory;
- drafts the client's and the maintainer's messages, for the user to send;
- checks each reported PR against its inventory rows, and asks for an audit pass: the
inventory marks what the PR actually landed.
Before the review request for a batch, it makes the trial build: the base branch plus
every PR of the batch, outside contributors' PRs included (their code only in the
outside-code container), merged in the planned order; build, vet and the full test suite
run on the result. Each PR green alone is not enough: combinations show a test type
declared twice, a test that fails with another PR's change, and pairs of PRs that
conflict on merge. Findings go back to the lanes before the request is sent.
A lane session stays open while it has an open PR, a pending step in the "After a merge,
do" table, or an embargoed branch. Once all its PRs are merged and nothing is pending for
it, the coordinator closes it, after moving any open item into the plan (section 6).
The coordinator checks this after each merge of a lane's PR and whenever a lane reports
nothing open. Before closing, it asks the lane the close-out questions: findings not
filed, steps pending after a merge, what only its context holds, what slowed it and what
it would change. Answers on code and tasks go into the plan; answers on process go into
the retrospective file, as proposals for the user. Why:
an idle session costs nothing, but waking it after the prompt cache expires (about an hour)
re-reads its whole context uncached, hundreds of thousands of tokens for a long lane, and
autocompact costs about one such pass plus a summary and drops detail. Its state is in the
plan file, the embargo ledger and the pre-PR results file, so a fresh session picks it up
from a brief. Keep the context only where it pays: a lane answering the reviewer on its
own open PR.
Keep small steps off long sessions. Waking a lane after the prompt cache expires
re-reads its whole context uncached. A mechanical step (merging the base into a PR with a
known resolution, waiting for CI, rerunning a known command) goes to a fresh cheap-model
subagent or a coordinator script, not to a lane session. A lane runs /clear between
unrelated tasks and resumes from the plan file and its brief.
Reports are short. A lane writes the detail to its results file and sends the
coordinator 5–8 lines: the file path, the new head, and what needs a decision. The
coordinator passes the user only what needs their decision.
It finds a lane by worktree and PR list; the tab name is only a label, and the tab id
locates the tab. Session names change; worktrees and PRs do not.
4. Shared resources and state files
Anything that would die with a session goes into a file at the moment it is decided.
Lanes read the plan file; only the coordinator writes it.
| File |
Holds |
Updated by |
| Plan file |
every section of 1. Preparation, and statuses |
the coordinator, from lane reports |
| "After a merge, do" table, in the plan |
one line per pending step: the merge that unblocks it, the step, who does it; struck when done |
the coordinator, when a lane reports the step |
| Embargo ledger, out of git |
unpublished security branches: branch, head, worktree, who gives the go |
the owning lane, on every amend, push or PR |
| Pre-PR results file |
each PR's pre-PR check result and the commit it ran on |
the lane, after each run |
| Heavy-run lock |
a script every heavy run goes through: race-detector runs, whole-package suites, long loops |
each session, per run |
| Retrospective file |
process notes from lane close-outs and reports; proposals waiting for the user |
the coordinator |
| Outside-code container |
the only place an outside contributor's code builds and runs: no network after dependencies, no host mounts, no credentials, queued on the same lock |
whoever reviews the outside PR |
The plan holds current state: the lanes table, the "After a merge, do" table and open
items. The coordinator moves finished history to an archive file next to it, so each resume
re-reads a short plan.
An outside contributor's PR goes through your external-PR review, and nothing is posted
until all its checks have run.
5. Failure modes
| Symptom |
Cause |
Fix |
| A lane's report goes nowhere, or a lane decides its result is lost |
the coordinator died or was renamed |
every brief names a fallback recipient or a results file; the coordinator maps lanes by worktree and PRs |
| After compaction or a restart, a session has forgotten a pending step, an embargo or a pre-PR result |
the state lived only in session memory |
the files of section 4; on resume, a session re-reads the plan file first |
| Test runs exhaust memory, or sessions queue for many minutes |
heavy runs from several sessions at once |
the lock, a time limit per test process, long loops split into batches and started after the pre-PR check |
| An agent skips checklist items, or follows a brief to a moved file |
brief rot: a count ("all four items") outlived the checklist; a copied path went stale |
write "all items of "; cite rules ("heavy runs per the repo's rules"), not paths |
6. Ending a phase
Done when every lane has answered the inventory round and every open item sits in the
plan file.
- Inventory round. Ask every lane still open the close-out questions (section 3) and
its lane ↔ PR mapping.
- Audit pass over every PR without one. The coordinator tracks this from the PR list;
lanes do not.
- Close the lanes. Each open item moves into the plan ("After a merge, do" or
Status) before its lane closes; which lanes close is set in section 3.
- Process ideas from the retrospective file go to the user as proposals that wait for
a go-ahead, each naming where it would land: this skill, the repo's rules, or the user's
own config.
1---2name: lanes3description: >4 Use when one effort spans many PRs across several code areas that can move in parallel:5 plan it, then run it as one coordinator session plus parallel lane sessions. Also6 triggers on "split into lanes", "start a lane", "coordinator session", "lane brief", and7 on ending a phase of such work ("inventory round", "close the lanes"). Not for: one8 area done in sequence (one session), or a bounded task whose answer fits a paragraph9 (a subagent).10license: MIT11metadata:12 source: https://skillmd.com/skills/edshav/lanes13---1415# Lanes1617A multi-PR effort runs as one **coordinator** session, which writes no code, and several18**lane** sessions, each owning a slice of the PRs. Sessions die, get renamed and get19compacted; files outlive them. The whole method: decide in a file, then act.2021## When it applies2223Many PRs across several code areas that can move in parallel. It pays off most when the24work outlives any single session, and when one maintainer reviews PRs in batches.2526One area worked in sequence fits one session. A bounded task whose answer fits a27paragraph fits a subagent.2829## The user decides3031The coordinator runs supervised through preparation and lane start. It proposes each32decision there and acts on it after the user's go-ahead. A proposal is a few lines: what,33why, and the alternative weighed. Then the coordinator stops and waits. A go-ahead covers34the decision it was given for; the next decision is asked again. Writing an approved35decision into the plan file needs no second go-ahead. When unsure whether something is a36decision, ask.3738Decisions include:39- each plan section: the inventory buckets, the spec, the PR map, the lane cut, batches40 and merge order, the review process;41- per lane: its model, its placement and name, the full text of its brief before it is42 sent.4344Lanes run at their usual pace; their briefs add no extra stops.4546## 1. Preparation4748Done when the plan file has every section below in place. The plan file sits next to the49code and is kept out of git.50511. **Inventory.** One row per change the effort must land (a hunk, a finding, a52 requirement), sorted into buckets.532. **Spec.** What done means: a spec the PRs are measured against.543. **PR map.** Inventory row → PR → branch → commit, the commit filled in from the55 lane's report. Each PR's branch name follows the repo's convention, and its base is56 the base branch (e.g. `origin/main`) or the PR it builds on. Each PR carries its open57 questions for the maintainer or the developer. Every row lands in a PR or states why58 it does not.594. **Lanes.** Cut by code area and merge order, with overlap checked at function level:60 two lanes may share a file when they edit different functions. When the changes61 already exist as patches, check with `git apply` onto the base branch, in plan order and62 with each pair of lanes swapped; otherwise compare the lanes' function lists. A63 function two lanes both edit fixes an order: the later PR rebases onto the earlier64 one. The lanes table names each lane's functions, PR order, worktrees, session model65 (as approved) and, once the lane reports, its tab id.665. **Merge order**, and batches when the maintainer reviews in batches. Batch 1: every PR67 that stands on the base branch by itself. Batch n+1: PRs that build on a batch-n PR,68 started after the maintainer's pass on batch n so they take in the remarks. Before69 asking the maintainer to review a batch, the coordinator runs the trial build (section 3).706. **Review process.** Agreed with the client, if any, and the maintainer before the71 first PR: who reviews, who merges, who requests reviews.727. **"After a merge, do"** (section 4) and **Status**, empty at the start.7374## 2. Starting a lane7576- **Model, per lane and per task.** The strongest model for the lane session itself when it77 touches money, consensus, keys or judgement calls. Inside a lane, each subagent call names78 its model and gets the cheapest one that fits: the strongest for the first grade of79 judgement items (tests, mutations, money logic) and for fact-checking a review text with80 technical claims; a cheaper one for mechanical checks, re-grades after a small fix, trial81 builds and fact-checking a short text (a one-line closing comment). Effort stays at the82 default. The coordinator stays on the strongest model: it catches errors across PRs, and83 it saves by taking fewer, shorter turns, not by a cheaper model.84- **Worktree.** One worktree per PR, on the branch and base the PR map names.85- **Placement.** One session per lane, in a terminal multiplexer if you use one (e.g.86 Herdr, tmux), in the repo's workspace or session. The tab is named `<lane> · <session name>`:87 the lane first, because sidebars cut names from the end (`b · 6c`; the coordinator88 `coord · da`). The tab gets the last segment of the session name once the session89 runs; cross-session messages go to the full name. The workspace already says the repo.90 The lane label names the code area loosely; the plan's PR list stays the authority. A91 security or embargoed lane gets a neutral label (`sec`), never what it fixes. When a92 lane's report arrives from a new session name, the coordinator renames the tab. It93 finds the tab by the tab id the lane states in its first report and in its first94 report after a restart. A resumed session does not notice a restart by itself: the95 coordinator asks for the report when a lane's session name changes in the session list.96- **First prompt.** Filled in from [`brief.md`](brief.md).9798Per-PR steps, in the lane:991. Branch as above; read the PR's inventory rows.1002. TDD where the change alters behaviour: a test that fails without the change, then101 the change.1023. Run your review pipeline, plus every domain auditor whose area the diff touches.1034. Run your pre-PR check and write its result to the pre-PR results file. Before handing104 the check to its grader, the author walks the check's mutation categories itself, so the105 grader confirms rather than finds. A commit made after the check gets its diff read for106 leftovers (debug output, stray files) before the push.1075. Publish per the brief's "Who publishes": push and open the PR in one command108 (`git push … && gh pr create …`). Where a hook asks before a push or a post, its prompt109 is the user's word: say in two or three lines what goes out (branch, head, PR or post),110 then run the command, with no dialog of your own. Without such a hook, ask for it (and111 for any other outward step: a post to the code host, a message) through the112 AskUserQuestion dialog, with options like "push and open" / "not yet", not as a113 question in the reply text, where it gets lost in long output. A PR body states what a114 test checks and what the pre-PR check needs, not reasoning about edge modes; text for115 the code host goes through the review pipeline once, after the code has settled. A116 branch in the embargo ledger waits for the go the ledger names.1176. Report to the coordinator: the PR and its commit, the inventory rows it covers, any118 step due after a merge.119120A gap in tests the user has accepted on one PR may be accepted on a like PR without asking121again; the lane names it in its report.122123**Scale the pipeline by risk.** The plan assigns each PR a tier; the brief names it.124- *Comments, docs or tests only:* the review pipeline once; from the pre-PR check only the125 items that need no mutations (stand-alone, consequences, overlap); no live run.126- *Logic without money, consensus or keys:* the full review pipeline and the full pre-PR127 check; no live run unless sync or restart behaviour changes.128- *Money, consensus or keys:* everything: the full review pipeline, the full pre-PR check,129 every domain auditor, the live run.130131Below the top tier, one combined review agent replaces the separate review agents: they132read the same diff and mostly overlap.133134## 3. The coordinator135136Writes no code. It:137- keeps the plan file: statuses and the "After a merge, do" table, from lane reports;138- routes briefs to lanes and answers between them, taking branch names and heads for a139 brief from git or the code host, never from memory;140- drafts the client's and the maintainer's messages, for the user to send;141- checks each reported PR against its inventory rows, and asks for an **audit pass**: the142 inventory marks what the PR actually landed.143144Before the review request for a batch, it makes the **trial build**: the base branch plus145every PR of the batch, outside contributors' PRs included (their code only in the146outside-code container), merged in the planned order; build, vet and the full test suite147run on the result. Each PR green alone is not enough: combinations show a test type148declared twice, a test that fails with another PR's change, and pairs of PRs that149conflict on merge. Findings go back to the lanes before the request is sent.150151A lane session stays open while it has an open PR, a pending step in the "After a merge,152do" table, or an embargoed branch. Once all its PRs are merged and nothing is pending for153it, the coordinator closes it, after moving any open item into the plan (section 6).154The coordinator checks this after each merge of a lane's PR and whenever a lane reports155nothing open. Before closing, it asks the lane the close-out questions: findings not156filed, steps pending after a merge, what only its context holds, what slowed it and what157it would change. Answers on code and tasks go into the plan; answers on process go into158the retrospective file, as proposals for the user. Why:159an idle session costs nothing, but waking it after the prompt cache expires (about an hour)160re-reads its whole context uncached, hundreds of thousands of tokens for a long lane, and161autocompact costs about one such pass plus a summary and drops detail. Its state is in the162plan file, the embargo ledger and the pre-PR results file, so a fresh session picks it up163from a brief. Keep the context only where it pays: a lane answering the reviewer on its164own open PR.165166**Keep small steps off long sessions.** Waking a lane after the prompt cache expires167re-reads its whole context uncached. A mechanical step (merging the base into a PR with a168known resolution, waiting for CI, rerunning a known command) goes to a fresh cheap-model169subagent or a coordinator script, not to a lane session. A lane runs /clear between170unrelated tasks and resumes from the plan file and its brief.171172**Reports are short.** A lane writes the detail to its results file and sends the173coordinator 5–8 lines: the file path, the new head, and what needs a decision. The174coordinator passes the user only what needs their decision.175176It finds a lane by worktree and PR list; the tab name is only a label, and the tab id177locates the tab. Session names change; worktrees and PRs do not.178179## 4. Shared resources and state files180181Anything that would die with a session goes into a file at the moment it is decided.182Lanes read the plan file; only the coordinator writes it.183184| File | Holds | Updated by |185|---|---|---|186| Plan file | every section of 1. Preparation, and statuses | the coordinator, from lane reports |187| "After a merge, do" table, in the plan | one line per pending step: the merge that unblocks it, the step, who does it; struck when done | the coordinator, when a lane reports the step |188| Embargo ledger, out of git | unpublished security branches: branch, head, worktree, who gives the go | the owning lane, on every amend, push or PR |189| Pre-PR results file | each PR's pre-PR check result and the commit it ran on | the lane, after each run |190| Heavy-run lock | a script every heavy run goes through: race-detector runs, whole-package suites, long loops | each session, per run |191| Retrospective file | process notes from lane close-outs and reports; proposals waiting for the user | the coordinator |192| Outside-code container | the only place an outside contributor's code builds and runs: no network after dependencies, no host mounts, no credentials, queued on the same lock | whoever reviews the outside PR |193194The plan holds current state: the lanes table, the "After a merge, do" table and open195items. The coordinator moves finished history to an archive file next to it, so each resume196re-reads a short plan.197198An outside contributor's PR goes through your external-PR review, and nothing is posted199until all its checks have run.200201## 5. Failure modes202203| Symptom | Cause | Fix |204|---|---|---|205| A lane's report goes nowhere, or a lane decides its result is lost | the coordinator died or was renamed | every brief names a fallback recipient or a results file; the coordinator maps lanes by worktree and PRs |206| After compaction or a restart, a session has forgotten a pending step, an embargo or a pre-PR result | the state lived only in session memory | the files of section 4; on resume, a session re-reads the plan file first |207| Test runs exhaust memory, or sessions queue for many minutes | heavy runs from several sessions at once | the lock, a time limit per test process, long loops split into batches and started after the pre-PR check |208| An agent skips checklist items, or follows a brief to a moved file | brief rot: a count ("all four items") outlived the checklist; a copied path went stale | write "all items of <skill>"; cite rules ("heavy runs per the repo's rules"), not paths |209210## 6. Ending a phase211212Done when every lane has answered the inventory round and every open item sits in the213plan file.2142151. **Inventory round.** Ask every lane still open the close-out questions (section 3) and216 its lane ↔ PR mapping.2172. **Audit pass** over every PR without one. The coordinator tracks this from the PR list;218 lanes do not.2193. **Close the lanes.** Each open item moves into the plan ("After a merge, do" or220 Status) before its lane closes; which lanes close is set in section 3.2214. **Process ideas** from the retrospective file go to the user as proposals that wait for222 a go-ahead, each naming where it would land: this skill, the repo's rules, or the user's223 own config.