Three skills run on my machines every hour, whether I am working or not.
One prepares the review of every pull request waiting on me, one repairs the failing CI on my own pull requests, and one drafts my replies to reviewer comments.
Each one is a skill file that fans out agents to do the reading, wired to a scheduler, and I have stopped doing the corresponding work by hand.
The schedule is what turned them from tools I have to remember to use into infrastructure that works while I am away, and it reduced my part of the job to reading prepared options and deciding.
An interactive agent session starts when I remember to start it.
That ordering makes the work wait for me, and it makes me the one component in the system that can forget.
Loops as Files makes the point generically: a skill with no trigger leaves the human as the trigger.
These three loops are my version of taking the cron off me.
The waiting is the other half of the problem.
An interactive session is synchronous: I trigger it, then I sit there while it reads, runs, and reports.
A single analysis takes between 2 and 15 minutes depending on its complexity, and triggering them one at a time would spend my day waiting.
The scheduled runs are asynchronous: they prepare the information a decision needs while I am away, and the decision is the only part left that happens with me in the room.
One benefit of the workflows is that the information for a decision is ready when I sit down, instead of arriving only after I trigger an agent and wait for its output.
A schedule, rather than GitHub events, is a deliberate choice.
Most pull requests I touch live in repositories I do not control, so I cannot install workflows, webhooks, or bots there.
A local scheduler is the one trigger I own everywhere.
Hourly is the cadence that works: fast enough that queues never age overnight, slow enough that each run is cheap and usually finds nothing new to do.
(The triage loop could safely run every fifteen minutes; hourly keeps the three aligned.)
All three run from my agent skill library, each as a markdown skill file plus a small deterministic discovery script.
The skills are reusable by hand at any time; the schedule is just what keeps them from waiting for me to remember.
The first run (review-requested-prs) prepares the pull requests waiting on my review, where I am the requested reviewer or already have.
A script lists them all, then checks which review steps are already done for each pull request’s current commit, because every finished step leaves a report keyed to the commit SHA.
Only the stale steps get dispatched, one agent per pull request, running up to five checks: risk assessment, test-coverage analysis, product validation, conformance verification, and code-craft review.
The agents run in parallel, so a slow build on one pull request never delays the others.
When I sit down to review, the verdicts and findings are already there, computed against the exact commit I am about to look at.
The run does not approve anything; it does the reading so my part of the review starts at the decision.
The second run (handle-failing-pr-ci) lists my open pull requests and their combined CI status.
Every pull request with failing checks gets its own agent in its own git worktree, so concurrent fixes never collide.
The agent reads the failing logs, diagnoses the root cause, pushes the smallest fix that addresses it, and watches the checks settle.
The autonomy is bounded: transient failures get a rerun, an unclear root cause comes back to me as a written diagnosis instead of a guess, and two failed fix attempts stop the loop.
My pull requests arrive green, or they arrive with an explanation of why they are not.
The third run (triage-pr-feedback) scans the pull requests I authored for reviewer comments still awaiting a response.
For each pull request with new comments, a read-only agent checks out the pull request head and writes one recommendation file per comment: what the reviewer is asking, whether the claim holds against the code with file and line evidence, whether to implement or decline, how confident the analysis is, and a draft reply in my voice.
State is one file per comment id, so a re-run only sees genuinely new feedback and never re-analyzes something I already decided.
I read the resulting decision table, choose implement, decline, or defer, and only then does an executor skill post replies or push changes.
Nothing reaches GitHub from this loop without my decision.
The three runs look different from the outside, but they are the same pipeline wearing three sets of labels.
Four properties make the pipeline safe to leave running.
Discovery is deterministic.
A script, not a model, decides what needs work and what is already done.
Discovery runs on every tick, so mistakes there compound, and judgment belongs in the per-item agents instead.
Work is fanned out one agent per pull request.
Each pull request gets its own agent, its own worktree, and its own failure domain, so a slow or broken run stays contained.
State lives in files, not in an agent’s memory.
Verdict reports keyed to commit SHAs and one file per comment id mean a re-run is a no-op unless something changed.
That is the property that makes an hourly cadence quiet instead of expensive.
Write access is bounded and layered.
The triage loop never writes to GitHub at all; it produces recommendation files.
The review loop writes only step markers, so a later run knows which checks are done.
The CI loop pushes, with pre-approval scoped to the smallest fix and explicit abort conditions that route back to me.
Merging and replying stay mine.
Review stopped being interrupt-driven: prepared material waits for me instead of the other way around, and I pick the moment to sit down to it.
That is the batching You Are the Bottleneck argues for, minus the fixed timetable.
CI failures stopped interrupting me because an agent picks them up within the hour, and I hear about one only when its diagnosis needs a human.
Replying to reviewer comments became choosing between prepared options, which takes minutes instead of a context switch per thread.
The costs show up anyway.
Skills drift as repositories and CI systems change under them, so the library needs tending.
Correlated errors are possible: all three runs share one skill library, so one bad edit degrades all of them at once.
And preparation is not judgment, which is why the risk-and-confidence routing from How Much Attention Does This Pull Request Deserve? matters once the agents produce more review than I can read.
Every loop is designed so the taste decision (merge this, decline that) stays with me.
Pick the queue you check most often; for most engineers that is pull requests or CI.
Encode the discovery as a script: what needs work, and for each item, what is already done.
Wrap the per-item work in a skill that one agent can run alone.
Fan out one agent per item and write per-item state so re-runs are no-ops.
Then schedule it, read-only first.
Add write access last, scoped, with abort conditions that route back to you.
Agents on my machines now review every pull request that asks for my attention, and they produce more review than I can read.
That inverts the old problem: review used to be the scarce resource, and now the scarce resource is me.
Most agentic reviews end in a single verdict, approved or rejected, and a single verdict throws away the two things I need in order to decide what to do next.
Every agentic review should end with two scores, one for risk and one for confidence, because the real question is never “is this pull request good” but “how much of my attention does it deserve”.
When an agent review ends in a bare verdict, the verdict hides as much as it reveals.
“Approved” can mean “I checked everything and found nothing”, or it can mean “I glanced at the diff and found nothing”, and those are very different claims.
The fix is to split the judgment in two.
Risk is a judgment about the change: how much damage it does if it is wrong, and how hard it is to undo.Confidence is a judgment about the review itself: how much of the risk judgment rests on evidence rather than on hope.
The two scores combine into a routing decision that neither score can give alone.
A low-risk change with low confidence deserves a cheap second look, not a merge.
A high-risk change with high confidence deserves a human reading the named risk drivers, not a rubber stamp.
And a high-risk change with low confidence is the dangerous case: the review is saying “this could hurt us, and I could not check much of it”, which deserves the strongest default.
My risk rubric, part of my agent skill library, scores seven factors, each Low, Medium, or High.
Blast radius asks who calls the changed code, and whether the effect crosses package boundaries.
Public interface asks whether the change breaks or removes a contract that other code depends on.
Security sensitivity asks whether it touches authentication, authorization, cryptography, secrets, or input validation.
Reversibility asks whether a revert undoes it, or whether it is a migration with no way back.
Operational exposure asks whether the changed behavior sits on a hot path or behind a flag.
Coverage gap asks whether tests cover the changed behavior.
Churn asks how often the touched files changed in the past year, a cheap proxy for fragility.
Two rules keep the scores grounded.
Every score above Low must cite file and line evidence, so a suspicion the agent did not confirm does not count.
Every High score must name the concrete failure it makes expensive, and if the agent cannot name one, the score comes down to Medium with an explanation.
The rollup is deliberately blunt: any High factor makes the change High risk, two or more Medium factors make it Medium, and everything else is Low.
The bluntness is a feature, because the goal is not a precise number, it is a defensible triage call.
Confidence is not the reviewer’s gut feeling about its own work, it is an audit of what the review could actually verify.
My rubric counts six evidence points: a current validation report, a current verification report, runtime proof of its must-have criteria, a current code-craft review, a linked issue that states the intent, and a diff small enough to have been read in full.
The caps matter as much as the points.
No linked issue caps confidence at Medium, because there is nothing to check the change against.
Verification that never ran the code caps confidence at Medium, because reading is not proof.
A diff of a thousand lines or more caps confidence at Medium, and the report must say which areas were sampled rather than read.
The sentence I require most in the report names what would raise confidence.
“Running the verification skill would add two points” turns the score from a vague judgment into a list of concrete actions.
Because the scores are pinned to a commit, the assessment can be re-run when the evidence lands, and the same pull request climbs from Low to High confidence without anyone re-arguing the risk.
Confidence is not a number you state once, it is a number that should rise as evidence lands.
The two scores route each pull request to one of six verdicts: fast-track, confirm, investigate, decide, block, and hold.
fast-track means I owe the change minutes: merge once checks pass.
confirm means pay for one cheap review first, then fast-track.
investigate means the evidence is too thin to route on, so run the full review pipeline and score again.
decide is the interesting middle: the risk is Medium but the evidence is strong, so I read the named drivers and choose with findings in hand.
block and hold are the expensive verdicts: the drivers must be resolved, or the change is treated as high risk until proven otherwise.
Each verdict names its next action, and that is what puts a price tag on attention.
A queue of forty pull requests becomes a triage sheet: fast-tracks to clear immediately, a hold to schedule an evening for, and one decide to actually think about.
The scores do not review the code, they decide where the scarce reviewer hours go.
The verdicts never gate the agent pipeline.
A block verdict does not halt the chain of validation, verification, and craft review, and the chain never halts the risk assessment, which runs concurrently so the triage signal exists before the deep review finishes.
The scores are advisory on purpose: the pipeline’s job is to produce evidence, the human’s job is to spend attention, and merging those jobs is how automation starts overruling people quietly.
The verdict travels in a machine-readable marker pinned to the commit, so my orchestrator displays the risk and confidence columns without parsing a word of prose.
The same design is what makes the system scale.
One script discovers every pull request across every repository that asks for my review, a fan-out gives one agent session to each pull request, and the orchestrator session collects a summary table for triage.
The agents burn tokens, which are cheap, and I spend attention, which is not.
Everything that can be mechanical is pushed to the machines, and what reaches me is a short list of decisions that cannot be.
Three illustrative scenarios, the same ones I use as worked examples in the skill itself, show the range.
A small internal fix, covered by tests, in files that change once a year: every risk factor Low, but no pipeline reports exist yet, so confidence is Medium and the verdict is confirm, one cheap review then merge.
An authentication change with the full pipeline behind it: security sensitivity High, but runtime proof of every must-have criterion, so confidence is High and the verdict is block until the named session-invalidation gap is fixed.
A 1200-line billing migration with no linked issue: reversibility and coverage both High, confidence Low and capped, so the verdict is hold, and the same pull request re-scores to decide once the full review lands.
Same rubric, three very different amounts of reviewer time.
If you run agent reviews, force every review to end with both scores, not one verdict.
A five-minute rubric beats a bare approval: three risk factors and three evidence points are enough to start.
Ban unverifiable confidence language: if the score cannot cite the evidence behind it, it is not a score.
Make every verdict name its next action, so the queue reads as a budget rather than a pile.
And track the mis-routings, because a fast-tracked pull request that burns your evening is calibration data, and the rubric should get stricter wherever it fails.
Over the past nine months I have run LLM agents against the largest projects I have ever worked on alone: the open source tools I use and maintain daily, and the automated pipeline that publishes part of this blog.
The models improved underneath me the whole time, and that helped less than I expected.
What actually helped was learning to handle four challenges: providing the right context, iterating through non-obvious design decisions, managing the scale of the work, and keeping artifacts consistent while decisions change.
None of the four is about getting a model to write better code.
All four decide whether the code the model writes turns into a finished project.
GitHub gives the scale better than my memory does: since January I have contributed 1,338 commits across 51 repositories, along with 66 pull requests and 181 issues.
By mid September, 9 months in, the session counter read 3,400 sessions, 82,000 messages, and 6.8 billion tokens, 6.5 billion of them served from cache, spread across 63 projects and 33 models, on a path that had moved from Claude Sonnet 4.5 to GLM 5.3 Flash.
The volume is not the point.
The point is that the same four challenges appeared in every project, and how I answered them changed more than any model upgrade did.
Nine months ago my working assumption was that a capable agent would gather whatever it needed by exploring the repository.
On a small project, that assumption holds.
On a large one, it fails quietly: a session is generally scoped to a single location, one repository or directory, and a large project rarely fits inside one, so each session sees a narrow slice of the project, and the knowledge outside that slice might as well not exist.
The cost showed up as steering time.
I would launch a session, come back, and find it had built on a wrong assumption, then spend the next half hour correcting course.
Worse, the corrections sometimes left the written context inconsistent, one artifact updated while the artifacts that depend on it stayed stale, and later sessions inherited the contradiction as ground truth.
On a large project, under-provisioned context does not just slow one session down, it poisons the sessions that follow.
What I do now is treat context provisioning as a phase with an exit condition, not a chore.
Access first: every source the answers live in gets a way in and a pointer, which is the setup I described in Teach Your Agent Where Everything Lives.
Then the map: which repositories exist, how they relate, where decisions live, written down so a cold session can orient in minutes.
The exit condition: a cold session, dropped into the project with only its instructions file, can find every source it needs without asking me.
I test it by handing the session a question whose answer I know lives in one of the mapped sources, and provisioning is done when it comes back with the answer and the trail instead of a question.
The principle underneath is the one I keep coming back to, that context quality dominates model choice.
Every session I launch inherits the preparation, and every session I under-provision collects the tax in steering time.
Challenge 2: Iterating Through Non-Obvious Design Decisions
#
The decisions that sink large projects are rarely the ones I can state up front.
They are the non-obvious ones: how two modules should share a data format, what happens when a change is abandoned halfway through, whether a behavior belongs in a shared library or in the calling code.
I cannot enumerate those in a prompt, and an agent cannot discover them from the code alone, because half of them are not written down anywhere.
What I do now is iterate.
Before any implementation session launches, I work with an agent to understand the current codebase and describe the changes we need to make, and we go back and forth until most open questions are resolved.
The agent is a design partner, not a typist: it restates my description, catches the cases I glossed over, and proposes the alternatives I did not consider.
The exit condition is simple: when the questions the implementing agent would ask have already been asked and answered, the design conversation is done.
Answering a design question in conversation costs minutes.
Answering it mid-implementation costs a stalled session, a wrong branch, or a refactor, and the stalls compound on every long run.
This is the principle behind Say It Once, that every question an agent would ask mid-run should be answered before the run, applied one phase earlier: not just the standing rules, but the design itself.
Here is the loop as it runs today, from first contact with the codebase to the moment parallel sessions can safely start:
flowchart TD
A[Explore the current codebase with an agent] --> B[Describe the change]
B --> C{Open questions remain?}
C -->|yes| D[Agent questions assumptions and proposes alternatives]
D --> B
C -->|no| E[Write decisions into the artifact tree]
E --> F[Seed requirements and specs per feature]
F --> G[Stand up the verification environment]
G --> H[Partition the work and launch parallel sessions]
A large project carries more work than one session can absorb, and more than I can supervise.
On the most feature-heavy project I have run through my pipeline, the features outnumbered my attention within weeks: creating a directory per feature was cheap, walking each one through design personally was not.
The answer is delegation and parallelism, but both have to be earned.
Parallel sessions collide unless the work is partitioned along real seams, and the seams only become visible through the design iteration of the previous section.
The preparation is what makes scale manageable.
Each feature keeps its own artifact directory, seeded before any implementation session starts.
Owning agents take features as far as they can and stop at the gates that need a human decision.
Sessions get their own worktrees, so parallel work never steps on itself.
Tasks that share a file serialize; everything else runs in parallel.
Parallelism is earned at partition time, not at spawn time.
Spawning ten sessions on an unpartitioned codebase produces ten half-features and a merge conflict.
Spawning ten sessions along the seams the design conversation exposed produces a project.
The other half of scale is me.
With a dozen sessions running, I become the bottleneck unless decisions are batched and gates are explicit, which is the supervision problem I worked through in Managing Many Concurrent LLM Agent Sessions.
Challenge 4: Keeping Artifacts Consistent While Decisions Change
#
The final challenge never stops.
On a project with dozens of interlocking features, decisions keep changing, and every change ripples.
A revision to one feature’s specification forces updates in the requirements and plans of the features that consume what it produces.
A session forked last week works from a snapshot that the sessions around it have already moved past.
Nine months ago I treated consistency as something to check at review time.
Review time is too late: the stale artifacts have already fed other sessions by then.
What I do now comes in two layers.
Artifacts declare what they depend on, so the ripple has a map, and a propagation pass follows the map when an artifact changes, updating dependents or raising questions where a decision is needed.
I worked out that mechanism in detail in What Needs Updating When Agents Do the Work.
Verification environments catch whatever the map misses: an hour spent making the environment catch the inconsistency beats an hour reading diffs hoping to see it, which is the trade I laid out in My AI Workflow.
Consistency on a large project is not a milestone you reach, it is a loop you run, and only a machine can run it at the frequency the project changes.
Before launching implementation, run the design loop with an agent until the open questions are resolved, and write the answers where the implementing sessions will read them.
Treat context provisioning as a phase with an exit condition: access, map, pointers.
Seed the artifact tree per feature before the first implementation session starts.
Partition along the seams the design work exposed, isolate with worktrees, and serialize whatever shares a file.
Add dependency declarations and a propagation pass so artifact consistency is maintained by loop, not by review.
Watch your steering time: if you correct sessions more than you review them, the context was under-provisioned.
When agents do the maintenance, every repository you keep is a subscription to future work, and the subscription is paid in tokens.
The instinct at scale is to automate harder, Dependabot on everything, a scheduled agent per repository, alerts routed to a bot.
That instinct treats each repository as its own problem, and at fleet scale the fleet itself is the problem.
Agentic maintenance is fleet management: deciding which repositories deserve work at all, deciding what work they deserve, and reusing every decision across as many repositories as it applies to.
A repository that sits active in an organization is never neutral.
Its Dependabot config opens version-bump pull requests on a schedule.
Its security alerts accumulate.
Any scheduled agent that sweeps the fleet reads all of it as a backlog.
A repository that humans would quietly ignore, agents cannot, because an agent’s correct behavior when pointed at a repository full of signals is to act on them.
When I maintained five repositories, ignoring a dead one cost me a guilty glance once a month.
With fifty, ignoring is no longer possible, because the automation keeps generating work regardless of whether anyone wants it.
The cost is not per decision anymore, it is per repository per unit of time, whether or not anyone looks.
Adding a repository to the fleet is adding a standing order for future work, and canceling that order is a maintenance task in itself.
Dependabot has no strategy.
It does not know that the library it wants to bump was superseded by another one, that the project is in maintenance mode, or that the product behind the repository was deprecated last quarter.
It opens the pull request because a newer version exists, and it will keep opening them until someone makes it stop.
The same is true for every scheduled agent: an agent that finds dependency alerts in a repository treats them as its work queue, because that is what it was told work looks like.
A dependency bump in a repository nobody is investing in is pure waste.
It costs tokens to generate, CI minutes to validate, attention to review, and merge effort, and the value delivered is zero because nobody is deploying the result.
Multiply by the number of dead repositories and the number of updates per year, and the fleet is running a small factory that manufactures unneeded pull requests.
Bots generate work at a fixed rate per repository, independent of that repository’s value, so the value decision has to be made somewhere else, by you, before the bots run.
The cheapest way to stop work on a repository is to archive it.
An archived repository becomes read-only: issues, pull requests, and code can no longer be changed, which means Dependabot has nowhere to open its pull requests, alerts have nowhere to be fixed, and scheduled agents have no work to perform.
The archive state is also a legible signal.
GitHub describes it as marking a repository as no longer actively maintained, so bots, agents, and humans all read the same message: no future work here.
I used to think of archiving as an admission of failure, a small funeral for a project.
That framing is what keeps dead repositories alive, because nobody schedules funerals.
When I finally ran this pass over my own fleet, most of the repositories went straight to the archive, and the guilt I had been carrying about them turned out to be a bug in my process, not a flaw in my priorities.
The better framing is mechanical: archiving is the off switch for automated work, and a repository that will not receive maintenance should be switched off.
A repository that is archived cannot waste tokens, and a repository that is merely neglected wastes them on schedule.
If the project matters again later, GitHub supports unarchiving, so the downside of a wrong archive decision is small.
The downside of the opposite mistake, keeping a dead repository live, compounds every week the bots keep running.
The lifecycle has three tiers, and the automation should differ on each one:
flowchart LR
A["Active<br/>full automation: Dependabot, scheduled agents, alerts"] -->|fewer users, less investment| B["Maintenance mode<br/>security updates only, batched and infrequent"]
B -->|no users, no fixes planned| C["Archived<br/>read-only, no automation, zero token spend"]
C -.->|a reason returns| A
Not everything belongs in the archive, and not everything active deserves full service.
A library with real users but no development might deserve security bumps only, batched monthly.
A template repository might deserve updates once a quarter.
The tier matters only if the machines can read it.
The Dependabot config can encode part of the policy: version update schedules can be set to daily, weekly, or monthly, with per-dependency ignore rules for anything the policy declines.
But the part that matters most to agents lives in the repository’s agent instructions, the AGENTS.md layer, because that is the file agents actually obey.
“Dependency pull requests: security alerts only, otherwise close with a pointer to the maintenance policy” is a sentence an agent can execute.
No policy at all is also an instruction, and the instruction it gives is “everything here is worth maintaining”.
An agent faced with an unannotated repository will invent a policy, and the invented policy is always maximum effort.
Sweep the portfolio, do not fight per-repository fires
#
The wrong way to run maintenance agents at scale is one agent per repository on a timer.
That design multiplies cost by the repository count and makes the agent re-learn the same context on every run.
The right granularity is the portfolio sweep: one scheduled run that walks every repository, collects the signals, and produces a ranked list of what deserves action this week.
The sweep output is a triage report, not a pile of pull requests.
Agents then get dispatched only at the top of the list, where the value is, and everything below the line gets a note instead of a token budget.
A sweep also sees what per-repository agents cannot: the same change suggested everywhere.
Dependabot does not coordinate across repositories.
It will open the same GitHub Actions version bump in thirty repositories, each one arriving as an independent pull request that looks like independent work.
Read as a pile, that is thirty tasks.
Read as a list, it is one upgrade.
Aggregating the suggestions before acting on any of them is what turns the pile into a list, and the list is where the economies live.
The decision is the expensive part, and the decision does not often change per repository.
Deciding whether actions/upload-artifact should move from v3 to v4 costs the same investigation whether you run it once or thirty times: what breaks, which workflows depend on the old behavior, what the migration needs.
The per-repository work is the applying, and applying a decided change is mechanical, cheap, and fully delegable to an agent.
So decide once, write the rationale once, and send the same answer to all thirty pull requests, applying the change in every repository and flagging the few that need an exception.
The application happens once per repository either way, the saving comes from paying the decision once across all of them.
A suggestion that keeps returning is also a design signal.
If every repository carries its own copy of the same workflow steps, every upstream action bump becomes thirty pull requests again next quarter, and the decision cost recurs with them.
Move the repeated piece into a shared component, a reusable workflow or a composite action that lives in one repository and is called by all the others, and the next bump happens in one place by construction.
The best fix for a maintenance task that repeats across the fleet is to stop repeating it, by giving the change exactly one home.
Human-scale maintenance was measured in hours, and hours were scarce enough to force triage on their own.
Agentic maintenance is measured in tokens, and tokens are cheap enough that the waste hides until the invoice arrives.
So make the bill visible: track tokens spent per repository per month, alongside how much of that spend produced merged work.
The numbers feed the pruning loop.
A repository that burns a large share of the budget while producing no merges is either misconfigured or dead, and either way the fix is the same conversation: what is this repository for, who uses it, and should it still be in the fleet.
The token ledger is the portfolio review, and the portfolio review is where the fleet decisions come from: what to keep active, what to demote to maintenance, and what to archive.
List every repository you maintain and mark each one with the tier it deserves: active, maintenance mode, or archive.
Archive everything in the third bucket today, and turn off its dependency automation before you do.
For every repository that stays, write its maintenance policy into its agent instructions: what kinds of updates are wanted, at what cadence, and what should be declined automatically.
Replace per-repository scheduled agents with one portfolio sweep that produces a ranked list, and dispatch agents only at the top of the list.
Aggregate the open suggestions across repositories before acting on any of them: group identical changes, make the decision once, and apply it everywhere with the same rationale.
Centralize the pieces that repeat, such as shared workflows and composite actions, so the next change lands in one place.
Track tokens per repository per month, and let the biggest spenders with the fewest merged outcomes lead the next round of archive decisions.
Maintenance at scale is not a stack of per-repository chores, it is the management of a fleet: admit work deliberately, decide once where the same change repeats, and keep the automation pointed at the repositories that matter.
What Needs Updating When Agents Do the Work - the maintenance loop agents run after a change lands, the machinery this article says to point only at repositories that matter
The Self-Evolving Repository - the end state where a repository maintains itself, which only makes sense to build for repositories that earned a place in the fleet
The Codebase Gardener - why maintenance is gardening rather than construction, and why gardens need beds retired, not just watered
GitHub Docs, “Archiving repositories” - the read-only semantics of archived repositories and the unarchive path, which ground the claim that archiving stops automated work
When an agent pushes a code change, the change itself is the fastest thing in the pipeline.
The PR title and description written before the second revision, the review comments nobody answered, and the red CI run all become outdated and inconsistent with the code.
Agentic work does not end when the code is written, it ends when a change has propagated through the graph of records in both directions.
In human-paced development, a push was a statement of completion.
The author finished the work, wrote the PR title and description last, and pushed once.
The PR title and description were accurate because they were written after the code settled.
Agentic development breaks that ordering.
An agent pushes a first draft, receives feedback, addresses it, and pushes again.
Then it rebases, fixes a failing test, and pushes again.
Each push improves the code and invalidates the records describing the previous version.
The diff updates itself on every push, the PR title and description do not.
That asymmetry is the whole problem.
After three iterations, a pull request can contain correct code wrapped in a wrong story.
The PR title and description explain a feature that no longer exists.
The comments hold questions the final code already answers.
The last CI run failed before the final fix landed, and nothing explains why the failure no longer matters.
Nothing in the code is broken, and everything around the code is stale.
These stale records present themselves as a checklist: walk the pull request and fix each one.
The checklist view fails because the records are not independent, each one was written from another.
The artifacts around a change form a directed acyclic graph.
The issue feeds the requirements, the requirements feed the specification, the specification feeds the code, and the code feeds the tests, the PR title and description, and the documentation, and no artifact feeds back into itself.
Each artifact should declare what it depends on, because the declarations are the map that a propagation pass follows.
Here is the structure, with a change entering at the code node:
flowchart TD
ISSUE[Issue] --> REQ[Requirements]
REQ --> SPEC[Specification]
SPEC --> CODE[Code]
CODE --> CI[Tests and CI]
CODE --> DESC[PR title and description]
CODE --> DOCS[Documentation]
SPEC --> DESC
X([A change lands in one artifact]) -. enters .-> CODE
ISSUE <-.-> REQ
REQ <-.-> SPEC
SPEC <-.-> CODE
CODE <-.-> CI
CODE <-.-> DESC
CODE <-.-> DOCS
SPEC <-.-> DESC
Solid arrows are declared dependencies: an artifact is built from the artifacts its solid arrows come from.
Dotted double arrows are propagation, and they run along every edge in both directions.
Downward, a changed artifact updates its dependents: the PR title and description must be rewritten, the documentation must describe the new behavior, and the test expectations must assert it.
Upward, a changed artifact questions its premises: if the code had to deviate from the specification to work, the specification is now wrong, the requirements it satisfied are in doubt, and the issue behind them may be wrong too.
No matter where the change lands, the two walks visit every artifact the declared edges connect.
Propagation has to run in both directions, because each direction catches a different kind of staleness.
Downward-only propagation keeps the record aligned with the change while leaving the premises unexamined, which produces a consistent account of the wrong decision.
Upward-only propagation questions everything and updates nothing.
An agent runs both walks mechanically: it follows the declared edges, applies every update whose resolution follows from the change, and raises a question wherever two connected artifacts disagree in a way that admits more than one resolution.
A single forward pass is the ideal Say It Once argues for.
The issue produces the requirements, the requirements produce the specification, the specification produces the code, and the code produces the rest, with every question answered before the next artifact starts.
In most cases, though, the forward pass cannot complete in a single iteration, because some gaps become visible only when a downstream artifact is produced.
Writing the code is how you learn the specification never said what happens when the input is empty.
Writing the documentation is how you learn that nobody decided what the feature is called.
Producing a downstream artifact is also a probe: it tests the artifacts before it, and every gap it finds sends the walk back upward.
The loop below is the graph in motion at the pull request node, the place where every agent-authored change lands first.
Automated review reads the diff and produces feedback.
An agent addresses that feedback, with a human steering when judgment is needed.
The agent then brings the pull request back in sync: it replies to the review comments, handles the CI failures, and updates the PR title and description if the latest push made them outdated.
The documentation that describes the changed behavior is updated in the same pass.
Then review runs again.
flowchart TD
A([Code change pushed]) --> B[Automated review and CI run]
B --> C{Feedback or failures?}
C -->|none| M([Ready to merge])
C -->|yes| D[Agent addresses the feedback]
HUMAN[Human feedback] -. steers .-> D
D -. raises questions .-> HUMAN
D --> U[Agent brings the PR back in sync]
U --> F[Replies to PR comments]
U --> G[Handles CI failures]
U --> I[Updates the outdated PR title and description]
U --> DOCS[Updates the documentation]
F --> B
G --> B
I --> B
DOCS --> B
Every station in this loop has an owner, and the default owner is the agent.
Assigning any station to a human by default re-serializes work the machine could finish in minutes, the same mistake made at pipeline scale when human review gates machine-rate output in Rethinking Code Review in the Age of LLMs.
The update loop runs several times per pull request, so any station handled by hand multiplies by the number of iterations, not the number of pull requests.
At the pull request node of the graph, the propagation pass takes the form of three jobs.
Documentation is a dependent of code too, and it is updated in the same pass, inside the same pull request as the code change.
An unanswered review comment is ambiguous.
The reader cannot tell whether the agent missed it, disagreed with it, or resolved it silently in a later push.
The agent should reply to every comment with what it changed and why, including an explicit “declined, because” when it rejects a suggestion.
The reply is not politeness, it is what turns the thread into a record.
A thread where every comment has an answer reads later as a decision log, and the human who scans it before merging reads conclusions instead of mysteries.
For a human author, a red build is a judgment to react to.
For an agent, it is input to consume.
The agent reads the failure, fixes the code, reruns the suite, and pushes.
The loop continues without a human ever opening the log.
Escalation stays reserved for the cases that need a decision: the same failure returning across pushes, a flaky test worth deleting, or a fix that changes behavior the specification did not authorize.
A CI failure routed to a human queue is a decision the pipeline refused to make.
The PR description is written when the pull request opens, which means it describes draft one.
The title goes stale the same way: it names the purpose the change opened with, and the purpose may have moved by the third revision.
By the time the code merges, both can be documents about a version that no longer exists.
The agent should rewrite the description after significant revisions, and update the title whenever the purpose of the change moved, so both always describe the current diff: what changed, why, and which suggestions were rejected and why.
A PR title and description are a promise about what the diff does, and an agent that stops updating the promise is asking the reader to audit the diff to find out.
The human feedback in the loop enters as steering, not as typing.
The human does not write the replies, fix the builds, or reword the PR titles and descriptions.
The human reviews the agent’s proposed resolutions and decides the contested suggestions.
The human also ends disagreements, because an agent arguing with an automated reviewer can cycle forever, and only a human can decide the outcome.
And the human answers what propagation cannot settle: an update either follows from the change or it does not, and when it does not, the upward walk stops and hands the human a decision instead of a diff.
The human’s job is not to answer the comments, it is to decide what the answers mean.
Attention spent typing replies is attention not spent steering, and steering is the part of the loop a machine cannot do, which is the same division of labor argued in The Acceptance Gap.
I run this loop on my own work.
When I open one of my agent’s pull requests, the threads are answered, the failures are explained, and the PR title and description match the diff.
The judgment calls are still mine, which is exactly where my attention is worth the most.
The division also has an upstream payoff.
When review feedback keeps revealing the same misunderstanding, the fix is not a better reply, it is a better specification, and the human is the only one positioned to write it.
Make “reply to every review comment” a standing rule in your agent’s instructions, with an explicit declined-and-why format for rejected suggestions.
Have an agent handle PR feedback asynchronously: when a piece of feedback lands, it is already addressed by the time you look, and your part is to immediately pick the action to take instead of manually triggering an agent to address it.
Route CI failures to the agent before they reach a human, and escalate to you only on repeat failures or ambiguous fixes.
Add a PR title and description refresh as a required step before every re-review request and before merging, so both always match the latest diff.
Declare the dependencies between your artifacts: which issue a requirements document answers, which requirements a specification satisfies, which specification a change implements, which code a PR title and description describe. Propagation without a map is guesswork.
After every change, run the propagation pass in both directions: update what depends on the change, and re-check what the change depends on.
Watch the loop for livelock: when the same feedback returns twice, stop the agents and make the design call yourself.
Audit the artifact graph occasionally: check whether every artifact still matches what it depends on, across issue, requirements, specification, code, tests, PR title and description, and documentation, and treat the mismatch rate as the measure of how much of this loop you are still running by hand.
Rethinking Code Review in the Age of LLMs - the argument that verification moved from human reading to automated gates, the context that makes an agent-owned update loop necessary.
Say It Once - the same principle applied around a run: answer the questions before the run, and answer every comment once, in the thread, after it.
Nine Months of LLM Agents on Large Projects - the project-scale version of the artifact graph, where artifacts declare dependencies and a propagation pass follows the map when one changes.
The Acceptance Gap - why acceptance, not review, is the gate between an agent and production, and where the human in this loop should spend attention.
My AI Workflow - where the skills and verification environments that automate this loop come from.
GitHub, “About GitHub Copilot cloud agent” - evidence that agent-driven changes with iterate-through-review cycles are shipped product behavior, not a personal experiment.
When a senior engineer opens a pull request, not reconstruct what it does.
The standard is that everything which did not require a second brain is already done before the review request goes out.
CI is green, the diff is small and single-purpose, the description explains the change, the author has already read their own diff, and the proof that it works is in the PR.
Anything less quietly converts review time into discovery time, and discovery is the most expensive way to use a reviewer.
Stripped of argument, here is what a reviewer can assume when a senior engineer opens a PR:
CI is green on the latest commit.
The diff does one thing; refactors and behavior changes live in their own PRs.
Stray logs, commented-out code, and unrelated reformatting are gone.
The author has read the full diff as a stranger would and annotated the lines that need context.
The description answers what changed, why, and how it was tested, and points at where to look closely and what is out of scope.
Proof that it works is in the PR: tests for new behavior, plus written manual verification when tests are impractical.
The requested reviewers own the subsystem you are touching, not whoever is idle.
Each of these assumptions a reviewer has to re-verify by hand is attention taken away from judging the change.
When one of them breaks, the reasonable response is not a comment, it is returning the PR to draft.
The unit of waste in review is the round trip: the author requests review, the reviewer finds a gap, comments, and the change then sits in a queue until both people are free at the same time again.
One round trip costs four context switches, two per side, plus a wait for the other person’s next open slot.
The reviewer switches out of their own work to read the diff and back into it after commenting, and the author later switches out of their work to address the comment and back into it after pushing the fix.
Because each switch means rebuilding the mental state you had before the interruption, a gap the author could have closed in minutes costs days of calendar time.
Every expectation in the standard above exists to delete one class of round trip.
A green build deletes the “your build is broken” loop, a single-purpose diff deletes the “split this up” loop, an annotated self-review deletes the “what is this line for” loop, and real proof deletes the most expensive loop of all, “your tests do not cover this”, which costs a test rewrite plus a full second pass.
Research on real reviews backs the self-review half of the deal: in industrial code review, most comments ask for improvements and clarifications rather than catching real defects (Bacchelli and Bird, 2013), and Google’s study of its own process treats small, fast changes as the mechanism that keeps review load sustainable (Sadowski et al., 2018).
Review latency is mostly queueing, not judging, and the standard is how you stop feeding the queue.
Review is a handoff, and a handoff has two sides.
The author’s side is logistics: prove the change works, make it easy to read, explain why it exists.
The reviewer’s side is judgment: design, correctness, and whether the code will still make sense in a year.
When the author skips their half, the reviewer inherits it.
A PR that forces the reviewer to reconstruct the intent is a PR that was opened too early.
The division of work looks like this:
flowchart LR
subgraph Author["Author, before opening"]
A1[CI green]
A2[Self-review done]
A3[Description written]
A4[Proof of testing]
A5[Small single-purpose diff]
end
A1 --> O[Open PR]
A2 --> O
A3 --> O
A4 --> O
A5 --> O
O --> R["Reviewer: judgment only<br/>design, correctness, maintainability"]
The highest-leverage habit is also the dullest one: keep the diff small.
Google’s engineering practices make the case from experience, small changes get reviewed faster and more thoroughly, and reviewers miss fewer defects.
Size is not the only variable though, purpose is.
A senior engineer separates refactoring from behavior changes, because a diff that does two things forces the reviewer to review both at once and catch neither.
If a PR needs a live walkthrough before anyone can understand it, that is usually a sign it should be several separate PRs.
There are legitimate exceptions, a generated-code migration or a mechanical rename can be large and still easy to review.
The mark of a senior engineer is knowing which kind of large diff they have, and saying so in the description.
Before requesting review, the author reads their own diff on the same screen the reviewer will use, the Files Changed tab, end to end.
This pass has two jobs.
The first is debris removal: stray logs, commented-out code, leftover debugging, unrelated reformatting that inflates the diff.
The second is annotation: leaving comments on the lines that need context, “this mirrors the logic above”, “this limit matches the upstream API”, so the reviewer does not have to ask.
Self-review is also where a senior engineer catches the embarrassing stuff, and catching it yourself is the whole point of being senior.
Every defect the author removes before the review is a round trip that never happened.
A Description That Answers the Obvious Questions
#
The description exists so the reviewer never has to ask questions the author could have answered in writing.
The questions are predictable:
What does this change do, and why is it needed?
How was it tested?
What should the reviewer look at most closely?
What is deliberately out of scope?
Screenshots for UI changes, before-and-after output for behavior changes, and a link to the ticket all belong here.
The ticket link is a pointer, not a description.
A reviewer who has to read the ticket to know what the PR does has been given homework instead of a review request.
The author’s job is to demonstrate the change works, not to believe it works.
That means tests for new behavior, updated tests for changed behavior, and a written note on manual verification when tests are impractical (“ran the migration against a copy of staging, 4.2M rows, 90 seconds”).
I put this in the description under “How I tested this”.
The reviewer’s job is then to audit the proof: are the tests real assertions or tautologies, do they cover the failure modes, is the manual claim plausible.
An author who ships “seems to work” is asking the reviewer to do QA on a hunch, and most reviewers will price that in with a request for changes.
The standard does not end when the PR is opened.
Watch CI and fix failures immediately; a PR with a red build is blocking a reviewer for nothing.
Respond to comments within a day, even if the answer is “I’ll get to this Thursday”.
Push fixes as commits so the reviewer can see what changed since their last pass, and say when the PR is ready for a re-review.
When a comment thread passes about twenty back-and-forths, take it to a call and write the conclusion back into the PR.
And when you disagree with a reviewer, either convince them, accept the change, or escalate; a senior engineer does not let a PR rot in a stalemate.
The standard has legitimate exceptions, and seniority shows in running the exception protocol instead of quietly lowering the bar.
Sometimes the approach is still unsettled, sometimes a change cannot be split cleanly, and sometimes you need early eyes to avoid building the wrong thing for a week.
Each case has a protocol that keeps discovery on the author’s side of the handoff:
The approach is unsettled: settle it in a short design note or issue before writing code; a paragraph of prose resolves an approach faster than three rounds of review comments on code headed for the trash.
You need early feedback: open the PR as a draft and name the exact question and the lines that answer it, for example “design feedback on the cache interface only, ignore the internals”.
The diff is unavoidably large: stack it, base each PR on the previous one, and keep every PR in the stack single-purpose so the reviewer can approve them in order.
flowchart TD
Q{"Cannot meet the<br/>standard yet?"} -->|"Approach unsettled"| D["Design note or issue<br/>settle the approach first"]
Q -->|"Early feedback needed"| E["Draft PR<br/>name the question and the lines to read"]
Q -->|"Diff too large"| S["Stacked PRs<br/>each one single-purpose"]
D --> R["Then open a PR<br/>that meets the standard"]
E --> R
S --> R
The difference between a draft and a premature PR is that the draft tells the reviewer what to look at, and what to ignore.
“Is this the right approach?” is a question a reviewer can answer in five minutes.
“What is this PR doing?” is homework.
None of the seven expectations should depend on memory, because memory fails on exactly the days the standard matters most, the rushed ones.
Encode it once and let the system carry it:
A PR template with the four description questions already written out.
Format and lint gates in CI, so reformatting noise never reaches a human-reviewed diff.
A draft-first habit: every PR is born as a draft and only flips to ready when the checklist passes.
Reviewer assignment by code ownership, so requests route to the subsystem’s owners instead of whoever is idle.
There is a quieter reason a senior engineer holds this line.
A senior engineer’s PRs are the template the rest of the team copies, because people calibrate to what actually gets merged, not to what a wiki says.
The first time the team watches its most senior member ship a rushed PR to quick approvals, the written standard is dead.
If you want to change how a team reviews, change what its most visible engineers ship.
Before you click “Request review” next time, walk the seven expectations in the list above one last time, in order.
Then go a step further and audit your last three merged PRs: find the expectation you break most often under deadline pressure, and encode it once, as a template line, a CI gate, or a personal checklist item.
A standard you re-derive from memory every time will erode; a standard encoded in the system survives your worst week.
None of this requires talent.
It is the difference between treating review as a service you consume and a contract you enter, and seniority is mostly showing up on the right side of that contract.
A team of six engineers runs the on-call rotation for an entire system, and the request for more people goes nowhere.
The instinct is to treat this as a hiring problem and wait for management to fix it.
Hiring is the slowest and least controllable lever you have, so the rotation has to get lighter first, and the case for headcount has to become a business case instead of a complaint.
Here is what I would do in that position, in order.
Start with the arithmetic of a six-person rotation.
Each engineer is primary once every six weeks and secondary once in the same window.
Every primary shift demands enough context to triage, mitigate, and escalate a failure anywhere in the system.
Between shifts, five weeks pass with little reason to touch the parts of the code you only see when they break.
Memory of unfamiliar subsystems decays in days, not months, so by the time your shift arrives you are substantially relearning the system.
When every shift requires remembering everything and the gaps between shifts let the memory rot, you have not designed a rotation, you have designed a scheduled relearning exercise.
The Google SRE book, “Being On-Call” states the standard explicitly: an on-call engineer should feel capable of swift, effective action, and high page load or long post-shift recovery is treated as a defect of the system design, not of the person.
The SRE Workbook’s on-call chapter makes the same point operationally: burden has to be balanced, or the rotation quietly converts engineers into ex-engineers.
A six-person full-system rotation where nobody feels capable of acting is not a staffing failure yet, it is a design failure.
Instrument the pain first, because adjectives do not move management and you need the numbers for the later steps anyway.
Export four weeks of paging data and compute a handful of numbers:
Pages per shift, split by primary and secondary, and by day versus night.
The actionable ratio: the fraction of pages that required genuine human judgment rather than a restart, a throttle bump, or an acknowledgment and nothing.
Time to mitigate, and specifically how long it took the responder to have enough context to act at all.
Repeat incidents: the same failure mode paging more than once.
Re-entry ramp: how long it took each engineer to be fully productive on their normal work after coming off a shift.
Most teams that run this exercise discover that half or more of their pages were noise, and that the re-entry ramp after every shift costs a day or more of productive work per engineer.
You cannot make a rotation lighter if you cannot say what it currently weighs.
With the data in hand, reduce what pages and what a page demands.
Apply the alerting standard from the SRE Workbook’s “Alerting on SLOs”: a page is for a user-visible symptom that needs human judgment right now.
Everything else becomes a ticket, a dashboard entry, or nothing.
The alert that fires twice a week and is always dismissed is not information, it is an alarm nobody heeds, and it is eroding the reflex you need at 3 a.m.
For the pages that survive, write runbooks so the responder can act without tribal knowledge.
A page with a runbook is a procedure, and a procedure survives the five-week memory gap.
A page without one is a puzzle, and puzzles are what burn people out at night.
The PagerDuty Incident Response guide’s “Being On-Call” chapter treats runbooks and escalation paths as core equipment of the on-call, not nice-to-haves.
Then standardize the machinery behind the alerts: one deployment path, one logging format, one dashboard layout per service.
Most of the weight of on-call is not the size of the system, it is the size of the system minus what is written down.
You do not control headcount this quarter, but you control this, and it compounds.
Split the Territory Instead of Stretching the People
#
If six people cannot hold the whole system, stop asking six people to hold the whole system.
Partition ownership into two or three areas, by product surface or by subsystem, and rotate on-call within an area.
The primary for another area becomes the escalation target when a page turns out to cross boundaries, which the incident review will catch and correct.
Figure 1: the split. Each area gets its own three-person rotation over half the services, and the other area’s primary is the escalation target.
A three-person rotation puts the pager on each engineer every three weeks instead of every six, for half the system.
But there is a trade-off: each area develops less cross coverage than one shared pool.
You mitigate it by pairing the secondary from a neighboring area on big changes, and by rotating engineers between areas every few quarters so knowledge diffuses.
Figure 2: the cadence trade-off side by side, and the deciding variable: how heavy a single shift is.
The reason the more frequent cadence is survivable is the one this article opened with: the pager arrives before your memory of the territory decays, and when it does arrive, the relearn covers four services instead of eight.
Figure 3: context freshness across the rotation cycle. The 6-week whole-system cycle crosses the action threshold before every shift; the 3-week half-system cycle refreshes before that happens.
Team Topologies makes the underlying principle explicit: team cognitive load is the limit on what a group can own, so territory should be handed out in proportion to absorption capacity.
Six people whose absorption capacity covers half the system are not underperforming, they are correctly reporting the size of the system.
There is a second benefit that matters for the hiring fight: if the system genuinely needs two rotations to be covered safely, you now have the strongest possible evidence for your headcount case, in the org’s own vocabulary.
Headcount requests die as complaints and survive as cost calculations.
Convert your measured pain into money: incident minutes multiplied by their revenue impact, engineer hours spent on re-entry ramps, and the replacement cost of an engineer who leaves, which Gallup puts at half to two times annual salary.
Attrition is the number that lands, because a burned-out on-call engineer does not just handle pages badly, they take their context with them when they quit.
Then present the ask as a trade-off management has to accept in writing, not a favor it has to grant.
With current staffing, one of three things happens: the team accepts a higher incident risk, the team accepts reduced coverage or slowed delivery, or the team gets help.
If management reads that page and still does nothing, the pain has been priced and accepted, and you should operate knowing that.
Operate knowing it means this: keep doing the work you unilaterally control, the alert pruning, the runbooks, the territory split, and decide for yourself how long the residual risk is worth absorbing with your own nights.
Export four weeks of paging data and compute the actionable ratio and re-entry cost.
Delete or downgrade every alert that is not a user-visible symptom needing judgment now.
Write a runbook for each of the top five recurring pages.
Propose two or three ownership areas with a rotation per area, and run it as an experiment for one cycle.
Put the one-page business case in front of management with an explicit accept-or-fix decision requested.
Headcount may well be the right answer eventually, but a rotation you made lighter and a case you made undeniable are the only two things you control this quarter.
Code review is a human-speed step inside a pipeline that now runs at machine speed.
I have gathered every reason I can find to abandon it in the age of agentic software development, and together they are stronger than any argument for keeping it.
I have argued pieces of this case before, in Rethinking Code Review in the Age of LLMs and The Future of Code Review.
This article puts every reason in one place, grouped by where it comes from: throughput, cognition, reliability, sociology, and safety, plus the reasons no reform can rescue the practice.
A coding agent is not autocomplete.
Autocomplete typed faster, and the human still wrote the code.
An agent takes a ticket, plans, edits across files, runs the tests, and opens a pull request, and it can do that several times a day, in parallel with other agents doing the same.
When generation becomes a machine-rate activity, every human-rate step downstream becomes the constraint, and per-diff human approval is that step.
Nothing else in the pipeline caps throughput the way review does.
The queue shows it: once you supervise enough agents, review items arrive faster than you can clear them, and the surplus waits on you.
1. Agents parallelized generation, and review is still serial.
An agent fleet works across worktrees at the same time.
Human review funnels all of that output through one reader at a time.
The step agents made parallel, review re-serializes.
2. The queue math guarantees collapse.
Review is a queue with an arrival rate and a service rate.
Agent output raises the arrival rate, and a human cannot raise the service rate by trying harder.
When arrivals exceed service, the queue grows without bound, and no amount of discipline fixes it (You Cannot Out-Review a Machine by Hand).
3. Review latency destroys the value of agent speed.
An agent that finishes in twenty minutes and waits a day for approval delivers in a day and twenty minutes.
The machine idles at the one station that cannot speed up.
Buying speed at the generation stage and giving it back at the approval stage is paying twice for nothing.
4. Review cost scales with output, and gate cost does not.
Every human review is rent, paid again on every pull request, forever.
A check in CI is built once, maintained occasionally, and runs on every change in between.
The more the agents produce, the more the rent costs, and the more a gate saves.
5. Mandatory review converts machine failure into human exhaustion.
A misconfigured agent can open hundreds of pull requests in an afternoon.
If every pull request needs a human, the agent’s failure mode consumes your entire week.
Rate-limit the pipeline, not the people reading it.
6. Human-in-the-loop approval pairs machine-rate generation with human-rate approval, and pays for both.
All-human development was internally consistent: people wrote at human speed and approved at human speed, so the pipeline was slow but never mismatched.
Fully autonomous development is consistent too: machines generate and gates approve, end to end.
Mandatory human review glues the two together: fast cheap generation upstream, slow expensive approval downstream.
The fast stage produces work that waits, and the slow stage spends senior attention clearing what waited.
You pay machine prices to produce and human prices to approve, and the pipeline still delivers at human pace.
7. Reviewing agent code is verification, not review.
Review works when reviewer and author share a mental model, so the reviewer can build on the author’s reasoning and ask what they meant.
An agent has no intent to consult, so the reviewer reconstructs meaning line by line, alone.
That is not review; that is re-deriving the code from scratch with extra steps.
8. Attention collapses exactly where agents guarantee volume.
Studies of real review practice put the useful band of a diff around two to four hundred changed lines, and effectiveness falls off sharply beyond it (SmartBear, “Best Kept Secrets of Peer Code Review”).
Agents produce volume, and volume guarantees you exceed the range where review stays effective.
The conditions that make review worth doing are the conditions agents make impossible.
9. The diff is the wrong unit of correctness.
Review inspects a slice of code.
Correctness is a property of the whole system: how the change behaves under load, against real data, alongside the other changes landing the same hour.
Staging and load tests approximate a few of those properties; production is where all of them show up at once.
10. Plausibility defeats skimming.
Agent code is trained on human code, so it looks like code.
It has the conventional structure, the familiar names, the confident test coverage.
A human skim pattern-matches “looks fine” and moves on.
The better the model gets, the less a skim finds, because skimming works by noticing oddity, and agents are optimized to minimize oddity.
11. Review comments no longer land anywhere.
With human authors, a review comment taught the author, and the lesson compounded over years.
An agent does not carry the lesson out of the pull request.
The loop that actually teaches the system is the specification and the test suite, so the comment is a cost with no memory.
13. Review is a sample; a gate is a census.
A human reads some of the lines, once, on one Tuesday.
A check runs on every line, on every run, for as long as the codebase exists.
When review finds an issue, the fix is one pull request; when a gate catches a class of issue, the fix is permanent.
14. A verdict that depends on the reviewer is not a verdict.
The same diff gets approved at 9 a.m. and rejected at 5 p.m., approved by one lead and nitpicked by another.
CI gives the same answer every time.
Process decisions that matter should not hinge on who had coffee.
15. The approve click produces the feeling of safety.
Most approvals are decided by CI status, author reputation, diff size, and the description, before the code is read (You Already Review Code Without Reading It).
The signature certifies that a person was present, not that the code was examined.
Feeling safe and being checked are different products, and review sells the first one.
16. Accountability theater allocates blame instead of preventing harm.
The approving signature exists so that, after an incident, someone can be pointed at.
In practice nobody blames the reviewer; they blame the author, the tests, or the process.
A mechanism whose output is blame allocation does not need to sit between your agents and production.
17. The social benefits had a human on both ends, and now they do not.
Mentoring juniors, building trust, sharing context, softening criticism: these justified review’s cost when two humans met at the diff.
An agent is not mentored by comments, does not build trust through diffs, and has no feelings to manage.
The functions that made review worth its cost had a human author as their subject, and the human author is gone.
18. Review is where bikeshedding lives.
Naming debates, brace placement, and abstraction preferences consume senior hours while the change waits.
When output is cheap to regenerate, nitpicking the diff is the wrong loop; improve the spec and regenerate instead.
Gates never argue about tabs.
19. Approval is a permission slip, and permission is the bottleneck.
What review actually gates is not quality but permission to merge.
When agents can produce the change in minutes, the scarce resource is the yes.
Queueing the yes is pure overhead: nothing is learned there, and little is checked that CI could not check.
20. Knowledge diffusion is the one real loss, and it has cheaper substitutes.
Review did spread awareness of the codebase, and I count that as the strongest argument for keeping it.
But the same awareness comes from spec review, design review, ownership docs, and rotation, where people learn decisions instead of skimming one diff.
Buy knowledge where it is cheap; do not price it in approvals.
21. Production is the ground truth review pretends to be.
Google’s SRE organization reports that 70% of outages are due to changes in a live system (Google, “Site Reliability Engineering”).
Most of those are configuration, data, load, and integration effects that no diff-reader can see.
Canary deployments, feature flags, monitoring, and tested rollback observe the real system instead of predicting it.
A reviewer guesses; a canary measures.
22. Reversibility beats pre-approval.
Making changes hard to make is one way to stay safe; making them cheap to undo is another.
Small, independent, backward-compatible changes with tested rollback paths cap the damage of any single mistake, including mistakes no reviewer would have caught.
An undo button outperforms a gatekeeper.
23. Skimming misses security; gates do not.
A tired reviewer scanning a diff will not spot a subtle injection or an import that quietly resolves to a lookalike public package.
Static analysis, dependency policy gates, and a dedicated adversarial agent hunting the change will, on every pull request, at machine speed.
24. If review is worth doing, delegate it to a system.
A reviewer agent reads the whole repository, never tires on the fourth diff, and when it finds a class of issue, writes the gate that catches that class forever.
An ad hoc human reviewer catches what they happen to notice, once.
Machine review at machine speed is the only review that scales with machine generation.
25. Every reform keeps the cost and shrinks the benefit.
Checklists, review SLAs, smaller pull requests, review budgets: each trims waste at the edges and preserves the ritual at the center.
The math is unchanged, because per-diff human attention cannot scale to machine-rate output.
Reforming review is spending effort to keep the bottleneck comfortable instead of removing the bottleneck.
26. The judgment moves upstream, where it always belonged.
Abandoning review does not mean abandoning scrutiny.
It means scrutinizing specifications, acceptance criteria, gates, and the small set of irreversible, trust-boundary changes that genuinely deserve slow human reading (The Merge Gate).
Review the intentions and the mechanisms; stop reviewing the output.
Measure the queue first.
Count agent pull requests arriving per day and the hours you actually spend reviewing.
If arrivals exceed service, you have already abandoned review; you just have not admitted it in policy.
Then make the default explicit.
Low blast radius changes merge on green: CI, gates, and the reviewer agent, no human click.
Reserve deliberate human reading for irreversible changes, security boundaries, and the gating system itself.
Convert every catch.
Each time review or production surfaces an issue, encode it as a check before moving on.
The list of checks is the review process you are actually running; the queue is just where its results used to wait.
Code review was the right process for software made at human speed.Agents ended that era, and the process should end with it.
When I work with a coding agent, most of the wall clock time goes to waiting.
The agent thinks and edits, I watch the spinner, then review the result, then queue the next task, and the whole loop runs serially all day.
The biggest speedup available in agentic coding is not a smarter model, it is running more of the work at the same time.
Almost every real codebase carries more independent work than one session can absorb: the bug in the parser, the new endpoint, the dependency upgrade, the flaky test.
The hard part is not spawning extra sessions, it is keeping them from conflicting with each other, and that is a git and workflow problem before it is an AI problem.
A single session is not literally a queue of length one, most harnesses let you queue or steer messages that the agent consumes at its own pace.
But a queued message is not parallel work: the session still executes its queue one item at a time, so task two waits while task one runs, and the agent waits while you review.
The model inside the session is not the constraint, the serialization is.
The progression I use goes from one branch with one task, to one branch with several non-colliding tasks, to one worktree per task, and finally to a pool of worktrees fed with more tasks than there are worktrees.
Shared branches are the cheap first step, git worktrees are the mechanism that makes concurrency safe once tasks start colliding, and an orchestrator is what you add when coordination itself outgrows your attention.
The progression I climb looks like this, one rung at a time:
The configuration you already run is one branch with one task and one session.
When your tasks provably cannot collide, the cheapest upgrade is to keep that single branch and add sessions to it, each working on separate files at the same time.
Nothing to merge, no duplicated environments, and the moment a session finishes, its work is already on the branch.
The failure modes are just as real: two agents editing the same file silently overwrite each other on disk, an agent’s context goes stale as files change under it, and simultaneous commits race on the git index.
Last writer wins, and nobody notices until tests fail for reasons neither change explains on its own.
Sharing a branch moves the isolation problem from the filesystem into your head, so only use it when the tasks provably do not touch the same files.
The rules that make it work:
Partition by module before spawning, and state each session’s file scope in its prompt.
Prefer additive tasks: new files, new endpoints, new tests rarely collide.
Have each session commit early and often, scoped to its own paths, and stagger commits so index operations do not race.
If two tasks genuinely need the same file, stop pretending and serialize them.
The decision rule I use has three tiers.
If two tasks share no file and no interface, they are trivially parallel, put them anywhere.
If they share an interface but not files, define the interface first, then parallelize.
If they share a file, serialize.
Most of the bad experiences people report with parallel agents are tier violations, not tool failures.
Sooner or later a shared-branch batch produces its first silent collision, and that is the signal to graduate to worktrees.
A git worktree gives you several working directories that share one repository.
Each worktree is a full checkout on its own branch, so two agents can edit, build, and run tests without ever seeing each other’s half-finished changes.
The command line story is short:
Point session one at ../myrepo-auth-fix, session two at ../myrepo-api, and they are fully isolated at the filesystem level.
git worktree list shows what is checked out where, and git worktree remove cleans up when a task lands.
Because all worktrees share the same object store, branches created in one are immediately visible in the others, and git only adds a little per-worktree metadata under .git/worktrees.
Worktrees are the default answer because isolation is what lets you stop thinking about collisions.
You stop rationing attention across “which files is the other agent touching” and spend it on the work instead.
Worktrees also outlive their first task: keep a pool of them and route the next task into whichever one just freed up, and you are running the final configuration, more tasks than worktrees.
The cost is environment duplication: each worktree needs its own node_modules or virtualenv, its own build artifacts, and its own port for a dev server.
I pay that cost by keeping environment setup scripted and boring, so a new worktree is ready in a minute, and by assigning port offsets per worktree.
If your setup takes an hour instead of a minute, fix that first, because a slow setup will kill the parallelism on its own.
The second cost arrives at integration: parallel work postpones conflicts instead of eliminating them, so keep the tasks on disjoint modules or the merge becomes the new bottleneck.
Add an Orchestrator When Coordination Becomes the Job
#
With two or three sessions, you can be the coordinator.
Past that, coordination starts eating the day you were trying to save, which is Amdahl’s law applied to your own attention: the serial fraction (decomposing, assigning, integrating, deciding) eventually caps the speedup no matter how many workers you spawn.
The fix is to promote coordination into a role, the orchestrator, and let it own four jobs.
It decomposes the goal into a task graph and marks what can run in parallel.
It assigns subtasks to worker sessions, each in its own worktree.
It enforces contracts between workers, and it integrates, merging finished branches in dependency order and resolving conflicts itself.
An orchestrator earns its place not by typing faster than the workers but by owning the contracts that make parallel work safe.
The contract step is the one people skip, and it is the one that matters.
Before any worker starts, the orchestrator writes down the interfaces the workers will build against: the API schema, the shared types, the module boundaries, the test contract.
Workers then develop against a fixed interface instead of against each other’s moving output, and integration becomes mechanical instead of investigative.
Pair this with critical-path thinking (the critical path method is the old, good version): start the longest task first, because parallelism cannot shorten the chain of dependent work.
You can be the orchestrator, run a dedicated session for it, or delegate it to a planning agent that fans out work and collects results, in the pattern I described in Scaling the LLM Agent Company.
I still orchestrate small batches myself, because writing the task graph is where the actual judgment lives, and judgment is the one input the cheaper workers around it cannot supply.
The failure mode to watch for is an orchestrator that decomposes badly: workers then block on each other, and you pay coordination cost for serial work.
Worktrees and orchestration are the structural moves, but several smaller changes compound with them.
Shorten the feedback loop first.
An agent iterates at the speed of your test suite, so a ten-minute suite turns every edit-test cycle into ten minutes, and no amount of parallelism fixes a slow loop.
Keep a fast test subset that agents run by default, parallelize the full suite, and make lint and typecheck instant.
Speed of iteration is a multiplier on every session you run.
Tell agents when to verify, not just how.
is the minimum baseline, and one that says when to run them is worth more.
Left unsupervised, a diligent agent runs the whole suite after every small edit, and on a large project that habit converts hours of work into waiting.
The instruction that pays is something like “make all your edits first, then run the full check suite once before you commit, and use targeted tests only while debugging a specific failure”.
Verification is a batch job at commit time, not a reflex after every change.
This is a pure instruction-file change: same commands, same rigor, a fraction of the wall clock time.
Write the context down once.
Every session that has to rediscover your conventions burns time you did not budget for.
A good AGENTS.md or equivalent, covering layout, conventions, commands, and the “never do this” list, turns that rediscovery into a file read, and better context also means fewer wrong turns per task (The Importance of Context When Interacting with LLMs).
Warm the environments.
Prebuild dependencies so a fresh worktree is functional in seconds: cached package installs, a devcontainer, or a declarative environment.
The parallel workflow dies quietly when every new checkout costs an hour of setup.
Route models by task.
Use the cheap, fast model for exploration, searching, and summarizing, and the strong model for design and edits.
An explorer session answering questions alongside a writer session doing edits is cheap parallelism that pays immediately.
Plan before you fan out.
Run a planning pass that produces the task graph before spawning workers.
A graph written up front is what makes fan-out fast and integration boring, and it is the artifact you review when something goes wrong.
Supervise asynchronously.
Do not watch every session.
Let them run to a blocker, checkpoint their state, and batch your decisions at fixed intervals, the pattern from Managing Many Concurrent LLM Agent Sessions.
Synchronous supervision caps you at one session no matter what git says is possible.
Watch the review gate.
Parallel agents outproduce your review capacity fast, and then review and integration become the wall (You Are the Bottleneck).
Budget for it: batch your reviews, review outcomes (tests, recordings, benchmarks) before diffs, and treat rising integration time as the signal that your task boundaries are too coarse.
Profile where the time actually goes.
Agent sessions write detailed logs by default, so the raw material for a time audit is already on your disk.
A tool like AgentsView indexes those session files from every harness into one local archive with usage, cost, and history analytics (my research note on agentsview covers the details).
Read the report the way you would read a profiler output: find the phases that consume the most wall clock time, then ask what instruction, script, or boundary would shrink the biggest one.
Long working phases point at slow test loops or oversized tasks, heavy token spend on easy work points at wrong model routing, and sessions that stall waiting for you point at supervision that should be more asynchronous.
Treat your agent workflow like a hot path in code: profile it, find the biggest cost, and cut that first.
The workflow improves the same way code does, by measuring before optimizing.
The techniques above are the baseline for a parallel workflow.
The ones below are bigger investments, and they pay off once the basics are routine and the profiling data tells you where the remaining time goes.
Race N attempts and keep the winner.
For tasks that are small but hard, run two or three attempts in parallel worktrees and keep the one that passes tests or benchmarks best, discarding the rest.
The losers cost tokens, the winner saves a debugging session.
A cheaper variant is session forking: at a real design decision, fork the session and try both options from the same context, then keep the branch with the better result.
Close the loop from CI back to the agent.
When a check fails after the agent commits, route the failure straight back to the authoring session, or to a fresh session seeded with the failure context, instead of queuing it for a human.
Batch the day’s failures into one repair pass so the full suite runs once for all of them.
The goal is a pipeline where a human only looks at changes that already pass everything.
Cascade models instead of routing them statically.
Start each task on the cheapest model that could plausibly succeed, and escalate to a stronger one only when a signal says it failed: tests red, low confidence, or a critic flag.
Static routing pays strong-model prices on every task, a cascade pays them only on the hard tail.
Make the codebase legible to agents.
Every convention an agent discovers by exploration is paid again by every session, so move conventions from documentation into mechanics: lint rules instead of style guides, generators instead of templates to copy, strict types instead of tribal knowledge.
Design module seams deliberately so that future parallel tasks touch disjoint files by construction.
A codebase machines can navigate without asking is the multiplier that applies to every session you will ever run.
Turn frequent operations into tools.
If every session hand-rolls the same shell commands to query the schema, run a migration, or deploy a preview, encode those operations once as CLI commands checked into the repo.
Prefer a plain CLI over agent-specific tool protocols: every harness already speaks shell, so a command written once works in every session, every worktree, and your own terminal too.
Share one code index across sessions.
A prebuilt index (LSP, ctags, or embeddings) lets sessions query the codebase instead of crawling it, and the index is built once and reused by every parallel session.
Exploration is often the largest single phase in an agent session, and a shared index attacks it directly.
Run a critic alongside every writer.
A reviewer agent that reads the writer’s diff as it lands catches most defects before the human gate, and you review its verdicts instead of every diff.
This is how you shrink the review wall without lowering the bar: the critic applies the checklist, the human applies judgment.
Eval your workflow like you eval models.
Keep a set of golden tasks for your repo, fix this bug, add this endpoint, with known-good outcomes, and score candidate models, prompts, and tools against them before adopting anything.
Adopting on vibes imports regressions silently, evals catch them before they cost you weeks.
Move the runtime off your machine.
Local parallelism caps out at your cores, your disk, and your patience, so run sessions in ephemeral cloud environments that can be snapshotted and restored, one warmed environment per session.
This buys isolation you cannot get locally: a session restored from a clean snapshot cannot be poisoned by another session’s half-installed dependencies.
Speculate on what comes next.
While work runs, an idle agent prefetches for the likely-next tasks: summarizing the module a task will touch, pre-building the target, drafting the context file.
When the task starts, its context is already warm, and the startup cost drops to near zero.
Everything above optimizes the machine side of the loop, and the machine side is the side getting cheaper fastest.
While models are slow and expensive, parallelizing them safely pays, which is what most of this article is for.
Follow the trajectory, though, and the serial fraction of the loop stops being the agent and becomes you.
The agent finishes a task in minutes, turns around, and waits, not for compute but for you to decide what it should do next.
Once that is the failure mode, worktrees, orchestrators, and cascades stop buying wall clock time, because the queue the agents pull from is your capacity to specify and decide, the exact shift The Shifting Bottleneck describes.
I treat the playbook above as advice for the current regime, and the part that survives is the part the machines cannot accelerate: knowing what is worth building and saying it precisely.
This week, pick three genuinely independent tasks on your codebase and run them concurrently, on your existing branch if they share no files, or one worktree per task if they do.
Time two things: the environment setup per worktree, and the integration at the end.
If setup dominates, script it until it does not.
If integration conflicts dominate, your tasks were not independent, and the fix is in how you draw task boundaries, not in the tools.
Once three concurrent sessions feel routine, write your first explicit contract before spawning workers on shared interfaces, and add an orchestrator only when coordinating them takes more of your day than deciding what they should build.
In my experience two to four concurrent sessions is the sweet spot for one person, and the binding constraint past that is never the model.
Adopt the advanced strategies one at a time, and only when your profiling data says the basics have stopped moving your wall clock number.
Trunk Based Development - the integration discipline that shared-branch and frequent-merge workflows sit on
Amdahl’s law - why the serial fraction (decomposition, integration, decisions) caps the speedup from adding agents
Critical path method - why the longest dependency chain, not the task count, sets the minimum wall clock time
Maurice Heumann, “235 Billion Tokens Later: Auditing What The AI Agents Really Did” - a session-log audit of a production multi-agent workflow that grounds the profiling advice, the cut-the-biggest-cost findings (idle waits, CI polling, redundant test runs), and the critic-agent claim that the reviewer’s model matters more than the worker’s
Planning a feature splits into two jobs: finding out what the questions are, and answering them in an order that lets each answer build on the one before it.
The two jobs reward opposite working modes, which is why running them as one activity fails.
When I planned linearly, writing the requirements first and the specification next, the questions surfaced late, after the artifacts they invalidated were already written.
The method I use now runs the two jobs as two distinct phases: I iterate on every artifact of a feature in parallel until the big questions surface, then I make one ordered forward pass that settles each file in the sequence the SDLC defines.
The two phases and the switch between them fit in one picture.
Everything I plan lives in a .sdlc/features/N-feature/ directory, one per feature.
A feature starts as a problem statement in its own file, because a feature whose problem cannot be written down is not ready to be designed.
Around that seed the directory grows into the full artifact set the SDLC skill defines: needs assessment, feasibility, requirements, specification, tests, and the rest.
A mature feature directory carries the full artifact set the SDLC templates define, needs assessment, requirements, existing solutions, codebase analysis, feasibility, specification, plan, tasks, tests, and a review findings file paired with each, one purpose per file.
On top of that standard set sit the files of my own that hold the directory together.
README.md is the overview of the feature and the guide to how the other files should be consumed, which makes it the entry point an agent reads first.
files-flow.md records which files depend on which in terms of content, and it matters enough to get its own section below.
Many files drift.
A decision that changes in the requirements silently invalidates everything downstream of it, and my memory is not a mechanism I trust to find all of it.
So every feature directory carries files-flow.md, a mermaid graph of how the files depend on each other in terms of content.
An edge from X to Y means Y’s content is derived from X’s content, and the rule the graph encodes is mechanical: when file X changes, every Y that depends on X gets re-verified against the new X.
The graph is documentation for me and a worklist for the agent at the same time, which is the only way a consistency rule survives contact with ten interlocking artifacts.
The first pass over a new feature directory is deliberately chaotic.
I write the problem statement, then jump into the requirements, the specification, and the component plans all at once, in whatever order the thinking wants to happen.
Writing a specification forces questions the requirements never answered, and writing a component plan forces questions the specification never answered, so working the files together is the fastest way to find the holes.
Iterating in parallel is a question-finding machine: the point is not to finish any file, it is to make every file betray what I do not know while the cheapest possible response is still to write the question down.
Within a few passes I have the list of risks and open questions that would otherwise have surfaced at implementation time, when each one costs an order of magnitude more to fix.
Once the large questions have answers, I switch modes.
The iteration stops and the forward pass starts: problem statement, then requirements, then specification, then the plans and tests, in the sequence the SDLC skill defines.
A colleague of mine pictures the sequence as a funnel that expands as clarity about what we are building accumulates.
The problem statement is the narrow end, and each artifact downstream widens it, requirements expanding the problem, the specification expanding the requirements, plans expanding the specification.
Walking the funnel in order works because each file gets finished before the next one begins, so every downstream file is written against an upstream that is stable rather than half-moved.
By the time the pass reaches the component plans, most of the content is transcription, because the hard decisions were made during the parallel phase.
The forward pass is cheap precisely because the parallel phase paid for it.
Linear planning discovers questions at the worst possible time, after the artifacts they invalidate exist.
Parallel-only iteration has the opposite failure: it keeps re-litigating every file and never converges.
The two-phase split gives each mode the job it is good at, and the switch between them is a deliberate decision, not a drift.
My rule for switching is simple: when another pass over the files stops producing new questions, the questions are found, and it is time to answer them in order.
None of this makes the order sacred, and an unknown piece of functionality is where I stay most open about how to work.
The instinct is to proceed methodically, but when an LLM can explore a design space in minutes, the smarter sequence is usually reversed: use the model first to identify the risks, surface the questions, and lay out the options, and only then backtrack and write the relevant documents in order.
Exploration is nearly free, so the failure mode to avoid is premature documentation, not wasted exploration.
Wikipedia, “Cron” - the time-based scheduler these loops run on
Git, “git-worktree” - the isolation mechanism that lets one agent per pull request work concurrently
