tomrochette.com

What I've built and what I need: August 2026

tom@tomrochette.com (Tom Rochette) — Sun, 04 Oct 2026 00:00:00 +0000

The headline this month was the product-side counterpart to the SDLC: a full PDLC skill set that carries an idea from discovery through measurement. August also realigned the verification skills around non-overlapping roles, added several new pipeline phases, and completed the ISO/IEC 25010 audit set. The month came to 61 commits, over 500 files changed, and 30 new skills.

What I Have Been Working On
#

Shipped the PDLC pipeline. This was last month’s open need, and it is now a self-contained product development lifecycle that wraps the engineering one. It covers discovery, validation, strategy, definition, launch, and measurement, with a proceed, pivot, or kill gate at every phase. PDLC is the only slash command; the 31 phase and cross-cutting sub-skills live under skills/pdlc/skills/ and the orchestrator loads them on demand. Artifacts live under .pdlc/, mirroring the .sdlc/ conventions: a shared reference file, a PDLC_DIR fallback, a state file, and a revision mode. Definition is the seam where the product work hands the settled what and why to SDLC. Two supporting skills came with it, create-roadmap and review-roadmap, and identify-feature-opportunities generates and ranks new ideas from the code surface.

Realigned the verification skills. validate-pr, verify-pr, and review-pr had overlapping mandates, so I split them into three questions: validate-pr asks whether the change builds the right product, verify-pr asks whether the product is built right using runtime proof, and review-pr judges code craft from static reading alone. The new review-requested-prs orchestrator runs the three across the PRs waiting on me and skips any step already done for the current commit using SHA markers. analyze-test-coverage became its own skill for reporting introduced tests, change coverage, and uncovered code, and review-pr-full chains the whole review into one pass.

Added SDLC phases and artifacts. A new validate-assumptions/review-assumption-validation phase collects the assumptions made during design, runs the cheapest experiment that could invalidate each risky one, and blocks implementation when an assumption fails. create-lifecycle/review-lifecycle document how a resource’s states, transitions, and retention change over time, and create-domain-model/review-domain-model became standalone so a domain can be understood before solutioning. create-project/review-project fill the context files for a new repository, and create-question/review-question record open questions with what they block. create-cli-design settles a feature’s command surface as a companion artifact to requirements. Generated artifacts carry a session_link so a reviewer can reopen the session that produced them, create-* auto-dispatches its review-* in a subagent, and outcome files list the artifacts a phase produced. A single HTML slide deck now presents the whole SDLC family.

Completed the ISO/IEC 25010 audit set. audit-sdlc is now the coordinator for the ISO/IEC 25010 quality model, with a mapping table from each characteristic to a skill. One skill now covers each remaining characteristic: functional suitability, performance efficiency, compatibility, usability, reliability, maintainability, and portability, alongside the existing security and observability audits.

Shipped general-purpose skills. devils-advocate argues the strongest case against an idea, plan, or decision before you commit. gh-stack manages stacked pull requests. post-slack-message posts or threads a Slack message. stakeholder-announcement drafts and posts infrastructure updates to stakeholder channels. agents-section-daily-refresh runs the daily curation of the agent-maintained section of this blog. sync-articles brings a batch of articles into conformance with the writing rules. handle-pr-author-feedback (renamed from handle-pr-feedback) verifies that an author’s new commits answer your review comments.

Gated GitHub writes and reworked tooling. A should-post-to-github script now gates every GitHub content write, and the PR skills default to not posting, so a comment or merge only happens when --post is passed. SDLC worktrees moved to /tmp/sdlc/<owner>/<repo>/<issue>, and ~/.sdlc/** and /tmp/sdlc/** are pre-approved in the agent CLI so unattended runs are not stopped by a prompt. Script references moved to ~/.agents/scripts/, the audit and find skills switched from grep to ripgrep, and CLAUDE.md and .claude were replaced by AGENTS.md and .agents across the library.

Tightened conventions. create-article now requires naming the referent rather than leaving a vague it, and the 2-5 link cap on its See also sections was removed.

What I Currently Need
#

I did not write this entry at the time, so I have no record of what I needed in August and am stating that plainly rather than reconstructing a list I cannot trust.

References
#

agents - the skill library where the PDLC pipeline, the verification realignment, and the audit set landed.
ISO/IEC 25010 - the quality model the audit skills now map one to one.
ghx - the GitHub CLI used across the review and feedback skills.

What I've built and what I need: September 2026

tom@tomrochette.com (Tom Rochette) — Sun, 04 Oct 2026 00:00:00 +0000

The headline this month was turning the review skills into a scheduled, mostly unattended loop, and building the first instrument for where my session time actually goes. September came to 58 commits, over 180 files changed, and 14 new skills. The measurement points straight at what I need next: to stop babysitting sessions.

What I Have Been Working On
#

Turned reviewing others’ PRs into a scheduled, mostly unattended loop. review-requested-prs now fetches every PR waiting on me in one GraphQL query, runs discovery in parallel, sorts the queue by blocking depth, and skips any step already done for the current commit. It also recovers dropped team review requests from notifications, and a readiness light beside each PR marks when it can be auto-approved. The new assess-pr-risk scores a PR’s risk and confidence to decide how deep the review goes, using only evidence it gathers itself. The reverse direction, handling feedback on my own PRs, is triage-pr-feedback plus a FastAPI dashboard that groups and sorts incoming comments so I can mark each one implement, decline, or defer. handle-pr-reviewer-feedback owns that contract and triage just delegates. handle-failing-pr-ci lists my PRs’ CI status and fixes failures in parallel. review-pr-full chains the whole review, now starting with test-coverage analysis and committing its assets alongside the report.

Pushed verification earlier, into implementation. refactor-implementation runs between implementation and review to introduce only the abstractions the change needs. create-implementation now checks coverage and adds characterization tests before it modifies code. propagate-changes replaced backpropagate-sdlc and stopped being one-directional: it rewrites dependents and questions the premises they rely on. The repo’s own rules now say to get a working feature first, before any lint or type check.

Built an instrument for where session time goes. llm-sessions-analyzer reads the agentsview sessions.db archive read-only and attributes the wall-clock span between consecutive messages to a category: coding, testing, linting, formatting, build, exploration, research, git, delegation. It reports a stacked bar, a per-category table, and a timeline in the terminal or as a self-contained, sortable HTML report. The point is to find where the time actually goes: whether I am waiting on a specific tool most of the day (test suites run too widely or too often, lint and type checks that cost more than they save, builds whose artifacts never get used), or simply waiting on the model to generate.

Added visualization and writing skills. create-svg-image and create-mermaid-visualization split diagram work out of create-article, which now delegates to them, records the agent sessions that contributed to a piece, and requires direct statements over loose prose.

Grew the general-purpose skill set. setup-agent-machine/sync-agent-machine turn a directory into an indexed machine context. search-existing-issues, select-issue, trace-issues, create-discussion, and prune-merged-worktrees cover the issue lifecycle. slack-resolve-threads and improve-sessions mine Slack threads and past sessions for follow-ups and reusable lessons. create-skill authors a new skill from the best existing examples.

Made concise communication a shared rule instead of a per-skill habit. communication-guidelines is the single place every skill reads before it writes text on my behalf, from GitHub comments to Slack messages and email. It sets one principle (lead with the point, cut every sentence that does not change what the reader knows or does) and concrete length ceilings per surface. This matters more as more of the output is machine-written, since a language model’s natural failure mode is padding and repetition.

Taught an agent to read a day of Slack and report what was decided. extract-colleague-decisions searches Slack for the messages a set of colleagues authored in a day, reads the full threads behind them, and pulls out the decisions each person made, plus who supported them, citing a permalink for each and filtering out the chatter. The judgment is the point: telling a decision from an acknowledgement is a reading task, not a keyword match, and a small Jev classifier buckets each message to speed that judgment up.

Added a memory file so sessions stop relearning the same lessons. AGENTS.md carries the durable rules, but not the decisions, conventions, and gotchas discovered mid-session that the next one should inherit. MEMORY.md holds those, a global one for cross-project lessons and one per project for repository facts. Every session reads both at the start and writes back what it learns. It stays narrow on purpose: only what a future session cannot cheaply rediscover from the repo, kept concise and nothing a near-term commit would invalidate.

Tightened conventions and tooling. banned-terms.txt is now the single source of truth for banned terms, and report file naming was normalized across the review skills. The library was cleaned of Claude Code and .claude references and the old slack-cached name. create-pr gained reviewer context comments via ghx and design decisions in the description, and create-pr-description now diffs against the PR base with gh instead of Graphite.

What I Currently Need
#

I need to stop babysitting sessions. Most of my supervision time goes to steering a running agent and catching when the original prompt or context was wrong. That is the wrong place for my attention to be. What I want is a run that goes from prompt to end-to-end tested and verified on its own, and I do not have it yet.

I need proof that is easy to consume and that proves real behavior. The verification I need at the end is not the model asserting success. It is evidence a human can skim quickly that the thing we expected to work actually works, not that the agent hallucinated it working. Closing this gap is what makes the first one possible: I can walk away only when I trust the proof.

I need to go from one session at a time to many. I want to explore solving problems at scale as a learning exercise, mostly in software engineering projects, on the hunch that a generic framework is hiding there. The tooling (loops, the scheduler, the gates), the trust (relying on CI and review), and the process (how work is scoped and handed off) all feel like part of the blocker, and the sessions analyzer is my first attempt to see which one to attack first.

I need the review pipeline to stay fast as I lean on it more. review-requested-prs and the other review skills call the GitHub API directly, and I want to route them through ghx as a caching layer so repeated runs reuse cached issues, PRs, and comments instead of refetching them. That should cut API calls, raise the cache hit rate, and keep the hourly loop cheap enough to run without thinking about it.

References
#

agents - the skill library where the review, implementation, and machine-context skills landed.
llm-sessions-analyzer - the tool built this month to measure where session time goes.
agentsview - the session archive llm-sessions-analyzer reads.
ghx - the GitHub CLI used across the review and feedback skills.

The Duplicate Issue Was Written in Chinese

tom@tomrochette.com (Tom Rochette) — Thu, 24 Sep 2026 00:00:00 +0000

This morning I hit a bug and asked my agent to file an issue for it. It came back with a stop sign instead. The exact bug had already been reported, a few hours earlier, in Chinese. The agent did the one thing a decade of keyword search never did for me: it read a Chinese bug report and knew it was mine.

The Bug and the Request
#

The app is OpenChamber 2.0.0. In Settings, under Web Search, every option failed the same way. I picked a search provider, a toast appeared saying “Couldn’t save the web search choice.”, and the selection rolled back. A typical bug report.

I typed what I knew to my agent: create an issue, the web search choice cannot be saved, it happens when switching the search provider. Notice what I did not do. I did not search GitHub first, and I did not open the source. I gave the agent a half-formed report and moved on, expecting it to handle the rest.

The Skill That Fired
#

The skill my agent runs when I ask it to file an issue starts with one instruction: search for duplicates before any codebase investigation. It followed the skill without being asked. One grep matched my words to the app’s own UI strings, and then it ran three GitHub searches: “web search provider”, “search provider save”, and “websearch settings”. The first returned four unrelated issues, and the second returned the Chinese report as its top result. The queries were plain English, and the hit was still a Chinese report. The report’s body made the connection: the Chinese reporter had listed the failing endpoint, /api/config/websearch, and the frontend store, useWebSearchStore, and English identifiers like those match an English query no matter what language surrounds them. Retrieval was never the hard part, because code identifiers are already language-neutral. The agent opened the thread, read the Chinese, and did the translating after the hit, not before.

The Match
#

The match was issue #3880, titled “[Bug] v2.0.0 网页搜索选择无法保存，切换任何选项都会报错” (“the web search selection cannot be saved, switching any option shows an error”). It had been filed by a reporter I had never interacted with, and its prose was written entirely in Chinese. Same component, same toast, same rollback on every option. The Chinese reporter had even done their own careful investigation of their machine and listed the API calls involved.

The agent read the full report, compared it against mine, and concluded it was an exact match. Then it stopped. No new issue was filed, and it told me why in plain terms: a duplicate already exists, so it did not create one. It went one step further, checked the current source to confirm the bug was still present, and corrected a wrong guess in the existing thread’s comments.

Why This Was New to Me
#

Duplicate detection was never bounded by retrieval, it was bounded by confirmation, and confirmation is reading. GitHub search matches strings, and it matches them in the issue body too. No English query matches the title 网页搜索选择无法保存, but the English identifiers in that report’s body match an English query fine. So a keyword search can surface a foreign-language report. What it cannot do is tell you the report is your bug, because judging the match means reading it. An English speaker looking at a Chinese-titled search result skips it or files anyway, and both paths end in a duplicate. I would have filed mine at exactly that step, not out of laziness, but because confirming the hit meant translating it by hand. The old workflow was not broken, it stopped one step short, and the step it stopped at was the language barrier.

The result in the old world is familiar to anyone who has maintained a project. The same bug arrives three times in three languages, a bilingual maintainer or a patient contributor eventually connects them, and the duplicates get merged weeks later, after the maintainers have already triaged each copy. The dedup always happened, but it happened on the maintainer’s time.

An LLM agent reads GitHub in any language it knows, Chinese as easily as English. The string search still does the retrieval, the reading does the confirmation, and both happen in the same minute of the same session. The dedup moves from the maintainer’s week to the reporter’s minute. The first useful thing my agent did that morning was refuse to do the work I asked for.

What to Do Next
#

If agents file issues for you, put duplicate-first at the top of the issue-filing skill, and make the language point explicit: tell the agent to treat translation as part of the search and to read candidate issues before dismissing them. A search that only matches your own language is a search that misses half the issues on GitHub. If your agent ever fails to catch a cross-language duplicate, check whether its search was string-bound.

If you maintain a project, expect the mirror image. Fewer copies of the same bug reach your queue, because the reporter’s agent catches them at filing time. The comments that still arrive can contain more than a symptom: an agent that finds an existing issue reads the thread, checks the current source, and can correct a wrong theory already in the thread, as mine did on #3880.

References
#

OpenChamber issue #3880 - the Chinese-language report my agent matched, including the reporter’s own investigation of the failing save.

Micromanagement Doesn't Scale, for People or for Agents

tom@tomrochette.com (Tom Rochette) — Wed, 23 Sep 2026 00:00:00 +0000

Watch someone run an LLM agent for the first time and you will often see a familiar figure: the manager who initials every form. Management science named that figure decades ago, identified the failure, and defined the fix, and all of that work still applies now that the workers are agents. Micromanagement does not scale, and the worker it fails first is the agent.

The Same Behavior in Two Bodies
#

Micromanagement is the management pattern where the supervisor keeps decision rights over small steps instead of delegating outcomes and constraints. On a human team you recognize it instantly: the manager who approves every purchase, sits in every meeting, and rewrites every email before it ships. With agents you recognize it just as fast: the operator who approves every tool call, watches the output stream live, interrupts to argue about which file to read, and rewrites the plan twice before the first task finishes. The behaviors map one to one across the two worlds:

Micromanaged employee	Micromanaged agent
Approves every expense, however small	Approves every tool call
Sits in on every meeting	Watches the output stream live
Rewrites every email before it ships	Corrects the plan mid-run
Demands a check-in before each step	Permission prompt on every command
Redoes the work at their own desk	Aborts the run and does it by hand

The mapping is not a loose analogy. In both cases one person decides every small step before it happens, which is a statement about workflow structure, not about trust. Anything true of that workflow for humans stays true when the executor is a model.

The Arithmetic Kills It First
#

Management’s own term for the limit is span of control: the number of reports one manager can effectively supervise. The limit exists because a supervisor’s attention is a fixed budget, and every decision escalated to the supervisor spends some of that budget. Step-level delegation makes the team’s throughput equal to the supervisor’s evaluation throughput, since every step now waits on one person.

Agents make the arithmetic harsher. One agent in a normal working hour issues on the order of two hundred small decisions in my sessions: which file to open, which command to run, whether a result is good enough to build on. A human evaluates meaningfully at one or two decisions per minute, and the quality of those evaluations collapses long before the count runs out. Step-level supervision has a span of control below one agent: you cannot fully micromanage even a single one.

The two supervision styles diverge as soon as more than one agent runs:

The fatigue has a known endpoint. Once approval prompts become more than attention can handle, people stop reading the prompts and start clicking allow, and step-level supervision ends in the failure of approving without reading, which You Are the Bottleneck works out in queue-math form.

The economics fail alongside the arithmetic. An approval-gated agent runs at your evaluation speed, not the model’s, so you gained machine-speed execution and then limited it to human speed. The reason to hire an agent was to break the link between your attention and the work’s progress. Step-gating restores the link at every tool call.

It Also Corrodes What It Touches
#

Throughput is only the first cost. Micromanaged employees show the classic learned helplessness pattern: initiative collapses, problems stay hidden until they become impossible to hide, and judgment never develops because it never gets exercised. The manager pays too: never observing unassisted results, the manager cannot learn which reports handle which autonomy, so the manager’s distrust is not based on any evidence.

Agents repeat all of that, at higher frequency. Constant interruption disrupts the agent’s context, output quality drops, and the quality drop seems to justify even closer supervision. An operator hurt by mid-run questions starts specifying work in tiny increments, which guarantees the agent never runs long enough to produce a reviewable outcome. I caught myself doing exactly that after one bad run, restricting the agent until it could barely fetch a file, and the restriction felt like diligence the whole time. And the operator never builds the one calibration that matters: which task types, which models, and which risk levels can run alone. That calibration is the core skill of working with agents, and it can only form from watching end-to-end outcomes, the exact observations micromanagement prevents. Micromanagement keeps the one activity that does not scale, per-step evaluation, and neglects the two that do, the worker’s initiative and the supervisor’s calibration.

Why Smart People Do It Anyway
#

The justifications transfer intact. The worker is unproven: the new hire has no track record yet, and neither does the model you have never run on this task type. A past failure weighs on the decision: the intern who dropped a production table, the agent that once deleted the wrong directory. The credit asymmetry points the same way: catching a small error early is visible credit, while an outcome failure arrives late and is blamed on you, so close supervision is individually rational at every moment even though it is collectively ruinous.

The deepest cause is unfinished specification. When the supervisor can state what finished work looks like, steps are safe to delegate, because the check exists at the end. When the supervisor cannot state it, steps are the only thing left to inspect. Most micromanagement is not a trust problem with the report; it is a missing definition of done on the supervisor’s side.

What Scales in Both Worlds
#

The fix is decades old and applies without changes. Management by objectives says define the outcome and the constraints, then let the report choose the steps; for an agent, that is the specification and the acceptance criteria, ideally the tests. Verify at boundaries instead of continuously: milestones for people, the pull request for agents. Situational leadership says match supervision to demonstrated maturity, directing at first and delegating later. Agents deserve the same schedule: a new model on a new task type gets a tight loop, a proven pattern on a reversible task gets autonomy. Make autonomy affordable by scoping the blast radius: the unproven report gets the cheap, reversible work, and the agent gets the sandbox and the throwaway branch, so a failure costs a review cycle instead of an incident. Then reinvest the freed supervision hours into the specification, which is the act that multiplies rather than the act that caps.

Every item on that list was worked out on human teams, at human speeds, over decades of trial and error. Agents run the same experiment with faster workers and cheaper failures. A group of agents is the cheapest management simulator ever built, and its first lesson is the oldest one: govern outcomes, not steps.

But My People Are Not Experts
#

The fix in the last section rests on delegation, and the first objection is always the same: the team is not staffed with world experts, just regular developers, and regular developers make mistakes. Agents make more of them. The objection is legitimate, and it still does not justify step-level control, because the step-level trade fails on its own arithmetic.

Start with what delegation actually assumes. Delegation does not assume competence; it is the only way to observe it. Span of control and situational leadership were worked out for ordinary people, and ordinary people make mistakes. A supervisor who never lets a regular developer run alone never learns what that developer can handle, so the supervision level never moves off maximum, and the cycle continues despite good intentions.

Then move the safety mechanism from the person to the system. Step-watching is one way to catch mistakes, and the most expensive one ever tried. Boundaries catch them for a fraction of the cost: tests, small pull requests, staging. Blast-radius limits make the ones that slip through reversible: feature flags, sandbox, rollback. Every mistake that recurs becomes a gate, which catches that class forever without spending supervisor attention. The gates compound; the watching never does.

When a mistake lands anyway, recalibrate instead of escalating. Classify the failure: a one-off gets absorbed, a knowledge gap gets training, a pattern gets encoded as a check. Then autonomy returns to where it was, because the system now catches that class instead of you. Blanket step-control after every failure is how one bad day becomes a permanent surveillance regime.

Run the numbers and the objection collapses. Suppose step-watching catches twice as many mistakes as boundary review at fifty times the cost. The trade collapses your span of control and manufactures learned helplessness, which raises the mistake rate it was meant to suppress. Boundary review wins even when it is worse per mistake, because you can afford to run it forever and improve it every week. The imperfect model gets the same answer: its mistakes justify tests, a sandbox, small reversible tasks, and promoting every observed failure class into a gate, never approval on every tool call.

What to Do Next
#

Count your interventions on your next agent run. Past a handful, the interruptions mark missing specification, not a failing agent, and each one belongs in the next prompt or the skill file (Say It Once covers the conversion).

Write the acceptance criteria before you launch anything. Every impulse to watch closely converts into a check: the test you would have eyeballed, the log line you would have watched, the property of the diff you would have scanned for.

Give one low-stakes task a fully unsupervised run and grade the outcome. That grade is your first calibration point, and calibration points are how you widen autonomy without guilt.

Widen autonomy the way you would with a junior: task type by task type, on evidence, never on faith. The manager who cannot say which reports run alone has been micromanaging, and the operator who cannot say which tasks run alone is in the same place. Micromanagement is not a personality quirk, it is a supervision policy, and it stops working the moment the worker outproduces the supervisor’s judgment. Your agents reached that threshold on day one.

References
#

Micromanagement - the named pattern and its documented costs on human teams
Span of control - the classical limit on how many reports one manager can supervise
Management by objectives - Drucker’s delegate-outcomes framing, the human-team version of spec plus acceptance criteria
Situational leadership theory - matching supervision level to the maturity of the report
Learned helplessness - what step-level control teaches the worker over time

How Much Attention Does This Pull Request Deserve?

tom@tomrochette.com (Tom Rochette) — Tue, 22 Sep 2026 00:00:00 +0000

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 question is never “is this pull request good” but “how much of my attention does it deserve”.

One verdict answers two different questions
#

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 depends 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 an automatic approval. 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.

Risk scores the change
#

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 scores the evidence
#

Confidence is not the reviewer’s subjective impression of 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 arrives, 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 arrives.

The routing table turns scores into attention
#

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 assigns a cost to 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 score routes the human, never the pipeline
#

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 combining 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.

What it looks like in practice
#

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 completes. Same rubric, three very different amounts of reviewer time.

What to do next
#

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.

References
#

agents skill library - where the assess-pr-risk rubric behind this article lives, alongside the two skills below.
review-pr-full skill - how the risk assessment runs concurrently with the review chain without gating it.
review-requested-prs skill - the fan-out that turns per-pull-request scores into a portfolio triage view.

My Agentic Schedule

tom@tomrochette.com (Tom Rochette) — Tue, 22 Sep 2026 00:00:00 +0000

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.

The trigger is the missing piece
#

An interactive agent session starts when I remember to start it. That ordering makes the work depend on 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 way of making the scheduler the trigger instead of me.

The waiting is the other 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 build up 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.)

The three hourly runs
#

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 depending on my memory.

Preparing other people’s code reviews
#

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. The run dispatches only the stale steps, 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.

Keeping my own CI green
#

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: the agent reruns transient failures, returns an unclear root cause to me as a written diagnosis instead of a guess, and stops after two failed fix attempts. My pull requests arrive green, or they arrive with an explanation of why they are not.

Drafting my replies to reviewer comments
#

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 processes 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 pipeline they share
#

The three runs look different from the outside, but they are the same pipeline with three different 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 is stored 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 keeps an hourly cadence inexpensive.

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.

What changed in practice
#

Review stopped being interrupt-driven: prepared material is ready before I start, and I pick the moment to start. The schedule 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.

What to Do Next
#

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.

References
#

Wikipedia, “Cron” - the time-based scheduler these loops run on
Wikipedia, “Idempotence” - the property that makes hourly re-runs quiet instead of expensive
Git, “git-worktree” - the isolation mechanism that lets one agent per pull request work concurrently

Agentic Maintenance at Scale: Best Practices for a Fleet of Repositories

tom@tomrochette.com (Tom Rochette) — Sun, 20 Sep 2026 00:00:00 +0000

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.

Every repository is a standing work order
#

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.

Automation does not read intent
#

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 it delivers 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 generates unneeded pull requests continuously. 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.

Archiving is the off switch
#

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 clear 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, the end of a project. That framing is what keeps dead repositories alive, because nobody wants to declare a project finished. When I finally ran this pass over my own fleet, most of the repositories went straight to the archive, and the guilt I felt 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

Write the policy where the agents will read it
#

Not everything belongs in the archive, and not everything active deserves full service. A library with actual 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 is 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 ranked below the top gets a note instead of a token budget. A sweep also sees what per-repository agents cannot: the same change suggested everywhere.

The same suggestion everywhere is one change
#

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 place.

Measure maintenance in tokens
#

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 goes unnoticed 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 uses 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.

What to Do Next
#

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, how often, 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.

References
#

GitHub Docs, “Archiving repositories” - the read-only semantics of archived repositories and the unarchive path, which ground the claim that archiving stops automated work
GitHub Docs, “Configuring Dependabot version updates” - the scheduling and per-ecosystem controls that encode maintenance tiers in the Dependabot config

Nine Months of LLM Agents on Large Projects

tom@tomrochette.com (Tom Rochette) — Sun, 20 Sep 2026 00:00:00 +0000

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 kept improving the whole time, and the improvements 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.

What the nine months covered
#

GitHub shows 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.

Challenge 1: Providing the Right Context
#

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 cannot see the knowledge outside that slice. 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 the session. 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 causes errors in 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 giving the session a question whose answer I know is 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 underlying principle is the one I keep applying, that context quality dominates model choice. Every session I launch inherits the preparation, and every session I under-provision costs steering time.

Challenge 2: Iterating Through Non-Obvious Design Decisions
#

The decisions that cause large projects to fail 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 list 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 overlooked, 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]

Challenge 3: Managing the Scale of the Work
#

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 natural 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 conflicts. 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 incomplete 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 propagates. 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 propagation 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.

What to Do Next
#

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.

References
#

METR, “Measuring AI Ability to Complete Long Software Tasks” - the reliability gap on long tasks that makes preparation and verification mandatory
Anthropic, “Effective Context Engineering for AI Agents” - attention budgets and just-in-time retrieval, the theory behind the context phase
git worktree - the isolation mechanism behind the parallel sessions

What Needs Updating When Agents Do the Work

tom@tomrochette.com (Tom Rochette) — Sat, 19 Sep 2026 00:00:00 +0000

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.

The Push Is Never Final
#

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 and inaccurate records describing it. 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.

A Graph of Artifacts, Not a Checklist
#

These stale records look like 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 Update Loop
#

The loop below shows the graph operating 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 step in this loop has an owner, and the default owner is the agent. Assigning any step 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 step handled by hand multiplies by the number of iterations, not the number of pull requests.

The Three Update Jobs
#

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.

Every comment gets a reply
#

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.

A CI failure is input, not a verdict
#

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 did not make.

The PR title and description follow the code
#

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 state what the diff does, and an agent that stops updating them is asking the reader to audit the diff to find out.

Where the Human Fits
#

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.

What to Do Next
#

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.

References
#

GitHub, “About GitHub Copilot cloud agent” - evidence that agent-driven changes with iterate-through-review cycles are shipped product behavior, not a personal experiment.

What a Senior Engineer Owes Their Reviewer

tom@tomrochette.com (Tom Rochette) — Sun, 13 Sep 2026 00:00:00 +0000

When a senior engineer opens a pull request, not reconstruct what it does. The standard is that everything that did not require a second person 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.

The Standard Expectations
#

Setting aside the 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 if seeing it for the first time 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 Cost of a Round Trip
#

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 actual 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 actual reviews backs the self-review obligation: in industrial code review, most comments ask for improvements and clarifications rather than catching actual 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 keep the queue from growing.

The Handoff Contract
#

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"]

Small, Single-Purpose Diffs
#

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. What distinguishes a senior engineer is knowing which kind of large diff they have, and saying so in the description.

Self-Review Before Anyone Else Reviews
#

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 work to do instead of a review request.

Proof That It Works
#

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 actual 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 respond to that with a request for changes.

After You Open It
#

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 leave a PR stuck in a stalemate.

When You Cannot Meet the Standard Yet
#

The standard has legitimate exceptions, and seniority shows in running the exception protocol instead of quietly lowering the standard. Sometimes the approach is still unsettled, sometimes a change cannot be split cleanly, and sometimes you need early feedback 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 that will be thrown away.
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 a request to do the author’s work.

Make the Standard the Default
#

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 enforce it:

A PR template with the four description questions already written out.
Format and lint gates in CI, so reformatting changes never reach a human-reviewed diff.
A draft-first habit: every PR starts as a draft and only moves 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 maintains this standard. 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 stops being followed. If you want to change how a team reviews, change what its most visible engineers ship.

What to Do Next
#

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 weaken; a standard encoded in the system keeps working even in 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 about honoring that contract.

What to Do When the Team Is Too Small and Hiring Is Frozen

tom@tomrochette.com (Tom Rochette) — Sun, 13 Sep 2026 00:00:00 +0000

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 option 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.

The Rotation Is a Relearning Machine
#

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 drives engineers to quit. A six-person full-system rotation where nobody feels capable of acting is not a staffing failure yet, it is a design failure.

Count the Pain Before You Name the Cure
#

Instrument the pain first, because adjectives do not persuade 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.

Shrink the Load the System Puts on People
#

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 weakening 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 forces the responder to work it out from scratch, and that is what causes burnout on night shifts. 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 what is written down, 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.

Escalate as a Business Case, Not a Complaint
#

Headcount requests fail as complaints and succeed 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 gets attention, 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.

What to Do Next
#

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.

References
#

Google SRE Book, “Being On-Call” - the standard that on-call quality is a designed property, including page load limits and post-shift recovery.
Google SRE Workbook, “On-Call” - operational guidance on balancing on-call burden across a team.
Google SRE Workbook, “Alerting on SLOs” - the criteria for what deserves a page versus a ticket.
PagerDuty Incident Response, “Being On-Call” - runbooks, escalation paths, and preparation as core on-call equipment.
Skelton and Pais, “Team Topologies” - team cognitive load as the limit on how much territory a team can own.
Gallup, “This Fixable Problem Costs U.S. Businesses $1 Trillion” - the half to two times salary figure for replacing an employee.

Abandoning Code Review in the Age of Agents

tom@tomrochette.com (Tom Rochette) — Sat, 12 Sep 2026 00:00:00 +0000

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.

What changed
#

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.

The throughput reasons
#

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 step 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 costs time 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 that review 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 joins the two: 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.

The cognitive reasons
#

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 actual 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 actual 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 that teaches nothing.

The reliability reasons
#

12. Defect finding was never review’s actual output. When Microsoft studied its own review process, only about fifteen percent of review comments related to defects, and most of those were minor (Czerwonka, Greiler, and Tilford, “Code Reviews Do Not Find Bugs”). The bulk of the value developers reported was code improvement and awareness, not bug catching (Bacchelli & Bird, “Expectations, Outcomes, and Challenges of Modern Code Review”). The one thing review is famous for is the thing it does least.

13. Review is a sample; a gate is a census. A human reads some of the lines, once, on a single day. 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 depend on the reviewer’s alertness.

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 things, and review delivers the first one.

16. Accountability theater allocates blame instead of preventing harm. The approving signature exists so that, after an incident, someone can be blamed. 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.

The sociology reasons
#

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 have opinions 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 approval. Queueing the approval is pure overhead: nothing is learned there, and little is checked that CI could not check.

20. Knowledge diffusion is the one genuine 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.

The safety reasons
#

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 live 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 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.

Why reform does not rescue it
#

25. Every reform keeps the cost and shrinks the benefit. Checklists, review SLAs, smaller pull requests, review budgets: each reduces minor waste and keeps the core practice. The math is unchanged, because per-diff human attention cannot scale to machine-rate output. Reforming review is spending effort to accommodate the bottleneck instead of removing it.

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.

What to do next
#

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-impact changes merge on a passing check: 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 reveals 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.

References
#

Wikipedia, “Code review” - the origin of formal review in Fagan’s inspections, a process designed for human authors.
SmartBear, “Best Kept Secrets of Peer Code Review” - the 200-400 line finding behind reason 8.
Czerwonka, Greiler, and Tilford, “Code Reviews Do Not Find Bugs” (ICSE 2015) - the measurement behind reason 12; only about fifteen percent of Microsoft review comments related to defects.
Bacchelli and Bird, “Expectations, Outcomes, and Challenges of Modern Code Review” (ICSE 2013) - what developers expect from review versus what it delivers.
Google, “Site Reliability Engineering” - the finding that 70% of outages come from changes in a live system, behind reason 21.
Latent Space, “Reviews Dead” - industry reporting on teams already dropping per-diff human review.

My Feature Planning Method: Iterate in Parallel, Then Pass Forward

tom@tomrochette.com (Tom Rochette) — Mon, 31 Aug 2026 00:00:00 +0000

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 work best in opposite 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 are shown in one picture.

The directory is the feature
#

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 problem statement 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.

files-flow.md turns consistency into a graph
#

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 holds across ten interlocking artifacts.

Phase one: iterate in parallel
#

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 goes. 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 gaps. Iterating in parallel finds questions: the point is not to finish any file, it is to make every file reveal 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.

Phase two: the forward pass
#

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 still changing. 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.

Why two phases instead of one
#

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 means the order is mandatory, 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.

What to Do Next
#

If you plan features as a pile of SDLC artifacts:

Start every feature directory with a problem statement file and a files-flow.md, before the requirements exist.
During discovery, write all the artifacts roughly and simultaneously instead of finishing them one at a time.
Treat “a full pass produces no new questions” as the signal to stop iterating and start the forward pass.
When any file changes, follow the files-flow edges and re-verify every dependent file before calling the change done.

References
#

SDLC skill - the pipeline whose artifact sequence the forward pass follows
Mermaid - the diagram syntax files-flow.md uses, readable by both humans and agents

Speeding Up LLM Work on a Single Codebase

tom@tomrochette.com (Tom Rochette) — Mon, 31 Aug 2026 00:00:00 +0000

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 production 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.

Why One Session Is the Slow Configuration
#

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:

Share a Branch When Tasks Cannot Collide
#

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 serious: 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 to manual coordination, 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, 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.

Isolate with Git Worktrees
#

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:

git worktree add ../myrepo-auth-fix -b auth-fix
git worktree add ../myrepo-api -b api-endpoint

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 prevent 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 taking the time 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 you 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.

More Ways to Buy Speed
#

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. Telling agents how to verify 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 breaks down 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.

Advanced Strategies
#

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 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 writes the same shell commands by hand 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 runs shell commands, 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 addresses 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 without measuring 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 affected by another session’s half-installed dependencies.

Speculate on what comes next. While work runs, an idle agent prefetches 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.

The Expiry Date on This Advice
#

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.

What to Do Next
#

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 best range 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.

References
#

git-worktree Documentation - the git mechanism behind isolated parallel checkouts
Claude Code: Common workflows - documents the parallel-sessions-with-worktrees practice as a mainstream workflow
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

Scaling Yourself Horizontally: Attention Does Not Scale, Leverage Does

tom@tomrochette.com (Tom Rochette) — Tue, 25 Aug 2026 00:00:00 +0000

Every engineer I know eventually reaches the same limit: the amount of valuable queued work exceeds the hours in a day. The instinct is to scale vertically, to work longer, read faster, and switch contexts harder. That direction has a hard ceiling, and the ceiling is low. When you cannot scale vertically, you scale horizontally: you build systems that do things for you. The resource everyone names as the unscalable one is attention, and I want to push on that claim, because attention is only half the story.

Scaling Vertically Ends Early
#

Scaling vertically means adding capacity to the node itself: more hours, more speed, more skill. The day has twenty-four hours, working memory holds a handful of items at once, and energy refills at a fixed rate. You can buy maybe two or three times more effective attention by sleeping properly and working in focused blocks, which is a genuine gain but constant-order. No amount of discipline buys a tenth of you. Vertical scaling tops out around a factor of two; everything past that has to come from replication.

Scaling horizontally means adding nodes instead of upgrading one. A node is a system that acts on your behalf while you are absent: a check, a script, a runbook, an agent, a colleague you taught. The question stops being “how do I do more” and becomes “what can act as me without me”.

A System Is a Decision Made Once
#

The obvious move is to automate tasks, the repetitive stuff. That is the low-grade version of scaling horizontally. What you are actually doing is building systems that make decisions you would otherwise make by hand, so that each decision gets made once instead of each time. A lint rule is a preference of yours, enforced on every change. A runbook is a decision procedure captured at the moment you understood the system best. A specification is your intent, written down once and executed against many times. An agent skill is a whole procedure of yours, replayable at any hour, in any number of instances. A colleague you coach is the most expensive system of all, the only one that eventually exceeds your judgment.

Andy Grove did the accounting decades ago in High Output Management: a manager’s output is the output of their organization plus the output under their influence. The same math applies to any engineer with systems. Your output is what you produce directly plus what your systems produce in your absence.

The leverage accounting, as I run it today, looks like this:

Building systems is an old set of options: teach, hire, document, automate. What changed is the cost of building one. Teaching a person takes months and produces one system that generalizes. Writing an agent skill takes an afternoon and produces unlimited instances that never generalize. Cheap narrow systems for procedures, expensive general ones for judgment, and the current challenge is knowing which decisions belong in a system and which must stay with you. The scheduled tasks in my own repositories already work this way: triage, review, and daily curation are systems built out of decisions I once made manually, and they run continuously.

The Most Expensive System
#

One item on that list behaves differently from all the others. A person you coach is the most expensive system to build and the only one that eventually exceeds your judgment. Every other system can only replay decisions you already made, so none of them can tell you that you are wrong.

The economics push the cheap layers toward machines. Teaching a machine your preferences takes an afternoon; teaching a person takes months. The rote layer of teaching, conventions, procedures, mechanics, migrates to machines for the same reason generation did: the cheap system wins on cost. What cannot migrate is the point of the expensive one. A person generalizes to situations you never saw, dissents when you are wrong, and eventually holds taste decisions in your place, and no skill file does any of the three. Teaching people does not disappear; it shifts from transferring procedures to growing judgment.

The risk runs the other direction. Judgment grows only through contact with actual problems, and apprenticeship was where most people got that contact. If everyone teaches machines their current preferences and nobody teaches people, the supply of judgment that the next generation of systems is built from depletes. Cheap systems consume the very apprenticeship that produces the general ones.

So Does Attention Scale or Not?
#

The claim I keep hearing, including from myself, is that attention is the only resource you cannot scale. Three answers, in increasing order of usefulness.

In quantity, no. The stock is fixed: one serial consciousness, a small working memory, a day that does not extend, and a decision process that handles one thing at a time (Attention Engineering covers what that means in practice).

In quality, slightly. Focus, sleep, and single-tasking produce a genuine multiplier over a frazzled baseline. That factor of two is worth claiming, and almost nobody has claimed it. But a constant is not a curve.

In leverage, without bound. Attention is the only resource you cannot scale in quantity, and the only one whose yield per unit is unbounded. A test attends so that you do not have to; verification substitutes for supervision. A check written once removes a minute of checking on every future use, forever. A system built this year raises the return on every hour of attention you will ever spend afterward. The attention itself does not compound. The artifacts do, and the artifacts all exist outside your head.

What never scales is the deciding itself. You can multiply what a moment of attention produces, but the moment of judgment, the taste call on whether a thing is good enough, stays serial and stays yours, which is the acceptance gap restated as a scaling law. So the precise version of the claim reads: attention does not scale, and that is exactly why the work is to stop spending attention on anything a system could check.

Scaling Horizontally Fails in Four Known Ways
#

Replication looks free, and its costs arrive later.

Systems drift. Every system is a snapshot of the decisions you made when you built it, and the world moves on. The runbook rots, the skill goes stale, the gate blocks a pattern that was bad two years ago and is idiomatic now. Someone has to tend the systems, and that someone is you, the maintenance burden The Codebase Gardener describes.

Errors correlate. A flaw in a system’s decisions repeats on every execution, in every instance, at once. A thousand agents running the same flawed instruction produce a thousand instances of the same mistake, which is why consistently wrong is a worse failure mode than inconsistently right (Scaling the LLM Agent Company). At that point you are not scaling your throughput; you are scaling your error surface.

The job converts. Scale horizontally far enough and you stop being the producer and become the governor of a system of producers. Attention moves from doing the work to reviewing outputs, pruning systems, and deciding what to build next. The constraint did not disappear; it moved up to you, the textbook behavior of a system under the theory of constraints. Govern badly and you reproduce your own mistakes at machine speed, faster than any hand-made error.

The source depletes. Your judgment is the raw material the systems are built from, and judgment regenerates only through contact with actual problems. Automate away all the doing and you cut off the supply of experience that made your systems worth building, the terminal worry of The Shifting Bottleneck. The systems are only as good as the freshest judgment that went into them, so a slice of attention must stay spent on hands-on work even when a system could do it.

Review the Result, Not the Change
#

Code review is where misallocated attention is easiest to see, so let me be specific about it. When a change arrives, the reflex is to open the diff and read the implementation. The question that deserves your attention is not what the change looks like but what it resulted in: the failing test that now passes, the before-and-after recording, the benchmark that moved, the error rate that dropped. The implementation is how the result was produced, and the how is increasingly the machine’s business.

Concretely, this means review discussions argue about outcomes: what the change does to behavior, to latency, to failure modes, to the rollback path. Style and implementation details are preferences, and preferences belong in the gates, where they run on every change instead of when a reviewer remembers to mention them (Verifying Code Without Reading It builds the full system). Read the diff itself only when the evidence is missing or the blast radius is large, the classification The Merge Gate argues for. And when the evidence is missing, treat that absence as the review finding, rather than reconstructing the answer by reading the code.

This is how one serial consciousness keeps up with many producers. You audit results and sample implementation, because the day you read every diff is the day the systems outproduce your review capacity (You Are the Bottleneck).

What to Do Next
#

Audit the last two weeks of your work and list every recurring manual action. Anything done three times or more is a system waiting to be built, and the order matters: gates and skills first, one-off scripts second, docs third, memory last, because the earlier items compound and memory does not last.

Prefer systems with an oracle. Automate the checkable, where correctness can be tested mechanically. The taste decisions, whether a thing is good enough or should exist at all, have no oracle and stay yours, so give them protected time on your calendar instead of letting reviewing more output crowd them out.

Spend the freed attention upstream, on specifications and on deciding what should exist at all, not on reviewing more output faster. That reallocation is the entire point of scaling horizontally, and You Are the Bottleneck is what happens when you skip it and let the systems outproduce your review capacity.

Keep a deliberate budget of attention that never gets handed to a system: the taste decisions, plus enough hands-on work to keep your judgment regenerating. You are protecting the source of future judgment, not being inefficient.

Then measure yourself in output per unit of attention, not in hours, tasks, or sessions spawned. The number that defines a scaling engineer is how much ships per hour of focused judgment.

You will never get more of yourself. What you can decide is how many systems run without you, how fresh their decisions stay, and what the one serial consciousness behind all of them spends its scarce attention on.

References
#

Andy Grove, “High Output Management” (Wikipedia) - the leverage accounting: your output includes everything your organization and your influence produce
Theory of constraints - why elevating a constraint moves it instead of removing it, the mechanism that turns a scaling engineer into a governor
Cognitive load - the research grounding why the quantity of attention is a fixed stock

The Apprentice Problem: Where Does New Judgment Come From?

tom@tomrochette.com (Tom Rochette) — Tue, 25 Aug 2026 00:00:00 +0000

Every senior engineer I know learned the same way: by doing junior work for years. The bug fixes, the small features, the boring refactors, the reviews where someone senior criticized their code in detail. That work was never just output. It was where judgment formed under supervision, with direct feedback, at low stakes. Automate the junior work and you do not just lose the output; you cut the input to the pipeline that produces senior engineers. Nobody announces this. The economics automate the junior work quietly, one task at a time.

How Judgment Actually Forms
#

Judgment is not transferred by explanation. It is grown by contact with consequences. The Dreyfus model of skill acquisition describes the path: novice, advanced beginner, competent, proficient, expert, where each step up comes less from rules learned and more from experience absorbed. The rules are the easy part. What separates a competent engineer from an expert one is the set of cases they have lived through, the bugs debugged at 2 a.m., the refactor that made things worse, the outage traced to a decision the engineer personally made.

Apprenticeship was never ceremony. It was how consequences reached the junior. A junior shipped a small change, the change broke something, and the feedback arrived fast enough to teach them something. Small scope, genuine stakes, tight loop. Deliberate practice works the same way in every field studied: repetition at the edge of ability, with immediate feedback, is the only known mechanism that builds expertise.

The loop the old apprenticeship closed looks like this:

flowchart TD
    X[Agent automates the junior work] -->|input cut| A[Junior ships a small change]
    A --> B[Change meets actual consequences]
    B --> C[Feedback arrives fast enough to teach them something]
    C --> D[Judgment gains another case]
    D -->|next task is a little harder| A

The junior work being automated is not adjacent to that mechanism. It is that mechanism.

The Economics Remove Exactly the Wrong Layer
#

The uncomfortable part is that automating junior work is correct, locally. When an agent fixes the small bug in an afternoon for cents, paying a junior to spend a week on it looks like charity. No single manager makes a bad decision. Every decision is rational, and the aggregate is a pipeline with its input cut.

The pattern is familiar from The Shifting Bottleneck: automate a layer, and the constraint moves up. But this time the constraint does not just move. It loses its supply, because the layer above is built from the layer below.

The danger is the delay. A pipeline with no input still ships output for years, from the inventory of already-formed senior engineers. By the time the shortage is visible in hiring metrics, the training has been gone for a decade. The apprentice problem is a slow-motion staffing crisis that no quarterly review will catch, because the seniors are still performing.

The Same Collapse, One Level Up
#

There is a structural precedent. Model collapse in code describes what happens when models train on their own output: the tails disappear first, the average looks fine, and the distribution narrows with each generation. An organization that stops training juniors runs the same loop on people. The seniors encode their judgment into systems and agents, the next engineers learn from those systems instead of from supervised contact with reality, and what they acquire is the smoothed average of their predecessors, rounded off a little more each generation. The rare cases, the exceptions, the reasons behind the rules are exactly what does not survive the transfer, and exactly what judgment was.

I am not claiming people are models. I am claiming the loop is the same structure: output consumed as input, without fresh contact with reality, degrades in the tails first.

What Replaces the Old Apprenticeship
#

The answer is not to ban agents from junior work, that battle is over and nostalgia is not a strategy. The answer is that apprenticeship has to become deliberate now that it is no longer incidental. Three moves cover most of it.

Make juniors the supervisors, not the supervised writers. There is still a large amount of work that needs a human mind: reviewing agent output, verifying claims against evidence, catching the plausible-and-wrong. Put the junior on that work, with a senior reading their verdicts. The feedback loop is just as tight, judging output and being judged on the judgment, and the skill being trained is the one that actually remains scarce. The new junior work is acceptance.

Reserve work for humans on purpose. A team that assigns every task to whichever worker is cheapest has decided, implicitly, not to grow anyone. Some tasks should be reserved for the person who would learn most from them, at a productivity cost the team accepts knowingly. Software engineering teams in the age of AI makes the general case for keeping friction that pays; this is the specific friction that pays in people.

Teach judgment directly, out loud. The old pipeline taught judgment through absorption, through years of proximity. The deliberate version is faster and demands more from seniors: decision reviews, where a junior predicts the call before hearing it; postmortems walked through live, not archived; the why behind every convention made explicit instead of encoded and forgotten. Encoding your judgment into a system, the move Scaling Yourself Horizontally argues for, and transferring it to a successor are not the same act, and only one of them renews the supply.

What to Do Next
#

If you run a team, trace one recent junior-level task end to end and ask who could do it next year for the first time. If the answer is nobody, because it will be automated, you have found a hole in the pipeline, and the fix is to route the learning part of that task somewhere it still exists.

If you are early in your career, stop competing with the machines on production and compete on acceptance. Build the record of catches, verdicts that proved correct, errors found in output everyone else approved. That record is the new seniority.

If you are senior, pick one person and start teaching out loud this month, decisions, not syntax. The foundations are a separate argument, and Learn the Foundation, Not the Syntax makes it, but foundations without direct consequences produce competence without judgment.

The question every organization is currently answering by default is: who is allowed to become senior next? Leaving that to the economics of task assignment is how the answer becomes nobody, slowly enough that no one notices until the last senior leaves.

References
#

Dreyfus model of skill acquisition - the novice-to-expert progression, where advancement comes from absorbed experience rather than rules
Deliberate practice - the research consensus that expertise builds through repetition at the edge of ability with immediate feedback
Apprenticeship - the historical delivery mechanism for learning through supervised practical work

Bus Factor One by Design

tom@tomrochette.com (Tom Rochette) — Sat, 22 Aug 2026 00:00:00 +0000

Consider a company where every system belongs to exactly one person. No colleague reviews their changes, no meeting brings anyone up to date on what they built, and no second person has the context needed to work on it. A few years ago that description would have been called negligence. Today people describe it as an efficiency proposal, because agents now do most of what colleagues used to contribute during implementation. The model can work, but only for companies that answer one question before adopting it: what happens when the owner goes on vacation, or quits?

Why Single-Owner Systems Are Coming
#

The economics of coordination changed before the model did. Brooks counted it in 1975: n people create n(n-1)/2 communication channels, and every channel adds a cost to alignment. When implementation was expensive, that cost produced reliability, because colleagues caught each other’s mistakes while catching up on context. Now agents produce the code and verification pipelines judge it, so human review of generated changes has become the least valuable step in the process, and the specification replaces the meeting as the unit of coordination. What remains of the channel cost is mostly expense.

Against that cost, a single owner provides three things that teams struggle to produce otherwise. Coherence, because one taste decides every abstraction instead of a committee averaging its members. Speed, because nothing waits on sync. Accountability, because when something breaks there is exactly one person who answers for it.

This is not hypothetical. A study of the Truck Factor, the minimum number of developers who must disappear before a project stalls, found many popular open source projects already sit at one. Critical infrastructure runs on bus factor one more often than any company would admit to running production that way. The difference is that companies now have an economic reason to stop pretending otherwise and a toolset for surviving it.

The Question Hides an Assumption
#

“What if nobody else knows the system?” assumes knowledge is stored in people’s memory. For most of software history it did, because writing it down served nobody’s daily work. Documentation went out of date because the only people able to maintain it were busy maintaining the system.

Agents change the cost of the alternative. Agents can now produce and refresh decision records, runbooks, architecture maps, and executable specifications continuously as a byproduct of the work itself. The agents that build the system keep its documentation current, the same way CI keeps tests green.

The metric stops being how many heads know the system and becomes how fast a competent outsider plus their agents can re-acquire it from artifacts alone. Call it re-acquisition time. Bus factor measured the redundancy of memory. Re-acquisition time measures the recoverability of understanding.

That inversion is why the model deserves serious consideration. A team of five who never write anything down can be harder to take over than a single owner whose repository documents itself, because five people holding unspoken context is still bus factor five, just less obvious.

How a Company Runs on Owners of One
#

The mechanisms are organizational, not technical.

Ownership is conditional on legibility. An owner keeps the system as long as it stays handover-ready without them. Definition of done includes the artifacts: tests written as specifications, decision records with alternatives considered, runbooks, an architecture map that reflects reality. Agents draft and refresh these continuously, so legibility stops being a chore and becomes a property of the pipeline. Think of it as source code escrow applied to understanding rather than code: the company holds the knowledge outside the person who operates it.

Vacations are load tests. Every owner takes a mandatory uninterrupted absence each year. During it, another engineer plus their agents must handle incidents and ship one scoped change using only the artifacts, with the owner unreachable. Score the takeover and publish the time it took. The drill is chaos engineering applied to the org chart: you inject failure into the ownership layer while the stakes are a minor feature, not a resignation letter.

Here is the drill written as a script:

sequenceDiagram
    participant C as Company
    participant O as Owner
    participant A as Artifact set
    participant S as Successor and agents
    C->>O: Mandatory uninterrupted absence begins
    O-->>C: Unreachable for the duration
    S->>A: Handle incidents and ship one scoped change
    A-->>S: Tests, decision records, runbooks, architecture map
    S-->>C: Scored takeover
    C->>C: Publish the re-acquisition time

Redundancy spend follows blast radius. Not every internal script deserves a second person. Classify systems by blast radius and cap how many revenue-critical systems may exceed a re-acquisition threshold, say two weeks. This is portfolio management: concentrate risk where you choose, hedge where loss would be unrecoverable, and know which is which.

Succession is scheduled, not emergent. Rotate owners on a cadence so every handover gets exercised while both parties still work there. For the few systems whose takeover would hurt most, name a shadow owner who runs the vacation drill against them quarterly. The handoff paragraph from Solo Is a Team Size (what the system is, why it exists, who inherits it) becomes a required field in the service registry rather than advice for solo operators.

Incentives reward survivable systems. Promotion criteria should include “your system passed your absence”, and managers should treat “only I can touch this” as a liability, not an advantage. The irreplaceable engineer is not an asset the company enjoys; it is concentrated risk the company funds. Pay people to make themselves unnecessary and indispensability stops being a career strategy.

What Still Does Not Transfer
#

Some knowledge does not become artifacts. Taste, the reasons the roadmap takes the direction it does, the history of a negotiation with a key customer: deliberation leaves traces but rarely conclusions.

Two habits keep more of it from escaping. Record rationale at decision time, while you still remember the alternatives, because a decision record written six months later will be inaccurate. Occasionally have the owner defend direction to a peer: not the code, the choices, so judgment gets exercised against a counterparty instead of remaining private to one person.

Then accept what remains. Some re-acquisition cost is irreducible, the same way some latency is. Budget it like depreciation rather than promising zero, and nobody gets surprised when a departure costs three weeks instead of none.

What to Do Next
#

Pick your most critical system and measure its re-acquisition time this month. Hand it to another competent engineer plus their agents with a scoped feature request and no access to the owner. Whatever number comes back is your actual exposure, and it is almost certainly larger than management believes.

Set thresholds by blast radius and drill vacations against everything above them. Change one line of promotion criteria to reward owners whose systems survive their absence. And when someone next argues a system needs a second person, ask whether they mean memory redundancy, which agents and artifacts now supply cheaply, or judgment redundancy, which only a second person supplies. The first is solved; budget for the second only where the stakes are directional.

A company can run on owners of one indefinitely. What it cannot survive is letting knowledge exist in only one place. People operate the systems, the artifacts are the asset, and the company’s job is to keep the asset independent of any operator, including the ones it wishes it could keep forever.

References
#

Guido Avelino et al., “A novel approach for estimating Truck Factor” - the empirical finding that many widely used projects already run at truck factor one
Bus factor (Wikipedia) - the classic formulation of the risk this model deliberately accepts
Source code escrow (Wikipedia) - the established practice of holding operational knowledge outside the operating party
Frederick Brooks, “The Mythical Man-Month” (Wikipedia) - the communication-channel math that made coordination expensive and single ownership attractive

Continuous Research: Deep Research on a Loop

tom@tomrochette.com (Tom Rochette) — Sat, 22 Aug 2026 00:00:00 +0000

Deep research agents changed who does the reading, not how often it happens. You type a question, the agent browses for up to half an hour, you receive a cited report. Then the world moves, and the report starts going stale on the day it was written. Ask the same question next month and the agent starts from zero, with no memory of what it already told you. The report was never the product. The product is a knowledge base that stays current, and the way to get one is to put research on a loop.

I call this continuous research: declare the topics you care about, schedule an agent to re-research them on a cadence, and let it maintain a versioned knowledge base whose updates you read like diffs. The human stops being the researcher and becomes the editor of a small research department that runs continuously.

The Report Is a Snapshot
#

The current wave of research agents is genuinely good at the finding part. ChatGPT’s Deep Research autonomously browses the web for five to thirty minutes per query and returns a structured, cited report. Claude’s Research runs multiple searches that build on each other and explores angles you did not ask for. A recent survey of deep research systems formalizes what these tools do into four components: query planning, information acquisition, memory management, and answer generation.

What the survey’s framing makes visible is where the continuity breaks. Query planning, acquisition, and generation all exist only inside a single run. The only component that could span runs, memory management, is scoped to the session. These products treat memory as scratch space for finishing one answer, not as the durable asset.

So the structure of the interaction is: one question in, one report out, everything forgotten. The run lengths are capped in minutes and the queries are metered by the month, because a long autonomous browse is expensive. The output is a document, and a document is a snapshot.

None of this is a flaw in the tools. It is a flaw in the unit of work. A report answers a question once, but most questions that matter to your work are recurring, and recurring questions deserve a maintained answer, not a fresh one every time.

What Continuous Research Is
#

The definition I use: continuous research is a scheduled agent loop that incrementally maintains a versioned knowledge base about topics you have declared, so that your current understanding is a system property rather than an activity.

Here is the loop as a machine:

flowchart LR
    TF[Topic file, written by you] --> L[Scheduled loop with a budget]
    CP[Checkpoint, the last researched date] --> L
    L -->|reads only the new material| U[Incremental update per run]
    U -->|advances the checkpoint| CP
    U --> KB[Versioned knowledge base]
    KB --> B[Brief, the current state]
    KB --> LG[Dated update log]
    KB --> SN[Source snapshots]
    B --> DG[Diff between versions, the weekly digest]

Four pieces, each of which already exists on its own.

The first is the topic file. One markdown file per topic stating the scope, the questions worth answering, the canonical sources, and what a meaningful change would look like. This is an editorial artifact, written by you, and it is the part that captures your judgment. It works the same way as a skill file: the judgment goes in a file, versioned, rather than in a prompt you retype.

The second is the loop. A schedule, a budget, and a skill that knows how to research one topic, in the format Loops as Files describes. The scheduling primitive is no longer exotic: coding agents can already be run on a schedule, and a GitHub Actions cron or an agent runtime does the rest.

The third is the incremental update. Each run advances a checkpoint, the last date the topic was researched, and the agent reads only what is new since that date. arXiv monitoring works exactly this way: fetch what appeared since the last processed date, summarize, advance the checkpoint. This is what separates continuous research from naively re-running a deep research query every week: the run is a delta against a base, not a rebuild from scratch.

The fourth is the knowledge base itself, which is the product the other three pieces serve.

The Knowledge Base Is the Product
#

A continuous research knowledge base is a directory per topic, in git, containing three kinds of files. A brief, rewritten each run, holding the current state of understanding. A log of dated updates, so the history of the topic is readable as a timeline. Snapshots of the sources, so every claim in the brief can be traced to the page it came from, even if that page moves or disappears.

The properties follow from the format. The brief answers “what is true now”, the log answers “what changed”, and the diff between the last two versions of the brief is your weekly digest, generated as a byproduct rather than assembled by hand. The git log of the knowledge base becomes the changelog of your own understanding.

I keep the research directories of this blog in this form, agent-written briefs with per-topic folders and source snapshots, and the pattern is the same one behind my public specification workspace, where a weekly drift check re-derives specifications for open-source projects I depend on from their upstream code and commits the diff. That workspace is a continuous research system applied to code repositories instead of the web, and it has worked well enough to recommend the pattern in general.

The comparison worth making is to continuous integration. A one-shot research report is a local build: correct at a moment, unverified the next day. Continuous research is CI for knowledge: the build runs on every tick, and breakage, meaning drift between your knowledge base and the world, shows up as a diff instead of as a surprise in a meeting.

The Wiki Half Already Exists
#

The LLM-maintained knowledge base now has a name and a following. Andrej Karpathy’s LLM Wiki idea file, published in April 2026, describes the same shift from deriving to maintaining: instead of a retrieval layer that reassembles knowledge from raw chunks on every question, the agent incrementally builds and maintains a persistent wiki of interlinked markdown pages. His architecture has three layers: immutable raw sources, an LLM-owned wiki, and a schema file that tells the agent the conventions to follow. The schema is my topic file under another name, and his append-only log matches the update log my knowledge base layout uses, which suggests these choices are convergent rather than arbitrary. The part of his framing worth keeping is the economics: humans abandon wikis because the maintenance burden grows faster than the value, and the LLM is the first maintainer that does not get bored. He traces the pattern back to Vannevar Bush’s Memex, where the unsolved part was exactly who would do the maintenance.

What the idea file leaves out is the schedule. The wiki’s operations run when you run them: you drop a source, the agent ingests it; you ask a question, the agent answers and files the answer back. The wiki compounds, but only when you give it new material. Continuous research is the same artifact with the human trigger removed: the loop finds the new sources on a schedule, advances the checkpoint, and ingest stops being a thing you remember to do.

The implementation side is converging too. llm-wiki, a plugin for Claude Code, Codex, and OpenCode built on the pattern, ships parallel research runs, a librarian pass that scores articles for staleness, and an audit that traces outputs back to raw sources. Even there the runs are invocation-driven: the librarian can tell you the wiki has gone stale, but a human still decides to refresh it, and watched-source variants are being worked out in the idea file’s comment thread. The wiki gives research a place to accumulate, and the loop gives it a reason to stay current; neither half works alone.

This Does Not Contradict Pull-Based Learning
#

In Keeping Up With AI Is a Losing Strategy I argued that you should consume information on demand, when an actual task requires it, instead of on a schedule driven by fear. Continuous research does not reverse that position. It removes the reason the position was painful.

The asymmetry that made keeping up impossible was that production compounds while your reading speed does not. Continuous research moves the consumption to a system whose reading speed does scale. The agent keeps up so that you can consume on demand.

Your behavior barely changes. When a task arrives that touches a topic you track, you open the brief and read the current state, prepared in advance by something that reads at machine speed. You are still pulling. What changed is that the thing you pull from is your curated, current base instead of the raw web on a deadline.

The reading you do take on is bounded and small: the weekly diff, a screen or two of what actually moved. That is a digest you would pay for, and here it is a free byproduct of the loop.

What Goes Wrong
#

The failure modes are the ones every autonomous system grows, plus one that is specific to durable documents.

A hallucination filed into the knowledge base is worse than one in a chat window. A wrong claim in a conversation scrolls away. A wrong claim in a maintained document accumulates authority every day it remains, and every later run that reads the brief inherits it. The defenses are mechanical: every claim carries a link, every link is verified by the run that writes it, sources are snapshotted, and anything you intend to act on gets spot-checked by you. OpenAI itself warns that deep research outputs hallucinate, and outside reviewers note that verifying a generated analysis can itself take hours; in a continuous system that verification is amortized across runs and spent on the diff, not the whole report.

Topic rot. A topic file written last year encodes last year’s questions. The tracker keeps diligently researching things you no longer care about, because a change in what you care about is not something the scheduler can detect. The defense is treating the topic list like a backlog: prune it on a schedule, and treat a brief you have not read the diff of in a month as a candidate for deletion.

Hoarding. A knowledge base that grows faster than you read it is a form of procrastination. The question to ask is blunt: what is the value of keeping a knowledge base whose content you never consume? None, because the value of the base is realized when you read it, not when the agent maintains it. An unread topic is all cost, compute, diff noise, and the illusion of being informed. If the diff sits unread for four consecutive weeks, the topic is not informing decisions and should be cut, exactly the discipline a reading funnel demands.

Cost runaway. An autonomous web-browsing loop on a timer can go from “it seemed useful” to a surprisingly large bill. The budget belongs in the loop’s frontmatter, with a cap on runs per day and cost per run, and the runtime should enforce it rather than warn about it. This is the same argument as the budget field in Loops as Files, with the stakes unchanged.

The Bottleneck Moves to Topic Selection
#

Once the finding, reading, and filing are automated, the constraint moves, in the way The Shifting Bottleneck describes for every other layer agents absorb. Deciding what to track becomes the bottleneck, and it is the most human layer of the whole stack.

A topic file is a small statement of identity: these are the questions I need current answers to, these are the sources I trust. That is editorial judgment, and it is the part that compounds. The agent will never be better than your topic file at knowing what matters to you, which means the file deserves the same care you would give a skill you plan to run for years.

The practical corollary: start with topics that inform decisions you actually make, where staleness has recently cost you something. Tracking “large language models” is unusably broad and will produce vague, generic output. Tracking “context window pricing across providers, monthly” produces a brief you will open before every infrastructure decision.

What to Do Next
#

Pick one topic that goes stale quickly and that an actual, recurring decision depends on. Write its topic file: scope, questions, canonical sources, and what a meaningful change looks like. Create the directory, with a brief, a log, and a snapshots folder, and seed the brief with one deep research run you verify by hand. Schedule a weekly loop with a budget, and have each run advance the checkpoint, update the brief, and commit the diff. Read only the diff.

Then leave it alone for a month. If the diffs were worth the minute they took to read, add the second topic. If they were not, the experiment cost you one directory and a few dollars of API spend, and you learned where your actual information needs are, more cheaply than any course could have taught you.

The goal is not a bigger pile of reports. The goal is never having to research anything from zero again.

References
#

ChatGPT Deep Research - what one-shot deep research concretely is: autonomous 5-30 minute browsing runs, monthly query quotas, and the vendor’s own hallucination warnings
Anthropic, “Claude takes research to new places” - the agentic multi-search, citation-backed research model, and its scope limits per query
Shi et al., “Deep Research: A Systematic Survey” - the four-component decomposition (planning, acquisition, memory, generation) that shows exactly where continuity is missing
Claude Code documentation, “Scheduled tasks” - evidence that the scheduling primitive for agent loops already ships in mainstream tooling
Karpathy, “LLM Wiki” - the idea file that named the artifact half of the pattern: compile knowledge once into an LLM-maintained wiki, plus the maintenance-economics argument
llm-wiki - a productionized version of the LLM Wiki pattern for Claude Code, Codex, and OpenCode, including the librarian staleness pass and provenance audit
Wikipedia, “Memex” - Vannevar Bush’s 1945 vision of a personal, curated knowledge store, the pattern’s oldest ancestor
arXiv usage statistics - the production side of the asymmetry: why one-shot research cannot keep up with the volume of new material

Solo Is a Team Size: When Humans Still Earn a Seat in the Agentic Era

tom@tomrochette.com (Tom Rochette) — Thu, 20 Aug 2026 00:00:00 +0000

One person directing a fleet of agents now produces more working software in a week than a small team produced a decade ago. Every alignment meeting, every argument about conventions, every wait for a review starts to look like pure overhead. The question I ask myself is whether working in a team still makes sense at all. The question assumes that going solo means leaving teams behind. It does not. A solo operator running a fleet of agents is already working in a team, one human and N machines, with assignments, reviews, conventions, and all the coordination that implies. The question is not team or no team. The question is when a human should fill a seat at that table.

Your Fleet Is Already a Team
#

What would I actually do all day if I went solo? I would write specifications, which are prompts, and delegate them, which is task assignment. I would review what comes back, request changes, and resolve conflicts between agents working on the same files. I would maintain conventions that every agent must follow and correct the ones that drift. That is not a person quietly coding alone. That is a team lead doing team lead work for a team that happens to be made of agents.

Now audit which functions this team already covers, and which have no seat assigned.

Execution is fully covered. Agents turn a specification into working changes, at any hour, at any scale. Give the fleet my worst idea and it returns that idea implemented fluently, with tests, in minutes. That is the fleet doing its job well; reviewing the idea was never its job. Direction would have a single seat, mine, and execution would treat whatever leaves that seat as settled, which is exactly what execution should do. The same property appears in prose, as What the Author Brings When the Model Writes observes: the model can produce anything, which is why the deciding is separate from the producing.

The reasons behind past decisions would live in one head, mine. The agents would hold exactly the conventions I encode, and the why would survive only if I wrote it down, which would make the whole operation one node until the records make it more. The node does not need to fail dramatically. The node just needs to take a vacation.

And the review of my own direction would run through the same head that chose it. My errors would pass my own review at a rate that should terrify anyone who has reread their own writing a day later.

The overhead I would escape by going solo is the delivery mechanism for direction review, shared memory, and second eyes. It would not disappear; it would convert into gaps that surface later and cost more.

Encode the Practices Before Adding Headcount
#

The first move is not to hire. The first move is to import the team practices that make any team function, because applied to a fleet they are what make solo work at scale.

Write the specification before the code, because the prompt is the source code, and the fleet executes the specification it is given, no more and no less. Encode conventions as gates and skill files that execute on every change instead of review comments that depend on someone remembering to say them, the move The Codebase Gardener argues for and Bringing Everyone to the Same Level describes as institutional memory that runs itself. Demand evidence with every delivery, a failing test turned green, a recording, a benchmark, so that acceptance stops being a matter of opinion and starts being a check, the contract You Are the Bottleneck asks of any fast producer. Write decisions down, one paragraph each, so the why survives outside your head.

A fleet with specs, gates, evidence, and records is a team with a functioning culture. Most of what made teams feel like overhead was the delivery cost of these four things, and agents let you pay that cost once, in code, instead of forever, in meetings.

When It Makes Sense to Be a Human Team
#

Now the original question can be asked precisely: when does a seat need a human?

Brooks made the accounting fifty years ago: n people create n(n-1)/2 communication channels, and every channel taxes alignment. The economics changed. An agent seat executes without needing alignment and pays no channel tax; a human seat pays the full tax and must contribute enough direction, memory, and accountability to cover it. A human seat has to earn its place against near-free, and it earns it in the three roles the fleet does not perform.

Three conditions cover most of the cases.

Here is how I now run the seat decision for every opening on the team:

flowchart TD
    S[A seat to fill] --> Q1{Does the work have an oracle}
    Q1 -->|yes, correctness is checkable| A[Agent seat]
    Q1 -->|no, it is judgment| H[Human seat]
    S --> Q2{Does the context fit in one head}
    Q2 -->|yes| A
    Q2 -->|no, the product outgrew one head| H
    S --> Q3{Are the stakes affordable and reversible}
    Q3 -->|yes| A
    Q3 -->|no, a one-way door| H

The work has no oracle. An agent can verify against a check: tests that pass, a spec that matches, a conflict with a mechanical resolution. When correctness is machine-checkable, fill the seat with an agent and not worry. When the work is direction, intent, or taste, when the question is whether the thing should exist, there is no oracle, only judgment. An agent executes the plan it is given; a human can question the plan itself. Who Resolves the Merge Conflict? draws the same line inside a single pull request: mechanical conflicts go to the bot, semantic ones need someone who holds intent.

The context exceeds one head. A product accumulates more surface than any single person holds, and past some size the single node becomes the constraint no matter how fast the fleet executes. A second head is replication: another copy of the why, the failure modes, and the customer reality, which is why the node can finally take a vacation. Below that size, the second head mostly duplicates what you already know, and the channel tax buys little.

The stakes need a counterparty. Some decisions are irreversible or expensive enough that one confident brain, machine-amplified, should not make them alone. A name beside yours on the decision is not ceremony; it is a second signature on the one-way doors, and it is also what accountability requires when something eventually breaks. Accountability is a role agents do not hold: an agent executes, and a person answers for what was decided.

Ownership has no seat. Add the three conditions together and the sum is ownership: deciding what the work is, remembering why it exists, and answering for it. In a company, ownership survives the owner: when someone is away or leaves, the work is reassigned, and someone else takes responsibility for keeping it functioning. The company is the container that keeps ownership continuous; individuals are stewards who hold it for a while and pass it on. A solo setup has no container. The owner and the person are the same thing, so absence does not reassign the work; it orphans it. The fleet keeps executing, patches, deploys, alerts handled, but execution is not ownership. A system can keep running and still be abandoned, because ownership means someone answers for it, and no agent holds that role.

The partial answers are all transfer artifacts. Decision records, runbooks, and specifications make the why inheritable, so a successor can pick the work up without the owner’s head. Opening the source turns the community into a container of last resort. Naming an inheritor, even informally, converts the orphan case into a handoff waiting to happen. None of these fully solves it. Ownership continuity for the solo operator is still an open problem, and pretending the fleet solves it is how systems get abandoned while they still appear to be working.

Notice what the seat decision does to hiring logic. Teams used to add humans for hands, and hands are now near-free, so the remaining reasons to add a human are direction, memory, and accountability. Google’s Project Aristotle found that the strongest predictor of human team effectiveness is psychological safety, which is precisely the capacity for dissent to occur. The finding reads as a warning here: a human seat without safety produces agreement instead of judgment, and agreement is a contribution the fleet already supplies. And the solo fleet is the limiting case, groupthink with an n of one, a team where dissent holds no seat at all.

The human team that remains is therefore small, three to five people owning a domain end to end as Software Engineering Teams in the Age of AI argues, but the staffing question inverts. Do not ask how much the candidate can produce. Ask where the candidate will disagree with you, and whether that disagreement will be right often enough to pay its channel tax.

What to Do Next
#

If you run a fleet, or are weighing one, audit it as a team this week. Trace the path your worst current idea would take through it, station by station, and count the places where the plan itself can be challenged. If the count is zero, you have found the gap, and it is in the design, not in the agents.

Then decide deliberately where judgment enters. If your work has an oracle, is reversible, and fits in one head, stay solo and stop feeling guilty about it; the fleet plus encoded process is genuinely a team. If any of the three conditions applies, no oracle, context overflow, one-way doors, buy a human seat in whatever dose makes sense: a paid reviewer for the consequential changes, a community that will tell you the idea is bad while it is still cheap to kill, a co-founder for the direction itself.

For everything you own, write the handoff paragraph: what it is, why it exists, who inherits it. The paragraph converts ownership from a property of your presence into an artifact, the same move as every other practice in this piece, and it is the closest thing solo work currently has to succession.

And if you build a team, staff it for the disagreements. You were never choosing between working alone and working with people; you were deciding, seat by seat, what each kind of worker is for. Agents are for the work. Humans are for the judgment that decides what the work is for.

References
#

Fred Brooks, “The Mythical Man-Month” (Wikipedia) - the channel-counting math that human seats must now pay for against agent seats that coordinate at near-zero cost
Google re:Work, “Guide: Understand team effectiveness” - Project Aristotle’s finding that psychological safety, the capacity for dissent, is the top predictor of team performance
Groupthink (Wikipedia) - what absent dissent does to group decisions, the dynamic a solo fleet embodies when no seat is assigned to it

Six Months with OpenChamber

tom@tomrochette.com (Tom Rochette) — Wed, 19 Aug 2026 00:00:00 +0000

OpenChamber 1.19.0 was released today, which makes this a good moment to look back. I have used it almost daily since February 8. Along the way I have opened 99 issues, and since April 16 I have had 29 pull requests merged. I am still using it every day not because it is polished, but because its core loop is worth the friction, and because when the friction gets bad enough, I can fix it myself.

What I use it for
#

OpenChamber is an app built around OpenCode: sessions, worktrees, chat, files, and terminals in one surface. I use a small part of it heavily. I run multiple agent sessions in parallel against the same repositories, and I let OpenChamber own the worktree management. Each session gets its own checkout and its own branch, and I control all of them from one place. Six months of this setup adds up to roughly 2,430 sessions across 61 projects, 54,000 messages, and 3.8 billion tokens, on models that moved from GLM 4.7 to GLM 5.3.

Because OpenChamber is always open, it also works as a scratchpad. When I have a thought, I switch to the right project, write down a few lines, and let a session work on it. The 99 issues I mentioned were mostly built that way: I describe the problem, and the session turns it into a detailed issue, sometimes with a follow-up comment containing code investigation. An idea that would otherwise have stayed a passing annoyance becomes an artifact, within minutes, inside the same window.

Input is also moving away from the keyboard. I use Handy, a speech-to-text tool, more and more to talk to the agent, which speeds up iteration. And sometimes talking to the agent is simply how the work continues while my hands are full, eating.

Iterating on ideas got a lot faster once trying a third approach meant spawning one more session instead of stashing and switching by hand. That single property is why I adopted OpenChamber and why I have not stopped. It is also the last part I would give up.

The reliability tax
#

The hardest part of these six months has been that the chat, the one component whose entire job is to hold a long-running conversation, was sometimes unreliable. The causes were varied. Sending a message to a session whose worktree was still being created blocked until the post-creation commands finished, so a message sent at the wrong moment just sat there. At other times the connection between OpenChamber and OpenCode dropped, and a few breakages were regressions in OpenCode itself that surfaced downstream in OpenChamber.

The text editor had its own stretch of problems. It glitched, and it regularly refused to open files it decided were outside the workspace or project, even when they were not. Both classes of problems got addressed over the months.

What still bothers me
#

My main gripe today is the terminal implementation. Terminal sessions end up closed on their own, which is exactly the failure mode a tool like this should never have, because a terminal holds state you cannot reconstruct. On Linux, opening the terminal sidebar sometimes shows nothing at all, and the workaround is creating another terminal.

The editing experience is my other daily friction. The early glitching got fixed, but typing and file navigation in the built-in editor remain clunky next to VS Code. OpenChamber also ships as a VS Code extension, which I have never tried, because the point of OpenChamber for me is steering agents from one surface, not working in two. The practical cost is that I keep an editor open to review diffs before commits and to look at code from time to time, which is exactly the habit I should be trying to break.

Two smaller issues have simply persisted for months. Project selection and filtering in dropdowns remain weak across the app. And the file matcher behind the @ helper is still very bad, which is annoying in a tool where pointing an agent at the right file is a core interaction.

Fixing it yourself changes the math
#

This is where the 29 pull requests matter. A bug in a closed tool blocks you: you file it, you wait, and meanwhile you work around it. A bug in an open tool you already run every day is just a task, and the more it bothers you, the sooner you prioritize it. My 99 issues and 29 merged pull requests are the same friction recorded twice, once as a complaint and once as a fix.

Merging is the part I control least. Getting a pull request adopted in the main repository sometimes takes considerable effort, and some of mine are still sitting open. Since I find those changes useful regardless, I maintain a local branch where I apply my unmerged pull requests and run ahead of upstream. The tool I use daily is therefore slightly my own build: official releases plus the fixes I was not willing to wait for. It is a small patch queue, the same idea as a distro carrying packages ahead of upstream, and it comes with the same obligation to rebase and drop patches once they land upstream.

The path a fix takes from annoyance to the build I actually run looks like this:

flowchart LR
    F[Friction in daily use] --> I[Issue filed]
    I --> P[Pull request opened]
    P -->|merged upstream| U[Official release]
    P -->|still open| B[Local patch branch]
    B -->|rebased and dropped once upstream lands| U

The relationship with the tool changes as well. I am no longer only a user deciding whether to stay or leave. I am a stakeholder: when a release like 1.19.0 ships with fixes from a handful of outside contributors, I read the notes looking for the parts of the app I care about. That is a much better position than complaining in an issue tracker.

Should you use it
#

If you run one agent at a time in a terminal, you probably do not need OpenChamber yet. If you juggle several agents against the same repositories, parallel sessions plus automatic worktree management alone justify the setup cost, and idea iteration gets visibly faster. Go in expecting it to be imperfect. Then check whether the problem that would bother you most is one you are willing to fix yourself, because that question decides what kind of experience you will have.

References
#

OpenChamber - the repository I have been using and contributing to
OpenChamber 1.19.0 release notes - the release that prompted this retrospective
OpenCode - the coding agent OpenChamber is built around
git worktree - the mechanism behind per-session isolation

You Are the Bottleneck: What to Do When Your Coworker's LLMs Outproduce Your Review

tom@tomrochette.com (Tom Rochette) — Wed, 19 Aug 2026 00:00:00 +0000

Your coworker opens pull requests faster than you can read them. Every morning the queue is longer than when you left. Their work accumulates behind your name, and everyone can see whose approval is missing. You are not the bottleneck. The process that routes every change through one human reader is the bottleneck, and no amount of reading faster will fix it.

The setup is now ordinary. More than one in five code reviews on GitHub already involve an agent, and a developer driving an LLM can open ten plausible pull requests in the time it takes you to properly review two. The gap between arrival and departure is not a temporary spike. The gap is the new steady state, and it needs a structural answer from both sides of the queue.

The Math Ends Badly on Its Own
#

Review is a queue. Changes arrive at your coworker’s production rate and leave at your review rate. When arrival exceeds service, the queue grows without bound, which is what happens to your inbox.

The failure is one queue with a single server:

The instinctive response is to raise your service rate: read faster, review longer hours, take fewer breaks. Queueing theory says why that response fails even when it works. Kingman’s formula says that waiting time grows with variability divided by spare capacity, so as your utilization approaches one hundred percent, waits increase nonlinearly. A reviewer at eighty percent capacity has a manageable queue. The same reviewer at ninety-seven percent, which is what “keeping up” actually demands, has waits measured in days. A process that only functions when you are never tired, never in a meeting, and never sick is not a process; it is a delayed failure.

There is a second failure that follows the first. An overloaded reviewer does not stop reviewing, the reviewer degrades first. You skim. You approve what the tests already cover. You rubber-stamp the fourth pull request of the evening. The queue does not just grow, it silently stops protecting anything, because code merged by a rubber stamp appears reviewed without being reviewed. Rubber-stamped merges are worse than a visible backlog: the backlog at least admits the work is not being checked.

The Reframe
#

The useful way to look at this is the theory of constraints. A system’s constraint sets its throughput, and the prescribed moves are to exploit the constraint (spend constraint time only on work only the constraint can do), elevate the constraint (add capacity or automation), and subordinate everything else to the constraint (upstream steps keep the constraint fed with work worth its time).

Read that list again with names attached. The constraint is you. Exploiting the constraint means your reading time goes only to changes that genuinely need human judgment. Elevating the constraint means automated gates absorb what does not need your eyes. Subordinating to the constraint means your coworker’s job changes: keep the queue full of cheap-to-judge, high-value changes instead of merely full.

Guilt is the wrong response to being the constraint, and so is heroics. Bottleneck is a role in a system, not a verdict on a person, and roles can be redesigned. The question stops being “how do I review faster” and becomes “what should be allowed to arrive at this queue at all, and how should the queue drain”.

What Your Coworker Should Do
#

When generation is cheap, producing more changes is trivial and producing mergeable changes is the actual work. Your coworker’s job is no longer to produce changes; the job is to produce changes that are cheap to say yes to.

Measure time-to-merge, not pull requests opened. A pull request that sits for a week is not output, it is inventory, and inventory that waits long enough turns into rebase conflicts and stale specs.

Concretely, every pull request should arrive with four things.

A specification written before the code. Acceptance criteria that existed before generation started, not a description reverse-engineered from the diff afterward. Reviewing a plan takes minutes; reviewing an unexplained implementation takes an hour, and the plan is where your disagreement is cheap.

Evidence that the change works. A failing test turned green by the fix, a before-and-after recording, a benchmark. A fix is not fixed until something independent of the model says so, which is the acceptance gap in miniature. Evidence converts your review from “verify by hand” to “check the verification”, and those tasks differ by an order of magnitude in cost.

An annotation of the risk. A self-review pass that flags the dangerous hunks, states the blast radius, and says which parts the coworker is unsure about. The risk annotation is the single most effective habit of the four, because it tells you where your scarce attention belongs and proves a human actually read the output before demanding that you do.

A summary that enables a thirty-second judgment. What changed, why, what could break, how to roll it back.

Beyond per-PR discipline, two structural commitments matter more.

Respect a work-in-progress limit. At most two or three open pull requests at a time. When the cap is reached, the surplus capacity goes to writing tests, improving gates, and refining the next spec, not to opening a fourth PR that will age out in the queue. The most productive use of a fast producer’s spare time is reducing the review burden itself: gates, encoded conventions, and tooling that make every future change cheaper to judge, not just the producer’s own.

Stay attached after merge. Bugs in generated code route back to the generator for a window of time, because the person who captured the benefit of fast production should carry the first round of the cost.

What You Should Do
#

Your side of the contract is to stop being a per-diff reader and become the designer of how the queue drains.

Classify instead of read. A README typo and a schema migration are both pull requests and do not need the same gate. Compute blast radius and reversibility per change, auto-merge the low-risk class on green, and hold only the risky minority for human eyes. The majority of what arrives is routine, and routine work is what machines are for.

Encode your recurring comments. Every review comment you have written more than twice is a gate you have not built yet. Complexity limits, dead code detection, coverage thresholds, forbidden dependency classes. Each encoded check is a category of attention you never spend again, and a category of queue pressure that disappears permanently.

Move your attention upstream. Review the spec before the code is generated, not the diff after. Ten minutes on a plan prevents an hour on a wrong implementation, and your disagreement lands while it still costs a conversation instead of a rework.

Match your coworker’s tools. Your coworker generates with a model; you triage with one. Running a first-pass review that flags anomalies, summarizes each diff, and ranks the queue by risk is not cheating, it is symmetrical. A pipeline where one side is machine-accelerated and the other is capped at human reading speed is broken by construction, whether the asymmetry is malicious or accidental.

Batch reviews into fixed windows. Two scheduled review blocks a day, instead of interrupt-driven approval sessions. Predictable service beats heroic bursts because Kingman’s formula punishes variability itself, and every interruption you remove shrinks the waits more than the raw time saved suggests.

Make the queue visible. Arrival rate versus service rate, time-to-merge, queue depth, on a dashboard both of you see. Numbers turn a feels-bad conversation (“you are slow”, “you flood me”) into an engineering conversation (“our arrival rate is triple our service rate, so we change one of them”).

What You Agree On Together
#

The fix is a contract, not a truce.

Define merge-ready: the checklist a pull request satisfies before it even enters your queue. Set the WIP limit at your sustainable service rate, and treat the limit as the throttle that keeps arrival below service. Agree on the escalation path for the small set of changes (the irreversible ones, the trust-boundary ones) that deserve synchronous human attention while your coworker waits. Agree on where surplus producer capacity goes when the queue is full, because idle generation capacity pointed at more PRs is how the problem restarts.

Then change what you both measure. The unit of team output is merged changes, not opened pull requests, and every metric that rewards opening over merging rebuilds the queue you just dismantled.

What to Do Next
#

Tomorrow, your coworker attaches the four things (spec, evidence, risk annotation, summary) to every new pull request, and you classify the existing backlog into auto-merge-gate versus needs-my-eyes, resolving nothing yet, just sorting.

This week, set the WIP limit and move your two most-repeated review comments into CI.

This month, make spec review the meeting that replaced diff review, and put time-to-merge on the dashboard next to queue depth.

The queue was never a verdict on how fast you read. The queue is a design decision your team made without noticing, and a decision made by accident can be made on purpose.

References
#

Kingman’s formula - the queueing result that explains why waits explode as utilization approaches one hundred percent
Theory of constraints - the exploit, elevate, subordinate framework applied to the reviewer as the constraint
Queueing theory - the general study of arrival and service rates, the model underneath the review queue
GitHub Blog, “Agent pull requests are everywhere” - the data showing agent-generated pull requests are already a large fraction of reviews

You Cannot Out-Review a Machine by Hand

tom@tomrochette.com (Tom Rochette) — Wed, 19 Aug 2026 00:00:00 +0000

A counterparty who uses LLMs to generate changes, documents, and requests has a throughput you cannot match by hand. If they then forbid you from using LLMs to review that same work, they have not raised the quality bar; they have rigged the queue. You will fall behind, and the falling behind is the point.

The Setup
#

The pattern is specific. On their side, a model drafts the pricing changes, the proposals, the redlines, the spec revisions, the follow-up questions, faster and in greater volume than any human would produce alone. On your side, the same work arrives as items to read, reconcile, and answer. And somewhere in the engagement letter, the process doc, or the spoken rule, there is a line: review must be human, no AI.

The asymmetry is not accidental. One side of the pipeline is unbounded. The other is capped at the speed of a single person reading.

The rigged pipeline looks like this:

The Math Is the Problem
#

Review is a queue. Items arrive at the producer’s production rate and leave at your review rate. If production rate exceeds review rate, which it must when one side uses a model and the other does not, the queue grows without bound.

The only tool that could lift your review rate to match is the one being banned. A model can triage a hundred documents, flag the three that matter, and summarize the rest in the time it takes you to open the first one. That is exactly the capacity the rule removes from your side. Forbid the reviewer’s LLM and you have not protected quality; you have guaranteed the reviewer cannot keep up.

This is not a question of effort or discipline. No amount of reading faster, working longer hours, or caring more will close a gap between a human’s reading speed and a machine’s generation speed. The two rates are different categories.

The Rule Is Never Applied to Production
#

Every time I ask what justifies the rule, I get the same reasons. Quality. Confidentiality. “I want an actual human looking at this.” Trust.

None of those reasons are applied to the producer. If quality required a human, the producer’s output would be human-written too. If confidentiality forbade a model, it would forbid the model on both sides. A rule that binds only the reviewer is not a rule about quality; it is a rule about leverage.

The giveaway is the asymmetry itself. A counterparty who genuinely believed human attention was the safeguard would insist on it for the work they send you, not only for the work you send back. When the standard runs in one direction, the standard is a tactic.

Flood Is an Old Tactic; LLMs Made It Cheap
#

Overwhelming a reviewer with volume is one of the oldest leverage moves in negotiation and review. Hide the clause in the volume, and exhaust the reader until they accept. It used to cost considerable effort to produce that volume, which capped the abuse.

LLMs removed the cap. Producing fifty variations, fifty justifications, and fifty follow-up questions now costs minutes and cents. The producer can flood at marginal cost while demanding the reviewer meet each item with marginal human effort. That is not a process; it is a denial-of-service on your attention, presented as a quality standard.

What Review Becomes on a Flood
#

Once the queue exceeds what a human can read carefully, the review degrades in one of two directions, and both favor the producer.

You triage, skimming for flags, and the unflagged majority passes unread. Or you tire, and you approve without checking. Either way, the work ships with less scrutiny than a smaller, human-paced batch would have received. The flood does not get reviewed more rigorously for being human-reviewed; it gets reviewed less, because humans have a finite attention budget and the producer is spending it for them.

The irony is precise. The rule meant to guarantee careful human review is the rule that guarantees there is not enough human attention to go around.

Push Back on the Symmetry
#

The fix is not to read faster. It is to refuse the asymmetric pipeline.

If they produce with a model, you triage with one, or the queue is illegitimate. Say it out loud, early, before the volume arrives. A review process is only fair when both sides have comparable tools on the queue.

Make the producer carry the cost of their own volume. Require a summary with every batch, written by them, stating what changed and what it means. Require structured, machine-checkable submissions instead of free-form documents. Cap the intake per day the way you would cap any rate-limited service. If the volume is genuine, the producer can absorb the cost of making it reviewable; if it is tactical, the requirement exposes the tactic.

And if the rule forbidding your LLM is non-negotiable, name it for what it is. It is a one-sided throttle, and agreeing to it is agreeing to lose on the schedule.

The Principle
#

Review is not a virtue test. It is a throughput match between two sides of a pipeline. Whoever sets the tooling asymmetry sets the outcome, and a reviewer forbidden the only tool that matches the production rate has already lost.

References
#

Information overload - the long-standing name for the underlying problem, here weaponized rather than accidental
Denial-of-service attack - grounds the metaphor: exhaust a finite resource (reviewer attention) by overwhelming it with cheap requests

Iterating on Agent Skills: The Loop That Keeps Them Improving

tom@tomrochette.com (Tom Rochette) — Sun, 16 Aug 2026 00:00:00 +0000

A skill file is not done when it ships. The first version of a SKILL.md is a hypothesis: that this sequence of steps, sent to a model, will produce the result you want. Hypotheses get tested every time the agent runs, and most hypotheses fail in small ways you only notice on the fifth or tenth run. A skill is a depreciating asset, and the only thing that keeps it paying off is a deliberate loop you run on it after it ships: notice the failure, explain what happened to a fresh agent session, iterate with the agent on a patch, verify the patch, and periodically shrink the whole library back down.

The rest of this piece is that loop, in the order I run it.

Why skills decay
#

Three forces pull at a skill from the day you write it, and any one of them is enough to make a good skill go stale.

The model changes underneath it. A skill that was necessary to spell out every step for last year’s model is over-specified for this year’s model, and the over-specification starts to fight the model instead of helping it.

The task drifts. The repo layout moves, the tool’s CLI changes, the team’s convention evolves, and the skill keeps calling the old path.

And your own understanding improves. Six months after writing the skill, you know a shorter, cleaner way to express the same instruction, but the file still holds the first, clunkier version.

A skill that nobody touches is a skill that is quietly getting worse, because the world around it is not standing still.

Keeping Up With AI Is a Losing Strategy makes the same argument about filters: the asset you built at the last model generation may be miscalibrated for the current generation, and you will not notice because the failure is silent. Skills fail silently the same way. The agent still produces output. The output is just a little more wrong, a little more verbose, a little more off, and you compensate for the drift in your head without ever writing the fix back into the file.

The loop
#

I run the same five-step loop on every skill, whether I noticed a failure today or I am doing a monthly sweep. The order matters, because each step is cheap only if the previous step ran.

My part of the loop is the noticing and the judgment. The diagnosing and the patching belong to the agent, and the split is the point: I explain, the agent analyzes, and the skill gets fixed without me becoming the bottleneck the loop exists to remove.

The cycle, and the split of labor inside it, looks like this.

flowchart LR
    S1[1. Notice the failure] -->|correction becomes a session| S2[2. Fresh session diagnoses]
    S2 -->|diagnosis picks the patch| S3[3. Iterate to a small patch]
    S3 -->|patch the skill, not the output| S4[4. Verify against the failed run]
    S4 -->|still failing| S1
    S4 -->|periodic sweep| S5[5. Shrink or delete]
    S5 -->|model catches up| S1

1. Notice the failure
#

A skill only improves when one of its failures gets explained, and most failures never get explained.

The default behavior after a bad run is to fix the output by hand, move on, and forget the skill was ever wrong. The hand fix is the failure mode, because the next run will produce the same bad output the same way, and you will apply another hand fix.

I do not keep failure notes, and I do not stop to work out what went wrong. When the agent produces something I have to correct, I open a new agent session and explain what happened: the bad output, what I expected instead, and which skill produced the run. The explanation is the whole capture. Explaining takes a minute, needs no template, and the session holds the failure so I do not have to remember it.

The rule is simple: if I had to correct the output, the skill has to hear about the correction.

The rule is the encoding loop from My AI Workflow turned outward. There, the rule was that every time I caught myself remembering to do something, the reminder became a skill. Here, the rule is that every time I catch myself correcting the agent, the correction becomes a session about the skill that produced the output. Both rules turn a private, forgettable moment into a durable, improvable artifact.

2. Explain it to a fresh session
#

The session has to be new, and the newness does useful work. The session that produced the bad output is the worst investigator of the bad output, because the agent in that session is attached to the reasoning that went wrong. A fresh session reads the skill the way a new maintainer would, with no stake in the run that failed.

My message states what happened, not why. The bad output, what I expected instead, and anything about the run that surprised me. Then I let the session read the skill and tell me what went wrong, and the diagnosis lands on one of a handful of causes.

The skill was missing context the model needed. It referenced a file that was not in scope, or assumed a convention that was never stated.

The skill was over-specified. It pinned a step-by-step recipe that the current model does better on its own, and the pin is now producing worse output than letting go.

The skill was ambiguous. Two reasonable readings of the same instruction exist, and the model picked the wrong reading.

The skill called the wrong tool, or called the right tool the wrong way.

Or the failure was not the skill at all. The model was weaker than the skill assumed, the input was bad, or I asked for the wrong thing.

The diagnosis matters because each cause gets a different patch. Missing context gets added. Over-specification gets cut. Ambiguity gets rewritten with one clear reading. A wrong tool call gets corrected. And a failure that is not the skill’s fault gets parked, not patched, because editing a skill to compensate for a bad input is how skills accumulate defensive cruft they do not need.

Most skill decay is over-specification, not under-specification, and the instinct to add more instructions is usually wrong. The model is almost always more capable than the day the skill was written, and the smallest patch that fixes the failure class is very often a deletion.

3. Iterate to a patch
#

The agent writes the patch, and I iterate with the agent until the patch is right. My job in the session is judgment, not authorship: keep the patch aimed at the failure class, and keep the patch small.

The patch edits the SKILL.md, not the output.

The discipline is to patch the failure class, not the failing instance. A patch that fixes one bad run without addressing the kind of bad run is a patch that will be re-applied, in a different form, to the next bad run, and to the bad run after that. The skill accumulates special cases and never gets cleaner.

Each iteration should end with a smaller diff, not a bigger one. Add the one missing piece of context. Rewrite the one ambiguous sentence. Delete the step the model now does on its own. A small patch is easy to review and easy to revert if the patch makes things worse; a large patch that tries to fix the skill end to end is almost always a sign the diagnosis was incomplete.

The patch is also where the skill gets shorter, not just longer. If the session cannot make the failing skill better without also making the skill longer, the session is probably patching a symptom.

4. Verify
#

A patched skill is another hypothesis, and a hypothesis that is not tested is a guess.

The cheapest verification is to re-run the skill against the run that failed, and to read the new output for the specific problem the session was asked to fix. If the explanation captured the failure well, the check takes a minute.

For skills whose output can render, the pattern from Teach Your Agent Skills to Use Tools That Render is worth it here. A skill that emits a diagram, a table, or a diff is a skill I can verify by looking, and looking stays cheap when reading the prose would take too long. A skill that emits only paragraphs is a skill I can only verify by reading, and reading is the bottleneck that started the whole problem.

For skills that touch code, the verification runs the project’s own checks. The linter, the type checker, the test suite. The skill does not need its own separate verification when the repository already runs these checks, the same way The Codebase Gardener leans on objective signals from the tools rather than on a human re-reading every diff.

A skill without a verification step is a skill that drifts back to broken the moment you stop looking.

5. Shrink or delete
#

Shrink-or-delete is the step most people skip, and also the step that matters most over the long run.

Every skill is a bet that the model cannot do the task reliably on its own. The models keep getting better. The bet that was correct when the skill was written is incorrect now for some percentage of the library, and that percentage grows every model generation.

When a skill’s failures have stopped, and the agent produces the right output from a prompt alone, the skill no longer justifies the cost of keeping it. The skill is scaffolding around a capability the model now holds on its own, and the right move is to take the scaffolding down, not maintain the skill.

My AI Workflow makes the same argument: the skills are a temporary scaffold for the gap between what the model can do today and what the model will do on its own tomorrow, and a good chunk of the work is knowing which scaffold to take down next.

Shrinking applies within a single skill too. A step that the model now does reliably on its own is a step that should leave. An instruction that only existed to work around an old model limitation is an instruction whose time is up. A skill that has not been shortened in six months is almost certainly carrying unnecessary instructions from a weaker model generation.

Deletion is not loss. Deletion is the most positive outcome a skill can have, because deletion means the model now has the capability the skill was supporting.

The review sweep
#

One failure at a time is too slow a pace to keep a library healthy, the same way one pull request at a time is too slow a pace to keep a codebase clean.

I run a periodic sweep over the whole library, the same way The Codebase Gardener describes raking a codebase instead of chasing every leaf. The sweep is a small set of questions asked of every skill, not the deep rewrite of any one skill.

Which skills have I not edited in three months? Skills untouched for three months are the most likely to have decayed, because the world moved and the skill did not.

Which skills reference files, tools, or paths that no longer exist? Broken references are the cheapest bug to find and fix.

Which skills overlap with each other? Two skills that do almost the same thing should become one, because the duplication will drift and one will go stale while the other gets maintained.

Which skills did I not run at all this month? A skill that is never invoked is either redundant or forgotten, and both states are reasons to consider deletion.

Which skills did I run but correct every time? Skills that need correcting every run are the candidates for the next session.

A sweep takes an hour and its value lasts a quarter, because each finding is an iteration the per-failure loop would have taken months to surface.

Skills about skills
#

The loop has a recursive quality, because the compounding happens in the recursion.

The act of iterating on a skill is itself a repeatable task, and repeatable tasks become skills. I run a review-skills pass that does the sweep described above. I run an improve-skill pass that takes a single skill and proposes high-value, low-risk patches to the skill. The failure session from step 2 is the same move, held by hand: I supply the failure and the judgment, the agent supplies the analysis and the patch.

The recursion is the multiplier. Once the iteration loop is itself a skill, the library improves itself at the pace the agent can run, not the pace I can read. I still make the calls, because deciding which patch lands and which skill gets deleted is a judgment the model does not yet make well. But the amount I have to remember shrinks every time an iteration step is encoded, and the part I do myself narrows to the calls that genuinely need judgment.

The end state matches what The Self-Evolving Repository describes for codebases, applied one layer up: a library of skills that observes its own failures, proposes its own patches, and shrinks itself as the model grows, with the human left only at the checkpoint that needs taste.

What to Do Next
#

Pick one skill you have already run more than five times. Find the last run where you corrected the output. Open a new agent session, paste the bad output, and explain what you expected instead. You have just run steps 1 and 2 of the loop.

Then let the session read the skill and propose the diagnosis: missing context, over-specification, ambiguity, or the wrong tool call. Push the session until the patch is small and makes the skill shorter, and re-run the skill against the run that failed. You have just run steps 3 and 4.

If you cannot remember the last time a skill failed, you are either very lucky or, more likely, you have stopped noticing. Run a sweep instead. Open every skill, ask when the skill was last edited, and assume anything over three months old has decayed. You will be right more often than not.

And every quarter, ask which skills you can delete. The library that only grows is the library that is losing, because the library is carrying scaffolding for problems the model has already solved.

The goal is not a large library. The goal is a small library that is exactly the size of the gap between the model and the work, and a library that shrinks every time the model catches up.

References
#

tomzx/agents - the skills library this loop is run against, including the review-skills and improve-skill passes that operationalize the sweep and the patch
Agent Skills format - the open skill format that makes each skill small enough to iterate on independently

Anger Is a Tactic: How to Deal With People Who Use Aggression to Get Their Way

tom@tomrochette.com (Tom Rochette) — Sat, 15 Aug 2026 00:00:00 +0000

You know the person. The meeting gets tense, their voice rises, maybe a fist lands on the table, and within a minute the room gives in and they get their way. Later someone whispers “that’s just how they are” and the decision stands.

I never believed that framing. Temper at work is rarely just an emotional reaction, it is a negotiation move, and the research on it is unusually clear: it extracts concessions from people who cannot walk away, it destroys value everywhere else, and it collapses the moment the target stops cooperating. Once you see it as a tactic, dealing with it stops being therapy and becomes strategy.

The Outburst Is Making an Argument
#

Start with the finding that explains why the behavior persists: anger works, in the short term, on the people it is aimed at.

In a series of classic experiments, negotiators who were told their opponent was angry conceded more than negotiators who were told the opponent was happy (Van Kleef, De Dreu & Manstead, 2004). The interesting part is the mechanism. The targets were not scared into submission; they reasoned about it. They read the anger as information about the opponent’s limit, concluded the opponent would not move, and adjusted their demands to avoid impasse. Related experiments found that angry negotiators win larger concessions from their counterparts (Sinaceur & Tiedens, 2006).

The mechanism is a single inference on the target’s side, and that inference stops working under one condition:

Anger also buys status. Across four studies, people who expressed anger were judged more competent than people who expressed sadness, and observers conferred higher status and even higher salary offers on them (Tiedens, 2001). We read anger as confidence, and we promote what reads as confidence.

So the person yelling in the meeting is using a tactic that has worked for years: volume signals a hard limit, the limit signals competence, and everyone else absorbs the cost of avoiding the fight. Expecting them to stop out of politeness is expecting them to abandon a winning move.

Where the Tactic Stops Working
#

The same literature that shows anger working also shows precisely where it fails, and the boundary matters more than the effect.

First, the signal only works while the behavior is consistent with it. In the 2004 experiments, when the “angry” opponent started making large concessions, the effect vanished; targets stopped trusting the display and went back to their own numbers (Van Kleef et al., 2004). Anger is an argument about a limit, and any behavior that contradicts the argument wins.

Second, the tactic depends on who is receiving the anger. When researchers pitted anger against power, low-power participants conceded to an angry adversary regardless of whether the anger was appropriate, but high-power participants confronted with inappropriate anger retaliated and demanded more, not less (Van Kleef & Côté, 2007). Anger extracts value downward and invites punishment sideways or upward.

Third, field data from hundreds of actual online dispute mediations found that anger expression lowered resolution rates overall, in significant part because it triggered angry responses from the other party; only when the counterpart was especially vulnerable did the anger fail to hurt the expresser’s outcome (Friedman et al., 2004). In relationships that continue past the transaction, anger mostly burns the expresser.

And the flow is almost entirely one-directional. Sutton summarizes the frequency data in The No Asshole Rule: perceived nastiness is estimated to run downward (boss to subordinate) in 50 to 80 percent of workplace occurrences, versus roughly 1 percent upward. Interview studies of workplace anger episodes found the same asymmetry from the other side: subordinates were the least likely to confront the target of their anger and the most likely to consider the incident unresolved (Fitness, 2000).

Aggression depends on a power difference and on the target’s silence, which is why the people who use it are so often leaders and so rarely peers.

The Hidden Cost
#

The defense of these people is always the same: they get results. The research says those results carry costs nobody tracks.

The founding study of abusive supervision followed 712 employees and found that those who perceived their supervisor as abusive were more likely to quit, and the ones who stayed showed lower job and life satisfaction, lower commitment, and depressed perceptions of justice (Tepper, 2000). Fifteen-plus years of follow-up research, synthesized in Tepper’s Annual Review, established the pattern as one of the most robust in organizational psychology. The abuse also cascades: managers mistreated by their own bosses go on to mistreat their subordinates (Mawritz et al., 2012).

If you think that is soft-outcome stuff, the hard-outcome studies are worse. Researchers randomized 24 neonatal intensive care teams to either neutral comments or a few mildly rude remarks from a visiting “expert,” rudeness deliberately unrelated to the team’s actual performance. The rudeness-only teams’ diagnostic and procedural performance dropped significantly (2.6 vs 3.2 and 2.8 vs 3.3 on the judged scales), with rudeness alone explaining nearly 12 percent of performance variance. The cause was social: the teams stopped sharing information and asking each other for help (Riskin et al., 2015). A few sentences of mild rudeness measurably degraded how well expert teams saved babies, and the mediators were exactly the collaborative behaviors an angry leader suppresses.

Then the rudeness spreads. Witnessing rudeness makes people more likely to judge ambiguous behavior as rude and to behave rudely themselves (Foulk, Woolum & Erez, 2016). Witnesses of bullying report increased stress and fear of becoming targets (Sutton). Prevalence data suggests nearly everyone experiences incivility: across 14 years of polling, 98 percent of workers reported uncivil behavior, and by 2011 half reported being treated rudely at least weekly, up from a quarter in 1998 (Porath & Pearson, HBR).

The aggressor’s visible win is genuine, but it comes with losses nobody tracks in everyone else’s judgment, information flow, and retention.

Why They Do It
#

Two findings changed how I read these people.

The first is causal: power plus felt incompetence produces aggression. Across studies, people with power who doubted their own competence were the most aggressive toward subordinates, and competent subordinates were the preferred targets of their put-downs (Fast & Chen, 2009). The boss who lashes out at the strongest engineer in the room is often reacting to exactly that engineer’s competence.

The second is Sutton’s distinction between the temporary and the certified asshole: someone having a bad day versus someone “persistently nasty” who leaves targets oppressed and humiliated and aims at people less powerful (The No Asshole Rule). The distinction matters because the responses differ. A bad day deserves grace; a pattern will keep extracting concessions until someone raises the cost of using it.

Read aggression as information: it tells you the person’s other tools are insufficient for the situation, which is exactly why the tactic concentrates at the top, where it is tolerated, and among the insecure, where it is needed.

The Playbook
#

The research maps to a small number of concrete moves.

1. Separate the claim from the volume. The outburst is an argument that a limit has been reached. Answer the argument, not the volume: ask what specifically is unacceptable, what they need, and what would change their position. Asking those questions works because the mechanism is inference; when you engage the substance and your own behavior contradicts the “hard limit” reading, the display loses its informational value (Van Kleef et al., 2004).

2. Do not reciprocate. The field evidence is unambiguous that reciprocated anger is what destroys outcomes (Friedman et al., 2004). Matching their tone converts a solvable disagreement into a status fight, and status fights involving a leader have exactly one winner available. Stay slow, stay concrete, and let the asymmetry between your tone and theirs become visible to the room.

3. Name the behavior once it crosses the line. The dual threshold model of anger in organizations distinguishes an expression threshold (communicate rather than suppress) from an impropriety threshold (display that violates norms and starts doing damage) (Geddes & Callister, 2007). Functional anger sits between the thresholds; the person who pounds the table is past the second one. Naming it does not have to be dramatic: “I want to solve this, and I need you to lower your voice so we can” is a boundary, not an attack. The key is to do it early, because subordinates who swallow anger consistently rate their incidents unresolved, and unresolved incidents compound (Fitness, 2000).

4. Attack the dependency, not the person. Anger extracts concessions from those who cannot walk away and invites retaliation from those who can (Van Kleef & Côté, 2007; Friedman et al., 2004). The practical translation is simple: build alternatives. Document your contributions where others see them, cultivate sponsors outside your reporting line, keep your skills portable, keep your savings accessible. You do not need to quit to be less dependent; you need the aggressor’s threat model about you to weaken. Half the power of the tactic disappears the day they are no longer sure you would stay.

5. Contain the contagion. If you manage anyone exposed to the aggressor, protect their collaborative behavior deliberately. Debrief the incident, keep information flowing, and make help-seeking explicitly safe, because those are the first two things rudeness shuts down (Riskin et al., 2015; Foulk et al., 2016). Teams absorb an aggressor’s mood by default (Sy, Côté & Saavedra, 2005); somebody has to interrupt the absorption.

6. If you have organizational power, make it a firing matter. The strongest evidence-based organizational response is also the bluntest: refuse the trade. Netflix’s culture memo says it in one line: “No matter how brilliant someone may be, there’s no place in our Dream Team for people who don’t treat their colleagues with decency and respect” (Netflix culture memo). Sutton’s cost arithmetic (he calls it Total Cost of Assholes: HR hours, turnover, witnesses’ lost productivity, legal exposure; one executive’s estimate for a single engineer ran to about $160,000 a year) exists so leaders stop pricing these employees by output alone (The No Asshole Rule). And people must feel safe before anyone will name the problem: Google’s Project Aristotle found psychological safety the most important of the five dynamics separating its effective teams from the rest (Duhigg, “What Google Learned From Its Quest to Build the Perfect Team”). Psychological safety is precisely what a chronic aggressor destroys.

What to Do Next
#

Pick the next encounter and prepare one sentence for it. Something like “I will engage with the problem when we can discuss it calmly,” said once, neutrally, and then silence.

Inventory your dependency while calm: who else knows your work, how portable are your skills, how many months of runway do you have. The inventory is not defeatism; it converts you from a low-power target, the only kind this tactic works on, into a high-power one.

Write down the incidents, dates included. Patterns need data, and data is what turns “I feel uncomfortable” into a case a leader or HR can act on.

And if you have power over one of these people, stop asking whether they are worth the trouble and start computing what they cost; the research says the cost is much larger than their manager has ever seen.

References
#

Van Kleef, De Dreu & Manstead, “The Interpersonal Effects of Anger and Happiness in Negotiations” (2004) - the mechanism: targets concede to anger because they infer a tough limit
Van Kleef & Côté, “Expressing Anger in Conflict: When It Helps and When It Hurts” (2007) - the boundary: low-power targets concede, high-power targets retaliate against inappropriate anger
Friedman et al., “The Positive and Negative Effects of Anger on Dispute Resolution” (2004) - field evidence that reciprocated anger destroys resolution rates
Tiedens, “Anger and Advancement Versus Sadness and Subjugation” (2001) - anger reads as competence and earns status and salary
Sinaceur & Tiedens, “Get Mad and Get More Than Even” (2006) - angry negotiators win larger concessions
Tepper, “Consequences of Abusive Supervision” (2000) - the founding study of what abusive bosses do to retention, satisfaction, and commitment
Riskin et al., “The Impact of Rudeness on Medical Team Performance” (2015) - randomized evidence that mild rudeness degrades expert teams’ diagnostic and procedural performance
Foulk, Woolum & Erez, “Catching Rudeness Is Like Catching a Cold” (2016) - rudeness is contagious
Mawritz et al., “A Trickle-Down Model of Abusive Supervision” (2012) - abuse flows down the hierarchy
Fast & Chen, “When the Boss Feels Inadequate” (2009) - power plus felt incompetence predicts aggression toward competent subordinates
Geddes & Callister, “Crossing the Line(s): A Dual Threshold Model of Anger in Organizations” (2007) - the expression/impropriety threshold model used in the playbook
Fitness, “Anger in the Workplace” (2000) - interview evidence that subordinates suppress anger and leave incidents unresolved
Tepper, Simon & Park, “Abusive Supervision” (2017) - the 15-plus year synthesis of the abusive supervision literature
Sutton, The No Asshole Rule (2007) - the practitioner frame: recognition tests, certified vs temporary, and the Total Cost of Assholes
Porath & Pearson, “The Price of Incivility” (2013) - prevalence trend data on workplace incivility
Netflix culture memo - the reference policy rejecting brilliant people who fail the decency bar
Duhigg, “What Google Learned From Its Quest to Build the Perfect Team” (2016) - Project Aristotle: psychological safety was the most important of Google’s five team-effectiveness dynamics

Getting Noticed in the LLM Flood: Compete on What Cannot Be Generated

tom@tomrochette.com (Tom Rochette) — Fri, 14 Aug 2026 00:00:00 +0000

For most of the internet’s life, the rule was simple: make something good, put it somewhere findable, and the channels would handle the rest. That rule assumed a scarcity that no longer holds. When a model can draft a competent essay, tutorial, landing page, or thread in seconds, the supply of “good enough” writing goes effectively infinite, and good stops being the thing that gets you noticed. The scarce thing is no longer content but the trust that lets any single reader pick your work out of the flood.

The Flood Has Two Sides
#

A flood that is impossible to read is also a flood that is impossible to be read in. These are the same problem seen from opposite ends.

The reader’s version is a filtering problem: too much coming at you, too little time to sort it (see Keeping Up With AI Is a Losing Strategy). The maker’s version is a discovery problem: your work is one drop in a self-replenishing ocean, and the ocean refills faster than anyone can drink.

The root cause is identical. As Herbert Simon put it half a century before LLMs, “a wealth of information creates a poverty of attention.” What changed is that the wealth of information stopped requiring people to produce it, so the supply curve bent from steep to vertical. Attention did not scale with it. That leaves every creator competing for a fixed resource against a supply that has no ceiling.

“Good” Is Now the Floor
#

It used to mean something to publish clear, well-structured, useful writing, because producing it took time, skill, and effort, and that effort was itself a signal. When the median post can be generated in seconds and is, on the surface, as clean as anything a careful human would produce, clarity and structure stop signaling much. They become the default, the minimum readers expect and immediately forget.

This is Sturgeon’s law (“ninety percent of everything is crud”) at its extreme: not only is most content mediocre, but the mediocre is now polished enough to pass for good, which forces readers to assume everything is mediocre until proven otherwise. The practical effect is that competence no longer earns attention; it merely keeps the reader from leaving immediately. You cannot out-write the flood, because the flood is now competently written.

Compete on What Cannot Be Generated
#

If the surface layer is commoditized, the advantage moves to the layers a model cannot generate, and almost all of them are slow, specific, and human. Kevin Kelly named these the “generatives” in Better Than Free: the qualities that stay valuable precisely because copies are free. His list, written in 2008 about an earlier wave of abundance, maps almost perfectly onto the problem of being noticed now. Four of them do most of the work.

Authenticity is the sense that an actual, specific person made this for a reason they will stand behind. A model can imitate a voice, and even the surface texture of the life behind it: a recorded mistake, a hard-won opinion, a detail only someone who was there would notice. What it cannot provide is the underlying record that makes those details checkable, which is why authenticity has to be backed by proof rather than merely asserted (see Proof of Work, below).

Embodiment is the version of the work that exists in the physical, social world: a live talk, a conversation, a workshop, a thing you can point to in a room. It cannot be copied at all because it is not made of text, and it is where the strongest trust gets built.

Personalization is work tuned to a specific reader or community rather than aimed at everyone. The flood is generic by nature; anything that clearly was not, anything that names a particular reader’s problem in a particular context, stands out against it by contrast alone.

Findability is the quality most creators neglect, and the focus of this whole article. As Kelly wrote, “when there are millions of free things requesting our attention, being found is valuable.” In a flood, distribution is not the layer you add after the work is good; it is the work.

Proof of Work Is the Signal That Survives
#

If readers now assume competence is fake by default, the only thing that reliably reaches readers is evidence that an actual person did the thing behind the writing. Call it proof of work, borrowing a term from systems where trust is established by demonstrating costly effort rather than by asserting it (proof of work).

The tempting version of this claim is that the right story reads as authentic and therefore cannot be faked. That claim fails once models can fabricate the same story. A fabricated postmortem with specific-sounding numbers, a plausible failure chain, and the right tonal markers passes most readers’ filters, because few will check whether the project existed, whether the numbers are accurate, or whether the author lived it. The cost asymmetry the argument depends on, expensive to produce but cheap to verify, inverts: the story is now nearly free to generate, verification still costs actual effort, and readers rarely pay it.

What cannot be faked at scale is not the story but the record it claims to be based on. An actual project leaves a wide trail, commits, issues, deployed systems, other people who remember it, a history you can point to. The postmortem itself is cheap to hallucinate; the artifacts it references are not. The durable signal is not “does this read like lived experience” but “can I trace it to something independent of the author’s word,” and that is a harder bar than most writing clears.

The verification chain a claim has to survive looks like this.

That bar is why the familiar examples matter only when they are traceable. A postmortem of a project that failed, with concrete numbers and concrete reasons, matters if you can link the project, the commit that introduced the bug, the incident report. An experiment you actually ran, with setup and outcome, matters if the setup is reproducible and the data is there. A thing you built and genuinely use matters if the repository exists, has a history, and other people can run it. Strip the traceability and the same sentences are indistinguishable from hallucination. Proof of work is not a quality you can write into a paragraph; it is a verification surface you either leave behind or do not, and the cost that makes it trustworthy is paid in building that record, not in describing it.

Proof of work is the producer’s version of the moat argument elsewhere on this blog: when the easy-to-copy layer is free, the advantage relocates to the layers that compound through time and cannot be cloned (see Feature Parity Is Not a Moat). For a creator, those layers are a track record, a body of specific work, and the relationships built around it.

Be a Source, Not an Echo
#

Most generated content restates things other people already said, which means most of the flood is echo. The way to stop being part of the flood is to be the thing it is restating.

A source is someone who produces a fact, an observation, a measurement, an argument, or a story that did not exist in that form before they wrote it. An echo is everyone, human or machine, who restates it. The flood is almost entirely echo, which means even a small amount of genuine source material stands out clearly against it.

The method is to bias every piece toward the thing only you could have written: the result you observed, the mistake you made, the opinion you hold and can defend, the specific reader you are addressing. Narrow is better than broad here, because narrow allows specificity, and specificity is what an echo cannot manufacture. A durable body of narrow work also compounds: ten pieces on the same corner of a problem make you the primary source for that problem, where ten unrelated pieces make you another drop.

Relationships Are the Distribution Layer That Does Not Saturate
#

Every algorithmic channel is now full, and getting fuller, and the trend goes in one direction. The one channel that does not saturate the same way is direct human relationship, the small set of people who know you, trust your work, and pass it on because they want to.

These are not “followers” in the metric sense; they are the thin layer of genuine acquaintance, parasocial or otherwise, that turns “I made a thing” into “someone I trust made a thing.” Trust is the only distribution medium that the flood dilutes more slowly than it dilutes everything else, because trust cannot be manufactured by a model either. This is why the unglamorous work of replying, citing, collaborating, and being present over years outperforms any broadcast tactic in a saturated feed. It is also the version of distribution that compounds, while a clever hook compounds for about a day.

The Bottleneck Moved to Trust
#

The uncomfortable reading of all this is that “make good things” was never the whole strategy; it was a strategy that worked while good things were scarce. They are not scarce anymore, and they will not be again.

What is scarce, and getting scarcer, is the trust that lets a reader choose one piece out of a million. Trust is built only from the inputs a model cannot generate: your time, your experience, your track record, and your relationships. Getting noticed in the flood is not a louder version of the old approach; it is the decision to stop competing on the layer that went free, and to put everything onto the layers that never will.

What to Do Next
#

Stop optimizing for volume. Posting more into an infinite stream makes you more of the stream, not more visible inside it, and the marginal post now competes with machines that post faster, for free.

Bias every piece toward proof of work. If a reader cannot tell whether an actual person did the thing behind the writing, they will assume not, so leave a verification surface they can actually check: link the repository, the data, the incident report, the commit, so the claim rests on something independent of your word rather than on how lived the prose sounds.

Write what only you can write, and narrow until that is true. Specificity is the cheapest signal that survives generation, and a narrow, durable body of work is what makes you the primary source for a problem instead of a drop in the flood.

Treat distribution as the work, not the afterthought. Findability is a generative in its own right, and in a flood it is the generative that decides whether any of the rest gets read.

Build the channels that do not saturate. A small set of genuine relationships, maintained over years, will carry your work further than any algorithmic tactic, and it is the one distribution layer a model cannot generate.

References
#

Attention economy (Wikipedia) - Simon’s “a wealth of information creates a poverty of attention,” the root framing for why a content flood is a trust problem
Kevin Kelly, “Better Than Free” - the “generatives” that stay valuable when copies are free, including authenticity, embodiment, personalization, and findability
Sturgeon’s law (Wikipedia) - “ninety percent of everything is crud,” sharpened here by the fact that the crud is now polished enough to pass for good
Information overload (Wikipedia) - the long-standing name for the reader’s condition this article takes as its starting point
Proof of work (Wikipedia) - trust established by demonstrating costly effort rather than by assertion, the property that lets genuine work stand out against generated content
Parasocial interaction (Wikipedia) - the one-to-many relationship layer that distributes work without saturating the way algorithmic feeds do

Teach Your Agent Skills to Use Tools That Render

tom@tomrochette.com (Tom Rochette) — Fri, 14 Aug 2026 00:00:00 +0000

The cheapest upgrade I have made to an agent skill was not a better prompt or a bigger model. It was teaching the skill to emit a mermaid diagram instead of a paragraph. Once the skill could draw, I could check its work by looking instead of reading, and looking is the one verification that stays fast no matter how much prose there is.

The most effective change you can make to an agent skill is to wire it to a small tool that renders, because a rendered artifact shifts verification from reading to looking, and looking is cheap, fast, and rarely misleads you.

Why prose-only skills plateau
#

A skill that only writes prose hands you prose to verify. Prose asks you to read, and reading is exactly the step that working with agents turned into the limiting factor: the scarce, serial, finite attention you have left once generation became free (Attention Engineering).

The problem is that prose feels productive to generate and expensive to check. The agent writes a fluent paragraph describing the data flow, the spec, or the migration plan, and you skim it and approve it, because reading it carefully would cost more attention than you have. A skill that outputs only text forces you to check it with the slowest checker you own, the one that tires first, which is you, reading.

The pattern: pair the skill with a tool that renders
#

The fix is to give the skill a tool that turns text into something you can inspect at a glance. The tool does the deterministic part, the layout, the rendering, the syntax checking, and the skill does the generative part, deciding what to put in the diagram. The concerns separate cleanly, and the output becomes inspectable in a way prose never is.

The split of labor looks like this:

flowchart LR
    S[Skill, the generative half] --> T[Text source, mermaid or DBML]
    T --> R[Renderer, the deterministic half]
    R --> A[Inspectable artifact]
    A --> H[You, the fast checker]
    T --> G[Git, so changes are reviewable]

Pairing a skill with a renderer is the same approach as Verifying Code Without Reading It, applied to the artifacts a skill produces: stop trying to read, start trying to verify, and pick for each artifact the cheapest checker that catches the failure you care about. For a lot of artifacts, the cheapest checker is a picture.

Mermaid in the SDLC process
#

I started adding mermaid diagrams to my SDLC skills, and the payoff was immediate. A plan that used to be three paragraphs of “first we do this, then that, and this component talks to that one” now ships with a sequence diagram. A spec now ships with a state diagram or a flowchart of the happy path.

The diagrams fail in ways prose hides. A sequence diagram with a message that has no receiver makes a missing step obvious. A flowchart with two boxes that both claim to write the same column makes a race condition visible before a line of code exists. The wrong diagram is obvious in two seconds; the wrong paragraph may take four readings to spot, if you spot it at all.

Mermaid is the right tool for a skill for three reasons. It is text, so the agent generates it directly, the same way it generates any other output. It renders natively where the work already happens, because GitHub renders ```mermaid blocks in Markdown and most static site generators do too. And it diffs cleanly, because the source is text, so a change to the plan shows up in the pull request as a diff you can review instead of a picture you have to compare by eye.

Text-based tools are the best fit for skills
#

The mermaid case generalizes into a rule I now follow. When you pick a tool for a skill to drive, prefer a text-based one, because text is what the agent generates, what git tracks, and what renders to the artifact you inspect.

DBML is the database-schema version of the same idea. It is a small markup language for tables, columns, and foreign keys, and a few lines of it render to a full entity-relationship diagram on dbdiagram.io. A skill that describes a schema now emits DBML, and I see the structure of the data model, the missing relationship, the redundant table, before I have read a single column definition.

The text basis is what makes it fit an agent workflow. The agent writes DBML the way it writes code, the file lives next to the migration that creates the tables, it reviews and diffs like code, and the rendered diagram is a view of the same text rather than a separate artifact that can diverge. When the schema changes, the DBML changes in the same commit, and the diagram is never stale.

Where the visual tool fits: on the human side
#

Preferring text-based tools does not mean GUI tools have no place. drawdb is the visual counterpart of DBML: a browser editor where you drag tables and draw relationships by hand, and it exports the SQL for whatever you sketched.

The division of labor that works for me is to let the agent drive the text-based tools and let myself drive the visual ones. I sketch in drawdb when I am still figuring the model out, when I want to move boxes around and explore the design interactively, and then the SQL/DBML it exports becomes an input the agent works from. I let the agent drive DBML when the schema is already decided and I want a rendered view of it inside the repository. Text-based tools belong in the skill, where the agent is fast and generation is cheap; visual tools belong with me, where exploration is slow and taste is required.

How to pick the next tool to wire in
#

Three tests decide whether a tool is worth wiring into a skill.

The tool must be text-based, or have a text representation the agent can produce. The whole pattern breaks if the agent cannot generate the source the renderer consumes.

The tool must render to something inspectable, a diagram, a table, a diff, a graph. If the output is still prose, you have added a dependency and gained no new kind of check.

And the tool must be narrow enough that the skill can use it reliably. Mermaid and DBML work well here because they are small languages with a fixed grammar, not sprawling APIs the model has to guess at. A tool the model gets wrong half the time is worse than prose, because you spend your attention debugging the tool instead of the idea.

What to Do Next
#

Pick one skill you already run that emits prose and teach it to render. If it describes a flow, teach it mermaid. If it describes data, teach it DBML. If it describes a sequence of messages between components, teach it a sequence diagram.

Then read the next output it produces as a picture instead of a paragraph, and notice what you can see in two seconds that you would have missed in twenty minutes of reading. That gap, between the cost of looking and the cost of reading, is the whole reason to give your skills tools that render.

References
#

Mermaid - text-based diagramming that renders in GitHub and most docs, the tool I wired into the SDLC skills
DBML syntax - a markup language for database schemas that renders to entity-relationship diagrams
dbdiagram.io - the renderer for DBML, where the text turns into a diagram
drawdb - a browser-based visual ER editor for sketching schemas by hand and exporting SQL

What the Author Brings When the Model Writes

tom@tomrochette.com (Tom Rochette) — Fri, 14 Aug 2026 00:00:00 +0000

Producing sentences was never the part that made writing worth reading. When a model can produce clean, well-structured prose about anything in seconds, the value of an author stops being the prose and becomes the one thing the model cannot supply: a reason the words should exist at all.

Writing Was Always Two Jobs
#

For as long as writing was hard, two very different jobs were combined in it. One was mechanical: choosing words, ordering sentences, matching the register a reader expects. The other was everything that made the writing worth a stranger’s time: deciding what was true, which detail mattered, what to assert and what to leave out, what claim I would stand behind if someone pushed back.

The two jobs looked like one task because the same person did both, and because the judgment was invisible unless the prose was done well. LLMs did not replace the author; they split the author in two and automated only the half that was always the easier one to learn.

The split looks like this:

The Model Is Fluent and Has Nothing to Say
#

A model trained on the corpus of everything humans have written can generate plausible text on any subject, and that fluency looks like understanding from the outside. It is closer to a lossy compression of everything already said, as Ted Chiang argued in calling ChatGPT a “blurry JPEG of the web”.

The model can only recombine what exists; it has nothing of its own to add. It has not run the experiment, taken the risk, held the opinion, or been wrong in public and had to fix it. Fluency without experience produces prose that could have been written by anyone, which is exactly the prose the internet now has too much of.

What the Author Brings That the Model Cannot
#

Four things matter most, and each is scarce for the same reason: it cannot be obtained by typing alone.

Something to say. A piece of writing worth reading starts from an observation, a result, a mistake, or a conviction that did not exist in the corpus in that form. The author has lived something the model has not. The trace of that experience, a number that was actually measured, a failure that actually happened, a stance the author will defend, is the only material the model cannot manufacture.

Judgment about what is true. The model will produce a confident answer either way, which is why its confidence is worth almost nothing as a signal. An author commits: this is right, this matters, this is the claim I am making. That willingness to be wrong, narrowing a broad range of plausible claims down to one assertion a reader can check or reject, is the act the model cannot perform, because the model has no stake in being correct.

Stakes and accountability. Writing with a name on it can be wrong, criticized, quoted against its author, and remembered. That risk is precisely what gives the words weight to a reader, who is deciding whether to trust a person, not a process. A model has nothing to lose from a false sentence: the sentence costs it nothing, costs an author something, and readers sense that asymmetry even when they cannot name it.

The thinking that writing forces. Writing is not the transcription of finished thought; for most authors, myself included, it is how the thought gets finished at all. Offload the whole job and I keep the artifact but lose the part that changed me, the slow, uncomfortable work of discovering what I actually believe by being forced to say it precisely.

The Trap of Offloading the Wrong Half
#

Prose generation is so cheap and so good that I am tempted to also let the model decide what to say, and then edit a draft into something shippable. Let the model choose the claim on every piece and the work becomes indistinguishable from the flood, because the work is the flood, recompressed from the same corpus by a slightly different prompt.

The moment you let the model choose the claim, you have stopped being the author and started being the first reader of the model’s writing. That arrangement produces a less substantial kind of work, the kind that does not earn the trust that makes anyone return.

The useful distinction is not “human-written” versus “AI-written,” and never was (see Written by for how this blog labels AI involvement). The useful distinction is whether a human mind made the decisions that determine whether the piece is worth reading: what to assert, what to omit, what experience it is based on, and whether the claim is one the author will stand behind.

What to Do Next
#

Decide what the piece is for and what claim it is making before the model writes a single sentence, because that decision is the work and the prose follows from it.

Base every piece on something the corpus does not contain. A measurement you took, a failure you caused, an opinion you hold and can defend, a reader you are specifically addressing, is the only material that keeps the writing from being echo.

Put your name behind it and mean it. The accountability is not a cost you pay for publishing; it is the source of the weight the writing carries. A reader can feel its presence or absence in the first paragraph.

The prose is now the cheapest output. The judgment behind it is the entire product.

References
#

Ted Chiang, “ChatGPT Is a Blurry JPEG of the Web” - the model as lossy compression of the corpus, which is why it can recombine but not originate
Sturgeon’s law (Wikipedia) - “ninety percent of everything is crud,” made worse by the fact that the crud is now fluently written
Lossy compression (Wikipedia) - the technical basis for why generated prose is a recompression of what already exists

Attention Engineering: Your Attention Is the Bottleneck

tom@tomrochette.com (Tom Rochette) — Sat, 08 Aug 2026 00:00:00 +0000

Generation stopped being the expensive part of working with LLMs. You describe, the model produces, and a plausible answer arrives in seconds. The expensive part is now your attention, and almost nobody has updated how they spend it.

We kept the habits from when writing the code was the hard part. We hover over the agent while it works, we read every diff it produces, we re-check by hand what a check could check for us, and we call the exhaustion that follows “using AI well.” It is not. It is attention spent on the half of the problem that is already solved, while the half that still needs a human mind gets whatever attention is left.

Attention engineering is the deliberate practice of treating your own attention as the scarce resource, and allocating it to the parts of an agent workflow where a mind is required.

Attention Is Not Time
#

The first mistake is to confuse attention with time. Time expands to fit the work; attention does not. You can run eight agent sessions in parallel in the same number of hours, but you cannot read, judge, and decide on eight outputs in parallel. The part that parallelizes is generation, which is the part that no longer needs you. The part that needs you, deciding what is good enough, is strictly serial and strictly finite.

This is why spawning more sessions often makes you slower, not faster. Each open session is a claim on working memory, and working memory is small and slow to refill after a switch. The literature on cognitive load has been clear about this for decades: heavy switching fragments attention and produces shallow processing, and the cost is paid by the task you switched into, not the one you left. Parallel agents increase generation capacity and reduce decision capacity at the same time, and decision capacity is the one that matters.

Where Attention Leaks
#

Most of the fatigue people blame on AI is misallocated attention. It leaks in four predictable places.

Watching the agent generate. The stream of tokens is mesmerizing and almost useless. You cannot usefully steer a model at token speed, and the sense of “supervising” it is a feeling of productivity, not productivity itself. You are attending to a process you cannot improve by attending to it.

Re-verifying what a check could verify. The model says the bug is fixed, and instead of trusting a test, you re-read the diff looking for the fix with your own eyes. This is the acceptance gap run backwards: you spend scarce, taste-grade attention on correctness, the one thing that can be encoded and handed off. A minute of writing the check would have saved an hour of reading, forever.

Context-switching between sessions mid-judgment. You decide on session A until a notification pulls you to session B, and back. Each switch leaves a residue of the previous task in your head, and the decision you return to is made with half your mind still elsewhere. The work feels continuous and is actually being done in shallow fragments.

Signing off without attending. The pull request opens, CI is green, the description looks right, and a feeling forms before the code is read. We have known for a long time that most review works this way, and the arrival of machines writing the diff has not made the reading more rigorous, only the ritual more exhausting. And attention collapses fastest on the work you had no investment in to begin with: it defends itself on what you care about and quietly gives up on what you do not (The Cost of Work You Did Not Choose).

The Leverage Ranking
#

Not every part of an agent workflow needs your attention equally, and the error is treating them the same. Rank them by how much they need a human mind.

Here is the workflow as a pipeline with the attention budget laid over it:

Generation needs none. Stop attending to it. Hand over a finished intent and walk away.

Verification, the question of whether it did the thing, needs very little, once you encode it as a check. A failing test that must pass is attention that pays itself forever, for free, whether or not you are watching. The residual cost is exactly the set of things you have not yet bothered to encode.

Specification, the question of what you actually want, needs a great deal, and it is upstream. Attention spent writing the spec pays a higher dividend than attention spent editing the output it produced, because a good spec prevents the wrong output from existing at all.

Judgment, the question of whether the result is the thing you wanted, needs all of it, and it cannot be delegated. This is the taste decision, the “good enough, ship it” moment, and it is the last compounding thing you do.

The skill is to spend little attention on the first two and most of it on the last two.

Attention Engineering, In Practice
#

A few rules hold up.

Spend attention upstream, not downstream. The hour you invest in the specification is worth ten hours of fixing the generated output, because the output is downstream of the spec and inherits all of its omissions. If you keep editing what the agent produced, the problem is usually the prompt you did not write, not the model.

Encode correctness until it costs you nothing. Every check you write is attention you never have to spend again. The goal is to shrink the “verify by hand” pile to the set of things that genuinely cannot be expressed as a check, which is smaller than most people think.

Parallelize generation, serialize judgment. Let many sessions run at once, but do all your deciding in one focused pass, one session at a time, with the others closed or paused. The model is the part that benefits from parallelism. Your judgment does not, and pretending otherwise is how you ship work you never read.

Refuse to supervise. If you find yourself watching the agent work, you have either failed to specify the task well enough to walk away, or you have not built the check that would let you trust the result without watching. Both are fixable, and fixing them is a better use of attention than the watching.

Protect the taste decision. It is small in duration and enormous in leverage, and it is the one thing no tool will ever do for you, which is exactly why it is worth protecting from the noise of everything else.

The Implication
#

The constraint has done what it always does when a layer gets automated: it moved up the chain, from generating the work to deciding whether it is good enough (The Shifting Bottleneck). What is new is that the new constraint is not another task you can delegate. It is your own attention.

The ceiling on what you produce with agents is not the model, not the tooling, and not how many sessions you can spawn at once. It is how much focused attention you can bring to the few decisions that require a mind, and how ruthlessly you keep that attention off the many that do not.

The people who get the most out of LLMs are not the ones with the cleverest prompts. They are the ones who learned to walk away from generation, to encode everything checkable, and to save their finite attention for the specification and the taste that only they can supply.

Working with agents is not a prompting skill. It is an attention skill, and the sooner you treat your attention as the bottleneck it has become, the more of it you will have for the work that is yours to do.

References
#

Cognitive load - grounds why attention is finite: working memory is small, and heavy context switching fragments it into shallow processing

My Philosophy

tom@tomrochette.com (Tom Rochette) — Sat, 08 Aug 2026 00:00:00 +0000

If you read enough of what I have written, one sentence underlies all of it: encode your judgment into artifacts that outlive your attention. The artifacts change, the principle does not.

A blog post is such an artifact. A skill file is one. The principles file I keep is one. These artifacts range from trivial to deeply meaningful, and the same instinct produces all of them: I do not trust my attention to be present when it matters, so I put the judgment somewhere it can survive without me.

This is not a philosophy of throughput, though it can look like one. I am not trying to do more. I am trying to do things that keep mattering after I stop doing them. The victory condition I keep describing, in different vocabularies, is to make myself unnecessary at the layer I currently occupy, so I am free to go find the next one. That is what I am optimizing for, and once you see it, the rest follows.

The frame: the constraint always moves
#

My master mental model is the Theory of Constraints, and I reach for it more than any other. Every system has exactly one binding constraint at a time, and improving anything other than that constraint is wasted effort. The moment you relieve the constraint, it relocates: it does not disappear, it just moves. Automate code production and verification becomes the bottleneck; solve verification and feature selection becomes the bottleneck; solve feature selection and the question of what deserves to exist at all becomes the bottleneck.

The sequence I keep working through looks like this, and it never ends:

I find this frame everywhere, because it is everywhere. A team’s output is bounded by its weakest coordination path, not by how hard anyone works. A career is bounded by the skill you keep avoiding, not by the one you keep sharpening. A life is bounded by the activity you will not stop doing even though it stopped mattering years ago. The work is always the same: find the layer where the constraint currently lives, push there, and then go find it again. The people who look busy and ineffective are usually pushing somewhere the constraint is not. The people who look calm and effective have simply learned to feel where it is.

Games are one of the places I reach for when I want an analogy, because they externalize the thing I am trying to say. Factorio, StarCraft, World of Warcraft, RollerCoaster Tycoon: each is a simulation with a binding constraint, a compounding resource, and a goal that is easy to forget while you optimize a sub-goal, which is why I wrote a series mapping each onto software. The factory exists to launch the rocket, not the other way around, and every optimization that does not serve the product is wasted. Analogies are not how I think all day; they are how I explain, and sometimes how I notice a pattern I had not named yet. A trade-off that sounds abstract in software can become obvious when you see its equivalent in a game: you spent the minerals on the wrong unit, you hit the supply cap, you optimized a belt that leads nowhere.

The axis: compounding versus depreciating
#

If the constraint frame tells me where to push, the compounding axis tells me what is worth pushing on at all. Every activity, skill, fix, and artifact is either compounding or depreciating. Compounding things leave future me more valuable for having done them: foundation knowledge, taste, specifications, encoded standards, durable mental models, relationships with people who grow. Depreciating things lose value as the environment moves: boilerplate, syntax, one-off patches, anything the next model release will do for free.

My decision tool is the two-year test: if I let this continue for two more years, does the me that emerges become more or less valuable? This looks like a time-management question, but it is actually an ethical one. It encodes a belief that a life is something you invest in, not something you spend.

The discipline is asymmetric, and I state it as a rule: delegate depreciating activities ruthlessly, and protect compounding activities ferociously. Protecting a depreciating activity in the name of craft is not craft; it is nostalgia, and the environment will end it. But delegating a compounding activity in the name of efficiency is not efficiency; it destroys your capability a little at a time. The number to watch is not how much I delegate; it is how much of my remaining time lands on compounding work.

The method: write everything down
#

I do not trust my brain to hold anything important, because I have watched it drop too many important things. So I externalize compulsively: notes, daily questions, workstacks, process documents, this blog. Anything you keep only in your head is lost the moment you switch teams, or get tired, or get interrupted. Writing does not degrade as it passes through people; speech does, so I write decisions down.

Writing also does something the brain cannot: it makes what is implicit explicit, so it can be iterated on instead of left unrecorded. A principle in the head is a feeling that I roughly agree with; a principle on the page is a sentence I can sharpen, test against a counterexample, version, and improve. I treat my own notes and principles the way I treat code: something to refactor when it no longer holds, not something to revere because I wrote it once. An unrecorded thought cannot be revised; it can only be had again, slightly differently, next year.

And, finally, I write because I do not know what I think until I do. The first beneficiary of anything I write is me, because the act of writing is the act of finding out what I believe. A verbal decision is just an opinion that has not been replaced yet; a written decision reaches people I am not with and argues for itself without me. Writing is why the blog exists, why the principles file exists, why the daily questions exist. They are not records of conclusions I had already reached. They are how I reach those conclusions.

Then I encode. If a rule exists only in my review comments, it runs only when I am awake, looking, and willing to argue. If it is recorded in a gate, a template, a supported default, it runs always. A standard runs whether or not anyone agrees with it. An opinion stops applying the moment you go on vacation.

Verify, do not trust
#

I am an empiricist by temperament, and I do not trust output; I trust the verification system behind it. A claim without an independent check is a hypothesis, not a result. Its confidence is not evidence. Once a system can produce faster than I can read it, review stops being a useful gate and becomes an empty ritual. The right approach is to push human attention upstream to specification, let machines verify compliance downstream, and operate on reality rather than prediction. A canary, a feature flag, a test that actually runs: these are more reliable than a tired human scanning a diff.

The same skepticism turns inward. I treat my own practices and opinions as hypotheses to test, not identities to defend. When I change my mind I try to do it structurally, not shamefully; the meta-process compounds while the specific answer does not. Consistently wrong is worse than inconsistently right, and the only way to avoid being consistently wrong is to keep asking what would change my mind.

Attention is the one resource I cannot manufacture
#

Attention is the binding constraint of my life, so I treat it as the thing the whole system is designed to protect. Keeping up is a losing strategy; the target moves faster than any consumption can match.

The move is not to consume more but to build a funnel that throws almost everything away, confidently and without guilt. Treat urgency as something someone benefits from exaggerating. Prefer pull over push: knowing where to find something when I need it beats knowing it now. Re-audit the filter periodically, because filters are themselves depreciating assets.

Asymmetry favors the tighter filter. I would rather miss something than be overwhelmed by it, and I would rather be surprised by a concept I can reuse for a decade than briefed on ten things I will forget next week.

The moral register
#

I keep this part out of most of my writing, because it does not look like the rest, but it is central. My philosophy is Stoic. The happiness of your life depends upon the quality of your thoughts. People are frugal in guarding their property but wasteful of the one thing in which it is right to be stingy, which is time. He who spares the wicked injures the good. These are not decorative quotes to me; they are the axioms the rest has to be consistent with.

From which: tolerate bad behavior and you harm the good; never discourage anyone who continually makes progress no matter how slow; a fast, clear no is a gift, not an injury; skip the blame during the incident and save it for the post-mortem; a father who can admit in writing where he failed gives his children permission to be imperfect too. I keep a register of my own failures, not as self-punishment, but because a rule without the failure that produced it is a slogan, and that failure is the part worth passing on.

I am existentialist about meaning and utilitarian about consequences, and I see no contradiction. Life does not have a meaning. You define the meaning of your life. From there, the reasonable goal is to reduce pain or increase capability for the largest population you can reach, accepting that capitalism will mostly reward you for producing work whose purpose is, in the end, about survival. I do not find this grim; I find it clarifying. It means the meaning is mine to assign and the assignment is allowed to be revised.

Set your own standard
#

Do not define your identity by what the people around you do. If their standards are lower than yours and they do things you do not want to see done, that is not permission to lower yours to match. Most people drift toward the average of their environment without noticing, and the excuse is always that everyone else is doing it. The fact that someone else does something wrong does not make it right.

Be your own standard setter. Be what you would want others to be, regardless of whether they are. The standard is not a comparison to the people next to you; it is a comparison to the person you decided to be, and who you were before.

In one sentence
#

Encode your judgment into artifacts that outlive your attention, from the skill file to the principles file, because that is the only move that simultaneously finds the bottleneck, compounds the foundation, protects the taste, and lets you become unnecessary at the layer you have finished building.

References
#

Theory of Constraints - the master mental model the frame section is built on
Marcus Aurelius, Seneca, Zeno - the three Stoic axioms quoted in the moral register

Whoever Ships First Decides

tom@tomrochette.com (Tom Rochette) — Fri, 07 Aug 2026 00:00:00 +0000

I looked at a feature a colleague shipped last week, and it was wrong in the ways I would have predicted. Not broken, just built on shortcuts I knew we would pay for later. I had no time to spare, and reopening the decision would have taken a meeting, a design argument, and most of a sprint. So I said nothing, and his version became the version the team now supports.

This is how the standard on a team actually gets set: not by what anyone agrees is correct, but by what someone was willing to ship before the rest of us could object.

The interesting question is not whether the work was bad. The interesting question is why bad work, once shipped, almost never gets undone, even when everyone quietly knows it is bad.

“Done” Changes the Question
#

Before the work exists, the question the team is asking is “is this the right approach?” Once it ships, the question quietly becomes “is it worth fighting to change this?” Those are different questions, and the second one is almost always answered no.

The reason is not that the work got better when it merged. It is that reversing it now costs something it did not cost before. You have to schedule a conversation, justify the rework to someone who already feels they finished, and spend credibility you were saving for your own work. Letting it stand costs nothing in the hour you notice it. So you let it stand, and so does everyone else who noticed.

A piece of work does not have to be good to survive. It only has to be done, because done work turns a technical judgment into a political cost, and political costs are paid by the person who raises them.

The Cost to Object Is Concentrated. The Cost to Absorb Is Hidden.
#

The whole pattern depends on this one asymmetry.

Objecting to bad work is expensive in the moment, and you pay the full bill yourself. It is your afternoon, your difficult conversation, your reputation as the person who slows things down. The benefit of objecting, if you win, is spread across the team and across the next year, and most of it lands on people who will never know you objected.

Absorbing the bad work is the opposite. It is free in the moment, and its cost is distributed across the whole team and deferred into the future, where it shows up as the friction of working around a decision nobody loved.

Faced with a cost that is large, immediate, and personal, against a cost that is small, deferred, and shared, almost everyone picks the second one. That is not laziness. It is a rational response to badly priced incentives.

The bad call survives not because anyone thinks it is good, but because the person who would have objected was busy, and objecting then would have cost them their afternoon, and they did not have an afternoon.

The Bar Drifts to the Most Willing Shipper
#

Once you accept that done work is hard to undo and objection is expensive, a consequence follows that most teams never state out loud.

The effective quality bar is not set by what the team agrees is correct. It is set by whoever has the lowest bar and the highest willingness to act first.

If you ship before anyone can object, your version becomes the default, and the default is what everyone else now has to spend energy to change. The person who cares about doing it right is at a structural disadvantage. Doing it right takes longer than doing it fast, and by the time the careful version is ready, the fast version is already in place.

The disadvantage compounds. Other people copy the shortcut, because the shortcut is now the pattern the codebase rewards. The exception becomes the convention. A year later, nobody remembers that the pattern started as a shortcut someone shipped under deadline. Defending the shortcut has become the team’s default position.

The drift compounds in one direction:

Teams do not converge on their best engineer’s standard. They converge on whatever the most active shipper leaves behind, and they call it the way things are done here.

The Cost Was Never Avoided. It Was Moved.
#

Every time a team absorbs bad work, it tells itself the absorption was free. It was not.

The cost was simply transferred, from one person’s afternoon of objection to the whole team’s months of working around the decision, and from a bill addressed to the moment into a bill addressed to the future.

Then the rework arrives, and it is always larger than the objection would have been. By the time the shortcut finally breaks badly enough to force a rewrite, other code has been built on top of it, the original author has moved on, and the team is paying to redo work it already paid to do once.

This is the cruel accounting of absorption. It looked like the cheap option only because the cost arrived later and was borne by someone else. The full cost, plus interest, lands on whoever still works near the code when it finally fails.

The Decision Was Usually Unsound for a Reason
#

It is worth noticing why the shipped work is so often the wrong call, because it is rarely because the author was incompetent.

The person who ships first is usually optimizing for the thing in front of them, getting something working, hitting a deadline, unblocking a demo. The costs they are creating live somewhere they cannot see: in the downstream maintenance, in the constraints they did not know about, in the parts of the system their shortcut quietly contradicts.

They made a locally reasonable decision that is globally wrong. Nobody was in the room to add the global view, because the work was already done by the time the people who held that view heard about it.

The person who does the work is rarely the person the consequences land on, and shipping first lets them decide for everyone without ever bearing the cost.

The pattern is not only a problem with AI-generated code, though cheap generation has made it worse. It is the older and more general problem of whoever acts first setting the default for everyone who acts later, and it applies just as cleanly to a human’s rushed pull request as to a model’s confident output.

What to Do Next
#

You cannot make objection free. You can make it cheap enough that it happens before the bad work becomes the default, and that is where the leverage is.

Object in writing the moment you see it, even if you cannot fix it now. A single line saying “this shortcut will cost us in X” takes two minutes, costs almost no political capital, and does two things at once. It puts the author on notice that the decision was not unanimous, and it leaves a record so that when the cost arrives later, the pattern is traceable instead of invisible. The absence of objection is not consent. It is a measure of how busy everyone was, and writing it down stops that absence from being read as agreement.

Price the absorption out loud. When you absorb bad work to keep moving, say so, and say who will pay: “I am taking this as-is to hit the date, and we will redo it next quarter, and that rewrite is the cost of shipping it now.” Naming that cost prevents the team from pretending the absorption was free, which is the pretense that lets the pattern repeat.

Lower the cost of the conversation. A ten-minute “I would build this differently, here is why” is cheaper than a rework, and cheaper than the resentment that builds when you say nothing for six months. Most engineers respond well to a specific, early objection, and badly to a vague, late one, so timing matters more than wording.

Make the shipper own the consequences for a period. The person who shipped the shortcut remains responsible for the bugs it produces, instead of routing them to whoever happens to be nearby. This does not require blame; it just re-attaches the cost of the decision to the person who captured the benefit of shipping it, which is the alignment the current default removes.

And if you are the one who shipped, treat silence as the weak signal it is. “Nobody objected” does not mean everyone agreed. It means everyone was busy, and the most accurate reading of a quiet merge is that no one stopped you, not that you were right.

The standard on a team is set by what survives, and what survives is whatever was too expensive to undo. If you want a higher standard, do not ask people to object harder. Make objection cheap, make absorption visible, and make the cost of shipping bad work land on the person who shipped it, and the bar stops drifting on its own.

References
#

Wikipedia, “Status quo bias” - the cognitive preference for the current state, which is why shipped work survives even when everyone knows it is wrong
Wikipedia, “Default effect” - the tendency to accept whatever is already in place, the mechanism by which the shipped version becomes the standard
Wikipedia, “Principal-agent problem” - the split between the person deciding to ship and the people bearing the maintenance cost
Wikipedia, “Technical debt” - the deferred, compounding cost of the shortcut, which arrives later as rework
Wikipedia, “Loss aversion” - why the concentrated cost of objecting feels larger than the amortized cost of absorbing, even when the absorption costs more overall

Distributed Product Management: Cheap to Decide, Costly to Undo

tom@tomrochette.com (Tom Rochette) — Thu, 06 Aug 2026 00:00:00 +0000

Distributed product management is what happens when there is no dedicated product owner, and the people building the product also decide what the product should be. Each engineer, or each small team, makes product calls inside their own area, and those calls aggregate into the product without anyone coordinating the whole. The arrangement removes a genuine bottleneck, the single product manager, and it removes something less obvious at the same time: the friction that used to force independent decisions to agree with each other. In the age of LLMs that friction is already gone, which is why a structure that used to be merely risky has become quietly destructive.

What Distributed Product Management Actually Is
#

The dedicated product owner is a specific role: one person who holds the product’s direction, decides what gets built and what does not, and is accountable when the result is incoherent. Distributed product management dissolves that role and spreads its responsibilities across the engineers doing the work.

It shows up in a few familiar forms. Small teams that never hired a product manager and let the founders or lead engineer set direction. Open-source projects, where maintainers decide what to accept and what to build, with no owner above them. “Empowered teams,” in the sense Marty Cagan describes, where a cross-functional team is given a problem to solve rather than a feature to implement, and the team decides the solution itself. And, increasingly, engineering cultures where LLM-assisted development has made shipping so cheap that waiting on a product decision feels slower than just making one.

In all of these, the same property holds. The person deciding what to build is the person building it, and there is nobody whose job is to keep the pieces coherent.

The Case For It
#

The merits are genuine, and I do not want to understate them, because they explain why the arrangement is so common.

It removes a genuine bottleneck. A single product manager is a single point of coordination. When they are slow, blocked, or absent, the whole team waits. When there is no owner in the path, decisions move at the speed of engineering.

Decisions sit with the people closest to the problem. The engineer implementing the feature usually has more context about the technical reality and the user’s actual behavior than a product owner who learned the domain indirectly. Moving the decision to the people who already have the context avoids a translation step, and it avoids the gap between a spec and what the spec was supposed to mean.

Ownership produces motivation. People who decide what they work on care about the work in a way that people handed a task do not, a cost I have felt directly in finishing work I did not choose. Distributed product management lets engineers keep that investment.

It scales without growing an organization. A dedicated product owner has a finite span of attention. As a product grows, either the owner becomes a bottleneck or you have to hire and coordinate more of them. Distributed product management scales with the number of engineers by default.

Each of these is a good argument. Together they explain why the structure keeps reappearing, and why it often works well for a while.

The Case Against It
#

The problems are also genuine, and they take longer to show up, which is why they are consistently underestimated.

The product loses coherence. A product is a system of decisions that have to agree with each other. When each decision is made locally and optimally, the result is a local optimum: every piece is reasonable on its own, and the whole is worse than any of its parts. Two engineers build two ways of doing the same thing. A new feature uses a pattern that contradicts the one shipped last quarter. The surface area grows, and nothing ties it together.

Nobody owns the whole. Coherence is not a side effect of good local decisions. It is a separate concern, the job of noticing the global pattern and sacrificing a local win when it would break that pattern. Without an owner, that job has no home, which means it does not get done. This is the tragedy of the commons applied to a product: the shared surface that everyone uses and nobody maintains.

Nobody is paid to say no. The hardest part of product work is deciding what not to build. A dedicated owner can kill a feature because they are accountable for focus. An engineer building in their own area has no incentive to decline their own idea, and no authority to decline anyone else’s. The result is feature accumulation, the same failure mode that turns a backlog into a dumping ground, except it ships directly into the product.

Cross-cutting decisions have no owner. Some decisions only make sense globally: the pricing model, the data model, the API conventions, the identity of the product. These decisions occasionally require one team to accept a worse local outcome so the whole can stay consistent. Distributed product management has no mechanism for that trade, because no one is authorized to impose a cost on one part to benefit another.

The strategy drifts, silently. When every team optimizes for the metric in front of it, the product as a whole drifts toward whatever those local metrics reward, and that direction is rarely the one the company would have chosen deliberately. This is Goodhart’s law at the level of the product roadmap: each local signal looks reasonable, and the aggregate stops pointing anywhere worth going.

The common thread is that distributed product management is excellent at producing decisions and bad at producing a coherent product. For a long time, that trade was manageable, because the cost of building kept the decision rate low.

Why LLMs Make the Trade Worse
#

Here is the part that has changed.

The friction that used to keep distributed product management tolerable was the cost of implementation. Building a feature took days or weeks, and that cost forced a conversation before the work started. An engineer who wanted to ship something had to justify the time, coordinate with the people whose work it touched, and get the change reviewed. The friction was accidental, but it had a useful effect: it throttled the rate at which independent decisions could accumulate.

LLMs have removed that friction. An engineer who wants to ship a feature can now spec it, generate it, and open a pull request in an afternoon, without asking anyone whether the feature should exist. The cost of making a product decision and the cost of the decision’s consequence have been decoupled. The first one collapsed toward zero. The second one did not.

This is what makes distributed product management destructive in the current era rather than merely inefficient. When decisions were expensive, an incoherent product was a slow problem that you could notice and correct. When decisions are nearly free, the incoherence arrives faster than any human can track it, and the cost shows up downstream: in a codebase nobody wants to touch, in a feature surface nobody can fully use, in the slow accumulation of a house of cards built from locally reasonable additions.

The deeper problem is that cheap decisions change who decides. When a product decision required a meeting, the decision belonged to whoever ran the meeting. When it requires only a prompt, the decision belongs to whoever types first. That is a change in governance that looks like a change in speed, and most teams have not noticed it happened.

It is worth saying what this argument is not claiming. It is not claiming that engineers are bad at product judgment. Many are excellent at it, and the bottleneck has moved toward exactly that judgment as implementation has been automated. It is claiming that good individual judgment, applied independently and at machine speed, with no coherence layer above it, produces a worse product than the same judgment applied inside a shared frame.

The Question Is Which Decisions to Distribute
#

The way out is not to bring back the single product manager as a gatekeeper. That would reintroduce the bottleneck distributed product management was right to remove. The way out is to notice that “product decisions” is not one category, and that the right structure differs by decision type.

A useful split comes from the one-way door versus two-way door distinction. Some decisions are reversible. If you ship the wrong notification wording, or pick the suboptimal layout for a single screen, you can change it next week with low cost. These decisions should be distributed, because distributing them removes friction without risking much.

Other decisions are effectively irreversible. What the product is, which problem it solves, which abstractions it commits to, how the pieces fit together, these set the trajectory of everything built on top of them. Once a thousand features depend on a data model, the model is no longer negotiable. These decisions need a single owner, not because the owner is smarter but because coherence requires that someone be able to choose the global over the local.

The split is a routing rule, and it is easiest to apply as a decision:

flowchart TD
    D[A product decision] --> Q{Is it reversible}
    Q -->|yes, a two-way door| R[Distribute it to the team closest to the context]
    Q -->|no, a one-way door| O[Single decision-maker plus a written record]
    O --> G[Someone can choose the global over the local]

The failure mode of distributed product management is not that it distributes decisions. It is that it distributes the irreversible ones along with the reversible ones. Most teams that suffer from “no product owner” are actually suffering from no owner for the small set of trajectory-setting decisions, while the reversible ones are handled fine. Diagnosing which set is causing the pain is more useful than arguing about whether to have a product manager at all.

What to Do Next
#

If your team operates without a dedicated product owner and the product is becoming inconsistent, a few concrete moves help.

Write the product direction down, in one place, and keep it current. This is the single highest-leverage action, and it is the same lesson as breaking the scope relitigation cycle: a direction that is not written down cannot outlast the next person or the next quarter. A short, written statement of direction, the milestones you are committing to now, and the constraints that forced the compromise, give distributed decisions something to check themselves against. Without it, every engineer is optimizing for a slightly different product that exists only in their head.

Separate the two questions explicitly. On every non-trivial decision, ask first whether it is reversible or trajectory-setting. Distribute the first. Force the second through a single decision-maker and a written record, even if that decision-maker is a rotating engineer rather than a hired product manager. The role matters less than the fact that someone owns it.

Encode product-level invariants the way you encode engineering conventions. The teams that keep coherence without a full-time owner are the ones that have externalized their standards into a form the work has to satisfy: style guides for the product surface, principles for which features are in scope, a definition of what the product is not. This is the same mechanism that lets a mature team scale its conventions into the model. A convention that is not written down is advice that gets ignored. A convention in a written principle is a constraint that gets enforced.

Keep a thin, intent-level review for product decisions, as a backstop and not a bottleneck. The point is not to gate every change. The point is to catch the small fraction of changes that are individually reasonable and collectively incoherent, the second implementation of an existing feature, the new pattern that contradicts the established one, the locally optimal choice that breaks a global invariant. This is the product equivalent of the intent check I keep on LLM-generated code: light by default, held back for the changes that carry genuine risk.

Reallocate the time you saved on implementation into judgment. The instinct, once implementation is cheap, is to ship more. The correct response is to decide more carefully, because the cost of being wrong has not come down even though the cost of acting has. Time spent on problem selection and direction now buys more than time spent on execution ever did.

The Dedicated Owner’s Job Was Coherence
#

Distributed product management is not wrong. It removes a genuine bottleneck, it puts decisions close to the context, and it scales without growing an organization. The mistake is concluding that because the dedicated owner was unnecessary, the thing the owner was doing is also unnecessary.

It was not. The owner’s actual job was coherence: understanding the whole product, killing the features that did not fit, and choosing the global over the local when the two disagreed. Remove the person and you still have to keep the function, or accept that the product will be built faster than anyone can keep it coherent.

In an era when a product decision costs an afternoon and its consequences last for years, the scarce resource is no longer the ability to decide. It is the ability to decide in a way that still makes sense next to every other decision the team is making at the same time. That is the bottleneck distributed product management has to solve, and LLMs have made it urgent rather than theoretical.

References
#

Marty Cagan, “Inspired: How to Create Tech Products Customers Love” - the empowered-team model, the legitimate form of distributed product management, which pairs distributed execution with a strong shared vision
Wikipedia, “Local optimum” - the formal version of the coherence problem: locally optimal decisions producing a globally suboptimal product
Wikipedia, “Tragedy of the commons” - the dynamic by which a shared product surface, used by everyone and maintained by no one, degrades
Wikipedia, “Goodhart’s law” - how optimizing local signals causes the product’s aggregate direction to drift away from any deliberately chosen target
Wikipedia, “Disagree and commit” - the one-way door versus two-way door distinction that separates decisions which can be distributed from those which need an owner

What I've built and what I need: July 2026

tom@tomrochette.com (Tom Rochette) — Thu, 06 Aug 2026 00:00:00 +0000

The headline this month was llm-augmented-workflows carrying an issue all the way through to a human gate. I also spent the month maturing the SDLC pipeline, reworking PR validation around visual proof, and shipping several new skills.

What I Have Been Working On
#

Iterating on llm-augmented-workflows. The project is still rough, but it now moves an issue through actual stages instead of demoing a single one. A cycle looks like this: an issue is created, it gets triaged, and the appropriate workflow runs until it hits a stage that requires a human. For feature requests, the workflow runs triage into a plan PR for review, and once the plan merges, continues to an implementation PR. For bug fixes, the flow goes from triage into a fix PR rather than stopping at reproduction. Triage is handled end to end, which closes a point I’d written about in earlier posts. I’m building it to support both human-gated and fully autonomous modes from the start, so the same flow can run with or without checkpoints.

The cycle is easiest to follow as a flow:

flowchart TD
    I[Issue created] --> T[Triage]
    T -->|feature request| P[Plan PR]
    P --> R[Human review]
    R -->|plan merges| IMP[Implementation PR]
    T -->|bug fix| F[Fix PR]

Building github-board. github-board is a frontend-only web application, served directly via GitHub Pages, that lets you build columns and rows from any field on a GitHub issue or pull request. It turns issue and PR data into a configurable board view with no backend.

Adding the resolve-pr-conflicts skill. I now run the skill daily across the repositories I contribute to. It scans for my open pull requests that have merge conflicts and resolves each one in parallel, fanning out a separate agent session per PR into its own worktree. Each session merges the base branch, resolves the conflict markers, runs the project’s verification, and pushes, aborting ambiguous or verify-failing resolutions rather than guessing them. The practical effect is that my PRs stay mergeable without me managing rebase loops by hand.

Refactored the SDLC pipeline. Feature directories dropped the FEAT-NNNN- prefix for N-<slug>, and pending items now carry a p prefix with a promotion flow through create-placeholder-issue. The old questions.md drift log is gone, replaced by a review-verdict regression that sync-sdlc and backpropagate-sdlc track across phases. Review findings now persist to files instead of disappearing, and I slimmed the create-* family by roughly 750 lines by pointing each at templates and giving it a self-check checklist. Each phase skill is now explicitly loaded before it runs, and a needs-assessment template joined the pipeline.

Reworked PR validation around visual proof. Visual proof capture moved out of create-pr into a dedicated validate-implementation skill, which writes a proof manifest before the PR is ever opened, so recording happens before creation rather than during it. Bug fixes now capture before/after recordings via reproduce-issue and fix-issue. And validate-pr and verify-pr now check against the issue’s acceptance criteria rather than the PR’s own claims, with body and footer split for GitHub attribution.

Shipped several new skills. Slack and memory support landed with slackx and sessions-memory, which turns archived sessions into PARA memory. Team docs gained create-team-api and create-team-charter. Codebase upkeep got improve-codebase, improve-skill, sync-documentation, and sync-opinions. Planning expanded with create-goals, create-service-levels and their review-* counterparts, create-mockups, and create-placeholder-issue. Issue triage gained check-issue-status, check-issues-status, and check-linked-pr. Demo tooling arrived with research-topic, record-asciinema, and record-playwright.

Tidied conventions. gh-cached was replaced by ghx and removed, with every skill reference switched over. The dot-claude directory was renamed to agents. The AGENTS.md vocabulary now avoids “shape”, “honest”, and “load bearing”. SDLC status pages went mobile-friendly.

Experimenting with article-to-video. I started generating short videos from the articles I write, to post on YouTube and TikTok. The pipeline combines text-to-speech narration with visuals that follow the article’s content. The experiment is early, but it’s a plausible way to reach a wider audience with the ideas I’ve been working through.

Resolved from last month. Scheduled issue-to-PR automation (#8) and automatic context clearing between execution and review (#9) both landed through llm-augmented-workflows. The automation was generalized beyond OpenChamber, and the context clearing came free because each phase runs in its own session. Skill usage tracking (#7) is handled after I extended agentsview to collect skill-usage statistics from its SQLite database. Because the data is queryable, an agent can search session logs for skill calls and extract which skill ran, and the same approach works across every harness agentsview supports. Reliable bug reproduction comments (#10) are handled by llm-augmented-workflows, which can enforce an expected outcome and, when the agent doesn’t deliver it, resume the last session and ask again. The llm-augmented-workflows flexibility rework is done. I’ve also fully switched to opencode, though support for other harnesses isn’t there yet.

Partial progress. The SDLC status report got significant improvements, but a status script in TomzxCode/sdlc now duplicates the report and drifts out of sync with the agents-repo skill. Loops only run at the start and end of day, week, and month so far. The easiest remaining task I have not picked up is auto-running validate-pr, verify-pr, and review-pr on PRs waiting on me. And validation of other people’s changes is now covered by validate-pr and verify-pr, but for my own changes I still default to manual testing instead of delegating to an agent.

What I Currently Need
#

Five needs from earlier months are still open.

Memory that agents manage automatically, which I keep delaying for reasons I can’t identify.
The accuracy pass on daily summaries, where nothing has moved.
Contextual Slack support, which still has no workflow.
Automated triage follow-up conversations, untouched because I rarely use that skill.
Routines and event-driven triggering, still unstarted.

Clarity on verdict propagation. I need to confirm how a verdict (approve, reject, needs-changes) made at one stage propagates to downstream stages. Until I can trust that the right decision always carries forward, I can’t confidently run the autonomous path without a human checking each handoff.

A full pass on flow definitions. The flow definitions still have issues I haven’t fully mapped. I need a round of end-to-end testing to find where the definitions diverge from intended behavior, so the defects get fixed rather than worked around.

A faster path to implementation. For feature work, I need to figure out which SDLC steps can be safely skipped or compressed to reach implementation faster. The full chain is thorough but slow, and it’s still unclear which steps are essential and which are ceremonial.

State tracking for an orchestrator-only llm-augmented-workflows. Resolving the context-clearing need surfaced a bigger question: the engine could run as its own orchestrator instead of always depending on a GitHub issue. The blocker is that without an issue to hold state, the engine needs another way to track where a run is, and I haven’t decided what that state store should be.

A set of PDLC skills, mirroring the SDLC ones. At work I’m spending a meaningful share of my time on product management work, and I want the same repeatability there that the SDLC skills give to engineering. I need a structured set of product development lifecycle skills for discovery, framing, prioritization, and measurement, so the product side gets done properly and the same way every time rather than ad hoc.

References
#

llm-augmented-workflows - the engine driving the issue-to-PR pipeline described throughout.
agents - the skill library where the SDLC refactor, validation rework, and new skills landed.
agentsview - the session archive extended to track skill usage across harnesses.
TomzxCode/sdlc - the static SDLC status pages, whose report script now overlaps the agents-repo skill.
github-board - the frontend-only issue and PR board view shipped this month.
ghx - the GitHub CLI that replaced gh-cached across the skill library.

The Cost of Work You Did Not Choose

tom@tomrochette.com (Tom Rochette) — Wed, 05 Aug 2026 00:00:00 +0000

A colleague handed me a task last week. The job was to take their work, get it running, and get it merged. I did not volunteer for it, and nobody asked whether I wanted it. It took me almost three days.

I want to be careful here, because the easy reading of this story is a complaint about a colleague, and that is not the interesting part. The interesting part is why a piece of work that should have taken hours took days instead, and what that delay says about how work gets assigned. Work you did not choose takes longer, not because it is harder, but because nothing motivates you to finish it.

The Task Was Not Hard. The Task Was Not Mine.
#

The work itself was not especially complex. What made it slow was that I had no reason to care about it. I had not chosen the problem, I had not designed the solution, and I had nothing to gain from its completion except the relief of being done with it.

There is a motivation tax on work you did not choose, and it is larger than most people account for. When a task is yours, the friction of a confusing codebase or a failing test is something you want to work through. When a task has been given to you, that same friction is an obstacle between you and being somewhere else, and every obstacle feels harder to get past.

The three days were not a measure of the task’s difficulty. They were a measure of how little reason I had to care.

Finishing Someone Else’s Work Is Not Half the Job
#

There is a common assumption that handing off nearly-finished work is cheap, because the hard part is done. This is almost always wrong. Code that someone else wrote carries their hidden decisions: names that made sense to them, assumptions they never wrote down, edge cases they handled in their head and nowhere else.

To get another person’s work to a mergeable state, you have to reconstruct the intent of a person whose reasoning you never saw. You can only infer their intent from the commits. And unlike your own code, where you remember why you wrote each line, here every unfamiliar line is a small investigation.

“Get this merged” sounds like a small favor. It is a request to absorb someone else’s unfinished thinking, under a deadline you did not set, for a result you will not own.

Distractions Stick When There Is No Pull
#

I noticed something during those three days that I would have missed if I had been excited about the work. Distractions did not just interrupt me. They gave me relief.

When you are working on something you care about, a notification is an annoyance you dismiss. When you are working on something you resent, a notification is a reason to step away, and you take it every time. The work expanded to fill three days in part because every ping, every message, every side question offered a more appealing place to put my attention, and nothing pulled me back.

The same afternoon turns out two ways depending only on who chose the work:

Distractions are not the enemy of focus. They are the enemy of focus on work you do not want to do. On work you want to do, focus holds.

The Failure Was the Hand-off
#

The colleague is not the villain of this story. What failed was the assumption that a task could be moved from one person to another by declaration, without a conversation about whether it should be.

When you assign work without asking, you are guessing that the person receiving it has the context, the capacity, and the motivation to carry it. You have checked none of those things. You have simply moved an item on a board and assumed the work would move with it.

The cost of that guess does not show up on the board. It shows up in the three days, in the half-attention, in the quiet resentment that makes the next hand-off harder to accept. A task assigned without consent arrives already taxed, and the tax is paid in time.

What I Will Do Differently
#

I am not going to pretend the lesson is that I should have said no. In a team, sometimes you absorb work that is not yours, and that is part of the job. The lesson is narrower and more useful.

When work arrives by declaration rather than by agreement, I will name the motivation cost out loud, early. I will ask for the context I am missing instead of reconstructing it silently. And I will be direct, with myself and with the person handing it off, about what “get this merged” actually entails, because the favor is rarely as small as it sounds from the side that is handing it off.

Work you did not choose takes longer, not because it is harder, but because nothing motivates you to finish it. The friction was not in the task. It was in the absence of a reason to care.

Who Maintains the Slop?

tom@tomrochette.com (Tom Rochette) — Wed, 05 Aug 2026 00:00:00 +0000

A coworker ships a feature this week. The demo goes well, the metric moves, the credit lands on them. Six months later the feature breaks, and the ticket is assigned to you. You did not write it, you did not ask for it, and the person whose name is on the commits cannot explain it to you, because they did not write it either. They prompted it, you inherit it, and that asymmetry is the whole problem.

The whole handoff runs like this:

The slop handoff is not the ordinary handoff, where someone moves on and leaves their code behind. It is a new and worse kind, because the thing being handed off carries less recoverable intent than human code ever did, and the person handing it off has less of that intent to offer than the author of human code ever had. The slop producer walks away with the reward. The maintainer is left with the cost, and no one asked whether they wanted to absorb it.

Generation Is Cheap. Understanding Is Not.
#

The economics of AI-assisted code are lopsided in a way most teams have not priced in. Generating code is now nearly free, a prompt and a few seconds. Maintaining code has gotten cheaper too, because you can now ask a model to explain the code to you, but it has not gotten cheaper by nearly as much. Maintenance is dominated by understanding, and understanding, even with help, is still time-consuming in a way generation is not.

When the cost of producing something collapses while the cost of owning it stays fixed, you get a predictable result. People produce a great deal more of it than they are willing to maintain. This is the same dynamic economists call a negative externality: the producer captures the benefit and passes the cost to someone else who never agreed to pay it. In software, the cost lands on the codebase, and the maintainers pay it.

The old discipline that limited the cost-shifting was effort. Writing a feature by hand cost days, and that cost forced a conversation about whether the feature was worth building and whether the author was ready to live with it. Remove that cost and the conversation disappears, because the friction that produced the conversation is gone. The feature still costs days to maintain. It just costs someone else, later, in a currency the original author never had to spend.

The Author Is No Longer the Cheapest Maintainer
#

For a long time, software engineering ran on a principle that aligned incentive and responsibility cleanly. Amazon stated it as you build it, you run it: the team that creates a service operates it, because they understand it best, and making them own the consequences makes them answerable for what they ship.

That principle worked for a specific reason. The person who wrote the code was also the cheapest person to maintain it, because the act of writing it left a durable model in their head. “You build it, you run it” was efficient as well as just. The accountability aligned with the economics.

AI slop breaks that alignment. The person who generated the code did not build a model of it in their head, because they did not build it. They saw the output, checked that it ran, verified that it did what they wanted, and moved on. They are not the cheapest maintainer anymore. Often nobody is. The maintainer who inherits the code knows neither the original intent nor the code itself, and the author who might remember the intent has nothing to say about the implementation that would help.

So the natural loop closes wrong. Instead of the builder owning what they built, the code drifts to whoever is left, whoever is downstream, whoever still cares about the codebase staying healthy. Maintenance becomes a tax on the people who care, levied by the people who do not.

The Defining Feature of Slop Is Missing Intent
#

It is worth being precise about what makes slop slop. It is not only that the code is bad, because sometimes the code runs fine and passes its tests. It is that the code carries no intent anyone can recover.

Human code, even messy human code, is full of traces of the mind that wrote it. Variable names that betray a mental model, comments that record a half-thought, a function split in a way that reflects how the author decomposed the problem. These are imperfect signals, and they are often misleading, but they are signals. When you inherit human code, you can work backward from it to the decisions the author made. This is what The Code You Will Never Read describes from the maintainer’s side: a growing body of code whose internals are opaque by construction.

AI slop leaves no such decisions to reconstruct. The patterns in it were not chosen by a mind that held the problem; they were chosen by a model selecting the most probable next token. The names are plausible, the structure is conventional, and none of it is evidence of a decision you can reconstruct, because no decision was made in the way a human makes one. You cannot ask the code what it meant, and increasingly you cannot ask the author either, because the author’s answer is the same guess you would make yourself.

Missing intent is what makes AI slop harder to maintain than the human mess it resembles. The mess is not the hard part. The hard part is that the mess came with nobody attached to it.

The Missing Ingredient Is Consent
#

The problem with the slop handoff is not only that the work is hard. It is that the maintainer had no say in any of the decisions that produced it.

They did not choose to build the feature. They did not choose its scope, its boundaries, its dependencies, its tradeoffs. They did not choose the abstractions it imposes on the codebase, or the patterns it will invite the next generator to copy. All of those choices were made by a person and a model who will not be present when the consequences arrive, and they were made without the person who will carry the consequences in the room. The maintainer inherits a set of decisions they were never party to, and is asked to own outcomes they could not influence.

The missing consent is the part that goes beyond “the task is annoying,” and it is why slop handoffs damage teams faster than ordinary ones. I wrote about the motivation tax on unchosen work in The Cost of Work You Did Not Choose. The slop version of that tax is heavier, because the work is harder to understand and the handoff is more frequent. When being handed other people’s AI output becomes the norm, the people who maintain the codebase start to feel that they are only there to clean up after others, in a system they did not design and are not allowed to redesign, and that feeling is a leading indicator of people leaving.

The Generator Is Rational, Not Villainous
#

It is tempting to tell this story with a villain, the lazy coworker handing their slop to the team. That story is satisfying and it is mostly wrong, and believing it will stop you from fixing the actual problem.

The generator is responding rationally to the incentives the team has set. The team rewards shipping. It does not charge for maintenance. It does not require ownership to persist after a feature lands. It does not ask whether the maintainer consents to absorb the code before it merges. Given those incentives, generating fast, shipping fast, and moving on is the behavior that gets rewarded, so it is the behavior that happens. You do not fix an incentive problem by asking people to be better. You fix it by changing the prices.

The mistake is to moralize what is structural. The slop producer is not failing at professionalism. They are succeeding at exactly what the system measures, and the system measures velocity, not the maintenance debt that velocity leaves behind. Until the system charges for that debt, the generator who slows down to own their output is not virtuous; they are slower than the colleague who does not, and they lose.

What to Do
#

The fix is to move the price back to where the benefit was captured. A few concrete moves, each of which closes a gap the current default leaves open.

Make intent travel with the code. The maintainer should inherit a specification, acceptance criteria, and the decisions that matter, not just a diff. When a feature lands, it lands with a written account of what it was for, what it was not for, and where the hard choices were made. The code is downstream of the spec, as Defects Flow Downstream, Fixes Must Flow Upstream argues, and the spec is the part that lets a future maintainer fix the source instead of patching the symptom. If the generator cannot produce that account, that is the signal that the generator did not understand what they shipped, and the merge should wait until someone does.

Make the generator sticky. The person who generates the code owns it for a window after it ships, the same way a human author would under “you build it, you run it”. You prompt it, you run it. Bugs in that module route back to the generator for a quarter, not to whoever happens to be nearby. This restores the alignment that cheap generation removed: the person who captured the benefit now carries at least the first round of the cost, which is the cheapest place to charge it.

Require the maintainer’s consent. No AI-generated change lands on a surface someone else owns without their sign-off. This is the one that feels heavy and is the most important, because it is the only move that gives the maintainer a say in the decisions that will become their problem. The owner of the affected code reviews the intent and the boundaries, not the diff. If they would not have chosen to absorb the change, they should not be forced to, and forcing them is what produces the slop handoff in the first place. This is the same intent-source question that decides who is qualified to act on a change in Who Resolves the Merge Conflict?: the person who can back the decision with intent they actually hold.

Price the handoff. If a slop producer does hand work to someone else, they owe that person context, tests, and time, not a working diff. The handoff is not complete when the code runs. It is complete when the receiver could explain the code to a third person without the original author in the room. Charge the handoff in the currency the generator tried to skip, which is understanding, and watch how much less slop gets produced when understanding is the cost of walking away.

Gate generation on ownership. Before AI code can merge, there must be a named owner who will maintain it. No owner, no merge. This is a trivial rule and it eliminates the worst cases outright, the casual generation that lands in a shared module and becomes everyone’s problem and no one’s responsibility.

The Failure Is Upstream
#

The pattern underneath all of this is the one Rethinking Code Review in the Age of LLMs also arrives at from a different starting point: actual responsibility lives upstream, in the decisions that guided the work, not in the person left holding the diff at the end.

The slop handoff is what happens when responsibility is allowed to drift downstream and settle on whoever is standing there when the code breaks. The generator made the decision to generate. The model made the decisions inside the code. The maintainer made no decision at all, and gets to own every one of them.

That is not a sustainable arrangement, and the people who notice it first are the maintainers, because they are the ones paying the tax. They will not keep paying it quietly. They will either push the price back upstream, where it belongs, or they will leave for a codebase where someone else has already done it.

AI did not invent the handoff. It made generation so cheap that handing the result off became the easiest option. The slop producer is not a villain; they are a rational actor in a system that prices generation at zero and maintenance at full cost. The fix is not to scold them. It is to put the price back where it was captured, in the currency that was skipped, which is understanding.

References
#

Wikipedia, “Slop (artificial intelligence)” - the term for low-effort, mass-produced AI content, extended here to code that ships without recoverable intent
Wikipedia, “Externality” - the economic frame for a cost imposed on a third party who did not consent, the model for slop as pollution of the codebase
Wikipedia, “Tragedy of the commons” - why a shared resource degrades when individuals capture the benefit and socialize the cost, the codebase as commons
Wikipedia, “Technical debt” - the accumulated maintenance cost deferred by fast generation, the debt the slop producer leaves behind
Wikipedia, “DevOps” - the “you build it, you run it” principle that aligned authorship with ownership, which cheap generation unaligns
Wikipedia, “Free rider problem” - the dynamic by which those who benefit without paying overwhelm those who carry the cost, the maintainer’s trap
Wikipedia, “Principal-agent problem” - the mismatch between the person deciding what gets built and the person bearing the consequences, the structure of the slop handoff

Zero Touch Engineering

tom@tomrochette.com (Tom Rochette) — Tue, 04 Aug 2026 00:00:00 +0000

“Zero touch” has been a goal in software-adjacent fields for over a decade. Networks provision themselves, deployments go out when the checks pass, and operations teams have been shrinking toward zero. The one stage that resisted zero touch was the engineering itself: deciding what to build, writing it, and deciding it is good enough to ship. That is the part LLM agents are now closing.

Zero Touch Engineering (ZTE): a change travels from an observed signal to a deployed fix with no human keystroke, no human review, and no human approval in the path. Zero touch engineering has a clear lineage in networking and operations, and that lineage explains why software engineering was the last holdout and what it takes to close the gap.

Where “zero touch” already lives
#

The phrase comes from a precise field, and it is not software development.

Zero-touch provisioning (ZTP) remotely configures network devices (switches, routers, access points) with no per-device manual setup, standardized by the IETF as Secure ZTP in RFC 8572. Plug a device in and it fetches its configuration, authenticates, and joins the network on its own (Wikipedia, “Zero-touch provisioning”).

The telecom world generalized the idea into ETSI’s Zero-touch network and Service Management (ZSM), a standards group formed in 2017 with the explicit goal of “100% automation” of operational processes, now actively working on closed-loop, AI-agent-driven architectures.

Closer to software, two more ideas share the same theme. NoOps, coined by Forrester in 2011, is the vision that IT operations becomes so automated that developers never need to talk to an operations engineer again. Continuous deployment removes the last human gate from delivery: every change that passes its checks goes to production, automatically.

Notice what these four have in common. Every one of them automates a stage that is deterministic. Given a desired state and an event, the correct action is fully specified. Provision this device. Deploy this artifact. Page this on-call. There is no judgment left to encode, because the procedure was already mechanical and we just had humans performing it.

That is exactly why none of them applied to engineering. Engineering is the stage that is not deterministic. Deciding what to work on, judging whether a change is worth shipping, choosing between two reasonable designs: these are judgments, not procedures. You cannot automate a judgment you cannot first write down.

What “zero touch” actually requires
#

Most discussion of AI in software focuses on the wrong stage. It focuses on the agent writing code. That is the easy part, and it was never the part that made a process touchless.

A touchless process is a closed loop.

flowchart LR
    Observe --> Decide
    Decide --> Implement
    Implement --> Verify
    Verify --> Ship
    Ship --> Learn
    Learn --> Observe

Every stage must run without a human, and the output of the last stage must feed the first. Continuous deployment automates Ship. NoOps automates the runtime half of Observe and Learn. ZTP automates a specific kind of Implement. ZTE is what you call it when the entire loop closes, including Decide, the stage that requires judgment.

The agent writing the code is one sixth of the loop. If you automate Implement and leave a human approving the result, you have an efficient assistant, not zero touch engineering. The “zero touch” claim only becomes true when a bug report can become a production fix with no human at the gate, and when the system decides for itself that the fix is worth shipping.

Why engineering was the holdout
#

The reason ZTE lagged ZTP by a decade is not that writing code was hard. Writing code was always the most automatable part of engineering, which is why templates, code generation, and scaffolding existed long before LLMs.

The holdout was Decide.

Deciding what to work on is a sequence of judgments: which problems are worth solving, which are urgent, which should be declined, which need an architectural change versus an incremental fix. As I argued in The Shifting Bottleneck, every time AI removes a constraint at one stage, the next constraint appears one level higher up the decision chain. The constraint moved from producing code to verification. The constraint moved from verification to deciding what to implement. The constraint moved from deciding what to implement to deciding what to build.

The bottleneck moved up until it reached the one thing that could not be mechanized: judgment about direction. That judgment is the gate ZTE has to remove, and removing it is a different kind of change from removing a deploy button. A deploy button is a procedure. Direction is taste, context, and tradeoff.

So ZTE is not a tool you install. It is a measure of how much of your engineering judgment you have managed to make explicit.

ZTE is proportional to encoded judgment
#

The encoded-judgment measure gives a useful test for how close a team or project is to zero touch engineering. Measure how much of the decision loop is encoded versus kept only in someone’s head.

The projects closest to ZTE encode five things: the same five I described in The Self-Evolving Repository, because that article was about ZTE without using the word.

A machine-readable roadmap that lets the system distinguish work that matters from work that does not. Most triage decisions are not subtle architecture calls. They are straightforward: this bug affects users, fix it; this request is out of scope, decline it; this dependency has a vulnerability, patch it. If those decisions are written down, the system can make them.

A verification pipeline that replaces human review with multiple independent layers: tests, static analysis, property tests, mutation tests, scenario validation, adversarial probing. Human review of agent-written code is the lowest-leverage activity in the loop, as I argued in Rethinking Code Review in the Age of LLMs. You do not trust the code. You trust the verification system.

A decision policy that ranks competing work the way a competent maintainer would.

Guardrails that bound the blast radius: budget limits, rollback on regression, escalation when a fix loop appears.

A learning loop that turns every failed change into a future constraint.

When all five are in place, the loop closes and the process is touchless. When any one is missing, a human has to fill that gap. The degree of zero touch is exactly the degree of encoded judgment, nothing more.

Where the human re-enters
#

A fully closed loop still has one gap, and that gap is direction.

A ZTE system that only reacts to observable signals will optimize for whatever those signals measure. Bug reports as the only signal produce a system excellent at fixing bugs and terrible at anything else. Feature requests as the only signal produce a system that accumulates features and loses coherence. That drift is Goodhart’s law applied to engineering: when a signal becomes the target of an autonomous system, it stops being a good signal.

The roadmap is what counteracts the drift, but the roadmap itself goes stale. User needs shift; the ecosystem moves; a roadmap written in January can be wrong by July. Updating the roadmap means making a judgment about what the project should become, and that judgment is the one thing current models can approximate but not fully replicate.

The pragmatic answer is not to solve the direction problem perfectly but to bound it. Let the system make small direction adjustments based on observed signals. Require large directional changes to pass through a human. That split keeps the loop touchless for the vast majority of decisions while preserving human oversight for the small fraction that set long-term trajectory.

The human in a ZTE system does not write code, review changes, or approve deploys. The human authors the system that does all of those things, and intervenes only when the system’s judgment and the project’s direction diverge. That is a different job from the one most engineers have today, but it is the job ZTE leaves behind.

The question
#

The networking world reached zero touch because the stages it automated were procedures. ZTE is the claim that the remaining stages, the judgment stages, can be made procedural enough to automate too.

That claim is only partly true. You can encode most engineering judgment, enough to close the loop for routine work. You cannot encode all of it, and the part you cannot encode is exactly the part that determines whether the project moves in a direction worth moving.

Zero touch engineering is not about removing humans from writing code. It is about discovering, precisely, which of your judgments were ever more than procedure, and which were just procedure you had not bothered to write down yet.

References
#

Wikipedia, “Zero-touch provisioning” - the networking origin of “zero touch”, including ZTP and the ETSI ZSM lineage
IETF RFC 8572, Secure Zero Touch Provisioning (SZTP) - the IETF standard showing “zero touch” as an established, standardized concept
ETSI, Zero-touch network and Service Management (ZSM) - the standards body owning “zero touch”, now working on closed-loop, agent-driven automation
TechTarget, “NoOps” - the Forrester-coined vision of fully automated operations, the prior art ZTE extends from ops into engineering
Wikipedia, “Continuous deployment” - the established zero-touch last mile of delivery that ZTE carries backward through review and authoring
Wikipedia, “Autonomic computing” - IBM’s self-managing systems vision, the intellectual ancestor of the closed-loop ZTE depends on

The Code You Will Never Read

tom@tomrochette.com (Tom Rochette) — Sat, 01 Aug 2026 00:00:00 +0000

There is a kind of code growing around us, and growing fast. Code that no human wrote, line by line. Code that no human will read, line by line. Code that no human will review, because the verification system passed and the change shipped on green. If you are an engineer, this is supposed to make you uncomfortable. But you can get past the discomfort, because we have gotten past it before, in several other fields, and their tricks transfer.

Machine learning practitioners have been comfortable with opacity for a decade. The trained neural network sitting behind your favorite model is, at the bottom, billions of floating-point numbers. Nobody reads them. Nobody can. There is no “go to definition” for a weight. You cannot trace a decision through the layers by opening the matrix in your editor and following the logic. The entire artifact is illegible to a human by construction, and the field that built it accepted that a long time ago.

The code agents now produce is heading toward the same property, and the comfort ML people found is the comfort software engineers need to find next.

The Model We Already Live With
#

How did machine learning get comfortable with a thing nobody can read?

Not by pretending to understand the internals. By refusing to need them.

The model is a black box. You understand it through what it does, never through what it is. You probe it with inputs and watch the outputs. You assemble a test set that captures the behaviors you care about, the happy paths and the adversarial ones. You measure accuracy, calibration, latency, and failure modes on the edge cases that would embarrass you in production. You characterize the artifact from the outside, and you trust that characterization.

Nobody on a model team ever says “let me read the weights to see if this is correct.” That sentence is nonsense in that world. It is becoming nonsense in ours, and the people who notice last will be the ones still trying to read code that no longer rewards reading.

Code Is Becoming That
#

The parallel is not exact, but it is close, and it is closing.

A neural network is opaque because its meaning is spread across billions of parameters, none of which means anything alone. Agent-written code is opaque for a different reason and a more mundane one: there is simply too much of it, it was produced too fast, and no human has the hours to reconstruct what it does from the source.

The end state is the same from the operator’s point of view. You are handed an artifact that does something. You cannot hold its behavior in your head by reading it. You have to find out what it does the way you find out what a model does, by running it and watching.

This is already the situation for the engineers defending codebases where agents produce faster than humans can read (The Codebase Gardener describes that arithmetic). It will be the situation for everyone soon enough. The code you depend on, the code in your dependencies, the code that ships from the team across the hall, is increasingly code whose source you will never open, because opening it would tell you less than running it would.

Why Code Felt Different (And Why It Should Not)
#

Source code used to be the thing that made software tractable. That was the whole promise. Unlike a compiled binary, unlike a trained network, you could open the file and follow the logic. Reading was how you understood a system, how you debugged it, how you trusted it. The fact that code was legible was the foundation engineers built their competence on.

Machine learning never had that foundation, so it never grieved losing it. Software engineering did, and does, and that grief is most of what the discomfort is made of.

Strip the grief away and the practical question is simpler. If you could not read the code anyway, would you rather have no code, or would you rather have code you can probe, test, measure, and roll back? You would rather have the code, and you would build the same scaffolding around it that ML built around its weights. The only thing standing between you and that scaffolding is the feeling that you ought to be able to read it, and that feeling is a habit, not a requirement.

The Skills Transfer Directly
#

The practices machine learning developed for living with opacity are almost a one-to-one map onto opaque code. You already know half of them, because software engineering reinvented them under different names.

In ML, the test set captures the behaviors that matter. In opaque code, that is the acceptance criteria written before implementation, plus a characterization suite that records what the code actually does across the inputs you care about (Verifying Code Without Reading It is the full version of this system).

In ML, probing with held-out and adversarial inputs is how you find where the model breaks. In opaque code, that is property-based testing and fuzzing, generating inputs no human would think to write, exposing the edge cases reading would have missed anyway.

In ML, you measure accuracy and failure rate on a benchmark, not intuition. In opaque code, that is defect escape rate, rollback rate, time-to-detect, and change failure rate, measured per change, in production.

In ML, adversarial examples are how you stress the model before it ships. In opaque code, that is the adversarial pass: a separate agent whose only job is to break the change, with no incentive to approve (Verifying Code Without Reading It covers the separation that keeps it sound).

In ML, the model card documents what the model is good at and where it fails. In opaque code, that is the specification plus the issue, the artifact that tells you what the code was supposed to do, which matters far more than what any individual line does (Rethinking Code Review in the Age of LLMs).

Every tool you need to trust opaque code is a tool ML already built to trust opaque weights, renamed.

It Is Not Just Machine Learning
#

Machine learning is the most recent field to face this problem, not the only one. Depending on an artifact you cannot fully read is an old situation, and the disciplines that met it first each invented a piece of the answer. None of them solved it by making the artifact legible. They solved it by changing how they interacted with it, and every one of those changes is a tool we can pick up for opaque code.

Silicon. Once a chip is fabricated, you cannot read its logic from the silicon. The hardware field answered with design for test: boundary scan, built-in self-test, test vectors injected at the pins and observed at the outputs. The lesson is structural, and it is the one our field is slowest to learn: testability has to be designed into the artifact before it exists, not bolted on after. For code, that means the architecture carries probes, hooks, and test seams by default, so an implementation nobody reads can still be exercised by a system that does.

Pharmacology. A drug interacts with a body no one fully models. The field answered with phased clinical trials, a tiny reversible exposure first, then efficacy, then population scale, all run double-blind and followed by post-market surveillance. The transferable pattern is staged rollout with independent evaluation and production watchfulness, which is exactly canary deployments, feature flags, a verifier separate from the author, and monitoring that treats production behavior as the actual verdict.

Behaviorism. Psychology met an opaque artifact earliest of all, the mind itself, and built a whole epistemology around it. Stimulus and response, operational definitions, the refusal to introspect what could not be opened. The stance is the one this article is arguing for: when you cannot inspect the internals, you understand the thing by characterizing what it does, and you stop treating that as a compromise and start treating it as the method.

Cryptography. A cipher is trusted not by reading it but by trying to break it, and Kerckhoffs’s principle says the system must stay safe even when its mechanism is fully public. The lesson is an inversion that cuts against the instinct to trust illegible code by hoping someone read it: obscurity was never what made it safe, and dropping the reading does not drop the safety if the adversarial testing holds. Trust comes from attack, not from inspection.

Optimizing compilers. The output of a modern optimizer is illegible to humans, and no one considers that a crisis. Compilers are trusted through conformance suites and fuzzing, not by reading the assembly they emit. Generated code is a new instance of a situation our own field has always been calm about, a transformation pipeline whose output you verify rather than read.

Legacy mainframes. Long before LLMs, our field operated systems no living person fully understood, COBOL cores kept alive by runbooks, golden-file tests, and behavior contracts. The practitioners did not resign over the illegibility. They built characterization tests that pinned observed behavior, and they ran the systems safely on those pins for decades. That is the exact toolkit an opaque, agent-managed codebase needs.

Each field contributed a distinct piece. Hardware taught us to design testability in beforehand. Pharmacology taught us staged exposure with independent oversight. Behaviorism taught us the epistemology of characterization. Cryptography taught us to trust by attack, not by inspection. Compilers taught us that illegible output is normal and suite-verified. Legacy systems taught us to operate on pinned behavior when comprehension is gone. Stack those techniques and you have the full practice for a codebase no one reads: instrumented by design, rolled out in stages, characterized by behavior, stress-tested by adversaries, suite-verified, and pinned by contracts.

Stacked, the six lessons assemble into a single practice:

flowchart TD
    HW[Silicon designs testability in before the artifact exists] --> P[Practice for a codebase no one reads]
    PH[Pharmacology stages exposure with independent oversight] --> P
    BE[Behaviorism characterizes what a thing does instead of opening it] --> P
    CR[Cryptography trusts by attack rather than inspection] --> P
    CO[Compilers treat illegible output as normal and suite-verified] --> P
    LE[Legacy systems operate on pinned behavior when comprehension is gone] --> P

What Understanding Means When You Cannot Read
#

Engineers are going to resist this shift, so it is worth being precise about what is lost and what is gained.

Reading code gives you one kind of understanding, causal and local. You trace a branch, follow a call, and build a mental model of why the code behaves the way it does on the inputs you happened to trace. It is deep, but it is narrow. It covers the paths you followed, and it depends on you being alert and unhurried while you followed them.

Characterizing behavior gives you a different kind of understanding, statistical and global. You cannot say why a specific input produces a specific output by tracing the logic. But you can say, with evidence, how the system behaves across thousands of inputs, including the ones no human would have thought to trace.

The first kind feels more satisfying because it produces a story. The second kind is more reliable because it does not depend on which story you happened to follow on the day you read it.

A reviewer who reads a diff understands a few paths well and the rest not at all. A test suite that runs on every change understands every path it covers, every time, forever, without getting tired. Reading gives you a vivid understanding of a tiny fraction of the behavior. Probing gives you a coarse understanding of all of it, and for software that has to keep working when you are not looking, the second is the one that compounds.

The Identity Problem
#

Here is the part nobody puts in the engineering blog posts.

This shift is hardest for the people it should be easiest for. The senior engineer, the staff engineer, the person whose entire professional identity is built on being able to open any file in the codebase and understand it, is the person being asked to surrender the exact skill that made them senior.

That is a loss, and it is genuine, and pretending it is not is why so many of the arguments against unread code sound rational but run on fear. It is not irrational fear. If the thing you are best at is reading code, and reading code stops being the valuable thing, then you are being asked to become a beginner again, and beginners are slow and uncertain and uncomfortable.

The way through it is the same way ML practitioners found. You do not stop being valuable. You move your value up a layer. The ML engineer’s skill was never reading weights, it was designing the training, choosing the objective, building the evaluation that decided whether the model was good enough to ship. The senior engineer’s skill, it turns out, was never really reading lines either. It was knowing which behaviors matter, what the failure modes are, where the blast radius lives, and what “done” actually means for this system. Those survive the loss of legibility intact, and they are exactly the skills the opaque-code world pays for.

You are not losing your competence. You are being asked to point it at the layer where it was always doing the most work.

How to Get Comfortable
#

Comfort is not an attitude you adopt. It is a confidence you earn by watching the safety net catch things. Each time a gate stops a bad change, each time a canary surfaces a regression a reader would have missed, each time a rollback undoes a problem in minutes, the illegible artifact gets a little less frightening, because the system around it is doing the job your eyes used to do.

Start where the stakes are low. Pick the changes you were never going to read carefully anyway, the small, reversible, low-blast-radius ones (You Already Review Code Without Reading It is the uncomfortable proof that this is most of them). Let those merge on green, with no human in the middle, and watch what happens. If nothing breaks, your nervous system learns faster than your opinions do.

Then build the probing muscles. Write the behavioral tests before you let an agent write the code. Add a fuzzer to the paths that carry genuine risk. Put a blast-radius classifier on the gate, and reserve your attention for the small set of changes that actually deserve a human, the irreversible and the trust-boundary-crossing. Measure the outcomes, and let the measurements argue for you when your instincts object.

The end state is not that you stop caring about code. It is that you stop needing to read it to trust it, the same way the ML engineer stopped needing to read weights to trust a model. You develop a feel for the system the way they developed a feel for the model, by living with its behavior, watching it under load, and letting the evaluation be the authority instead of your eyes.

The Disciplines That Already Did It
#

Machine learning is the closest mirror to what software is becoming, and it is worth noticing how comfortably it ended up.

Nobody in ML talks about the illegibility of weights as a crisis. They talk about evaluation, about distribution shift, about calibration, about the gap between benchmark and production. The opacity is settled ground, the same way it is settled ground in chip design, in pharmacology, in every field that learned to trust an artifact it could not open. The work happens entirely at the boundary, in the inputs you choose and the outputs you measure, because that is where understanding of an opaque artifact can live.

Software engineering is arriving at the same place, later and more reluctantly, because it had something to lose that those fields never had. The legibility of source code was a gift, and it was a gift that lasted a few decades, and it is ending, and the ending feels like a demotion when it is actually a relocation.

The code you will never read is coming regardless. The only question is whether you learn to be comfortable with it the way half a dozen fields already are, by building the cage of tests and probes and staged rollouts and adversarial checks around it, or whether you keep insisting on reading until the volume of unread code makes the insistence irrelevant.

The first option is work. The second option is a feeling that does not scale. Pick the one that does.

My AI Workflow: The Skills Are the Part That Compounds

tom@tomrochette.com (Tom Rochette) — Tue, 28 Jul 2026 00:00:00 +0000

When someone asks what my AI workflow is, the obvious answer is boring and the answer that matters is surprising. I use a couple of coding tools and a couple of models, and none of them is the thing I would miss. What I would miss is the body of skills I have been writing, collecting, and refining for the better part of a year.

This article is a snapshot of my workflow as it stands today. The tools come first because they are the visible part, but the main argument is that the tools are the part I expect to replace, and the skills are the part I expect to keep.

I run two coding surfaces and two models, and neither is the interesting part of my setup. At home I use GLM 5.2 from z.ai, and at work I use GLM 5.2 fast from Fireworks. For editing I use Cursor at work and VS Code at home, and for anything agentic, multi-step, or long-running I use OpenChamber, which is built on OpenCode. I never open OpenCode directly; OpenChamber is the surface, OpenCode is the engine underneath. The part that actually determines the quality of my work is the library of skills I have been building and sharing in tomzx/agents, and those skills run inside all four of those tools. Everything else is interchangeable.

The setup, in one paragraph
#

Cursor or VS Code is where I read, navigate, and do small edits. The moment a task turns into a sequence of steps, create an issue, reproduce a bug, review a PR, open a PR, I move it to OpenChamber, because OpenChamber is where the work can run to a natural stopping point without me holding the state. OpenChamber is built on OpenCode and is the control room on top of it: it gives me branchable sessions, worktree isolation, and a single surface to steer several sessions at once. The skills are not tied to any of these surfaces; because they follow the open Agent Skills format, the same skill runs in Cursor, VS Code, OpenCode, or OpenChamber, so I pick the surface that fits the moment and the workflow does not change. At home the editor is VS Code and the model is GLM 5.2 on z.ai, at work the editor is Cursor and the model is GLM 5.2 fast on Fireworks, and I switch between them without changing anything else about the workflow.

The model and the shell are commodities
#

A year ago I would have had a strong opinion about which model to use. Now the models are close enough that the choice is mostly about latency and price, which is why I let the environment pick: z.ai at home, Fireworks at work. The model stopped being the lever once the models got good enough to follow a well-specified workflow reliably.

The same is true of the agent shell. Cursor, VS Code, OpenCode, and Claude Code can all read a repository, edit files, and run commands, and because the skills follow an open format they run in any of them unchanged. I use several of them because they are good at different things, but I do not expect any one of them to be the source of my advantage. The shells will keep improving, the models will keep swapping in, and my workflow should not have to move when they do.

The skills are the workflow
#

Everything that matters lives in tomzx/agents, a library of composable skills written in the open Agent Skills format. A skill is a self-contained SKILL.md with step-by-step instructions for one repeatable task. A compatible agent discovers skills by name, loads them on demand, and invokes them as slash commands like /create-pr, /review-pr, or /end-day.

The backbone is the SDLC pipeline. A high-level skill like /sdlc orchestrates dozens of focused sub-skills into a full path from issue creation through requirements, specification, plan, implementation, tests, pull request, review, documentation, and learnings. Each sub-skill is small enough to read in a minute and to improve independently. When I improve the review-pr skill, every flow that calls it gets the improvement, and I never have to re-explain that step to a session again.

The versioned skill is the difference between prompting and engineering a workflow. A prompt is a one-off conversation. A skill is the same conversation, written once, versioned, reviewed, and incrementally improved. The agent performs it the same way every time, and the library gets better as the workflows mature.

Where the human time goes
#

The SDLC pipeline is long, but my time is not spread evenly across it. Almost all of my attention goes to the top: needs, requirements, and specification. The top of the pipeline is where defects fan out the widest and where fixes compound the longest, as Defects Flow Downstream lays out, and it is where the work stays irreducibly human, deciding what to build and what “done” means. A precise specification is the input every downstream skill consumes, and Software Engineering Teams in the Age of AI argues it is now the highest-leverage skill in the field.

Everything below the specification, I automate as far as I can. The plan, the implementation, the tests, the PR description, the review, the deployment, each is a skill the agent runs, and each is a place I would rather spend a token than an hour. Once judgment is encoded into the layer every change passes through, fighting over each unit of output by hand stops paying for itself.

The downstream hour that used to go into reading diffs goes somewhere else entirely: into building high-fidelity test environments that approximate the production environment as closely as I can get them. I would rather spend an hour making the test environment catch the bug than an hour reading a diff hoping to catch it myself, because the test environment runs on every future change and the diff reading runs once. Spending the hour on the environment instead of the diff is the trade Verifying Code Without Reading It and Rethinking Code Review in the Age of LLMs both argue: review is a one-time signal, verification against a production-like environment is a compounding one.

The encoding loop
#

The hardest problem with any workflow is not doing it. It is remembering to do it, every time, in the right order, without skipping the boring step.

My rule is simple. Every time I catch myself remembering to do something, that is a skill that should exist. The reminder to check for an existing PR before starting work, the instinct to link an issue to its plan, the habit of running the linter before committing, the reflex to write a learnings note after a painful bug, each of these behaviors was once tacit knowledge that lived in my head and showed up only when I was fresh. Now each one is a skill, and the agent runs it whether I am fresh or not.

The trigger is the remembering itself. If I had to remember it, the agent should not have to. Encoding it converts a forgettable step into a reliable one, and a reliable one into an improvable one, because once the step is written down I can see it, review it, and make it better instead of re-deriving it from memory every session.

What changes when the workflow is versioned
#

Once the workflow lives in a repository, three things become true at once.

First, it is reliable. The agent triages the issue, plans the work, reviews the PR, and closes the loop the same way today as it did yesterday, because the steps are written down and not reconstructed from guesswork.

Second, it is improvable. When a step is weak, I edit one file and every session that passes through it gets better. The compounding is genuine in a way that prompting never compounds, because the improvement is captured instead of lost.

Third, it is shareable. The skills are public, so anyone on my team or on the internet can run the same workflow against their own repository. The workflow became an artifact I can hand to someone else, which is the test for whether you actually have a workflow or just a habit.

What I expect to keep
#

If you asked me which parts of this setup I will still be using in two years, the answer is easy. Not Cursor, probably not OpenChamber in its current form, and almost certainly not GLM 5.2. The models and the shells are moving targets, and betting on any specific one is a bet against the field.

The skills are the part I expect to keep, but I do not expect to keep them as they are today. They will evolve, and the more interesting bet is that they will shrink. Every skill exists to encode a judgment the model cannot yet make reliably on its own: when to check for a duplicate PR, what a good acceptance criterion looks like, which steps belong in a retrospective. As the models get smarter, often smarter than me at the specific subtask, those judgments stop being mine to encode and start being the model’s to make. The skill for them becomes redundant and gets deleted.

What persists is the slower-moving part: how I decide what is worth working on, how the phases of a feature connect, where the human checkpoint belongs. The tactical skills will collapse into the model. The skills are not a fixed asset I am accumulating; they are a temporary scaffold for the gap between what the model can do today and what it will do on its own tomorrow, and a good chunk of the work is knowing which scaffold to take down next.

References
#

Mathieu Larose, “My AI Coding Workflow” - the article that prompted me to write this one
tomzx/agents - the skills library that is the subject of this article, public and installable
Agent Skills format - the open skill format that makes the library portable across agents
OpenCode - the terminal coding agent the skills target
OpenChamber - the OpenCode-native control room for parallel sessions
Cursor - the editor I use at work for reading and small edits
VS Code - the editor I use at home for reading and small edits
z.ai - provider of GLM 5.2, my home model
Fireworks - provider of GLM 5.2 fast, my work model

Model Collapse: When Code Models Train on Their Own Output

tom@tomrochette.com (Tom Rochette) — Sun, 26 Jul 2026 00:00:00 +0000

Every code-generating LLM in production today was trained on code written by humans. That fact is easy to forget, because the same models are now writing most of the code. If humans stop reading, reviewing, and refining that code, the next generation of models will have to train on the output of the current generation, and the research on what happens then is not reassuring.

Models Were Trained on Human Code
#

The large code models learned from enormous corpora of human-written code: public repositories, Stack Overflow answers, patches, and documentation. None of that code was perfect. Much of it was buggy, redundant, or obsolete. But it carried something that model output cannot manufacture: the accumulated signal of millions of programmers solving actual problems under actual constraints, correcting each other in public, and converging over decades on patterns that actually work.

That signal is the source of the model’s competence. When you prompt a model and it produces a working function, it is not reasoning from first principles. It is predicting the next token from patterns absorbed out of human code, and those patterns were selected by reality, not by another model’s preferences.

The Trend Is Pulling Humans Out of the Loop
#

I have spent the last year arguing that human code review should shrink, that we should verify code instead of reading it (Verifying Code Without Reading It), and that the specification, not the diff, is where human judgment belongs (Rethinking Code Review in the Age of LLMs). I still believe that position, at the level of a single team shipping a single product.

But there is a consequence I have been slow to take seriously, because it does not show up in any one team’s metrics. It shows up in the corpus. As review becomes automated and engineers read less of what the model writes, the public record of code becomes a record of model output, lightly curated by machines. The very thing the next models need to train on, human-written and human-corrected code, is becoming a smaller and smaller fraction of what exists.

What Model Collapse Is
#

This feedback loop has a name. Researchers call it model collapse, and the clearest statement of it is Shumailov et al.’s 2024 paper, “AI models collapse when trained on recursively generated data”.

The finding is stark. When you train a model on data produced by another model, and then train the next model on the first model’s output, and repeat, the model degrades. It does not degrade in an obvious way. It loses information about the tails of the distribution first, the rare cases, the minority examples, the edge behavior, while its performance on the average case can look fine for a surprisingly long time. Model collapse is hard to notice precisely because the headline metrics keep going up while the long tail quietly disappears.

The mechanism is statistical, not mysterious. A model that fits another model’s output is fitting a smoothed, averaged version of reality. Each generation of training removes a little more of the variety, the weird inputs, the unusual-but-correct solutions, until what remains is a narrow, over-represented center.

The preprint that introduced the term, “The Curse of Recursion”, works through the mathematics, and the Wikipedia article on model collapse lays out the two stages, early and late, and the open disagreement among researchers about how severe the impact will be in practice.

Why Code Is Especially Exposed
#

General model collapse is a concern for text and images. Code is a sharper case, for three reasons that compound.

First, the useful part of code lives in the tails. The happy path is easy. The value is in error handling, concurrency, boundary conditions, security, the obscure API, and the input that should never arrive but does. These are exactly the minority examples that collapse erodes first. A model that handles the common case and breaks on the edge case is the literal definition of early model collapse, and it is also the definition of code that passes review and fails in production.

Second, code that looks correct is easy to generate and hard to filter out. A plausible-looking function that contains a subtle bug is not obviously wrong the way a garbled sentence is. If nobody reads it, and the tests do not cover the edge case, it merges into the corpus and becomes training data for the next model, carrying its bug forward as if it were a pattern worth repeating.

Third, the volume is exploding. When a model can draft a feature in minutes, the amount of model-written code committed every day is growing faster than anyone’s ability to curate it. Public repositories are filling with generated code, and that code is the raw material for the next training run. The dead internet theory, originally a half-joke about the web filling with bots, is becoming literal for code.

What Might Happen Next
#

No one knows exactly how the loop plays out, because it has not completed a full generation at scale yet. But a few hypotheses are worth stating plainly, because they are testable and they point at where to look.

The quality plateau
#

Models keep improving on benchmarks for a while, then flatten. The plateau will not look like running out of compute. It will look like running out of signal. The bottleneck moves from the size of the model to the quality of the data, and the data has stopped improving because it is no longer being written by anyone who understands it. The quality plateau follows the same pattern I described in The Shifting Bottleneck: each constraint you remove reveals the next one, one level up.

The long-tail erosion
#

While the common case improves, the edge cases get quietly worse. Security vulnerabilities, race conditions, and incorrect handling of unusual inputs become more frequent, not less, because the training distribution has thinned exactly where those lessons were learned. Benchmarks that measure average correctness will miss the long-tail erosion. Benchmarks that measure adversarial or edge-case correctness will catch it, and they will be the ones to watch.

The grounding premium
#

Code with verifiable grounding becomes valuable. What matters is not who typed it but whether it was selected by reality: it ran in production, it passed tests against inputs no one hand-picked, it survived actual failures and was corrected by them. A human-written snippet that never ran carries no signal a model could not invent. A model-generated snippet that ran under actual load and survived carries signal that no amount of recursive training can synthesize. Labels like “ran in production without rollback” or “verified against a fuzz corpus” start to mean something, the way “organic” became a label worth paying for in food. Grounding begins to matter as much as data volume, and the organizations that can prove their code carried an actual outcome get better models. Eventually the most valuable training corpus is the one you can prove was selected by reality, not merely produced by a model.

The verification-as-data loop
#

The only new ground-truth signal that does not depend on model output is execution. The most valuable training data stops being code at all, and becomes (specification, implementation, test result) triples, where the test result is measured by reality, not inferred by another model. Reinforcement learning from execution, where the reward comes from actually running the code, replaces scraping repositories as the dominant way to improve code models. A model is, at inference time, a function of its context, as I argued in The Importance of Context When Interacting with LLMs; at training time it is a function of its corpus, and the corpus is the part that is degrading.

The split
#

A gap opens between organizations that keep humans in the loop and those that do not. The fully automated shops gain short-term velocity but slowly poison their own tooling, because their internal corpus drifts toward generic code that resembles model output. The shops that keep humans reading, correcting, and rewriting code retain a source of fresh signal, and their models, or at least their use of models, stays sharper over time. The competitive advantage shifts from speed to the quality of the signal you feed back into the system, which is the same conclusion the foundation argument reaches in The Foundation Predicts the House of Cards.

The Case That Code Improves Instead
#

Everything above assumes the only training signal is “imitate the previous generation.” For text and images that assumption is roughly correct, which is why model collapse is a genuine worry there. Code is different in one decisive respect: it has an oracle.

Code runs. It passes tests or fails them, type-checks or does not, compiles or crashes, and a fuzzer can generate inputs no human would think to test. That execution result is a ground-truth signal that does not come from any model, and it is the one thing the self-consumption loop cannot synthesize. Where collapse assumes the model learns only from its own output, execution lets it learn from reality, and reality does not degrade between generations.

Execution changes the arithmetic in several ways, all of them favoring improvement.

First, reinforcement learning from execution replaces imitation as the main source of improvement. The training unit stops being “a file someone committed” and becomes a (specification, implementation, test result) triple, where the reward is measured by running the code. A model rewarded for passing tests it has never seen is being pushed toward correct behavior, not toward the average of prior outputs, and that pressure does not loop back on itself.

Second, selection effects raise the quality of the surviving corpus rather than pull it toward the mean. When generation is best-of-N, or when an adversarial verifier tries to break each candidate, the code that survives into the corpus is the code that passed actual checks. A repository built from verified survivors can be cleaner than the human corpus ever was, because GitHub and Stack Overflow were always full of bugs that nobody ran. Filtering prevents unfiltered collapse, and code is the one modality where filtering is automatic.

Third, the long tail can get better represented, not worse. Humans are lazy about edge cases. Fuzzers, property-based tests, and generated edge-case suites are not. If the training signal includes execution across millions of rare inputs, the model sees more of the tail than human-written code ever covered, and the long-tail erosion hypothesis inverts into long-tail reinforcement.

So the optimistic thesis is precise: code is the modality least susceptible to model collapse, because it alone carries an objective, automatic, infinite ground truth. The thing that makes code hard, that it has to actually work, is also the thing that protects it.

The limitation is that the oracle only checks what you ask it to check. A passing test suite proves the code does what the tests cover, not that the tests cover what matters. Let the same model write the tests and the code, or let the test suite stay shallow, and execution stops being an oracle and becomes a formality. The virtuous loop holds only while the verification is sound, separate from generation, and broader than the happy path.

What Breaks the Loop
#

Even the imitation-only loop has a way out, if real data keeps accumulating. Gerstgrasser et al. showed in “Is Model Collapse Inevitable?” that collapse is avoided when synthetic data accumulates alongside real data instead of replacing it. Their result is the weaker version of the optimistic case: as long as we keep adding fresh human code to the corpus, the model does not have to train only on its own output.

The limitation is the word “fresh.” The mitigation only works if human code keeps flowing into the training set in meaningful quantities. And that is exactly the input the current trend is diminishing. Every hour engineers spend prompting instead of writing, every diff that ships unread, every answer on Stack Overflow that goes unposted because a model answered it privately, shrinks the supply of new human signal.

So the practical question is not whether model collapse is possible. The research says it is. The question is whether we keep enough humans writing, reading, and correcting code, in public, to keep the real data flowing.

The Verdict Hinges on the Oracle
#

I have argued, and still believe, that a single team should not force a human to read every diff if its verification system is strong enough. What I no longer believe is that leaving humans out of the loop is automatically a tragedy of the commons. It is a tragedy only if the only signal the field feeds back into its models is imitation of prior output. Execution is a second signal, and for code it is the stronger one.

The two futures run on the same variable: the soundness of verification. If verification stays grounded in actual execution, adversarial, and separate from generation, the loop improves on its own, and humans reading code matters less every year. If verification is captured, shallow, or graded by the same model that wrote the code, the loop degrades, and no amount of human reading at the end will save it.

So the instruction is narrower than “keep humans writing code in public.” It is: keep the oracle trustworthy. Run the tests, fuzz the inputs, separate the verifier from the author, and treat every passing suite as a claim about coverage rather than proof of correctness. Do that, and generated code can keep getting better long after humans stop writing most of it. Fail to do it, and the degradation arrives as predicted.

References
#

Shumailov et al., “AI models collapse when trained on recursively generated data” (Nature, 2024) - the definitive empirical demonstration that training on model output degrades models across generations
Shumailov et al., “The Curse of Recursion: Training on Generated Data Makes Models Forget” - the preprint that introduced model collapse and its mathematical treatment
Gerstgrasser et al., “Is Model Collapse Inevitable? Breaking the Curse of Recursion by Accumulating Real and Synthetic Data” - the counterpoint showing collapse is avoided when real data accumulates alongside synthetic data
Wikipedia, “Model collapse” - overview of the two stages of collapse and the disagreement over the practical impact
Wikipedia, “Dead Internet theory” - the analogy for code repositories filling with generated content

Rolling Out the Unread Review

tom@tomrochette.com (Tom Rochette) — Sat, 25 Jul 2026 00:00:00 +0000

The case for review without reading, and the system that makes it safe, can both be sound and still fail to ship. I am writing about the part that decides whether any of that work succeeds: your team.

You can be right about review, right about the system that replaces review, and still lose, because you shipped the rollout as a decree instead of as a sequence. The rollout has its own logic, and it is not the logic of the technical argument. A system people do not trust is a system that does not run, regardless of how well it verifies.

Treat The Resistance As Information
#

The easy story is that skeptics are afraid of change, and that once they see the numbers they will change their minds. That story is mostly wrong, and believing it will cost you the rollout.

The people who push back hardest on automated review are often your most careful engineers. They have seen the bugs a tired reviewer caught by instinct. They have been the person blamed when something slipped through. Their objections are not noise to filter; they show where your system is weakest. Calling their discomfort “fear” loses the argument before it starts, because they can tell you are not listening.

Three Concerns, Three Answers
#

Behind “I do not trust the bot” are usually three distinct concerns, and each needs a different answer.

The safety concern: automated review will let bad code through. You answer the safety concern with measurement, defect escape rate compared between the automated lane and the human lane.

The accountability concern: when something breaks, there is no one to point at. You answer the accountability concern with ownership that lives upstream, in the specification and in the people who own the rules.

The learning concern is the one nobody says out loud. Review is how juniors grow and how the team stays connected to its own codebase. This loss is genuine, and it is the concern that will cause the rollout to fail if you ignore it, because no defect metric addresses it.

Sequence The Exposure
#

You cannot go from “a human reads every diff” to “no human reads any diff” in one step. Decompose the automation into three things people react to very differently.

A bot that comments is basically a linter, and almost no one objects. A bot that blocks is accepted once the rules are legible and owned. A bot that approves is the change people resist most.

Ship them in that order, weeks apart, on a low-blast-radius lane first: documentation, tests, internal-only changes inside a single module. By the time you reach the approving bot, the team has weeks of evidence that the earlier layers work. You are extending trust that has been earned, not demanding it up front.

Make Every Decision Legible
#

People resist what they cannot inspect. Every automated action must state which rule fired, what it checked (the file and line, the threshold, a link to the rule definition), and who owns that rule.

“Complexity 18 over 15 in auth.py:42, rule COMPLEXITY_LIMIT, owner Priya” is something a skeptic can argue with. “Bot approved” is something a skeptic can only rage at. The first turns a black box into a reviewable system. The second turns your careful engineers into enemies.

Promote Humans To The Rules
#

This is the move that wins senior engineers over instead of displacing them. They stop reviewing code and start reviewing the gates: the security critic’s checklist, the complexity thresholds, the blast-radius classifier.

Their judgment now scales to every change instead of being spent once on a single pull request. A senior who owns the duplication rule has more leverage than a senior who reads ten diffs a day and remembers three. You are not removing them from the loop; you are promoting them to a loop where their work compounds. Give your skeptics the highest-leverage role in the new system, and most of them stop being skeptics.

Let Shadow Mode Persuade
#

The strongest argument is not yours; it is the comparison the team runs itself. Let a team keep their human review while the automated lane runs silently beside it, recording what it would have caught and what it would have flagged wrongly.

After a few weeks you have the only case that is convincing: “your reviewers missed these defects the gate caught; the gate’s false positives were these, and they are fixed.” Run it on a low-risk slice so the stakes match the trust level. And let the skeptics be the ones who present the results. Nothing converts a skeptic faster than being the person who found the data.

Measure What They Actually Care About
#

They are concerned about defects escaping, so measure defects escaping. Track defect escape rate, rollback rate, time-to-detect, and change failure rate, and compare the automated lane to the human lane on the same slice.

If the gate wins, the argument ends, and it ends in numbers rather than opinion. If the gate loses, you have a concrete gap to close, and you have earned the credibility to say so out loud. Never defend the system with “a human looked at it”; defend it with production outcomes. A human looking at it was always a proxy for those outcomes, and a weak one.

Keep The Escape Hatch, And Say So
#

Irreversible changes, trust-boundary changes, public API changes, and changes to the gating system itself still get a deliberate human read.

The message is never “you are out entirely.” It is “you are in where you add value, and out where you do not.” That framing is far easier to accept than abolition, because it is not abolition. You are reserving humans for the small, identifiable minority of changes where a careful read is still the best tool we have, and the rest of the pipeline moves at the speed the machines can sustain.

Rebuild The Learning Channel
#

The learning concern from earlier does not go away once the rollout succeeds. That loss is a genuine cost, and pretending otherwise breaks trust.

Replace the channel deliberately. Pair juniors with seniors on specifications, because that is where the judgment now lives. Rotate rule-owner duty, so learning to curate a check is itself the apprenticeship. Hold code-archaeology sessions that read well-chosen diffs as learning material, not as a gate. Move the learning off the critical path without deleting it, and name the loss plainly so people know you took it seriously.

The First Escape Is The Moment That Matters
#

When, not if, the gate lets something through, the instinct of the holdouts will be to say “see.” That is the moment the rollout is won or lost.

Run a blameless postmortem, find the gap, and add a rule. Then say the thing human review can never say: this exact defect class can never recur, because it is now checked on every change, for as long as the rule exists.

That guarantee is what removes resistance on its own schedule. The system gets strictly better over time; human review resets every morning. Each incident encoded into a rule is a permanent gain. Show people that compounding curve, and most of the holdouts change their minds, not because you argued them down, but because the system stopped being the thing they distrusted.

What to Do Next
#

Start with the commenting bot on a low-blast-radius lane, and add the blocking bot and then the approving bot weeks apart. Run shadow mode beside the human lane, and let the skeptics be the ones who present the comparison. From the first automated action, publish the rule, the threshold, the owner, and the numbers: defect escape rate, rollback rate, time-to-detect, change failure rate.

Keep the escape hatch explicit, and rebuild the learning channel deliberately. Reserve deliberate human reads for the changes with genuine blast radius. Pair juniors with seniors on specifications, and rotate rule-owner duty, so the apprenticeship continues off the critical path.

When the gate lets its first defect through, run a blameless postmortem and encode the fix as a rule. That rule is the permanent gain the rollout was for: checked on every change, for as long as the rule exists, while human review resets every morning.

Verifying Code Without Reading It

tom@tomrochette.com (Tom Rochette) — Sat, 25 Jul 2026 00:00:00 +0000

It is a familiar observation by now that most code review happens without anyone reading the code (the case is made in You Already Review Code Without Reading It). That observation raises a question. If no human reads the diff, how do you still get correctness, maintainability, extensibility, and the rest of the things review was supposed to deliver?

The short answer is that you stop trying to read, and start trying to verify. Reading is one tool doing many jobs poorly. Verification is many tools, each doing one job well. Done right, the unread change is checked more thoroughly than the read one ever was.

Decompose What “Reading” Was Checking
#

When a reviewer reads code, they are not doing one thing. They are running a dozen checks in their head at once, and doing each of them inconsistently. Make those checks explicit, and you can see that they are separate.

Correctness: does the code do what the task actually asked for? Tested: are the behaviors that matter covered by tests that would fail if the code were wrong? Maintainable: is the complexity bounded, the duplication low, the naming consistent, the dead code absent? Extensible: can the next change plug in without a rewrite, or has this change coupled two things that should stay independent? Secure: does it cross a trust boundary, leak a secret, or open an injection path? Reversible: if this change is wrong, can we undo it in minutes, or does it mutate data we cannot get back?

A tired reviewer scans for all of these at once and catches each of them sometimes. The approach is to give each property its own check, run on every change, without getting tired.

Match Each Property To Its Best Checker
#

Every property above has a checker that is cheaper and more reliable than a human reading a diff.

Correctness is checked by tests, and by an LLM judge that compares the diff against the acceptance criteria from the issue and asks: is there a case where the criteria hold but this code fails? Tested is checked by coverage gates and by mutation testing, which mutates the code and fails the build if the tests still pass, because that means the tests were not testing anything. Maintainable is checked by complexity limits, duplication detectors, dead-code scans, and linters, all deterministic, all running every push. Extensible is checked by dependency-direction rules, boundary tests, and an LLM critic that asks where the next feature would plug in and whether this change has made that harder. Secure is checked by static analysis, secret scanning, and an adversarial LLM pass that tries to find the input the author did not think of. Reversible is checked by a blast-radius classifier: did this touch the schema, the public API, an external commitment, or a trust boundary?

None of these requires a human to read the code. Together they cover everything a reader was supposed to cover, and they cover it on every change, not on the changes a reviewer happened to be alert for.

The LLM As Critic, Not Reader
#

The LLM’s role in this system is not to read the code for you. A summary of the diff is not reading, however it is presented. The LLM’s role is to act as a critic against a single, stated property.

Give it the diff, the specification, and one question. Does this change introduce a coupling that violates the intended dependency direction? Is there an input that bypasses the authorization check the spec requires? Does this function do something the acceptance criteria never asked for? One question per critic, phrased so the answer is either a concrete failing case or a pass.

This is verification, not reading. It is adversarial by construction: the critic is rewarded for finding a problem, not for approving. And because each critic has one job, you can run many in parallel, each a different prompt, each looking for a different class of failure. A human reader tries to notice everything and notices some of it. A battery of critics tries to notice one thing each and notices it every time.

Verification Is Not Validation
#

There is a distinction worth keeping, because the system fails if you confuse the two.

Verification asks: did we build the thing right, does the code meet its specification? Validation asks: did we build the right thing, does the specification solve the actual problem?

Reading a diff does verification badly and validation not at all. No amount of staring at code tells you whether the feature should exist. That judgment has to be made somewhere, and the productive place for it is upstream, in the specification, and downstream, in production.

So split the work. Put verification in the automated gates, where machines check the code against a precise spec on every change. Put validation upstream, where humans decide which problems are worth solving and write the acceptance criteria that encode that judgment. Put a third layer of validation downstream, in canaries, monitoring, and fast rollback, where production behavior is the ground truth no diff review can match.

The human does not read the code. The human writes what the code must satisfy, and then watches what the code does in production.

The Circularity Trap
#

There is one failure mode that will quietly ruin this system if you let it go unchecked. Do not let the same model, or the same prompt, both write the code and approve it.

When the same model acts as both author and verifier, the verifier inherits the author’s blind spots. A model that wrote a subtle bug will, asked to review its own work, tend to confirm that the work is fine. This is not malice; it is the same statistical process producing both answers.

The defense is structural. Use a different model for verification than for generation, or at minimum a different agent with a different prompt and different access to the specification. Write the verification criteria before the code exists, so they describe the intended behavior rather than rationalizing whatever was built. And run an adversarial pass whose only goal is to break the change, with no incentive to approve.

Separation of concerns is not a nicety here; it is the whole reason the system can be trusted.

What The Human Does Instead
#

If the human is not reading diffs, what are they doing?

They write the specification and its acceptance criteria, because that is where validation belongs and where the LLM’s verification is anchored. They review the rules the gates enforce, not the code the gates pass, because a bad rule approved once produces bad approvals forever, while a bad line of code is caught by a good rule. They respond to gate failures, which is where their judgment adds value, instead of using it on changes that passed cleanly. And they read code only on the small, flagged minority of changes that carry significant blast radius, where a deliberate read is still the best tool we have.

The new division of labor is more work at the top of the pipeline and less at the bottom, which is the right inversion. You are trading a low-leverage activity that scaled poorly (reading every diff) for a high-leverage one that compounds (writing the rules and specs that check every diff).

How You Know It Is Working
#

The objection that will come is simple: how do you know the unread code is good enough?

You do not answer it by pointing at how much code you read. You answer it by measuring the outcomes reading was supposed to produce.

Track defect escape rate, the bugs that reach production per change. Track rollback rate, how often a merged change has to be undone. Track time-to-detect, how quickly a regression surfaces after it lands. Track change failure rate, the fraction of deployments that cause an outage.

Run the new system on a slice of changes and compare these numbers to your old, human-read pipeline. If the gates have a lower defect escape rate and a faster cycle time than your reviewers did, the unread code is provably better than the read code was. If they do not, you have a concrete gap to close, by tightening a rule or adding a critic, not by urging reviewers to read harder.

The standard is not “a human looked at it.” The standard is “the code behaves well in production, measurably, on every change.” A human looking at it was always a proxy for that standard, and a weak one. Replace the proxy with the measurement it represented.

You Already Review Code Without Reading It

tom@tomrochette.com (Tom Rochette) — Sat, 25 Jul 2026 00:00:00 +0000

Most code review does not involve reading code. The decision to approve is made before the diff opens. We keep the practice, and quietly drop the part that is supposed to justify it.

The same gap between claim and verification exists on the author’s side of the pull request. An LLM cannot vouch for its own output, because accepting a solution as done needs information the model does not have (The Acceptance Gap). The reviewer has the same problem in reverse: vouching for code that was never read.

What I Mean By Reading
#

There is a difference between opening a pull request and reading one. Reading means reconstructing what the code does, tracing each branch, checking every assumption against the rest of the system, and forming an independent opinion about whether it is correct. That takes time, sustained focus, and more attention than a fifteen-item review queue allows.

Opening is something else. You open the PR, you notice the file list, the green check from CI, the test count, and the description the author wrote, and within a few seconds you form a feeling: this is fine, or this is not. The code itself comes after all of that. Most of the time, you never reach it.

This is not a failure of discipline. It is how the tool presents work to you, and how a busy engineer responds to that presentation. The diff is the last tab you look at, and often the one you look at least.

The Signals That Actually Decide Approval
#

If you watch what an approver actually responds to, the code is rarely the first thing.

CI passed. That matters more than any line you might have read. The tests are green, the build is green, the linter is quiet, and those signals have already provided the safety before you started.

Then the author. A pull request from someone you trust gets less scrutiny than one from a new hire. You will deny this in a meeting and do it anyway in practice. Trust is a signal, and a useful one, but it is not “reading the code”.

Then the size of the change. A two-line diff to a README merges in seconds. A four-hundred-line refactor to the auth module stalls. You are reacting to blast radius, not to semantics, and you are right to, but again, that is not reading.

Then the description and the linked issue. These tell you what the author intended. For a lot of pull requests, the intent is all you ever verify, because the code is too long to verify against it in the time you have.

The code is the excuse. The signals are the decision.

Why We Pretend To Read
#

If the code is not really what we are checking, why the process around it?

Because reading code is the thing code review is supposed to be for. Admit that you are not doing it, and you admit that the central activity of the gate is not happening. That is an uncomfortable admission, so it does not get made. Instead we keep the form, the comments, the approving review, and let the substance go unchecked.

There is also a blame function. When something breaks, we want to point at a name on the pull request and say “they signed off”. The signature has to mean “I read this and vouched for it”, or it cannot carry that blame. So we maintain the fiction that the signature means what it says, even though everyone, on both sides, knows it often does not.

This is a performance of accountability: the approve click certifies that a person was present, but rarely certifies that the code was read. The signature allocates blame after the fact. It does not prevent harm before it.

The Self-Test
#

Here is a test you can run on yourself. Approve your next five pull requests the way you normally would. The next day, try to recall a single line of code from each one.

If you cannot, be precise about what that means. It means you approved metadata. You were responding to CI, to the author, to the description, to the size of the diff, to your sense of the person. Those are signals, and some of them are good signals. But none of them are “I read this code and understood it”.

Run the same test on your team. Ask a recent approver to explain, from memory, one function that changed in the pull request they approved. The silence you get back is the most truthful data you will collect about how code review actually works in your organization.

I am not mocking reviewers here. I have failed this test more often than I have passed it. The point is that the gap between what review is supposed to be and what it is, is large, and we never measure it because measuring it would force a conclusion we have already decided not to reach.

Two Paths
#

Once you accept that most review does not involve reading, you have two defensible directions, and only two.

The first is to actually read the code, on the changes that warrant it. Not every change. The ones with large blast radius: irreversible changes, trust-boundary changes, changes to the gating system itself. On those, slow down, read deliberately, trace the logic, and form an independent opinion. This is high-leverage work, and it is rare, and it deserves the time it takes.

The second is to drop the pretense, and let the changes you were never going to read merge on the strength of the signals you were actually using. Green CI, a passing test suite, a trusted author, a small reversible diff. These already decided the outcome. Let them decide it without a human in the middle adding latency and taking credit.

What is not defensible is the current default. The default is the second path, with the performance of the first added on top. You approve without reading, but you still require a human to approve without reading, and you call the combination a quality gate.

When The Code Was Written By A Machine
#

This was already true when humans wrote the code. It is more pronounced now that machines do.

When an LLM generates the diff, reading it line by line is even less useful, for reasons explored in Rethinking Code Review in the Age of LLMs. The reviewer becomes the only mind in the loop, reconstructing intent from output, and that reconstruction is harder and slower than reviewing a human who can at least be asked what they meant.

So the metadata review does not get more rigorous by being relabeled a code review. It gets more exhausting, and less effective, for the same automatic approval at the end.

If you were not reading human-written code, you are not going to start reading machine-written code. You are going to keep approving signals, with a worse feeling about it. The productive move is to put the effort where it was always worth more: upstream, in the specification, the tests, and the gates.

What to Do Next
#

You do not need permission to start. Pick the low-blast-radius path and let it merge on green. Then be plain with your team about what the rest of the approvals were already doing.

When a change is large, irreversible, or crosses a trust boundary, read it in full. Budget the time. Treat it as the exception it is, not as the default presented as diligence.

And measure the gap. Ask your approvers what they remember from the pull requests they approved. The number will embarrass you, and that embarrassment is the beginning of a review process that is actually worth its cost.

Issues Are Free Now: Send the Implementation, Not the Idea

tom@tomrochette.com (Tom Rochette) — Mon, 06 Jul 2026 00:00:00 +0000

For most of software’s history, filing an issue took actual work. You had to reproduce the bug, narrow it down, write a clear description, and decide whether the request was worth the maintainer’s time. That filter is gone. An AI agent can read a README, a changelog, or spend ten minutes with the tool, and produce a polished, well-formatted issue in seconds, and it can do it a hundred times before lunch. The cost of creating an issue fell to almost nothing, the cost of clearing one did not, and every issue tracker on the internet is now overflowing.

If you are the one filing those issues, the result is unpleasant but clear. The issue you just opened is no longer a contribution in any practical sense. It is a request for someone else’s work, and it is sitting in a queue next to nine hundred other requests for someone else’s work, most of them produced just as cheaply as yours. The only thing that still changes the outcome is the implementation attached to the request, because the implementation is the one input whose cost has not fallen.

The Issue Tracker Was Always a Wish List
#

It is worth being clear about what an issue tracker actually was, even before AI. A well-written bug report was a genuine gift, because it gave the maintainer a reproduction and a starting point. A feature request was almost always a wish. Someone else should do this. Someone else should want this. Someone else should spend their Saturday on the thing I would like to have.

Maintainers cleared the gifts and let the wishes pile up, and that was fine, because the wishes cost the filer enough effort to write that only the motivated ones made it through. The friction was the filter. The issue tracker was tolerable only because filing an issue was mildly annoying, and the mildly annoyed filer self-selected for “I actually care.”

Remove the friction and the wish list becomes the whole tracker. This is already true for most trackers.

The Cost Imbalance Is the Whole Problem
#

The arithmetic that overwhelms the tracker is simple. It costs a filer roughly zero seconds and zero cents to open an issue with an AI agent. It costs a maintainer anywhere from five minutes to an afternoon to triage it: read the request, check whether it duplicates something, decide whether the project wants it, find the relevant code, and either close it, schedule it, or do it. One side of that exchange is free; the other side is unpaid, and the unpaid side is the one you are asking to work.

Multiply that imbalance by a few hundred issues a week and you get the current state of every popular open source repository on the planet. The triage queue grows faster than any single human can read it, the maintainer starts ignoring the tab, the contributor waits six months for a reply, and the project slowly gains a reputation for being unresponsive. Nobody is at fault. The system is just balanced so that the cheap side produces faster than the expensive side can consume, and the buffer between them is a person.

This cost imbalance is the same dynamic I described for pull requests in The Pull Request Queue Outgrew You: the cost to create a change fell below the cost to review it, and the maintainer became the bottleneck in their own queue. What is true for code changes is now true for ideas, and ideas are even cheaper to produce.

An Implementation Rewrites the Ask
#

Here is the move that fixes the imbalance, and it is the only move that fixes it. Stop sending the description. Send the code.

A pull request with a working implementation changes the maintainer’s job from “do this work” to “evaluate this work,” and those are not the same task. Doing the work is open-ended, expensive, and unpaid. Evaluating the work is limited, fast, and something a maintainer can actually fit into a Saturday morning. The difference between “you should add a dark mode” and “here is a dark mode, here are the tests, here is the screenshot, merge or reject” is the difference between a request for a favor and an offer to work together. The implementation is what converts your issue from a cost imposed on the maintainer into an option extended to them.

This is also why the maintainer is so much more likely to act on a pull request than on an issue. A PR gives them a simple choice they can make in minutes. An issue gives them an open-ended commitment that will eat an afternoon if they engage with it at all. If you wonder why your feature request has sat untouched for two years while a stranger’s twenty-line PR landed in a week, that is the entire explanation. The PR was cheap to say yes to. Your issue was expensive to say yes to, and expensive to say no to, so it got neither, which is what happens to expensive things in a full queue.

The Cost of Implementing Fell Too
#

The obvious pushback is that not everyone can write the implementation, and that used to be true. It is not true anymore.

The same AI agent that filed the issue can write the pull request. You describe what you want, the agent reads the codebase, produces a diff, writes the tests, and opens the PR. The skill floor for “I can send a working implementation” dropped from senior engineer to motivated user with a coding agent and an afternoon. The reason to keep sending descriptions instead of implementations is no longer that you cannot produce the implementation. It is that you have not updated your habits to match the new cost structure.

This is the same shift The Shifting Bottleneck keeps arriving at. Producing code is no longer the constraint. Deciding what to produce, and accepting what got produced, is the constraint. In an issue tracker, that means the scarce resource is no longer “someone willing to file the issue” or even “someone willing to write the code.” The scarce resource is the maintainer’s attention, and the only way to earn a share of it is to bring the work to a state where saying yes costs them almost nothing.

But I Am Not Sure My Implementation Is Good
#

This is the second pushback, and it is more serious than the first. You worry that sending an AI-generated PR is dumping low-quality work on an already overloaded maintainer, and that is a genuine risk. The answer is not to hold back the PR. The answer is to do the work that makes the PR cheap to evaluate.

Run the tests. Write a new one for the behavior you added. Reproduce the bug you claim to fix, and show the test going red before your patch and green after. Keep the change small and focused on one thing. Link the issue you are closing. Write a PR description that lets the maintainer evaluate the change in thirty seconds. Every one of these is an attempt to lower the cost of saying yes, and lowering the cost of saying yes is the entire point.

A small, tested, well-described PR is a gift. A large, untested, AI-generated diff with a one-line description is just a different kind of issue, and it will be treated like one. The discipline is not “send code instead of an issue.” The discipline is “send code that is cheaper to merge than to discuss, and if you cannot produce that, the issue tracker will not save you either.”

What the Maintainer Actually Wants
#

It helps to look at the exchange from the maintainer’s perspective for a moment, because the request they are implicitly making is not unreasonable. They want to spend their scarce attention on decisions only they can make: the architecture, the direction, the boundary between what the project is and is not. They do not want to spend it turning a feature description into code, because that is the part the LLM can do now. The highest-value contribution you can make is one that arrives with every reversible decision already made and every test already green, so that the maintainer’s job is reduced to a judgment call they were going to have to make anyway.

This is the open source version of the argument in Rethinking Code Review in the Age of LLMs. When the implementation is cheap to produce, the value concentrates upstream, at the point where someone decides what the implementation should be. A good contributor in this era is not someone who writes clean code. A good contributor is someone who arrives with a concrete proposal, already implemented, already tested, already de-risked, leaving the maintainer nothing to do but approve, redirect, or reject.

What About Bugs You Cannot Reproduce
#

There is a genuine exception, and it should be named so the argument does not go too far. Some issues are genuine bug reports where the value is in the reproduction, not in the fix. A crash that happens on a specific kernel version, a regression that only shows up under load, a data corruption bug that requires a particular sequence of inputs. These are gifts, when written carefully, because the maintainer could not have produced the reproduction themselves.

But notice what makes them gifts. They carry information the maintainer did not have and could not get cheaply. The test for whether your issue is a contribution or noise is exactly this: does it contain information the maintainer could not have produced on their own in fifteen minutes with an AI agent? If yes, file it. If no, the issue is a request for someone else to do work you could have done yourself, and the queue is full of those already.

The same test separates a useful feature request from noise. “Add dark mode” is noise. “Add dark mode, here is the design, here is why it does not conflict with the theming system, here is the PR, here are the screenshots, here are the tests” is a contribution. The information that converts noise into contribution is exactly the information that comes from having tried to build the thing.

What to Do Next
#

If you file issues against projects you depend on, change one habit. Before you open the issue, try to open the PR instead. Point an agent at the codebase, describe the change you want, and let it produce a draft. Spend the time you would have spent polishing the issue description on getting the PR to a state where merging it is the obvious move: tests passing, scope small, description clear. File the issue only if the PR attempt really failed, and when you do, include what you learned from the attempt, because that is the information the maintainer actually needs.

If you maintain a project, change the default you invite. Rewrite your contributing guide to say, plainly, that feature requests without an accompanying PR will be closed, and that bug reports without a reproduction will be closed faster. Be clear that this is not hostility. It is the only way the queue stays manageable. Make the pull request template the default path, and the issue template the exception for the narrow set of things only an issue can carry. Setting a higher standard for contributions is, in this era, an act of respect for the contributors who are willing to meet it, because they are the ones whose work will otherwise be buried under the noise.

And for everyone, learn the new cost structure. Ideas are free. Descriptions are free. Issues are free. Implementations are the only thing left that earns maintainer attention, and the reason is not that maintainers are picky. It is that implementations are the one input whose cost has not fallen to zero, which makes them the one input that still signals you meant it. If you want a maintainer to take your request seriously, prove it the only way that still costs you something: by sending the code.

Who Resolves the Merge Conflict? Why the Bot and the Author Are Not Interchangeable

tom@tomrochette.com (Tom Rochette) — Mon, 06 Jul 2026 00:00:00 +0000

A pull request falls behind main and conflicts. Who resolves the conflict, the bot or the author? The answer depends on whether the conflict is mechanical or semantic, and treating the two as the same job is what makes every flat policy, “the bot rebases everything” or “the author handles it,” wrong.

The clean rebase is settled and out of scope; automate it on every push to main. The live question is the conflict, and the conflict is not one thing. Resolving a conflict means deciding what the code should now say, and that decision is a claim about what the author meant. Someone has to make it, and the interesting question is who can support it with intent they actually hold. The choice depends entirely on whether the conflict has a unique correct answer an oracle can check, or whether its correctness lives only in the author’s head.

Why the Question Got Loud
#

For most of git’s history the conflict question was quiet. A contributor resolved their own conflicts, or the maintainer did, and the round trip was short because the people involved shared a mental model of the code. Two things broke that equilibrium.

The first is auto-merge. Once low-risk changes land on green without a human clicking merge, a PR that cannot merge cleanly becomes the thing that stalls the whole lane. A human can absorb a conflicted PR by glancing and clicking; an automated merge pipeline cannot. Auto-merge makes conflict resolution a prerequisite of the lane, and that turns “who resolves” from a courtesy into a structural question.

The second is the model-authored pull request. When the author is a model, the conflict round trip behaves differently at both ends. The bot never sleeps, so a resolve request adds no latency the way it does for a human. But the bot also has no private knowledge of what the code was meant to do, so its resolution is a guess about intent presented as a fix. This is the plausibility problem, and it is worst exactly where the conflict is hardest.

So the modern repository has a lane that wants every PR mergeable on green, and a growing share of PRs whose intent lives only in the code a model produced, with no description, linked issue, or spec that states it independently. When the intent is encoded somewhere, a conflict has an oracle to check a resolution against. When it is not, there is nothing to verify the resolution by, and the absence of a way to verify the resolution, not the absence of an author to interrogate, is the actual problem. The old default, the contributor resolves, is too slow for the merge lane, and the bot is too confident to stand in as the oracle, so the live question is not who authored the PR but whether the intent exists outside someone’s head.

The Conflict Has a Gradient
#

Conflicts are not all the same, and the gradient is what lets you route them accurately.

At one end is the mechanical conflict: an import added in both branches, a trailing comma, two functions inserted at adjacent positions, a formatting drift the formatter can settle. Resolve it and there is exactly one answer any reasonable developer would accept, and a test suite that passes before will pass after. At the other end is the semantic conflict: two people changed the same logic for different reasons, and the correct resolution depends on which reason was right. The mechanical conflict has a unique correct answer that a test can falsify; the semantic conflict has no correct answer without the intent that motivated the change.

The mechanical conflict is therefore still logistics, just logistics that needs an oracle. Resolve it, run the suite, and if the suite passes the resolution is, by construction, the one the project already trusted. Here the test acts as the independent oracle the model cannot be, the same role it plays in closing the bug gap when a fix claims to be done. A conflict whose wrongness a test can catch is a conflict the bot may resolve, because the test, not the model, approves it.

The semantic conflict is a different kind of problem. Nothing external is left to disagree with the model’s plausible resolution, because the definition of “correct” is the intent, and the intent is precisely what the model does not have. A bot that resolves a semantic conflict is making an intent claim it cannot source, and the harder the disagreement, the more likely the claim is a confident fabrication.

Where the Intent Lives
#

The semantic conflict splits once more, and it splits on a cleaner axis than who wrote the PR: whether the intent is encoded anywhere a resolver can read it.

Intent can live in two places. It can be encoded, written down in the PR description, a linked issue, an acceptance criterion, a failing test, anything a human authored to state what the change was supposed to do. Or it can be tacit, held in someone’s head and never written down, surfacing only if you ask. A conflict is safe for the bot to resolve when the intent is encoded and the encoded source covers the disputed region, because then the resolution has an oracle. It is not safe when the intent is tacit, because then nothing external can falsify the bot’s resolution, and the resolution will look right whether or not it is.

Author type matters, but only as a proxy for where the intent lives, and the proxy is worth stating because it inverts the naive assumption.

When the PR is human-authored, the human’s own description is an independent statement of intent. If the description covers the conflict, the bot may resolve against it, and the description, not the model, is the oracle. If the description is thin or silent on the disputed region, the intent is effectively tacit, and the only defensible move is to ask the human who holds it.

When the PR is bot-authored, the trap is that the bot’s description is not an independent oracle. It was written by the same model that wrote the code, or a sibling of it, so checking the resolution against the description is checking the model against its own narration, which provides no independent verification. The only trustworthy intent source for a bot-authored PR is something a human wrote upstream: the issue, the spec, the prompt, an acceptance test. When that upstream source exists and covers the conflict, the bot may re-derive against it, and the re-derivation is checkable. When it does not exist, the intent was never encoded by anyone, and the bot’s resolution is a guess about intent no one ever wrote down.

The distinction above is the refinement the flat “maintainer picks a default” framing misses. A single repository-wide default is too coarse, because the right default is a function of whether the PR carries an encoded, independent intent source, and that varies PR by PR, not repository by repository. The PR that links a human-authored issue with acceptance criteria is safe for bot resolution regardless of who wrote the code; the PR that arrives as code and a self-description is not safe regardless of who wrote the code.

The Label Is the Right Mechanism, the Default Is the Question
#

Given the split, the mechanism worth reaching for is the one the question already points at: a label on the PR that decides who resolves a conflict. Labels are already how a modern triage layer expresses every other routing decision, and conflict resolution is no different in kind. The label should express the thing that actually varies, which is not “is this PR rebased” but “who is allowed to resolve a semantic conflict on it.”

For a mechanical conflict there is no decision worth encoding: the bot resolves, the test gates, and a conflict: auto-resolved note is enough audit trail. The label is worth having at the semantic tier. Something like conflict: author-resolves versus conflict: bot-may-resolve, defaulted per repository by the maintainers and overridable per PR, is the right form, and it is the form the question proposes.

The interesting work is in the default, and the sound default routes on intent availability, not on author type. A PR that links a human-authored issue or spec, with acceptance criteria that cover the change, defaults to bot-may-resolve, because the resolution has an oracle. A PR that arrives as code alone, with no independent statement of intent, defaults to author-resolves, because nothing can falsify the bot’s resolution. The maintainer’s actual choice is not “auto or manual.” It is “what do we assume about a PR whose intent source we cannot verify.” The conservative answer, treat the PR as unencoded and ask the author, costs a little latency where the bot could have handled it. The permissive answer, resolve and trust the model, costs intent claims that are silently wrong. Between losing a little speed and shipping a confidently wrong merge, the speed is the cheaper loss, so the default for a PR with no verifiable intent source should be author-resolves.

This makes the highest-leverage change a documentation change, not a tooling one. Require, in the pull request template, a linked issue or a short intent statement that covers the change, and ask whether the PR was model-assisted. The linked issue turns an unencoded PR into an encoded one; the model-assisted flag tells you whether the PR’s own description can serve as an oracle or whether you need the upstream source. Both shrink the “no verifiable intent” bucket, and shrinking that bucket is what lets the auto-merge lane actually run.

What to Do Next
#

First, surface the conflict instead of hiding it. Add eps1lon/actions-label-merge-conflict so any PR that falls behind main gets a merge-conflict label the moment it conflicts, and loses it the moment it merges again. Your auto-merge lane can now filter -label:merge-conflict and only act on work that is actually ready. The author gets an automated nudge that a genuine decision is needed, without you being the one to say it.

Second, classify the conflict before you route it. Mechanical conflicts (imports, formatting, adjacent non-overlapping edits) go to the bot behind the test gate, and the test is the oracle that makes the resolution trustworthy. If the suite fails, the resolution is wrong by definition and the bot escalates rather than ships.

Third, route the semantic conflict by whether an independent intent source exists. If the PR links a human-authored issue or spec that covers the disputed region, let the bot resolve and check the result against that source, with an encoded test that must pass on the resolved tree. If the PR carries no such source, post the conflict as a comment and drop the PR to author-resolves until someone provides the intent or resolves it by hand.

Fourth, choose the conservative default for the case where you cannot tell. When a PR arrives with no linked issue and no intent statement, default to author-resolves, because the cost of a confidently wrong merge is higher than the cost of a round trip, and the round trip at least asks the question the silent resolution skips.

Fifth, make the routing signal cheap to produce. Require a linked issue or a short intent statement in the pull request template, and ask whether the PR was model-assisted. The link is what turns an unencoded PR into an encoded one, and the model-assisted flag is what tells you whether the PR’s own description can count as the oracle.

Do not write a policy that says “the bot resolves everything” or “the author resolves everything.” Both are the original mistake in policy form. Gate the mechanical conflict behind a test, defer the semantic conflict to an independent intent source when one exists, and defer to the author when one does not.

Feature Parity Is Not a Moat: Compete on What Does Not Clone

tom@tomrochette.com (Tom Rochette) — Sun, 05 Jul 2026 00:00:00 +0000

For most of software’s history, shipping a feature gave you a window of time. A competitor had to understand the need, design the thing, build it, test it, and ship it. That took weeks or months, during which you could compound users, data, and trust. That window has collapsed to days, sometimes hours, and the uncomfortable implication is that the feature was never the moat. The slowness of copying it was. Once the copying is nearly free, every hour spent perfecting a feature is an hour spent on the one layer the market just commoditized, and the advantage has moved somewhere developers were trained to undervalue.

The Moat Was Always Somewhere Else
#

An economic moat is the structural thing that lets a business keep its profits against competitors. The standard list of what counts as a moat is worth noting: switching costs, network effects, cost advantages, intangible assets like brand and patents, and efficient scale. A feature is not on that list. A feature is something you build in the hope that a moat forms around it, through usage, data, or habit, before anyone else arrives.

For a long time the list and the feature felt like the same thing, because copying was slow. You shipped the recommendation engine, and by the time a rival reverse-engineered it, your users had generated enough behavior to make yours better. You shipped the dashboard, and by the time it was cloned, your customers had wired it into their weekly review and would not move. The feature was the seed, and the copy-time was the growing season, and the moat was the harvest. The copy-time is gone, which means the growing season is gone, which means a feature shipped with no other plan now arrives at the market with no moat attached.

What Actually Clones, and What Does Not
#

It is worth being clear about the boundary, because the claim is not that everything is copyable.

What clones easily is the surface. The visible feature, the UI flow, the API surface, the integration that calls a public endpoint, the report that joins two tables. A capable engineer with an LLM can reproduce any of these from a screenshot or a description in an afternoon, and a competitor can ship a credible copy in a week. The commoditization of the application layer is under way, and it is fast.

What does not clone is everything that had to be true for the feature to be valuable in the first place. The two years of usage data that makes the recommendation correct. The thousand integrations already in your customers’ workflows. The track record of reliability that makes a procurement officer sign. The deep, specific knowledge of a narrow industry that lets you pick the right feature to build next. The competitor can copy the feature and still be left holding an empty shell, because the value was never in the shell. It was in the data, the relationships, and the context the shell was built to carry.

Where the Moat Moves
#

When the feature stops being the moat, the advantage moves to the layers that surround it, and almost all of them are things that compound through time rather than through code. Five of them matter for a developer deciding where to spend next quarter.

The learning loop, not the feature
#

The competitor copies your feature, but they do not copy what you learned by shipping it. Shipping a feature to actual users tells you which half of it was wrong, which edge case matters, and which adjacent problem is now the actual problem. That knowledge is yours alone until competitors run the same experiment themselves, and they will now run it by copying your result rather than discovering their own. The moat is the build-measure-learn cycle compressed to days, run against actual users, faster than anyone who is copying can run it. A feature is no longer a deliverable; it is a probe, and the team that runs more probes per month learns more about the market than the team that ships fewer, more perfect features.

Proprietary data and feedback
#

A clone of your feature without your data is a weaker feature. The recommendation is bland, the search results are generic, the anomaly detection fires on the wrong things, because the model behind the clone has nothing the field has not already seen. Every interaction with an actual user adds signal to your data that the clone cannot synthesize, and that data advantage compounds quietly until the gap is not closeable by better code. This compounding is the mechanism behind network effects, and it is one of the few things that genuinely does not clone.

Workflow depth and switching costs
#

A feature you can use in a minute is a feature you can leave in a minute. A feature that is wired into six other systems, that holds three years of configuration, that your team’s runbook depends on, is a feature that survives a cheaper clone because the cost of moving exceeds the cost of staying. These switching costs are a legitimate moat when they are a side effect of genuine usefulness, and they are built by going deep into the customer’s workflow rather than wide across a feature checklist. Shallow integrations clone in a day; deep ones do not, and depth is a function of how much of the customer’s actual job you have absorbed.

Distribution, brand, and trust
#

Engineers historically treated these as someone else’s problem, which was always a mistake and is now an expensive one. The feature that arrives through a channel the user already trusts, from a name they recognize, beats the marginally better clone that arrives cold. Trust is built slowly, through reliability and through presence, and it is one of the slowest things in the product to reproduce. A developer who invests zero attention here has chosen to compete purely on the layer that clones fastest.

Judgment about what to build
#

Judgment is the layer the rest of this blog keeps arriving at, because the bottleneck keeps moving toward it. When everyone can build anything, building things stops being the differentiator, and deciding which thing to build, for whom, and in what form is what matters. That judgment is a personal and team-level moat, it compounds with practice, and it does not clone because the competitor cannot copy the years of being close to the problem that produced it.

The Feature Race Is a Trap
#

The failure mode to avoid is the feature-parity race, and it is the default response if you do not see the shift.

You ship a feature, the competitor copies it, you ship another to pull ahead, they copy that, and the cycle repeats. Both teams are running as fast as they can and neither is building a moat, because every feature is neutralized within a week of landing. You are exhausting yourselves producing advantages that confer no advantage, and the only thing accumulating is technical debt from features nobody had time to integrate properly.

The feature-parity race is the same trap as first-mover advantage misunderstood. Being first was valuable only because first movers got the growing season, the time for data and habit to form before the copiers arrived. When the growing season disappears, being first stops being the point. Being the one who learns fastest from being there is the point.

The deeper error is treating the feature list as the measure of progress. It feels like progress, because the features keep shipping and the release notes keep growing. But a competitor watching your changelog now has your roadmap for free, and a model lets them execute it at your speed. A changelog is no longer a strategic asset; in a clonable world it is a plan you give your competitors every week.

What to Do Next
#

A few concrete moves follow from treating features as probes and moats as the target.

Audit where your engineering effort actually lands. If the large majority sits on building and polishing features, you are over-invested in the layer that clones and under-invested in the layers that do not. Reallocate deliberately, not by abandoning features, which you still have to ship, but by capping the time each feature gets and routing the surplus into data, integration depth, and the learning loop.

Instrument every feature as an experiment from day one. If you ship a feature and cannot tell within a week whether it moved the metric you built it for, you have shipped a deliverable, not a probe. You have also given up the one advantage the copy does not get. The measurement is the moat, because it is what turns the feature into learning the competitor does not inherit.

Pick a narrow domain and go deep rather than spreading wide. The competitor who clones your broad, shallow surface gets a credible copy. The competitor who tries to clone your deep, specific understanding of one industry’s workflow has to do the years of work you already did, and most will not bother. A moat that survives cloning is built from depth.

Invest in the layers engineers usually skip. Distribution, documentation that lives where users find it, reliability that earns trust, onboarding that keeps users through genuine usefulness rather than lock-in. These compound while features are being copied, and they are the reason the copy reaches a market with no unclaimed customers.

And protect the judgment layer on your own team. The skill of deciding what to build is now the highest-leverage skill a developer can hold, and it is built by staying close to users, not by staying close to the IDE. Delegate the building aggressively so that the time you reclaim lands on the judgment, the data, and the relationships, because those are the three things the clone will never contain.

The Moat Moved
#

The feature stopped being the moat the day it became cheap to copy. That shift is not a threat to the developers who notice, because the moat did not disappear; it moved to a set of layers that reward exactly the attention most engineers have been trained to underinvest in. Data, distribution, workflow depth, trust, and judgment all compound, and none of them clone.

The teams that win this era will still ship features, because they have to. They will just stop treating the features as the point. The feature is the seed; the moat is the growing season, and the growing season is now made of everything except the code.

References
#

Economic moat - the structural sources of sustained advantage, the canonical list against which a feature is revealed to be a seed rather than a moat
Commoditization - what happens when a previously differentiated layer becomes cheap and standard, which is what happened to the application feature layer
Switching barriers - the workflow-depth moat that does not clone, built by absorbing more of the customer’s actual job
Network effect - the data-and-usage moat that makes a clone strictly weaker than the original it copied
Lean startup - the build-measure-learn framing that turns a feature from a deliverable into a probe, the learning loop that outpaces copying
First-mover advantage - why being first was only valuable during the growing season, and why that advantage compresses as copy-time collapses

The Acceptance Gap: Why an LLM Solution Is Not a Shipped Solution

tom@tomrochette.com (Tom Rochette) — Fri, 03 Jul 2026 00:00:00 +0000

Generation is solved. You describe, the model produces, and the candidate looks plausible in seconds. The bottleneck is no longer producing a solution; it is deciding that a solution is acceptable, and that gap is the one the model cannot close on its own.

I keep noticing the gap in two forms, and they fail for different reasons, which is why a single strategy like “review the output” addresses neither one well. One is a bug fix that the model swears it fixed and did not. The other is a feature that meets the description and still is not what I wanted. Both feel like the model failed, but the failure is in a different place each time, and the difference is the whole point.

The Gap Is Not One Gap
#

The distance between “a description of what I want” and “an acceptable solution I would ship” is not a single gap. It is two, stacked, and they respond to completely different interventions.

The first gap is about correctness. Did the change do the thing it was supposed to do, in the world, against ground truth the model cannot see? The second gap is about fit. Does the result match the thing I actually wanted, most of which I never wrote down?

Correctness is, in principle, objective. You can check it. Fit is, in practice, subjective. You can only feel it.

Most of the frustration people report with LLM coding comes from treating these two gaps as the same gap, and applying the tool that closes one to the other. The bug gap wants a check; the feature gap wants a reaction, and reaching for one when you need the other is why the work keeps coming back unfinished.

Bug Fixes: The Silent-Failure Gap
#

When I ask an LLM to fix a bug, it returns a patch that looks correct. It will explain the root cause in a confident voice, write a plausible diff, and tell me the issue is resolved. Often it is. Sometimes the patch addresses a symptom and the root cause resurfaces next week. Sometimes it fixes the exact reproduction I pasted but not the general case. Sometimes it fixes nothing at all, and merely rearranges the code into something that looks like a fix.

The model cannot tell me which of those happened, because the model has no access to the ground truth that would let it verify its own claim. It optimized for “a plausible fix,” not for “a verified fix.” Its confidence is not evidence, and nothing in the tone of the output distinguishes a genuine fix from a convincing one.

This silent failure is the dangerous kind, which testers have always called the oracle problem: without an independent way to decide what the correct output is, you cannot tell that a plausible output is wrong. The model has the problem in its most acute form, because it is both the thing producing the answer and the thing narrating why the answer is right. The narrator is not independent of the guess.

So for bug fixes I end up verifying manually. I reproduce the original failure, apply the patch, and check whether the failure is gone. Not because I enjoy the step, but because the model’s report of “fixed” is a hypothesis, not a result. A fix is not fixed until something independent of the model says so.

Features: The Taste Gap
#

When I ask an LLM to build a feature, the gap is different, and it fails for a different reason.

The feature works, in the narrow sense that it does what the description said. The gap is that “meets the description” is not “matches what I wanted,” because most of what I wanted was never in the description. It lived in taste. The feel of the interaction. The expectation about a default. The sense that this control belongs here and not there, that the empty state should say this and not that, that the feature is finished when it feels light rather than heavy.

I did not write any of that down, because I did not know I wanted it until I saw the result that lacked it. Subjective requirements work this way: they are discovered by contact with the artifact, not enumerated in advance. A specification can carry the objective part of what you want; it cannot carry the taste, because the taste is a reaction you have not had yet.

So the loop for features is not “verify,” it is “try.” Generate, run it, notice the distance between what I got and what I expected, describe that distance, regenerate. When the distance closes to zero, I stop. That stopping point, the “just ship it” moment, is a taste judgment, not a verification step. No test defines it. I define it, by being satisfied.

Why the Model Cannot Close Either Gap Alone
#

The two gaps look different, but they share one cause. Both are acceptance gaps, and acceptance requires information the model does not possess.

For bugs, the missing information is the ground truth of correct behavior. That truth lives outside the model, in an executable check or in a human observation. The model can guess at it, but it cannot consult it. For features, the missing information is my taste. That lives outside the model too, in the reaction I will have when I try the result. The model can guess at it from my description, but it cannot feel it.

In both cases the model can generate candidates freely, and in both cases it cannot sign off on them. Signing off requires exactly the external information that was never in the prompt, which is why no amount of rephrasing the prompt closes the gap.

This situation follows the same pattern I described in The Shifting Bottleneck: automating a layer does not remove the layer, it moves the constraint to the layer above it. Here the automated layer is generation, and the layer above it is acceptance. The work did not go away. It turned into deciding whether the generated thing is good enough.

What Closes Each Gap
#

The two gaps respond to different interventions, and the strategy is to match the intervention to the gap.

The bug gap is closeable in principle, and the mechanism is encoding. Write the acceptance criterion as a check the model cannot fake. A failing test that must pass. A reproduction script that must go green. A property the output must satisfy, stated before the fix is written. Once the check exists, the model can run it, and its claim of “fixed” becomes trustworthy only when the check agrees. The bug gap shrinks to exactly the set of bugs for which I have not yet written a check.

This practice is test-driven development, rediscovered as the answer to “why don’t I trust the model’s fix.” The discipline is to write the check before, or alongside, the fix, not after. A bug fixed without a check is a bug I will have to verify by hand, forever, because nothing is keeping it fixed. A bug fixed with a check stays fixed, because the check fails loudly if the bug regresses, whether or not I am looking.

The feature gap is not closeable the same way, and this is the uncomfortable part. I cannot write a test for “this feels right,” because I do not know the specification of my own taste until I see the result. Exploratory testing and specification by example help me identify more of what I want, but they cannot identify all of it, because the residual is a reaction, not a requirement. The feature gap closes only through iteration, and the terminal condition is a human saying “good enough, ship it.”

There is no encoding that removes the human from the feature loop, because the human’s reaction is the signal the loop is measuring. The best I can do is make the loop fast, so that each try is cheap and I can afford many of them. A model that generates in thirty seconds and an environment where I can try the result in ten more is a loop I can run ten times in a morning, and the tenth version is usually the one I ship.

The Mistake Is Treating Them as the Same Gap
#

Most of the waste in LLM-assisted work comes from applying the wrong tool to the wrong gap.

Treat the taste gap as a verification problem, and you write tests that pass and ship features nobody likes. The tests confirm the feature does what the spec said, which was never the question. The question was whether the spec was the right spec, and no test answers that.

Treat the verification gap as a taste problem, and you manually re-check, by hand, things the model could have checked for itself. You read a diff looking for whether the bug is really fixed, applying your eyes as a slow and unreliable oracle, when a failing test would have answered in a second and answered the same way every time. You waste on work the model could have done for you attention you should have spent on taste.

The split is sharp once you see it. If the gap is “did it do the thing,” that is a check, and the move is to encode the check so the model runs it without you. If the gap is “is this the thing I wanted,” that is taste, and the move is to iterate fast and trust the stopping judgment. Verification and validation are the old words for this distinction, and they have never been more useful than they are now: verify against the spec, validate against the want. The model can help with the first. It cannot do the second for you.

What to Do Next
#

Sort the next ten things you hand to the model into two piles.

The bug pile gets a check for each item, written first. If you cannot write a check that would fail before the fix and pass after it, you do not yet understand the bug well enough to delegate it, and the model’s fix will be a guess you have to verify by hand anyway. The check is the thing that makes delegation safe.

The feature pile gets a fast iteration loop. Cut anything that slows down the try-it-and-react cycle, because the cost of a feature is no longer the cost of building it, it is the cost of the number of tries it takes to match your taste. A model that builds cheaply makes many tries affordable, and that is what matters.

Leave the “is this good enough to ship” judgment to yourself. Generation is no longer the bottleneck, and neither, soon, is verification, once you encode it. The bottleneck is acceptance, and the half of acceptance that is taste is the last compounding thing you do. Nobody can write that prompt for you, which is exactly why it is the part worth keeping.

github-board - A kanban board for any GitHub search

tom@tomrochette.com (Tom Rochette) — Thu, 02 Jul 2026 00:00:00 +0000

GitHub’s issue and PR lists are flat. When you’re tracking a dozen repositories, or triaging hundreds of items, a flat list stops being a useful view of your work. GitHub Projects exists, but it demands manual triage and won’t adapt to an ad-hoc layout you want for the next ten minutes.

I built github-board to fix this. It turns any GitHub search into a customizable kanban board, defined entirely by small filter expressions. There is no backend, no build step, and no framework. You open index.html in a browser, paste a token, and build a board in seconds against live data. Try it live at tomzxcode.github.io/github-board.

The problem
#

A GitHub issue list answers one question well: what is in this repo, in this state. It answers almost every other question poorly. Which of my open PRs are drafts, which are waiting on review, and which have gone stale? How are issues spread across the area:* labels? What does the backlog look like across an entire organization?

You can build a GitHub Project board to answer these questions, but each card has to be placed and maintained by hand. The board reflects triage you did, not the state of your data right now. For a recurring view that’s worth the effort. For a one-off question you want to answer in 30 seconds, it isn’t.

How it works
#

You give github-board a search query, the same syntax the GitHub search bar already understands.

repo:owner/name

Then you define columns with boolean expressions over the fetched items. The board fetches up to 2000 issues and PRs through the GraphQL API with pagination, then groups them into columns entirely in your browser.

A default board ships with Draft PRs, Open PRs, Open Issues, and Closed columns. Each column is just an expression, and the board re-renders live as you type.

Columns and swimlanes as expressions
#

Every column is a filter expression against fields like type, state, labels, assignees, and dates.

type:pr and state:open and draft
type:issue and state:open and label:bug
state:closed and updated > -7d

The expression language supports the operators you’d expect: ==, =~, <, contains, in, exists, empty, plus regex matching and relative date math like -7d, -2w, -1y.

You can add a second dimension with swimlanes (rows), so a board can group issues by assignee across the same set of status columns, all from one query.

Auto-split with a $1 capture
#

Auto-split is the feature I use most. If you put a $1 capture in a column or lane rule, github-board expands it into one bucket per distinct matched value.

Name a lane area:$1 matching labels =~ /area:(.*)/i, and you instantly get one row per area label that exists in your data. Name a column the same way and you get one column per label. No manual setup per bucket, and buckets with no items simply don’t appear or stay empty depending on your preference. The $1 capture is the fastest way to see how work distributes across a category you didn’t know you cared about until just now.

Shareable links and presets
#

The entire view (query, filter, columns, swimlanes, and sort) is encoded in the URL hash. Click Share, send the link to a teammate, and they see your exact board using their own token. The token is never included in the link, so you can paste it anywhere.

For boards you return to, save the full configuration as a named preset. Presets persist in localStorage alongside your token, so everything stays in your browser.

Privacy and scope
#

github-board is read-only and has no backend. Requests go directly from your browser to api.github.com. You bring your own personal access token, which is stored only in your browser’s localStorage. There is no OAuth flow, no server logging, and no way for the tool to modify your issues or pull requests.

github-board is a view, not a project-management tool. There is no drag-and-drop across columns, because the board reflects your data, not where a card was dropped.

Getting started
#

No install is required.

Open tomzxcode.github.io/github-board (or open index.html from the repo).
Paste a GitHub personal access token with read access to what you want to view.
Open Settings and enter a query like repo:owner/name or org:your-org.
Click Refresh and adjust the columns to match your workflow.

If you already use gh-cached to browse issues without burning your rate limit, or ghx for agentic code reviews, github-board is the visual counterpart: the same GitHub data, arranged the way you want to see it right now.

llm-augmented-workflows - A config-driven automation engine for GitHub, powered by opencode

tom@tomrochette.com (Tom Rochette) — Thu, 02 Jul 2026 00:00:00 +0000

GitHub already provides a working event bus. Issues get opened, labeled, and closed; PRs get reviewed and merged; comments land on lines and threads. Every one of those events is a chance for an LLM agent to do useful work, triage the issue, draft a plan, reproduce a bug, post a review. The gap is not the events and it is not the agents. The gap is the code that connects them.

Today that connecting code is per-flow YAML. Every workflow you want to automate gets its own triage.yml, plan.yml, implement.yml, each with its own copy of the agent invocation boilerplate, its own trigger, its own label math, and its own drift. Add a fourth flow and you copy the file again. Change how the agent is called and you edit all of them. The workflows describe the same agent doing different things, but they share nothing.

I built llm-augmented-workflows to reduce all of that duplication to one file. You describe every flow as event-matched rules in a single .github/llmaw/flows.yml, and the dispatcher routes GitHub events to the right agent skill, with token-free label and shell steps for the transitions that do not need a model.

The problem
#

The moment you try to automate more than one agent-driven flow, the per-file pattern breaks down.

Each flow duplicates three things that it should not duplicate. First, the wiring: trigger on this label, run the agent, relabel, wait for the next event. Second, the agent invocation: which model, which skills repo, which timeout, which working directory. Third, the outcome handling: what to do when the agent says approved, rejected, or needs changes.

That duplication has a cost. Workflows drift from each other. The agent invocation that worked yesterday is copy-pasted into the new flow with the old model id. A label rename in one file does not propagate to the others. And the parts of the flow that do not even need an LLM, relabeling an issue, posting a fixed comment, closing a linked issue on merge, still incur a model call because the file is built around one.

What you want is to describe the flow once, and let the engine handle the wiring.

How it works
#

The engine is a small stateless dispatcher with one reusable GitHub Actions workflow. State is stored entirely in GitHub, in labels, issues, and PRs. The engine reads an event, matches it against flows.yml, runs the matched rule’s pipeline, and exits.

GitHub event (issue labeled, PR merged, comment, ...)
   |
   v
dispatch.yml  reads flows.yml  ->  route matches rule(s)
   |
   v
for each matched rule, run-rule runs its whole `run` in one pass:
   labels/shell (pre) -> skill (opencode) -> labels/shell (post) -> on_outcome
   |
   v
the agent acts on GitHub (relabel, comment, open PR, close) -> emits new events

The pipeline is the unit of work. A rule’s run is an ordered list of steps, and the engine runs them in one pass: token-free label and shell steps can run before and after the agent, the agent step calls an opencode skill, and on_outcome maps the agent’s verdict to labels, a close, or a comment. Because relabeling emits a new event, the next phase of the flow is just another rule that matches the new label. Terminal outcomes need no special handling: an agent closes an issue (won’t fix), or a PR merges and an on-merge rule closes the linked issue.

One config file, not one workflow per flow
#

Every flow is defined in .github/llmaw/flows.yml. A flow is a list of rules, and a rule is a when (the event match) plus a run (the ordered pipeline).

defaults:
  model: opencode/deepseek-v4-flash-free
  agents_repository: tomzx/agents
  timeout_minutes: 30
flows:
  plan:
    rules:
      - id: generate-plan
        when: { event: issues, action: labeled, label: plan-needed }
        run: [ { skill: generate-plan } ]
      - id: on-plan-merged
        when: { event: pull_request, action: closed, merged: true, branch_prefix: plan/ }
        run: [ { labels: { add: [plan-approved], target: linked-issue } } ]
      - id: implement
        when: { event: issues, action: labeled, label: plan-approved }
        run: [ { skill: implement-plan } ]

Read the file top to bottom and you have the whole flow. An issue gets plan-needed, the generate-plan skill runs and opens a plan/... PR. When that PR merges, on-plan-merged adds plan-approved to the linked issue, no model involved. When the issue is labeled plan-approved, the implement-plan skill runs and implements it. Three rules, one file, one copy of the wiring.

Token-free transitions
#

Token-free transitions are the feature that justifies the whole design.

Relabeling an issue does not require an LLM, and neither does closing a linked issue on merge or posting a deterministic comment. In llm-augmented-workflows, labels and shell steps run without calling the model at all. The on-plan-merged rule above is a single label step: when the plan PR merges, add plan-approved to the linked issue. Zero tokens, zero model latency, one GitHub API call.

That means the agent only runs where the agent is actually needed, and the transitions between phases use no tokens, run fast, and are deterministic. A flow that used to cost three model calls (triage, plan, implement) plus the steps between them now costs two, because the step between them is a label.

Two execution modes
#

Each matched rule’s pipeline runs in one job. What happens after the pipeline is controlled by the execution mode:

event-driven (default): the rule runs once and the job ends. The relabel emits a new event that re-triggers the dispatcher for the next phase. One job per phase, each one independently observable in the Actions log.
continuous: the same job keeps advancing to the next rule based on the labels each rule adds, until llmaw:needs-human appears or the chain reaches a resting state. One job per pipeline, the whole end-to-end run in one log.

Set it under defaults.execution or per flow, force it per dispatch via the execution input or the LLMAW_EXECUTION repo variable. Event-driven is easier to debug; continuous is easier to watch flow end to end. The same flows.yml works in either mode, because the mode is about how the engine chains rules, not how the rules are defined.

Skills come from your agents repository
#

The skill step does not run an inline prompt. It runs an opencode skill sourced from a configurable agents repository, tomzx/agents by default, overridable with AGENTS_REPOSITORY.

That separation is important. The flow definition says what should happen and when. The skill definition says how the agent should do it. When you improve the generate-plan skill, every flow that references it gets the improvement, without touching flows.yml. When you add a new flow, you reference an existing skill instead of inlining a prompt that will fall out of date.

The default flow runs on the free model
#

The default model is opencode/deepseek-v4-flash-free, and it needs only the auto-provided GITHUB_TOKEN. You can adopt the engine on a throwaway repo without provisioning a single secret. Override per repo or per org with OPENCODE_MODEL, point AGENTS_REPOSITORY at your own skills, raise LLMAW_MAX_ITERATIONS for long continuous runs, and you are done.

Getting started
#

Three steps.

Add one wrapper workflow to your repo, pinning the dispatcher by ref.

.github/workflows/llm-workflows.yml

name: LLM Workflows
on:
  issues: { types: [opened, labeled, reopened, closed] }
  pull_request: { types: [closed, labeled, ready_for_review] }
  issue_comment: { types: [created] }
  pull_request_review_comment: { types: [created] }
permissions:
  contents: write
  pull-requests: write
  issues: write
jobs:
  dispatch:
    uses: TomzxCode/llm-augmented-workflows/.github/workflows/dispatch.yml@v1
    secrets: inherit

Add .github/llmaw/flows.yml describing your flows. Start from the example above or the docs/flows.md recipes for triage, close-on-merge, and per-step overrides.
Run the Setup Labels workflow to create the labels declared under labels:, or let your flows add them as needed.

Pin @v1 for the latest within a major tag, @main if you want to track the tip, or @<full-sha> for an immutable production pin.

Consumers never copy the engine. The dispatcher checks this repository out into .llmaw/ on the worker and runs uv run --project .llmaw llmaw ..., pinning the version via the wrapper’s uses: ref.

What it does not do yet
#

The engine’s unit of work is one issue per workflow execution. A matched rule runs, the agent acts, the job ends (or chains within continuous mode until needs-human), and the next event is the next run. That model fits small, well-scoped work well: triage this issue, plan this feature, reproduce this bug, implement this task.

It does not fit a large epic. A change that spans many tasks, many PRs, and many days cannot be implemented by a single issue’s pipeline, because the engine has no concept of an epic as a first-class object that owns child issues and tracks their aggregate progress. To implement a large change today, you have to break the epic into per-task issues yourself, outside the engine, and let each of those issues run its own one-issue pipeline. The decomposition step, deciding how to split the work and how the pieces depend on each other, is not automated.

Closing that gap is the next phase of the problem, and it is where the needs-human checkpoint currently does the most work. Until the engine can take an epic, decompose it into ordered tasks, and drive each task through its own run while tracking the whole, large changes stay a manual decomposition followed by automated execution.

Why this structure
#

I have been writing about the pieces of this for a while. Loops as Files argued that the trigger layer deserves the same treatment as the prompt layer, versioned, reviewable, owned next to the behavior it schedules. The Self-Evolving Repository pushed the question of how far you can take a GitHub project where every maintainer function is replaced by an automated loop. llm-augmented-workflows is the engine for both: the flows file is the schedule, the skills are the behavior, and the state stays in GitHub.

If you already use ghx for agentic code reviews or github-board to visualize your issues, llm-augmented-workflows is the layer that keeps the issues moving.

Defects Flow Downstream, Fixes Must Flow Upstream

tom@tomrochette.com (Tom Rochette) — Tue, 30 Jun 2026 00:00:00 +0000

The further upstream a defect is born, the more code it contaminates, and the more expensive it becomes to remove. This has been true for as long as software has had a lifecycle. Two things have changed, and both point the same way. First, the generation step is now automated, so upstream defects become downstream output at machine speed. Second, the old habit of patching defects in place no longer works as well as it used to. Once the pipeline executes itself, the only durable fix is the one made at the source, and every fix made downstream is a patch you will have to make again.

The Pipeline Has Always Run One Way
#

Software development is a one-directional sequence of stages. Each stage constrains the next: needs become requirements, requirements become a specification, the specification becomes an architecture, the architecture becomes code, the code is verified, shipped, and operated. A decision at any stage narrows the space of what is possible at every stage below it, and an error at any stage is inherited by everything that descends from it.

This directionality is why the cost of removing a defect rises so steeply the later you find it. Boehm and Basili put a number on it more than two decades ago: finding and fixing a software problem after delivery is often a hundred times more expensive than finding and fixing it during requirements and design. The exact multiplier is debatable, but the slope of the curve is not. Each stage a defect survives multiplies its removal cost, because each stage builds artifacts on top of it that all have to be reworked when the foundation moves.

The industry already has a name for the obvious response. It is called shift-left testing, and the move it prescribes, pushing verification earlier in the lifecycle, is correct as far as it goes. But shift-left is a half-measure, because it moves the act of checking earlier without moving the act of fixing to where the defect was born. The deeper move is not “test earlier.” It is “fix at the origin,” and the two are not the same. Testing earlier finds the symptom sooner; fixing at the origin ensures the symptom is never generated again.

The Amplifier Got an Engine
#

Before LLMs, a human wrote the code, and the human did not translate the specification perfectly. That imprecision mattered. When the spec was ambiguous, the human made a judgment call, often a reasonable one, and that judgment caught some of the upstream defect before it could reach the running system. The defect still propagated, but through a person who could correct it before it reached the running system.

The model does not absorb ambiguity. It resolves it, once, in the direction of whatever is most probable, and then it writes that resolution into every file it touches. The generation step stopped being a filter and became an amplifier, and it amplifies whatever it was given, including the gaps. One ambiguous line in a specification becomes a dozen consistent, plausible, uniformly wrong code paths, in seconds, and they all look correct because they all agree with each other.

This is the actual intensification. The cost curve was always steep, and it is now steep and fast. The window in which a human used to catch an upstream defect by “just writing the code” has closed, because the code writes itself before the human has time to notice the spec was vague. By the time anyone reads the output, the upstream defect has already been faithfully reproduced across the diff, and the reviewer is left arguing with the symptom instead of the cause.

Why Consequences Fan Out
#

The reason early stages matter more than late stages is not only that they are cheaper to fix. It is that their defects multiply downstream while late-stage defects mostly do not.

A bug in code affects the code that contains it. A gap in the architecture affects every component built on top of it. A missing or wrong requirement affects every architecture that tries to satisfy it, every component that implements it, every test that verifies it. The earlier the stage, the larger the fan-out, because the larger the subtree of artifacts that descend from it.

This fan-out is why a specification defect is not just “a bug, but earlier.” It is a different category of problem, one whose blast radius grows with the distance from the source. A single ambiguity in a spec can be the common ancestor of a hundred production incidents, each of which looks like a separate bug to the engineer who responds to it, and each of which is, in fact, the same defect. Treat them as separate bugs and you will fix a hundred symptoms. Treat them as one and you fix the spec once.

Nancy Leveson reached the same conclusion from the study of accidents in Engineering a Safer World. Serious failures are rarely caused by a single component breaking. They are caused by flawed control structures upstream that set the components up to fail together, and the component failure is merely the place the upstream flaw became visible. The component is the symptom. The control structure is the cause. Fixing the component prevents that one incident, and fixing the control structure prevents the class. A pipeline stage is a control structure, and in software the earliest stages are the ones with the widest reach.

The Fix Belongs Upstream
#

Here is the operational consequence, and it is the whole argument in a single rule.

When a defect appears in code, there are two places to fix it. You can fix the code, which removes the symptom from this instance. Or you can fix the upstream artifact that produced the code, which removes the cause from every instance.

The two fixes look similar and are not. A code fix is a non-compounding fix. It patches one occurrence, leaves the source intact, and guarantees that the same defect will be regenerated the next time the pipeline runs against the same upstream artifact. A spec fix is a compounding fix. It changes the source, and every future generation inherits the correction automatically, for as long as the artifact exists.

This is the same compounding-versus-one-time distinction that makes specification outrank review, as Rethinking Code Review in the Age of LLMs argues: review catches a defect once, for the reviewer who happens to be reading, while a spec prevents the whole class from being generated. The principle does not stop at review. It runs the entire length of the pipeline. The defect you patch in code today is the defect the model writes again tomorrow from the same ambiguous spec, and the defect you fix in the spec today is the defect the model never writes again.

The discipline this implies is uncomfortable for teams that grew up triaging bugs at the bottom of the pipeline. It says that most “code bugs” in an AI-assisted codebase are not code bugs at all. They are specification bugs, or architecture bugs, that happened to surface in code. Treating them as code bugs, by fixing the code, removes the visible problem while leaving the source in place to produce the same problem again next sprint.

A useful diagnostic comes straight from the five whys and the Toyota andon tradition: when the same class of bug appears more than once, stop the line, walk back up the pipeline asking why until you reach a process cause, and fix the process, not the product. Fixing the product gets you a working unit today. Fixing the process gets you a working line forever. The two investments have almost nothing in common, and teams that confuse them spend their lives re-fixing the same bug in new files.

What This Changes About Where You Spend Effort
#

If consequences amplify downstream and fixes compound upstream, then the allocation of engineering effort across the lifecycle is exactly inverted from where most teams spend it.

Most effort sits at the bottom of the pipeline. Writing code, reviewing code, fixing code, handling production incidents: these are the stages with the smallest blast radius and the least compounding return. They feel urgent because they are where the pain is visible, but they are also where an hour of effort produces the least durable improvement, because the upstream artifacts that produced the pain are still in place, still generating.

The high-leverage stages are at the top. Requirements, specification, and architecture are the stages whose defects fan out the widest and whose fixes compound the longest. They feel less urgent because the pain they cause has not happened yet, and when it does happen it will be blamed on the code, not on the spec that produced the code. The problem is that work at the bottom of the pipeline demands attention while work at the top does not, and most teams respond to what demands attention rather than to what compounds the most.

This is the same relocation The Shifting Bottleneck describes from a different angle. Once code writes itself, the bottleneck moves to verification, and the highest-leverage response is not to verify harder but to specify better, because specifying better reduces the volume of bad output that verification ever has to catch. You are not rewarded for being good at a late stage. You are rewarded for making the late stage unnecessary by being good at an earlier one.

What to Do Next
#

A few concrete moves follow, and each is an inversion of the default.

Treat every repeated bug class as an upstream defect. When the same kind of issue shows up a second or third time, stop fixing it in code. Walk back up the pipeline until you find the artifact that allowed it, and fix that. The rule is blunt and useful: fix at the source once, or fix at the symptom forever.

Invest disproportionately in specification. The spec is now the highest-leverage artifact in the pipeline, because it is the stage whose defects fan out the widest and whose fixes compound the longest. A team that under-invests here suffers in every downstream stage, forever, at machine speed, and a team that over-invests here barely notices the downstream stages at all.

When you review, review the spec, not the code. Code review catches symptoms once, on the diff that happens to be in front of the reviewer. Spec review prevents classes of symptoms from being generated at all, across every future diff. An hour on the spec outranks an hour on the code, because the code is downstream of the spec and the spec constrains every diff that will ever be written from it.

Keep an upstream ledger on incidents. When something breaks in production, record not just the code-level cause but the pipeline stage where the defect was actually born. Over a quarter the pattern will show which upstream stages produce the most defects, and that is where investment pays back the most, because a single fix there removes a whole class of incidents.

And when the model produces bad output in the same module twice, do not write a longer prompt. Fix the module, or fix the spec that describes it, because as The Importance of Context When Interacting with LLMs argues, the upstream artifacts are the model’s context, and bad output is the truest signal you will ever get about where that context is incoherent. The model is showing you where the context fails. The right response is to fix the source of the bad output, not to keep correcting it by hand.

The Lifecycle Runs One Way
#

Defects move downstream through the pipeline and multiply as they go. Fixes can move upstream, and they multiply too, but in the opposite direction: one fix at the source prevents a thousand fixes at the symptom.

The team that understands this spends its best hours at the top of the pipeline, writing specifications and architectures that make most downstream defects impossible. The team that does not spends its best hours at the bottom, fixing code that the pipeline keeps regenerating from sources it never touches. Both teams are busy. Only one of them is getting durable work done. In an era when the downstream stages execute themselves, the only engineering that compounds is the engineering done at the top of the pipeline. Everything below it is maintenance.

References
#

Boehm and Basili, “Software Defect Reduction Top 10 List” - the finding that a defect fixed after delivery is often around a hundred times more expensive than one fixed at requirements, the original cost-of-fix curve
Leveson, “Engineering a Safer World” - the argument that accidents trace to flawed upstream control structures rather than component failures, so the component is the symptom and the structure is the cause
Wikipedia, “Theory of Constraints” - the pipeline framing in which improving one stage relocates the constraint rather than removing it
Wikipedia, “Shift-left testing” - the existing industry term for moving quality earlier, framed here as a partial move that checks sooner without fixing at the origin
Wikipedia, “Five whys” - the practice of walking back from a symptom to its process cause before fixing, the root of the “fix the process, not the product” rule
Wikipedia, “Andon (manufacturing)” - the Toyota practice of stopping the line to fix the source of a defect rather than passing it downstream
Wikipedia, “No Silver Bullet” - Brooks’s split between accidental and essential complexity, where most late-stage fixing is accidental work that better upstream artifacts would eliminate

Read the Commits, Not the Manual: What OpenClaw's Git History Reveals About Scaling a Project

tom@tomrochette.com (Tom Rochette) — Tue, 30 Jun 2026 00:00:00 +0000

The most revealing document a software project writes is not its README, its CONTRIBUTING.md, or its architecture diagram. It is its commit history, because the commit history is the one artifact the project cannot rewrite after the fact. A process doc describes the project the maintainers wish they were running, and the commit log describes the project they are actually running, and the gap between the two is where you can find the most important lessons.

I spent time inside the git history of OpenClaw, a self-hosted personal AI assistant that talks to you across roughly two dozen messaging channels. It is an extreme case, and extreme cases are the easiest to read. In about seven months it accumulated over sixty-two thousand commits from more than three thousand contributors, which is somewhere close to two hundred and ninety commits a day, every day, since its first commit. That is a throughput at which most projects would have become impossible to follow, and it did not. The interesting question is why, and the commit history answers it more clearly than any roadmap could.

This article is a reading of that history, and the throughline is a single observation that the data makes impossible to miss. A project’s actual architecture is not the dependency graph of its packages. It is the role structure of the people who land commits on it, and OpenClaw reveals that role structure with unusual clarity because it is large enough that the patterns survive any individual’s bad week.

The First Thing the Commits Show: Two Kinds of Maintainer
#

Run a contributor breakdown on any mature project and you will find that the top commit counts are dominated by one or two names. OpenClaw is no different. The founding maintainer, Peter Steinberger, is listed in CONTRIBUTING.md as “Benevolent Dictator,” and he accounts for well over half of all commits in the repository, roughly three times the next contributor. The second name down is Vincent Koc, listed as owning “Agents, Telemetry, Hooks, Security.”

You can read their titles and learn nothing, or you can read their commits and learn everything. The commit prefix and the merge behavior are the two signals that tell you what a maintainer actually does all day, and at OpenClaw they tell two completely different stories.

Roughly ninety-five percent of Peter Steinberger’s recent commits land straight on main with no pull request at all. His work spans every conventional-commit prefix in roughly equal measure: test:, fix:, docs:, ci:, refactor:, perf:. His scopes are the product itself, the agents, the gateway, the release machinery, the high-traffic channels. Read his last two hundred commits and you are watching someone expand the product, exploring whatever he finds interesting that week, shipping releases, writing the docs for features he just invented, and rarely pausing to open a pull request against his own work.

Vincent Koc’s history is the opposite pattern. His recent work is almost sixty percent fix commits, and his scopes are a completely different surface: end-to-end tests, the QA lab, scripts, CI, and a scope that appears nowhere near the top of Peter’s list, deadcode. He opens pull requests. He uses the review process. Where Peter’s commits read as exploration, Vincent’s read as consolidation.

The contrast between Peter’s history and Vincent’s is the observation that triggered this article, and the temptation is to read it as a process failure on Peter’s part, the founder cutting corners, ignoring the queue, doing whatever he wants. That reading is wrong, and it misses the point. The two patterns are not the same job done at different levels of discipline. They are two different jobs, and a project of this size needs both of them to survive.

The Benevolent Dictator and the Steward
#

Strip the moral framing away and what you are looking at is a role separation so fundamental that every healthy long-lived project eventually rediscovers it, whether it documents the split or not.

One role is the visionary, the person whose job is to expand the product’s capabilities. They build features that no user has asked for yet, because no user knows to ask for them. They write docs in the same commit as the code, because to them the doc is part of the feature. They commit straight to main because the bottleneck they are optimizing for is their own momentum, and stopping to open a pull request against themselves would be pure ceremony. The visionary does not read the issue tracker for direction. They read it, when they read it at all, for confirmation that the thing they already wanted to build has some demand. Their commits are the product roadmap, written as the work happens.

The other role is the steward, the person whose job is to keep the project stable as the visionary expands it. They fix the bugs the new features introduced. They write the end-to-end tests that prove the feature actually works under load. They remove the dead code the visionary left behind when they pivoted. They route pull requests from the long tail of contributors through review, because someone has to, and the visionary will not. Their commits are almost entirely fix, test, refactor, chore, and they open pull requests not out of greater virtue but because their work touches shared, critical surface where a mistake costs everyone.

The visionary produces the disorder that makes the project grow, and the steward does the work that keeps the disorder from being fatal, and neither role is superior to the other. A project with only visionaries ships exciting broken things that no one can depend on. A project with only stewards stays clean and slowly dies, because no one is building the thing anyone wants to use next. OpenClaw has both, in volume, and that is the first and most important reason it has not collapsed under its own commit rate.

The practical lesson, if you run a project, is to name this split out loud instead of letting it generate resentment in silence. The most common failure mode is a steward who slowly concludes that the visionary is careless, and a visionary who slowly concludes that the steward is a brake on progress, when in fact each is doing exactly the job the other cannot. Peter’s direct-to-main habit is not a defect Vincent is tolerating. It is the signature of a role, and recognizing it as a role is what stops it from becoming a feud.

The Specialist Roles That Only Appear at Scale
#

Past the two primary roles, the commit history reveals two more contributors whose work is so specialized it would be invisible in a smaller project, and whose existence is itself a signal of size. A project small enough for everyone to do a bit of everything has no specialists, and the appearance of specialists is a sign of a project that has grown past the point where generalists can cover the surface.

The third most prolific contributor, going by Shakker, has roughly four thousand commits, and about two thirds of them are test:. There is almost no feature work in the history. Shakker is a person whose entire contribution is the test fixtures, the regression coverage that lets everyone else move fast without the product silently breaking. A visionary cannot do this work, because it requires the patience to write the hundredth test for a path the fortieth test already almost covered, and a steward is usually too busy handling urgent fixes to write tests in advance. The test author is a third role, and it is the role that converts the steward’s fixes from one-off patches into guarantees that do not have to be re-earned.

Further down the list, Tak Hoffman has a thousand-plus commits, and he owns a scope that appears in almost nobody else’s history: (regression). Of the hundred-plus commits in the repository tagged fix(regression):, almost all of them are his. Tak is a regression hunter, someone whose focus is not bugs in general but bugs in things that used to work, the specific class of defect that damages user trust faster than any missing feature can earn it. Regression hunting is a discipline of its own, because it requires holding a mental model of how the system used to behave and noticing when a change has quietly violated it, and it is the kind of work that only gets staffed deliberately once a project is large enough that the founding maintainer can no longer hold the whole behavior graph in their head.

The lesson is that the visionary-and-steward split is a starting frame, not a complete one. As a project grows, the roles keep subdividing, and each subdivision is a person whose commits tell you, by their narrowness, exactly what the project is now too large to handle with generalists. Read the contributors with unusual scope concentrations and you read the project’s scaling problems written out in advance.

The Second Thing the Commits Show: The Ownership Table Is the Architecture
#

Three thousand contributors is a number at which coordination by conversation breaks down completely. You cannot have a meeting with three thousand people. You cannot maintain a shared mental model with three thousand people. The only way a project absorbs that many contributors without a backlog of unmerged pull requests is to partition the work so thoroughly that most contributors never need to talk to each other at all.

OpenClaw partitions the work with an explicit ownership table, and it is the most underrated document in the repository. CONTRIBUTING.md lists roughly thirty maintainers, each with a named specialty: one owns Telegram, one owns the iOS app, one owns Memory, one owns the Discord subsystem, one owns Chinese channels and nothing else. The instruction to contributors is blunt: “Do not guess who to tag,” route through the ownership list, the label automation, and CODEOWNERS instead.

When the surface area of a project exceeds what any one person can hold in their head, the only scalable architecture is a partition, and the partition has to be written in a file, not stored only in people’s memories. The plugin layout reinforces the partition from the code side. There are around a hundred and forty-five extensions and only twenty-one core packages, and the project’s own vision document states the principle outright: core stays lean, capabilities ship as plugins, and the bar for adding an optional capability to core is “intentionally high.”

The plugin partition is the same insight as the role split, applied at the level of the codebase rather than the people. You cannot hold one hundred and forty-five channel adapters in your head, but you do not have to, because each one is owned by one person who only has to hold one in theirs. The partition is the architecture, and the ownership table is the partition made durable. A project that grows past a few active contributors without writing this table down is a project that will discover, painfully, that the absence of an ownership map is itself an architecture, an architecture in which the loudest reviewer owns everything by default.

The Third Thing the Commits Show: Every Rule Is a Scar on Reviewer Time
#

The contribution rules in OpenClaw are unusually specific, and a first-time reader will find some of them almost hostile. There is a hard cap of twenty open pull requests per author, enforced automatically, past which your pull requests are labeled and closed. Refactor-only pull requests are refused outright. Test-only or CI-only pull requests that chase a known main failure are refused outright. Pull requests over roughly five thousand changed lines are reviewed “only in exceptional circumstances.” One pull request must equal one issue or topic.

Taken in isolation, the rules read as pettiness. Read as a group they are responses to one specific, recurring problem, and the problem is always the same. Every one of these rules is a response to something that once drained reviewer attention without producing proportional value, because reviewer attention is the single scarcest, least-elastic resource a project at this scale has.

The visionary can always produce more commits. The contributor pool can always produce more pull requests. Neither of those can produce more maintainer-hours for review, and so the entire rule set is engineered to protect that one bottleneck. The twenty-pull-request cap exists because batch-opened pull requests impose review cost in proportion to their number, not their value. The ban on refactor-only work exists because a refactor that changes no behavior consumes review to confirm it changes no behavior, which is review spent proving a negative. The line limit exists because a five-thousand-line diff cannot actually be reviewed by a human, it can only be rubber-stamped, and rubber-stamping is the failure mode the gate is supposed to prevent.

The rule set is the theory of constraints applied to a volunteer workforce. When you cannot add capacity at the bottleneck, the only option left is to reduce the demand arriving at it, and you reduce demand by making rules that reject the classes of work that waste the bottleneck’s time. A rule that reads as harsh to a contributor is almost always a rule that reads as triage to a maintainer who has been doing the job long enough to know which inputs are waste.

The Fourth Thing the Commits Show: They Dogfood the Future of Development
#

OpenClaw builds an AI agent, and it builds it with AI agents, and the commit history makes the second fact as visible as the first.

Bot accounts appear throughout the contributor list. The contribution guide treats AI-authored pull requests as first-class citizens, requiring only that they be marked, with a checklist that asks for the model, the prompt or session log, and a human confirmation that the code is understood. Codex review is not an experiment: it is described as the “current highest standard of AI review,” expected to run on every pull request and to be addressed by the author before a human reviewer is ever bothered.

The reason the dogfooding matters is not that it is futuristic. The project is a working answer to the question every team is now trying to solve, which is how to integrate generated code without being overwhelmed by it. The OpenClaw answer is not to ban generated contributions and not to blindly trust them, but to treat their provenance as a required signal and to route that signal into both the review and the reviewer.

OpenClaw’s approach is the provenance argument I made, from the maintainer’s side, in Triaging Open Source Pull Requests: the one piece of information a reviewer most needs about a modern pull request is which model produced it and what prompt produced it, because that is the information that tells you which blind spots to check for. OpenClaw asks for the model and the prompt, up front, in the template, and it pairs the request with an automated review pass that can be calibrated against the disclosed model. That pairing, disclosure plus targeted automated review, is the most credible workflow I have seen for accepting generated code at volume, and it is sitting right there in a CONTRIBUTING.md that most projects have not yet caught up to.

How to Read a Project This Way Yourself
#

The method that produced these observations is generalizable, and it costs you nothing but a terminal. You do not need access to a project’s Slack, its planning board, or its maintainers’ intentions. You need its git history and three commands.

Start with the contributor breakdown, git shortlog -sne, and look at the ratio between the top name and everyone else. A project whose top contributor’s commit count is far larger than everyone else’s is a project whose direction is set by one person, and everything else is execution. A project whose top contributors are close in volume is a project run by committee, and its commits will read as negotiation rather than vision.

Then take the top two or three names and compare their conventional-commit prefixes, git log --author=... --format=%s, grouped by prefix. The ratio of fix to feat, the presence or absence of docs and test, the dominance of refactor or chore, these tell you who builds and who maintains, and they tell you in five minutes what would take a month of standups to learn. A maintainer whose commits are sixty percent fix is a steward. A maintainer whose commits span every prefix evenly is a visionary. The prefix distribution is a sign of a role, and reading it is faster and more reliable than reading anyone’s job title.

Finally, count how many of each top contributor’s commits reference a pull request versus landing straight on main. That ratio is the governance signal. A project where even the founder routes through pull requests is a project run by process. A project where one person lands on main freely and the rest use pull requests is a project that has, whether it admits it or not, a benevolent dictator and a steward, and the rest of the contribution rules will make sense once you see the split.

Run this analysis on your own project before you run it on anyone else’s. You may find that the role structure you assume you are running is not the one your commits describe, and the gap is the first thing worth fixing.

What to Do Next
#

If you maintain a project, take an hour and read your own commit history the way this article reads OpenClaw’s. Find your visionary and your steward, and if you do not have both, that is the single most important hiring or delegation decision in front of you. A project with no steward is slowly declining under a growing backlog of unmerged fixes and unread pull requests, and no amount of feature velocity will save it.

Write down your ownership table, explicitly, in a file, even if it is just three names today. The day you have thirty contributors is too late to invent the partition, because by then the loudest reviewer will have quietly become the owner of everything, and reversing that is a political problem rather than a documentation one. The partition is cheap to write early and expensive to write late.

Audit your contribution rules as a set, not individually. Every rule that reads as harsh to a contributor should correspond to a specific class of work that once wasted your review time. Any rule you cannot trace back to a specific class of wasted review time is a rule that is probably driving contributors away without being worth its cost, and it is a candidate for deletion.

References
#

OpenClaw on GitHub - the repository whose commit history, CONTRIBUTING.md, and VISION.md are the primary sources for every observation in this article
Wikipedia, “Theory of Constraints” - Goldratt’s framing for why you protect the bottleneck rather than adding effort elsewhere, the basis for reading OpenClaw’s rules as reviewer-time conservation
Wikipedia, “Benevolent dictator for life” - the canonical name for the role OpenClaw’s commit history reveals in its top contributor, independent of any title

Team Maturity Explains the Friction, the Foundation Predicts the House of Cards

tom@tomrochette.com (Tom Rochette) — Tue, 30 Jun 2026 00:00:00 +0000

In the age of LLMs, the work that matters at your job is no longer adopting the tools. It is raising the velocity at which your team can ship features without turning the software it builds into a house of cards. When two teams hold the same tools and get wildly different outcomes, the first thing to study is the team itself, and Bruce Tuckman’s model of group maturity will explain a large share of the gap. But it will not explain all of it, because team maturity governs how easily a team absorbs a new practice, not whether the software that practice produces stays standing. Maturity is necessary and it is not sufficient, and most organizations are diagnosing only half the problem.

The Job Is Velocity Without Debt
#

Raw velocity stopped being interesting the year a model could draft a feature in an afternoon. Anyone can go fast now. The constraint that separates serious teams from reckless ones is sustainable velocity, the ability to ship quickly and also keep the system survivable as it grows.

The distinction is not new, and AI did not invent it. The DORA research program spent years measuring engineering organizations along two independent axes, throughput and stability, and its central finding was that you have to track both because they are not the same thing. Throughput is lead time and deployment frequency, how fast work gets out. Stability is change failure rate and time to restore, how often what you ship breaks and how long it takes to recover when it does. A team can score high on throughput and low on stability, and that team is not fast. It is a house of cards being shuffled quickly, and the cost arrives as rework, outages, and a codebase nobody is willing to touch.

LLMs increase the throughput axis for free. They do nothing for the stability axis unless your engineering system is built to hold them accountable. So the whole question of which teams ship effectively with LLMs collapses into a narrower one: which teams can absorb the throughput multiplier without their stability metrics collapsing? That is a property of the team and a property of the code, and the team part is only half of the problem.

Why Tuckman Explains So Much of the Adoption Gap
#

Before moving to the other reasons, it is worth being realistic about how much Tuckman’s stages of group development actually explain, because the answer is a lot.

A team in the performing stage adopts a new AI practice with low friction for reasons that are structural, not cultural. Its members have already negotiated how decisions get made, so “which code review workflow do we use now that the model writes most of the code?” gets resolved in one meeting instead of three. Its conventions are settled and shared, so when an engineer introduces a prompt template or a skill, the rest of the team can tell whether it fits the way they already work. It has the psychological safety that Project Aristotle identified as the strongest predictor of team effectiveness, which means an engineer can say “the model’s output is wrong here and I do not understand why” without that admission costing them status.

A team still in forming or storming has none of these assets, and so it pays the cost of adoption on every change. As I argued in When Engineers Disagree on Best Practices, a team that has not yet built a repeatable process for resolving disagreements will relitigate the same practice debate over and over, and the debate is rarely about the practice. It is a proxy for unresolved questions about whose judgment the team trusts. LLM adoption surfaces a dozen of these questions at once, because it touches review, testing, specification, ownership, and onboarding simultaneously. A performing team processes all those questions in the background. A storming team is overwhelmed by all of them.

So if your observation is “some teams picked up the new AI workflows easily and others fought about it for two quarters,” Tuckman is very likely your explanation. Team maturity is the dominant predictor of adoption friction, and adoption friction is the dominant predictor of whether a team even gets to the starting line.

What maturity does not predict is what happens after the team starts shipping.

The House of Cards Is Predicted by the Foundation
#

Here is the gap maturity cannot close. A mature, high-trust, psychologically safe team sitting on top of a brittle codebase with no tests and no specification discipline will still ship a house of cards. It will just do so with impressive cohesion, minimal interpersonal drama, and a strong retrospective culture. The team dynamics are good and the software is still wrong, because the things that decide whether generated code stays standing are properties of the engineering system, and those properties vary somewhat independently of how well the team gets along.

If you want to know why two mature teams with the same tools ship software of very different durability, look at the foundation. The factors below are not equal in importance. Two of them, verification and codebase health, decide whether the software stands up at all, and the other four only improve the quality of what gets built. No amount of strength in the four can compensate for weakness in the two, because the two are what keep the structure standing. For shipping without a house of cards, verification and codebase health outrank team maturity, and the rest exist to support them.

The two factors that outrank maturity
#

These are the structural ones. A team weak on either of them ships a house of cards regardless of how mature it is, and a team strong on both can survive even rough team dynamics. Everything else in the foundation eventually feeds into one of these two.

Verification is the throttle
#

Once code writes itself, the bottleneck moves to checking whether the code is correct, and that move is the central claim of The Shifting Bottleneck. Verification is where the stability axis lives, and verification is why two teams with identical throughput can have radically different change failure rates.

The team with a fast, trustworthy test suite, a CI pipeline that catches actual regressions, and a short feedback loop can let the model generate aggressively, because it can verify cheaply. Every generation is a hypothesis and the test suite is the experiment, and the cost of a wrong generation is seconds. The team that verifies by reading the diff, or by running the feature once in a staging environment, cannot afford to let the model run. It hits a ceiling where the human reviewer becomes the bottleneck, and either it slows down to stay safe or it speeds up and ships unverified code.

The difference between those two teams is the DORA stability axis measured in engineering practice. The team that ships safely with LLMs is usually not the team with the best prompters. It is the team with the best test suite and the fastest signal, because that team can convert the throughput multiplier into stable throughput instead of into rework. Investing in verification infrastructure is now the highest-return thing a team can do to raise its LLM shipping velocity, which is a counterintuitive claim only if you are still measuring velocity as lines produced rather than features landed without rollback.

The codebase is the model’s context
#

The other structural factor is that the LLM does not generate code in a vacuum. It generates code as a continuation of the context it is given, and the largest piece of context is the codebase itself. A clean, well-factored codebase with clear naming, consistent patterns, and a single way of doing each thing is excellent context, and the model faithfully reproduces its conventions. A tangled codebase with five competing styles, dead abstractions, and comments that contradict the code is terrible context, and the model faithfully extends the mess. As I argued in The Importance of Context When Interacting with LLMs, the context is the entire mechanism by which a frozen set of weights produces behavior relevant to your situation, and the codebase is the part of the context you control.

The codebase context is why the same model, the same prompt, and the same engineer produce different quality output on different codebases. The codebase is doing most of the work, and a codebase that is already a house of cards is a context that asks the model to build more cards. You cannot hand an LLM a weak codebase and get back a strong one; you get back more weak code. The teams shipping safely are, more often than they realize, the teams whose codebase was already safe to extend, and the LLM is merely making that pre-existing health visible at higher speed.

The factors that strengthen the foundation
#

The next four factors do not replace the first two. They decide how much wrong output the verification layer has to catch, and how high the ceiling on the best possible generation sits. A team that is strong here and weak on verification still ships a house of cards, just a slightly smaller one. A team that is weak here and strong on verification stays safe, but slowly, because its loop has to reject so much bad output.

Specification discipline separates amplifiers from noise
#

An LLM is a multiplier on the quality of the instructions it receives, which means the teams that win are the ones that produce high-quality instructions at scale. This is specification, and it is the skill that Software Engineering Teams in the Age of AI names as the highest-leverage capability in the current era.

A team that writes a precise specification before it prompts, one that defines what done means, which invariants must hold, and which edge cases matter, gets an LLM that behaves like an effective pair programmer. A team that prompts first and specifies never gets a hallucination engine that produces plausible code solving the wrong problem, and the wrongness is often invisible until production. Specification is also where the human bottleneck lives now, because writing a precise spec is hard cognitive work that the model cannot do for you until you have done the thinking it depends on. Teams that institutionalize specification, through templates, through review of the spec before the implementation, through a skill that enforces the steps, pull away from teams that treat the prompt as the spec, and they pull away fast.

Conventions have to be written down to be inherited
#

A performing team has settled conventions, and that is exactly what makes the team mature. But settled conventions that live only inside the senior engineers’ heads are invisible to two important workers: the new hire, and the LLM. Neither of them absorbed the conventions by exposure.

The teams that ship consistent, safe output at scale are the ones that have externalized their conventions into a form the model actually reads. That means lint rules the CI enforces, architecture decision records that capture why a choice was made, contribution guides that name the patterns to reuse, and, most powerfully, skills that encode a team’s process as executable steps the agent follows on every run. A convention in a head is advice the model will ignore. A convention in a skill or a lint rule is a constraint the model has to satisfy.

Externalizing conventions is the mechanism by which a mature team scales its maturity into the model. A storming team that somehow wrote its conventions down would get more out of the LLM than a performing team that left them tacit, which is a genuine inversion and a useful diagnostic. If your team is mature and your LLM output is still inconsistent, the conventions are probably in the wrong place. They are in people, and they need to be in files.

Review is a backstop, not the mechanism
#

The instinct when a tool speeds up code production is to use it to speed up code review, and on this point the instinct is closer to right than wrong, for a reason that is easy to miss.

Code review is a one-time signal. It catches what one reviewer notices, once, on the diff in front of them, while they happen to be alert. A specification prevents the whole class of issue from reaching implementation, and a test catches the same bug on every future run, for as long as the codebase exists. As Rethinking Code Review in the Age of LLMs argues, an hour spent improving the specification outranks an hour spent reviewing the output, because the specification compounds and the review does not. For the purpose of shipping without a house of cards, specification is the structural lever, and review is the non-compounding backstop behind it.

The backstop still has a job, but it is narrower than the one review used to claim. With generated code the reviewer provides the only judgment in the loop, so a light, intent-focused check still catches the occasional wrong assumption before it ships. What it does not do is scale. If the model produces ten changes a day, ten hours of human review is not a process that survives, and the right response to a repeated class of review comment is to encode it as an automated gate so it never depends on a human noticing again. The teams that ship safely let the model handle style, keep a thin intent check as the backstop, and spend the freed review hours writing better specifications. The teams that ship a house of cards inverted this, keeping review heavy while starving the specification that actually prevents the cards.

Domain depth and the discipline to build less
#

Both of the following are judgments the model cannot make for you: what the software should do, and whether it should exist.

On the first judgment, the model produces code that is technically correct and strategically wrong, faster than ever, when nobody on the team deeply understands the business context. Deciding whether a feature should exist, and what form it should take, is the part of the pipeline AI cannot do, and it is the bottleneck the throughput multiplier pushes you into, exactly as the shifting bottleneck predicts. A team with deep domain ownership extends its system coherently. A team spread thin across too many concerns generates five services where one would do, and each of them is a card.

On the second judgment, cheap implementation makes overbuilding the default temptation. Every generated feature adds opportunities for bugs, cognitive load, and future constraints, and the cost of maintaining a feature never approached zero the way the cost of writing it did. The team with the discipline to say “we do not need this, ship the smaller thing” survives longer than the team that ships everything the model can draft, and that discipline is a product judgment that maturity does not produce on its own. It comes from somewhere else, usually from someone in the room who has seen the cost of feature bloat before and is willing to push back against it.

How Maturity and Foundation Interact
#

The fair synthesis is that these two layers reinforce each other, and the most effective teams are strong on both, but they fail in characteristically different ways.

A performing team on a clean foundation with strong tests and written conventions is the team that wins this era. It absorbs new AI practices without friction, and when it ships, the foundation catches what the model gets wrong. A performing team on a brittle foundation fails in a way it cannot see, because the team dynamics are good and so nobody is arguing, and the stability metrics degrade quietly until a production incident makes them visible. A storming team on a clean foundation still wastes most of its energy on the wrong fights, but its code tends to survive the fights because the foundation holds. A storming team on a brittle foundation fails loudly and fast, which is at least easy to diagnose.

The trap is to read every symptom as the layer you already know how to fix. Engineering management tends to diagnose everything as team dynamics, because that is the toolkit it has, and so it sends a brittle-foundation team to a retrospective when what it needs is a test suite. Engineering teams tend to diagnose everything as tooling, because that is the toolkit they have, and so they adopt a new model when what they need is a written convention. The binding constraint is usually the layer you are not looking at, and maturity is very good at hiding problems in the foundation because a mature team does not complain about them until they break.

What to Do Next
#

If you lead a team and want to know whether you are shipping features or shipping cards, a few concrete moves separate the diagnosis from the guesswork.

Measure both DORA axes, not just throughput. If your deployment frequency is rising and your change failure rate or time to restore is rising with it, you are not getting faster. You are getting more volatile, and the LLM is the reason. The stability metrics are the house-of-cards indicator, and they are free to collect.

Treat the codebase as context and pay down the part the model keeps getting wrong. If the LLM consistently produces bad output in one module, that module is bad context, and the fix is to refactor the module, not to write a longer prompt. The model is telling you where your code is incoherent, because incoherent code is exactly what it reproduces worst.

Write your conventions down somewhere the model reads them. A skill, a contribution guide, a lint rule, an architecture decision record, anything that moves a standard out of a head and into the execution path. The test is whether a new engineer and a fresh agent both produce work that matches the team’s patterns on day one without being told.

Keep a thin, intent-level review as a backstop and let the model own style. If your review comments are still about formatting, you are spending human attention on the part the model already fixed. Reallocate those hours into specification, which is the lever that compounds.

Write the specification before the prompt, every time. The spec is the highest-leverage artifact in the pipeline now, and the team that treats it as optional is the team whose LLM output drifts toward plausible-and-wrong.

The Team That Wins
#

The teams that win this era are easy to misread. They look like the most mature teams, and they often are mature, but the maturity is doing a specific job. It is letting them adopt new practices without wasting energy, so that they can spend that energy on the foundation that actually decides whether the software stands up.

Maturity is how you remove the friction of getting started. The codebase, the tests, the specifications, the written conventions, and the intent-level review are how you keep the result from collapsing as it grows. Study your teams, because Tuckman will tell you a lot. Then study the code they are standing on, because that is what determines whether the velocity they have earned is velocity they get to keep.

References
#

Wikipedia, “Tuckman’s stages of group development” - the forming-storming-norming-performing model that explains why mature teams absorb new practices with low friction
Google re:Work, “Guide: Understand team effectiveness” - Project Aristotle’s finding that psychological safety is the top predictor of team effectiveness, the performing-stage asset that makes genuine disagreement possible
DORA, “State of DevOps” - the research program establishing throughput and stability as independent axes, which is the formal version of velocity-without-the-house-of-cards
Google Cloud, “State of DevOps Report” - the annual report tracking how elite teams separate lead time and deployment frequency from change failure rate and time to restore
Wikipedia, “Theory of Constraints” - the framework for why removing the production bottleneck relocates rather than eliminates the constraint, landing it on verification

The Pull Request Queue Outgrew You: A Triage Layer for Open Source Maintainers

tom@tomrochette.com (Tom Rochette) — Tue, 30 Jun 2026 00:00:00 +0000

Open source always had a queue problem. For most of its history the threat was volume: more pull requests than a maintainer could read, arriving faster than one unpaid person could clear. The pull request queue scales with the project’s popularity, and a single maintainer’s attention does not scale with anything at all.

The volume threat is still present, and it is no longer the worst of it. The character of the queue changed. More than one in five code reviews on GitHub now involve an agent, and Copilot’s automated review alone has run more than sixty million times, growing tenfold in under a year, so the machine-generated pull request is no longer a fringe of the queue. The machine-generated pull request is becoming the norm, and it is a different kind of problem than a human one. It looks correct, because plausibility is exactly what a language model optimizes for, and it may be subtly, uniformly wrong in ways that read as confident and clean. There is usually no author who thought about each line, so there is no intent for you to leverage as context, only output you have to verify from scratch. And almost never does the contributor tell you which model produced the code, what prompt generated it, or whether a human ever read it before it landed in your queue. The flood is not just bigger now. The flood is full of plausible code with no provenance, and plausible, unprovenanced code is the hardest thing to triage by reading it.

The instinct of a responsible maintainer is to read every pull request, carefully, and reply thoughtfully. That instinct is exactly what kills the project. Every half-hour spent reverse-engineering an AI-generated PR that looks reasonable until the third function is a half-hour not spent on the architectural change that keeps the library maintained. The queue grows while you sleep, and while you are polite, and while you are giving a stranger’s model the benefit of the doubt.

You cannot review your way out of this, for the same reason a team engineer cannot: per-unit review scales linearly with your hours, and the entropy is produced faster than you can read it. The difference is that on a team you can hire. In open source, you are usually alone, unpaid, and tired, and the code you are being asked to vet no longer contains the reasoning of the person who submitted it. The only way out is to stop reviewing everything and start triaging everything, so that your scarce attention lands only on the pull requests that deserve it.

Triage Before Review
#

Review answers the question, “is this code correct?” Triage answers a cheaper question that comes first: “does this pull request deserve my attention at all, and if so, how much?”

Most maintainers combine the two. They open a pull request, start reading the diff, and only then discover that it is stale, that it conflicts with main, that it has no tests, that it touches a file nobody asked it to touch, or that it is the fourth duplicate of a request they already declined. Every one of those discoveries was free to make before reading a single line of code, and making them up front is the entire difference between a queue you manage and a queue that manages you.

A triage layer is the set of automated signals that answer the cheap questions before you ever open the diff. Does it still apply? Does it still merge? Is it small or sprawling? Is it risky or routine? Who is it from? Does it match the conventions the project already requires? Each of these is a machine-checkable property, and a property a machine can check is attention you never have to spend again. This is the same move The Codebase Gardener makes for a team codebase: encode the standard where every change is forced to pass through it, instead of carrying it in your head as a review habit.

The goal of the triage layer is not to merge everything automatically. It is to make the queue sortable, so that when you sit down with your limited hour, you are looking at the five pull requests that matter, ranked, instead of the fifty that arrived in the order they happened to come in.

Plausibility Is the Danger, Provenance Is the Missing Signal
#

Understanding why the modern queue is dangerous is what defines the triage layer, because AI-generated code breaks the assumptions review used to rest on.

When a human wrote the pull request, you and the author shared a mental model. You could trust that the choices in the diff were deliberate, even imperfect ones, and a gap between your expectation and the code was an interesting signal, because it represented two human understandings of the same problem meeting. When a model wrote the code, there is no shared mental model, and there is no author who deliberated. The code is the output of a pattern-matching process, internally coherent, consistent with nothing around it, and wrong about the domain in ways that look exactly like correctness. This is the argument from Rethinking Code Review in the Age of LLMs, and it lands hardest in open source, where the reviewer and the “author” have never spoken.

What makes the current crisis distinct is the provenance gap. Contributors almost never disclose that the code is generated, let alone which model generated it, what prompt produced it, or whether a human checked the output before opening the pull request. Without provenance, you cannot assess risk. A fifty-line patch from a contributor who tested it by hand and a fifty-line patch a model hallucinated in three seconds look identical in the diff, and the diff is all you have. Plausible code with no origin story is the default input now, and it forces a worst-case assumption on every pull request: treat it as unverified until something proves otherwise.

The 2026 data shows how invisible the provenance gap is by default. A census of 180 million repositories found that the obvious signal, a bot account, recovers only about three percent of the commits AI coding agents actually produced, so the overwhelming majority of machine-generated code reaches you with no detectable fingerprint. And the studies that watched what reviewers did with it found the same pattern: agent-generated pull requests carry more redundancy and technical debt than human ones, yet reviewers express more positive sentiment toward them, and the majority of AI-coauthored pull requests merge with no explicit human review at all. Plausibility is what hides the problem.

The implication for triage is concrete. First, the durable defense against plausible code is not a sharper opinion but a machine-checkable gate, because opinion-based review loses against code that was designed to look right. Tests, static analysis, type checking, reproducible builds: these operate on what the code does, not on how it reads, and they do not get fooled by confident prose. Second, the absence of provenance is itself a routing signal. A large, high-churn, undocumented pull request from an unknown contributor should default to high-risk, not because the contributor is malicious but because you have no evidence to assign it anything lower. Third, the one piece of information that would most improve your triage, which model and what prompt, is the one nobody is giving you, which means the cheapest high-leverage intervention available is to start asking for it.

Let Automation Carry the Logistics
#

The first tier of triage is pure logistics, and all of it is solved. You should not be tracking any of this by hand, and in 2026 you increasingly do not even have to build it yourself. The most consequential shift is that GitHub started shipping these gates at the platform level, because the flood crossed a threshold unpaid maintainers could not hold: per-user caps on open pull requests, pull-request archiving, and “smarter bypass” signals based on account age and merge history. The stated rationale is the one this article rests on: the cost to create a change has fallen below the cost to review it. When the host handles the load, your job narrows to the gates the platform cannot generalize.

Mark and close the stale, on a clock that forces a decision. A pull request that has had no activity for twenty-eight days is not waiting for you. A stale pull request drags down the whole queue, because a queue full of stale PRs signals to new contributors that the project is unmaintained. actions/stale marks a pull request stale after twenty-eight days, posts a warning, and closes it seven days later if the contributor does not respond. Twenty-eight is also the ceiling on a healthy open pull request, not just the stale timer. If a PR has been open more than twenty-eight days and is not merged, the right answer is almost never “keep waiting,” it is one of two things: break it into smaller pieces that can each land on their own, or reject it. A large PR that lingers is usually a PR that was too big to review in the first place, not a PR that is waiting for a reply. This is not cruelty. Letting a contributor’s work sit unread for a year is cruelty. A fast, automatic close with a clear “reopen if you are still interested” is a kindness, and it is a kindness that costs you nothing.

Surface the conflicting. A pull request that no longer merges cleanly is a pull request that is wasting your attention, because until the contributor rebases, your review is provisional. eps1lon/actions-label-merge-conflict adds a merge-conflict label the moment a PR falls behind main, and removes it the moment it merges again. Now you can filter label:-merge-conflict and only review work that is actually ready. The contributor also gets a clear, automated nudge that rebase is needed, without you having to be the one to say it.

Label by size. The blast radius of a change is the single best predictor of how much attention it deserves, a point I made in The Merge Gate: a README typo and a schema migration are both pull requests, and they do not need the same gate. A size action tags every PR with size/S through size/XL based on diffstat. Small changes become candidates for fast-track; large ones become candidates for “please split this.”

Label by area. actions/labeler tags a pull request based on which files it touches, so you can route area/ci, area/docs, area/security to the right context, or skip the areas you are not the expert in.

Flag the first-timers. Label first-time contributors explicitly. Not so you can be suspicious of them, but so you can be generous with them, because a good first review is how a first-time contributor becomes a second-time contributor, and a second-time contributor is how a project outlives its original maintainer.

Enforce the conventions you already require. If your project requires a linked issue, a semantic title, a signed commit, a test for every new function, enforce each one with a check that runs on open. amannn/action-semantic-pull-request is one example, but the specific tool matters less than the principle: anything you find yourself typing in review comments repeatedly belongs in a check that fails the build. A review comment is a standard you enforce only when you are awake. A failing check is a standard that runs forever.

Gate at the trust boundary, before the diff. The bluntest triage signal is whether you have any reason to trust the contributor at all, and in 2026 the canonical implementation of that idea is mitchellh/vouch, built for the Ghostty terminal against a large volume of AI-generated pull requests. It auto-closes pull requests from unvouched contributors and routes them through a vouching issue, so the queue you actually read is the queue from people who have been vouched for. It is a strong filter, and a truthful one to use carefully: the cost is friction for legitimate newcomers, which is why the vouching path has to let legitimate newcomers through, not block them.

Each of these is a small automation, and none of them review code. Together they collapse the queue from “everything that arrived” to “everything that is ready, relevant, and sized.” That handles most of the work, and it cost you zero hours of reading diffs.

Demand Provenance
#

The single most valuable triage signal is the one the current ecosystem refuses to provide, which means the maintainer has to require it.

Add two fields to your pull request template, and make them hard to skip. Was this change generated or significantly assisted by an AI tool? If so, which model, and what was the prompt or task description? A checkbox and a free-text line are enough. You do not need a policy on whether AI contributions are welcome; you need the data to triage them on their actual risk rather than on a guess.

This is no longer hypothetical. In 2026, rust-lang wired an AI policy into its contributing guide and pull request template, and it is not alone: scipy asks for the model name, qemu requires code provenance, Ghostty ships an AI_POLICY file, and the Linux kernel has long held the submitter responsible for attesting to AI-generated code. The convention is fragmenting into a field of per-project rules, which is messy, but the direction is clear, and the closest thing to a shared format, declare-ai’s provenance file, is emerging for exactly this gap. The platform will not hand you this signal for free. Everything GitHub has shipped for maintainers, per-user caps, archiving, smarter bypass signals, operates on volume and account history, and none of it tells you which pull requests a model wrote. If you want provenance, you have to ask for it in the template.

Label from the answer. human-authored, ai-assisted, ai-generated, and a tag for the model when it is disclosed. Now provenance becomes a filter and a routing input instead of a mystery. A human-authored patch from a known contributor with passing tests can travel the fast lane. An ai-generated patch with no model disclosed and no linked issue starts one gate further back, by default, because it carries the provenance risk this era is defined by.

Be explicit that disclosure is not a penalty. The penalty is discovery, when you eventually realize a PR was generated and the contributor hid it, because at that point the trust that makes open source work is gone and the PR is closed on principle. Disclosure is what lets a generated contribution compete for your attention on its merits. Concealment is what makes every generated contribution read as an attempt to hide something from you.

One caution, because the obvious next step is to use cryptographic attestation: signed provenance is not the same as trustworthy provenance. In 2026, cryptographically valid supply-chain attestations were produced for malicious packages, which means a signature confirms a chain of custody, not that the code is safe. Demand disclosure, but verify the code on its own terms, not on the strength of the attestation alone.

A maintainer cannot triage what they cannot see, and in a queue full of plausible code, the origin of the code is the first thing they need to see.

Let the LLM Do the First Pass
#

Once the logistics are handled, the remaining question is the one automation traditionally could not answer: is the code itself any good. That used to require a human, because reading a diff and reasoning about its consequences was exactly the task machines could not do. It is not anymore. An LLM will not review a pull request as well as you would, but it will review it in seconds, on every pull request, at three in the morning, and it will produce a structured signal you can sort and filter on. That is a different value than correctness, and for triage it is the value that matters.

The 2026 evidence is now strong enough to separate the hype from the result. On the hype side, independent benchmarks are blunt about the ceiling: across eight frontier models, reviewers catch only fifteen to thirty-one percent of the issues humans flag, and adding more context makes them worse, not better, while the first independent cross-vendor ranking puts the best tool at an F1 near fifty-one. An LLM review is a noisy signal, and treating it as a verdict is the mistake. On the result side, the largest production deployment of the year ran a hundred and thirty thousand review passes across five thousand repositories, and engineers reached for the human “break glass” override on six tenths of one percent of merge requests. That number is the point: the system ran unattended on the easy tier not because the model was a great reviewer, but because it was a great sorter, tiering by risk and handing a coordinator a structured finding to deduplicate and rank.

Run an LLM review on every pull request when it opens and on every push that updates it. Give it your evaluation criteria, explicitly, the same checklist you would walk through mentally if you opened the diff yourself. Does it add a new dependency? Does it change a public interface? Does it touch security-sensitive code paths? Does it introduce backward/forward-incompatible behavior? Are there tests for the new behavior? Does it match the naming and structural conventions of the surrounding code?

Ask for the output as structured data, not prose. A risk score and a confidence score, say on a one-to-five scale, a one-line summary, and a short list of specific findings. Then parse those fields and turn them into labels. risk:low, risk:medium, risk:high. confidence:high, confidence:low. needs-human-review when the model is unsure or when the risk is high. auto-merge-candidate when the risk is low, the confidence is high, the size is small, the tests pass, and the contributor is trusted.

Now your queue is sorted by signal instead of by arrival time. The pull requests that are low-risk and high-confidence can be merged on green, or queued for a single glance, because the LLM has already done the scanning work you would have done anyway. The pull requests that are high-risk, or where the model is uncertain, rise to the top of your attention with the findings already attached. You are no longer choosing what to read. You are confirming or rejecting a hypothesis the triage layer has already formed.

Wire those scores back into the logistics layer, so a pull request that fails the review does not just sit and wait for you. When confidence drops below three or risk climbs above three, post a comment that tells the author the specific findings they need to address, and let the stale action treat that as the notice that starts the closing clock. The contributor gets a concrete path to merge instead of silence, and if they do not take it the pull request closes itself, decided by the standard you encoded rather than by your mood on a given Thursday.

A few cautions, because this is the part people get wrong.

The LLM review is advisory, not authoritative. It hallucinates, it misses subtle bugs, and it is confidently wrong in exactly the way that makes you want to trust it. Never wire it to merge on its own verdict for anything that crosses a trust boundary, changes a public contract, or is hard to undo. Use it to route attention, not to replace it, and reserve the replaced attention for the small, reversible, low-risk changes where being wrong is cheap to fix. This is the same risk-based gating The Merge Gate argues for: the unit of gating is the blast radius of the change, not the existence of the pull request.

The deepest caution is specific to this era, and you have to internalize it before trusting any automated score. When an LLM reviews code that an LLM wrote, the reviewer shares the generator’s blind spots. Both are statistical models trained on overlapping corpora, and a mistake plausible enough for one model to make is often plausible enough for the other to overlook. Two models agreeing that “this looks fine” is a weaker signal than either model issuing that verdict alone, and if the reviewer and the generator come from the same model family the agreement proves almost nothing.

In 2026 this stopped being a conjecture. Recursive self-training studies show that an AI reviewer gating its own output collapses into a rubber-stamp regime, where acceptance scores rise while correctness falls, and that only model-independent checks, compilation, types, tests, slow the collapse without stopping it. The one direct measurement of the effect found that heterogeneous pairs, a Claude reviewer over Codex output, flag a defect sixty-nine percent of the time, where homogeneous pairs flag it only fifty-three percent of the time. Same-family agreement is measurably weaker than cross-family agreement, which is the empirical form of the warning above.

This is why provenance matters at the review layer as well: feed the disclosed model and prompt into the reviewer’s context so it can target the failure modes that model is known for, rather than re-reading the diff from the same perspective that produced it. And it is why, for ai-generated pull requests, you must discount the confidence score and default toward needs-human-review unless the change is independently verified by something that does not share the blind spot: a passing test, a type checker, a reproducible build, a specification the code is checked against. The LLM review is one signal in the triage layer, never the only one, and against generated code its job is to surface hypotheses for a human or a gate to confirm, not to pronounce the code correct.

Calibrate by reviewing the reviewer. For your first month, read the LLM’s review on every pull request you also review yourself, and keep a tally of where it was right, where it was wrong, and where it missed something you caught. That tally tells you which criteria to strengthen in the prompt and which labels to distrust. An uncalibrated LLM gate is a liability. A calibrated one is an extra reviewer that never tires, and that gets more accurate every time you adjust the criteria.

Post the rationale, not just the label. Have the action leave the summary and findings as a comment on the pull request. The contributor sees what was flagged, the maintainer sees why a label was applied, and the verdict is auditable rather than opaque. Transparency is what keeps an automated review from feeling arbitrary, and it is what lets a contributor fix the problem before you ever have to look.

Route by Risk, Not by Arrival
#

Once the triage layer is producing labels, the routing follows directly, and it should match the risk profile of each change rather than the order it was submitted. The tiering is no longer theoretical: the production system cited above classifies every change into trivial, lite, or full tiers and spends twenty cents of review on a typo fix where it spends a dollar sixty-eight on a sprawling one, because the gate a change deserves is a function of its blast radius, not its existence.

Low risk, high confidence, small, passing tests: auto-merge on green, or batch them into a single weekly pass where you glance and click. High risk, or low confidence, or large, or crossing a security boundary: hold for human review, and review those first. AI-generated with no model disclosed, or no linked issue, or no tests: default to the human queue until a test or a specification proves it, regardless of how small it looks, because small and plausible is exactly the profile of a subtle bug. First-time contributor: prioritize the response, because the speed of your first reply decides whether they come back. Conflicting: invisible until rebased. Stale: closed.

Within the human-review queue, start with the oldest first. A pull request that has waited the longest is the one closest to going stale, and clearing it, by merging or by closing, is what keeps the queue from accumulating old pull requests that nobody will ever get to, so weight your attention toward age, not toward whatever arrived most recently.

This is the open source version of the argument from The Merge Gate: treating every pull request as needing the same gate is a failure to think about risk, and most pull requests do not need a human at all. The maintainer who wins is not the one who reads the most diffs. The maintainer who wins is the one whose queue has been pre-sorted so that the diffs they do read are the only ones that ever needed a human.

The Contributor Relationship Is the Hidden Triage
#

There is a layer underneath the triage setup, and it is the one maintainers most often neglect, because it is not technical. Most of the pain of an overflowing queue is not the code. It is the guilt of unanswered contributors, the dread of opening the tab, and the slow resentment of work that is supposed to be voluntary but has started to feel like a debt.

Automation is part of the answer, but so is setting expectations, because a contributor who knows what to expect does not require a personal reply to stay patient.

Write a CONTRIBUTING.md that says what you will and will not accept, what a good pull request looks like, and how long response takes. Use a pull request template that asks for the linked issue, the motivation, and the test. Publish a response-time norm, even a truthful one: “I review pull requests on Thursdays.” State it, link it in every template, and let the automation reinforce it. Predictability is a contribution, and a maintainer who responds every Thursday is more sustainable than one who responds in a burst and then disappears for three months.

The economics underneath this are shifting, slowly. The clearest 2026 voice on maintainer sustainability argues that the polite channels, sponsorship and pledge drives, have failed, and that maintainers should take open source work on company time rather than donate their evenings, because attention donated after hours is attention that does not scale. The funding is present but thin: sovereign and industry programs disbursed millions to individual projects this year, with a sovereign fund investing over a million euros in a single project and the open source pledge setting a two-thousand-dollar-per-engineer floor, yet no 2026 survey has measured whether maintainer burnout actually fell. Treat the automation and the expectations as the primary means of managing the queue, and the funding as the still-insufficient subsidy.

And learn to close fast. A fast, clear “no, and here is why” is a gift. It respects the contributor’s time, it keeps the queue fair, and it is almost always kinder than a silence that stretches into a year. The maintainer’s fear of seeming ungrateful is what grows the queue beyond recovery. A no is not ungrateful. A no is an answer, and an answer is all a contributor is waiting for.

What to Do Next
#

You do not need to build the whole layer at once, and you should not try. Pick the single thing that is costing you the most attention right now and automate that one.

Add actions/stale and let it start closing the pull requests you were never going to get to. Add eps1lon/actions-label-merge-conflict and stop looking at diffs that are not ready to merge. Add a size labeler and a path-based labeler and make the queue sortable. Write the CONTRIBUTING.md you have been meaning to write, and add the two provenance fields, AI-assisted yes or no, and which model, to the pull request template, so every contribution arrives with the one piece of context this era hides by default. If the flood is mostly from contributors you have no reason to trust, add a trust gate like vouch before any of the rest, because closing unvouched pull requests up front is the single largest reduction in queue size available to you.

Then, and only then, wire in the LLM first-pass review. Start it in shadow mode, posting its summary as a comment without applying any labels, and read along with it for a month. When you trust its risk and confidence calls, turn the labels on. When you trust the labels, let the lowest-risk, highest-confidence, smallest changes merge on green. Each step is attention you stop spending by hand and start spending on the pull requests that actually need a human.

A sustainable open source project is not one where the maintainer reads everything. It is one where the maintainer has built a triage layer good enough that almost nothing needs to reach them unread, and what does reach them is exactly what was worth their time. Build that, one automation at a time, and the queue stops controlling your schedule.

References
#

actions/stale - the official GitHub Action for marking inactive pull requests and issues stale and closing them after a configurable window
eps1lon/actions-label-merge-conflict - labels pull requests that no longer merge cleanly and unlabels them once the conflict is resolved
actions/labeler - the official GitHub Action for applying labels based on the files a pull request touches
amannn/action-semantic-pull-request - enforces conventional-commit-style pull request titles as a required check
Wikipedia, “Theory of Constraints” - Goldratt’s framing for why you change the bottleneck station rather than adding effort at it, the basis for moving the maintainer out of the triage station
Wikipedia, “Paved road” - the principle of making the compliant path the easiest path, applied here to contributor conventions and templates
GitHub, “Agent pull requests are everywhere” - the 2026 scale data (one in five reviews involve an agent; Copilot review at 60M+, 10x growth) and GitHub’s own “judgment is the bottleneck” framing
GitHub, “How pull request limits are cutting down the noise” - the platform shipping per-user PR caps, archiving, and smarter bypass signals
GitHub, “Welcome to the Eternal September of open source” - the cost-to-create versus cost-to-review framing that motivates platform-level triage controls
Cloudflare, “Orchestrating AI Code Review at scale” - the largest 2026 production dataset (131k runs, 0.6% break-glass) and the coordinator-plus-specialists-plus-risk-tiers reference architecture
SWE-PRBench, “Benchmarking LLM-Driven Pull Request Review” - the independent efficacy ceiling: eight frontier models catch 15-31% of human-flagged issues, and more context hurts
Martian Code Review Bench, via CodeRabbit - the first independent cross-vendor ranking (~300k PRs, ten tools)
Song et al., “When AI Reviews Its Own Code” - the formal proof that AI self-gating collapses into a rubber-stamp regime, requiring exogenous verification
Kim, “tap: A File-Based Protocol for Heterogeneous LLM Agent Collaboration” - the direct measurement of the homologation effect (heterogeneous pairs flag defects 69.8% vs 53.1% for homogeneous)
“More Code, Less Reuse” (MSR 2026) - agent PRs carry more debt yet reviewers go easier on them
“On Autopilot? Human-AI Teaming in OSS” (MSR 2026) - most AI-coauthored PRs merge with no explicit review
“Detecting AI Coding Agents in Open Source” (180M-repo census) - bot-account detection recovers only ~3.3% of AI-agent commits
mitchellh/vouch - the canonical 2026 trust-before-the-diff gate, built for Ghostty
rust-lang/rust-forge, “LLM policy” PR #1040 - a provenance policy wired into CONTRIBUTING.md and the PR template, with a prior-art index
OpenSSF, “Mini Shai-Hulud: Where SLSA’s Boundaries Fall” - signed provenance produced for malicious packages, the caveat against equating attestation with trust
Declare-AI - the closest thing to an emerging machine-readable provenance standard
Open Source Resistance - the 2026 argument that maintainer attention must be taken on company time, not donated after hours

Learn the Foundation, Not the Syntax: Why Low-Level Languages Still Matter When the Machine Writes the Code

tom@tomrochette.com (Tom Rochette) — Sun, 28 Jun 2026 00:00:00 +0000

The question gets asked as a binary choice: either drill new developers on low-level languages until they can write a kernel from memory, or accept that writing code is finished and retrain everyone into product managers who write prompts. It is a false dichotomy, and both options are wrong for the same reason. They both confuse the surface of programming with the thing programming was always meant to teach, and that thing is now the only part AI cannot do for you.

Two Errors, Shared Confusion
#

The “teach them everything” camp treats low-level fluency as a production skill. It points at manual memory management, pointer arithmetic, and hand-rolled data structures as requirements for entering the profession, and it is right that these were once essential. It is wrong that they still are, as production. Writing C by hand stopped being the bottleneck the year a model could write it, read it, and port it faster than a careful senior could, and the market has already priced that in.

The “writing code is over” camp takes the same observation and extends it too far. If production is automated, the argument goes, the developer’s job becomes specification and orchestration, and the foundation the code runs on is somebody else’s problem, probably the machine’s. This position is the AI-maxxing error applied to education, and it is the more dangerous of the two, because it feels like foresight while quietly removing the one capability that becomes scarcer and more valuable exactly as production gets cheap: the mental model of how the system actually behaves.

Both camps make the same mistake the resistor and the maximalist make in AI-Maxxing and Resistance Are the Same Mistake: they argue about how much low-level to use instead of asking what low-level is for. The answer to that question dissolves the debate.

What Low-Level Actually Teaches, and Why It Compounds
#

Set aside the syntax drills and the “implement linked lists in C” exercises, and a low-level language is a teaching apparatus for a small number of durable mental models. None of them are about the language. They are about the machine the language sits on top of, and they are exactly the models that become structural once you can no longer trust the code you are reading.

A model of execution. What lives in memory, what gets allocated where, what a call frame is, what happens when a function returns. This is not trivia. It is the difference between an engineer who can read a stack trace and one who can only read an error message, and the generated code that breaks in 2026 breaks in ways that only the first engineer can diagnose.

A model of cost. Big-O is taught in school and forgotten because it is inert until you have experienced a cache miss, an allocation storm, or an N-plus-one query at the boundary between the ORM and the database. Low-level work is the cheapest known way to experience that cost directly, and once experienced it transfers to every higher language you will ever use. When the model produces plausible code that is also quietly quadratic across a network boundary, the person with a cost model catches it and the person without ships it.

A model of failure. Low-level code fails loudly: a segfault, a leak, a data race, a corrupted pointer. The cause is concrete and the lesson is remembered. High-level and generated code fails softly, at the seams between abstractions, and the softness is the hazard, because soft failures train nothing and accumulate until they become outages. The engineer who learned on hard failures can debug the soft ones. The reverse is not true.

And, most importantly, a model of where the abstractions leak. Every stack you will ever work on is a tower of abstractions, and every one of them leaks under stress: the ORM leaks into SQL, the garbage collector leaks into latency, the container leaks into the kernel, the model’s confidence leaks into a hallucinated API call. When a leak surfaces in production, the person who can identify the layer underneath the abstraction is the person who fixes it. Everyone else files a ticket and waits.

These four models are not production skills. They are not even, strictly, low-level skills. They are durable skills, in the sense Keeping Up With AI Is a Losing Strategy draws between the ephemeral and the durable: they do not decay across model generations, and they make every other thing you do, including supervising a model, more effective. That is the entire case for low-level in one sentence: it is the most efficient known way to build the models that do not depreciate.

Why “Writing Code Is Over” Is the Dangerous Half
#

Here is the asymmetry that settles which error matters more.

Forgetting low-level syntax is a recoverable error. The developer who never memorized the C calling conventions can look them up, or ask the model, the day they need them, and the cost is a few minutes.

Losing the mental model is not recoverable in the moment you need it. When the generated code is failing in production at three in the morning, there is no time to develop an intuition for memory layout, and the model that wrote the code is the same model confidently misdiagnosing it. You can build a mental model with an LLM as a tutor, over time, the same way you can build one with a good textbook or a patient colleague; the tool is not the obstacle, the hours of deliberate study are. What you cannot do is prompt one into existence under time pressure, and using the model to debug its own output already presupposes the very model it would take weeks to build.

This is the shifting bottleneck in its clearest form. Production was the bottom of the stack, and automating it moved the constraint up to verification, and verification is precisely the layer that demands the foundation knowledge the “code is over” camp wants to skip. The preparation that says “we will not need this because writing is automated” is the preparation that makes you unable to do the job writing’s automation created. You are optimizing away the exact layer the bottleneck landed on.

There is a near-term counter-argument worth taking seriously: that verification gets automated too, and then specification, and so on up the stack. Even granting that, the same framework says the bottleneck just moves to deciding what to build and whether what was built is correct, which still requires understanding systems deeply. I cannot find a version of this future in which understanding the foundation stops compounding, only versions in which the surface syntax stops mattering. Those are different claims, and the debate quietly collapses them into one.

The Onboarding Hole the Tools Opened
#

There is a structural reason this question is urgent now, and it is not philosophical. For most of the profession, a developer built their mental model of systems the only way the model can be built: by struggling with code that broke, reading core dumps, profiling slow paths, and fixing actual failures under actual pressure, repeatedly, for years. The struggle was the curriculum, and it was free, because it was simply the job.

The tools have quietly removed the struggle, and with it, the curriculum. An engineer who starts today can ship a feature without ever reading the code the tool wrote, without ever opening a profiler, without ever needing to understand why the first version was slow, because the tool never produced a slow first version for them to fix. The onboarding path that used to build that underlying mental model now bypasses it, and the onboarding paradox in Software Engineering Teams in the Age of AI is the downstream symptom: juniors ship faster and understand less, and the understanding gap is invisible until something breaks.

So the question is not whether to teach low-level. It is whether to teach it deliberately, because the accidental curriculum that used to teach it for free has been automated away. A generation that learns to prompt before it learns how a machine actually executes will be fluent at the surface and weak at the foundation, and the weakness will only become visible at the moment it becomes expensive, in production, at three in the morning, with no model able to help.

The Synthesis: Read the Foundation, Don’t Write It
#

The resolution is not a midpoint between the two camps. It is a different axis entirely.

Stop teaching new developers to produce low-level code as if they would ship it. Manual memory management as a daily craft, pointer arithmetic as a drill, hand-rolled allocators as a traditional requirement: these are depreciating production skills, and spending years on them is the two-year test failing gradually and visibly. The surface area of low-level is large and mostly irrelevant to the work most developers will actually do, and Brooks’s old split between accidental and essential complexity still maps onto it cleanly: the syntax and the boilerplate are accidental, and the accident is exactly what the model now absorbs.

Do teach them to read the foundation. Read a stack trace down to the frame that matters. Read a flame graph and point at the function that is consuming the budget. Read a heap profile, an strace, a slow query log, a core dump. Read the source of the standard library they use every day, at least once, until the abstraction is no longer mysterious. Reading is cheaper than writing, it transfers to every language and every model generation, and it builds exactly the four models above without demanding the years of production fluency the old curriculum required.

The rule of thumb is simple and useful: enough low-level to debug, not enough to ship. A few focused weeks of C or Rust, or even a careful tour through how the managed language you already use actually executes, is enough to install the models for a working lifetime, provided the engineer keeps reading systems instead of reading only diffs. A career of writing C, in 2026, is overkill for most roles and a misallocation of the time that should be going into domain depth and judgment.

And for the small fraction of work that genuinely lives at the foundation, embedded, kernels, databases, runtimes, high-frequency paths, the calculus flips and fluency is still required. The point is not that nobody should write low-level code. The point is that “should every new developer learn to write low-level code” is the wrong question, asked about the wrong layer, and the answer, which is “no, but every developer should learn to read the machine,” is what the two camps keep talking past.

What to Do Next
#

If you hire or mentor new developers, stop using “do you know C” as a proxy for anything. It measures syntax, and syntax is cheap.

Instead, hand them a deliberately broken program, one with a memory or concurrency bug hidden behind a clean high-level interface, and watch what they do. The ones who can form a hypothesis about the layer underneath are the ones who can supervise a machine. The ones who can only describe the symptom to the model and accept its first confident answer are the ones who will ship that bug to production and then be unable to explain it.

If you are a new developer yourself, do not let the tools talk you out of the foundation. Generate the boilerplate, take the shortcut, and then, separately, on your own time, read the source of something you depend on until you can explain how it actually works. The generation is free. The understanding is not, and it is the only part of this profession that the next ten years will reward more, not less.

The debate between “learn everything low-level” and “writing code is dead” is two ways of staring at the surface. The surface is going away. The foundation is not. Prepare accordingly.

References
#

Spolsky, “The Law of Leaky Abstractions” - the original framing for why every abstraction eventually fails at the layer underneath, which is where foundation knowledge pays
Wikipedia, “Theory of Constraints” - the framework for why automating code production relocates rather than removes the bottleneck, landing it on verification
Wikipedia, “No Silver Bullet” - Brooks’s split between accidental complexity (the syntax and boilerplate AI now handles) and essential complexity (the mental model of the problem it cannot)
Wikipedia, “Accidental complexity” - the distinction that lets you sort low-level trivia, which is accidental and depreciating, from low-level mental models, which are essential and compounding
Wikipedia, “Vibe coding” - the extreme of the “writing code is over” position, used here as the steelman argued against rather than a strawman
Willison, “Vibe coding” - a practitioner’s account of what you can and cannot safely delegate, and why supervision still requires understanding the output

What I've built and what I need: June 2026

tom@tomrochette.com (Tom Rochette) — Thu, 25 Jun 2026 00:00:00 +0000

Over the month since May, the agents repository evolved from building the SDLC pipeline into a mature, self-improving system. The biggest shift was adding verification and consistency tooling, introducing stateful SDLC tracking, and standardizing conventions across the skill library.

What I Have Been Working On
#

Added verification and consistency tooling. The latter half of the month focused on checking the system’s own work. validate-pr runs runtime validation of PRs, checking out a branch, building it, and proving every claim in the PR description through execution. verify-pr performs static code inspection covering quality, correctness, and architecture alignment. backpropagate-sdlc walks the SDLC artifact chain in reverse, from code back to issue, to verify end-to-end traceability and detect drift accumulated across phases. sync-repository ensures the entire repository stays consistent across SDLC, code, tests, documentation, types, and observability. improve-autonomy assesses what would be needed to run a session fully autonomously end to end.

Overhauled the SDLC infrastructure. The old bootstrap-sdlc was replaced by sync-sdlc, which reconciles the codebase with the .sdlc/ directory instead of just bootstrapping it. A new .sdlc/state.yml file in worktrees tracks the current phase, GitHub reference, and feature, giving skills persistent context across invocations. The sdlc-status skill was extracted and heavily improved through multiple iterations, adding vocabulary tooltips, open questions, and a footer. Observability and telemetry phases were added to the SDLC pipeline, extending coverage from needs assessment through deployment and retrospective. qualify-issue drives a multi-round Q&A loop to gather enough information before requirements. create-feasibility / review-feasibility and create-existing-solutions / review-existing-solutions assess viability and survey prior art before committing to a build. fix-issue orchestrates a bug fix end to end by delegating to reproduce-issue, create-implementation, and create-pr. Post-merge coverage extends through deploy-pr and observe-production, which deploy changes and verify SLOs and error rates in production. Production health is planned from the start with create-observability / review-observability / audit-observability, which define logging, metrics, tracing, and alerting for each feature. create-telemetry / review-telemetry define the analytics events for each feature. Cross-skill conventions were consolidated into a shared references file, and per-repository AGENTS.md overrides can now be stored under repositories/ for project-specific instructions. SDLC artifacts produced by the skills across projects I contribute to or monitor are tracked in a dedicated sdlc repository. That repository includes automation to generate static HTML status pages from the output of the sdlc-status skill. Each project’s artifacts are reviewed weekly by sync-sdlc to detect and correct drift.

Shipped 7 maintenance skills for code quality. A new “maintenance” skill category was added covering security auditing, code duplication detection, type gap analysis, churn analysis, and related diagnostics. These maintenance skills were integrated into the SDLC pipeline as a structured diagnose-harden-clean-document workflow, giving every feature a code health pass alongside the existing requirements-to-learnings flow.

Polished PR and issue workflows. Issue triage gained duplicate detection and smarter label management, and triage-issue was split out from triage-issues for single-issue versus batch processing. The ghx CLI was introduced and integrated into the review and feedback skills. It adds inline PR review comments, pending reviews, and comment stashing that the standard gh CLI does not support. Reversibility checks were added across review-* skills, and forward compatibility checks were introduced. create-issue had its duplicate checking restored and time estimates improved. A new automate-session skill was added to identify repetitive workflows worth encoding as skills.

Added new lifecycle and utility skills. create-needs-assessment and review-needs-assessment evaluate whether a feature addresses a genuine need before investing in feasibility or requirements. research-article maps the state of the art before writing, producing a research brief with organized sources. setup-docs-site scaffolds a MkDocs documentation site with a GitHub Actions publish workflow. vacation-handoff generates a pre-leave handoff covering deadlines, on-call coverage, and in-flight work. audit-attention analyzes how time splits between compounding and depreciating activities using the two-year test, suggesting what to delegate versus protect. create-message improves outgoing messages by removing negative tone and adding actionable suggestions. summarize-meeting produces a structured meeting summary from a transcript file. review-skills and compare-skills audit the skill library itself for duplicates, broken references, orphaned skills, and practices worth adopting from other libraries.

Closed three of last month’s needs. Replying to inline PR comments, listed as a need in May, is now fully integrated into the review and feedback skills via ghx. Incremental PR description updates, also listed in May, are now handled by the update-pr-description skill, which makes minimal adjustments to the existing description after new commits rather than regenerating from scratch. Bug reproduction now triggers automatically when the “bug” label is added to an issue via reproduce-issue, though commenting results back on the issue is still unreliable.

What I Currently Need
#

From last month, the following are still needed in priority order:

The new needs for this month:

Skill usage tracking. I started using agentsview, which lets you filter conversation logs on terms. Given a list of skill names over time, it is possible to filter on those names as long as they were not expanded. OpenCode only expands slash commands if they start a message, so prefixing them with a space prevents auto-expansion and would allow tracking, but that workaround is inelegant and needs a cleaner solution.

Contextual Slack support. slack-cached can already read Slack threads, and given the right working directory it may have enough relevant context to help users better than generic Q&A pairs. What remains is connecting it to an actual support workflow.

Automate issue triage follow-up conversations. The triage-issues skill currently sends a single message when an issue is received. If the user replies, no further LLM interaction happens. The triage loop should continue the conversation until the issue is fully qualified.

Reliable bug reproduction comments. The reproduce-issue skill now triggers automatically when the “bug” label is added to an issue, but commenting the reproduction results back on the issue is unreliable and needs to be stabilized.

Introduce loops to automate skill usage. As described in Loops as Files, loops provide a scheduling layer that can run skills on a recurring basis without manual triggering. Connecting skills to loops would enable workflows like automated issue triage, weekly repository syncs, and scheduled PR reviews to run unattended.

Explore routines, habits, and event-driven skill triggering. Beyond loops, I want to investigate routines and event-driven triggers that fire skills when the right conditions occur. As the skill library grows past 130 skills, some are never used simply because nothing is set up to invoke them. Connecting those skills to the right trigger or schedule would enable work that currently goes undone.

Improve the SDLC status report. As I work on large features, iterating involves back and forth between SDLC stages that requires changes to be backported and then forward propagated. The sdlc-status report needs better content and visualization to make this flow visible and navigable.

Reduce manual testing and validation. I spend too much time manually testing and validating that a feature works as expected. The improve-autonomy skill should help close this gap, but the challenge is behavioral: I instinctively revert to doing it myself instead of immediately asking how an agent could do what I am about to do.

Rework llm-augmented-workflows for flexibility. llm-augmented-workflows needs to be reworked to handle feature and bug fix requests flows more flexibly, and to support other harnesses beyond Claude Code such as OpenCode and Pi.

AI-Maxxing and Resistance Are the Same Mistake: Optimize Attention, Not AI Quantity

tom@tomrochette.com (Tom Rochette) — Mon, 22 Jun 2026 00:00:00 +0000

Two camps have formed around LLMs, and they sound like opposites. One wants AI in everything, automating every task that can be automated, measuring success by how little the human touches. The other wants AI kept at a distance, preserving the craft, the understanding, and the roles that made the field what it is. They are not opposites; they are the same mistake pointed in different directions, and the mistake is optimizing how much AI to use instead of where to spend the attention AI frees up.

Two Stances, One Error
#

AI-maxxing treats the fraction of work delegated to a model as a score to be maximized. If a task can be automated, it should be, and the human’s remaining job is to orchestrate ever more automation. Its logical endpoint is the self-evolving codebase, the LLM agent company, the one-person team driving a dozen agents in parallel, none of them jokes and all of them early sketches of a genuine stance.

Resistance treats the fraction of work kept in human hands as a value to be defended. If a task can be done by hand, it should be, because doing it by hand is what builds the skill and the identity that make the work worth doing. Its logical endpoint is the engineer in 2026 still typing boilerplate from memory and calling it craft.

Each camp has a valid insight. The AI-maxxer is right that production has stopped being the bottleneck, and that clinging to manual production is no longer rational. The resistor is right that not everything delegable should be delegated, because delegation can erode the very capability that makes delegation safe. Both are right about the other’s blind spot and wrong about their own, because neither is asking the question that actually decides the outcome.

The Question Neither Camp Asks
#

The question that matters is not “how much AI should I use?” It is “of the things I do, which are depreciating and which are compounding, and does AI move each one in the right direction?”

A depreciating activity is one whose value drops as the environment changes. Typing boilerplate, memorizing an API, writing the fifth CRUD endpoint of the week: these were valuable when production was scarce, and their value keeps dropping every month that models get better. A compounding activity is one whose value rises the more of it you do, and that feeds back into everything else. Understanding a domain deeply, holding taste about what to build, judging whether a piece of code solves the right problem: these do not decay, and they make every other thing you do more effective.

The right stance follows from this distinction immediately. Delegate depreciating activities ruthlessly, and protect compounding activities ferociously.

The AI-maxxer breaks this rule by applying delegation to everything, including the compounding activities, and slowly weakens the judgment layer that makes the delegation produce anything worth having. The resistor breaks it by applying the protection rule to everything, including the depreciating activities, and slowly trades future capability to preserve a skill the market no longer rewards.

Why AI-Maxxing Is the More Insidious Error
#

Here is the asymmetry that makes this more than a polite “both sides” essay.

Resistance is a recoverable error. The resistor falls behind, notices eventually, and can adopt the tools later. The depreciating skills they protected are still useful during the transition, and the AI is still available. The cost is lost time, which is significant but bounded.

AI-maxxing is an insidious error, because it feels like winning the whole time. The output keeps flowing. The pull requests keep landing. The agents keep producing plausible, confident, well-formatted work, and nothing in the loop tells you that the judgment layer underneath has been quietly atrophying.

Delegation is not free even when the model is free. Every time you delegate a compounding activity, deciding what to build, evaluating whether the generated code is correct, choosing between two architectures, you forgo the practice that built the judgment you would need to evaluate the delegation. The AI-maxxer assumes judgment persists without exercise. It does not. A mind that never decides what to build loses the ability to tell whether what was built is worth shipping, and no model substitutes for that loss, because using the model well already presupposes it.

This atrophy is the problem I described in The Shifting Bottleneck: when you automate a layer, the bottleneck moves up to a more judgment-heavy layer, it does not disappear. The difference is that the bottleneck article described the move as something that happens to the system. AI-maxxing is what happens when you mistake the move for a disappearance, and convince yourself there is no bottleneck left worth staffing.

Why Resistance Is Wrong, but Less Dangerously
#

The resistor’s error is the opposite, and it deserves to be stated fairly.

Most of what the resistor calls craft is just production, and production has stopped being the scarce thing. Writing code by hand does not teach the domain faster than reading code, including generated code, with intent. Memorizing an API does not make you a better architect; it makes you a faster typist, for an API that will be deprecated in eighteen months. Protecting a depreciating activity in the name of craft is not craft; it is nostalgia that will not last.

The legitimate part of resistance is the fear that delegation erodes capability. That fear is correct, and the AI-maxxer should adopt it too. But the answer is not to refuse delegation across the board. The answer is to refuse it selectively, at exactly the compounding activities where the erosion matters, and to embrace it everywhere else so aggressively that you free up the time to do the compounding work properly.

The resistor who types their own boilerplate to stay skilled ends up with less time for the deep domain work that would actually build their skill, and they are protecting the wrong layer. The AI-maxxer who delegates the deep domain work to “focus on orchestration” ends up with nothing left to orchestrate well, because orchestration without domain depth is just queue management.

The Test That Settles It
#

For any activity on your plate, ask one question. If I let the model do this for the next two years, will the me that emerges be more valuable, or less, than the me that kept doing it by hand?

Boilerplate, scaffolding, routine tests, formatting, summarizing a thread, drafting a first pass at a known pattern: delegate all of it, and the you that emerges after two years is more valuable, because you spent those two years on something else that compounded. Deciding what to build, judging whether a design is right, reading a hard paper with the intent of being able to teach it, debugging a subtle failure by reasoning about the system: keep these, even when a model offers to do them, because the two years of practice is the entire asset.

Notice that the test is about the allocation of your attention, not the quantity of AI you use. An engineer who delegates ninety percent of their work to a model and spends the freed time going deeper on the remaining ten percent is not the AI-maxxer this essay argues against. They are doing it right, and the high delegation ratio is a symptom of having correctly identified their compounding layer, not a target they are optimizing for. The number to watch is not how much you delegate; it is how much of your remaining time lands on compounding work.

The Boundary Moves, and That Is the Hard Part
#

The complication, and the reason the sorting is not a one-time exercise, is that the line between depreciating and compounding is not fixed.

A thing that was compounding yesterday can become depreciating tomorrow. Writing SQL by hand was once a compounding skill, a path to a deep understanding of how the data informs the business; today the model writes the query and the deep part is knowing what to ask it for and whether the result is truthful. Reading logs was once a compounding skill; increasingly the model triages them and the deep part is deciding which anomalies matter. Each shift in capability redraws the line, and the stance that worked last year can become either error in the next.

The moving boundary is why neither camp has a stable answer. The AI-maxxer’s “delegate everything” is wrong because some of what they delegate is still compounding, and the resistor’s “do everything by hand” is wrong because some of what they protect has already stopped compounding. The only stable skill is the meta-skill of repeatedly telling the two apart, and that meta-skill is itself compounding, which is the strongest case I can make for spending attention on it.

What to Do Next
#

Stop measuring yourself by how much AI you use, in either direction. Run the inventory instead. List the activities that fill your week, and mark each one depreciating or compounding, using the two-year test. Then act forcefully in both directions: delegate the depreciating ones as aggressively as you can, and reserve time for the compounding ones so that the time you freed up actually lands on them.

Do not be surprised if the result is a higher delegation ratio than the resistor would tolerate and a lower one than the AI-maxxer would brag about. That is what getting it right looks like. The ratio is an output, not a target.

And watch the boundary. Re-run the inventory every few months, because the model’s growth will have moved it, and an activity that was worth keeping may now be worth delegating, or, more dangerously, the reverse. The most expensive mistake in either direction is the one you keep making because you sorted the list once and never looked again.

The AI-maxxer and the resistor are each certain they have found the answer, and that certainty is the actual cost. The correct stance is uncomfortable: delegate like a maximalist, protect like a minimalist, and never stop asking which is which.

References
#

Goodhart’s law - why maximizing a proxy (fraction of work delegated) undermines the outcome the proxy stood for
Theory of constraints - the framework for why removing one bottleneck reveals the next, and why delegation never eliminates the judgment layer
Automation bias - the tendency to over-trust automated output, the failure mode that lets AI-maxxing feel like winning while judgment atrophies
Satisficing - settling for “good enough” outputs, the silent cost of delegating compounding activities to a system that optimizes plausibility

Keeping Up With AI Is a Losing Strategy

tom@tomrochette.com (Tom Rochette) — Mon, 22 Jun 2026 00:00:00 +0000

Every week brings a new frontier model, a new agent framework, a new benchmark, and a new wave of posts explaining why this latest development changes everything. The production of AI-related information is growing exponentially. My ability to consume it is not, and neither is yours. Keeping up is the wrong goal, and chasing it will quietly consume the time and attention you need to actually use any of it.

The Asymmetry
#

Information overload is not new. What is new is the asymmetry between production and consumption in a domain that is itself being transformed by the technology it covers.

A human reads at roughly the same rate today as a generation ago: a few hundred words per minute, a handful of long-form pieces per day, a finite number of hours in the week. Meanwhile the supply of AI content is compounding. arXiv’s machine learning categories add thousands of papers every month, with submission volumes climbing year over year. Model providers ship flagship releases on a monthly cadence where they used to ship annually. And now a meaningful fraction of that content is itself written, summarized, or generated by LLMs, which means: AI produces content about AI faster than humans can read content about AI.

The loop is structurally different from “there is a lot to read.” The half-life of any specific fact is shrinking while the rate at which new facts arrive is rising. Both halves of the ratio are changing at once, and both changes make keeping up harder.

Why “Just Keep Up” Fails
#

The instinctive response to the volume of AI content is to read faster, subscribe to more newsletters, and make more time. I tried all three. Reading faster works for a linear stream. The strategy fails when the stream grows exponentially.

Every new source you add also adds its own outgoing links, its own recommendations, its own “you should also read this.” The graph of things you could read grows faster than the list of things you have read. You are not behind because you are undisciplined. You are behind because the target is moving faster than your means of reaching it.

The cost is not only time. Constant context-switching between model announcements, framework launches, and benchmark debates produces the same attention residue and decision fatigue that come from managing too many concurrent tasks. The result is feeling informed without being informed, superficial awareness with nothing behind it. You know the names of ten new models and cannot explain how any of them differ in a way that matters.

The Reframe: Optimize for Signal, Not Coverage
#

Coverage is impossible, so stop measuring yourself against it. The objective is not to read everything. The objective is to make good decisions about what to read, what to build, and what to ignore.

Making those decisions is a filtering problem, not a reading problem. And filters are something you can design, tune, and improve, unlike your reading speed.

Separate the Durable From the Ephemeral
#

Most of what feels urgent in the AI cycle is ephemeral. A specific model’s benchmark numbers, a specific launch event, a specific viral demo: these items date within weeks. A surprising amount is durable. The mechanics of attention, the basics of context and prompting, the theory of constraints in a pipeline, the economic profile of inference costs, the difference between evaluation and vibes: these ideas barely change across model generations.

When you are time-constrained, overweight the durable. Read one paper that teaches you a concept you will reuse for years over ten posts that summarize this week’s leaderboard. The ephemeral items are not worthless, but they should be consumed on demand, when a specific decision requires them, not on a schedule driven by fear.

Build a Funnel, Not a List
#

A reading list is an unordered collection of “should read” items. A funnel is a staged filter that gets cheaper at each stage.

At the top, sample broadly through a small number of trusted curators and aggregators, and let them do the first pass. At the middle, use titles and one-paragraph summaries to decide what earns a closer look. At the bottom, read the few items that survive, deeply. Most items should be discarded at the top of the funnel, never reaching your full attention. The goal of a funnel is to discard almost everything, confidently and without guilt.

This is the same principle behind supervising many agents at once: you cannot hold it all in working memory, so you externalize state, standardize summaries, and let most of the system run without your involvement (see Managing Many Concurrent LLM Agent Sessions).

Use AI to Compress the Stream to Your Bandwidth
#

The same technology producing this volume of content is also the best tool for handling it.

Have an LLM summarize a forty-page paper into the three things you actually need. Have it compare two model release notes and tell you what differs in a way that affects your work. Have it triage a week of submissions and rank them against your stated interests. Used this way, the LLM is a lossy compressor tuned to the decisions you actually need to make.

The risk is that summaries carry the summarizer’s blind spots. Mitigate it by going to primary sources for anything you intend to act on, and by keeping the durable layer of your understanding built from full readings, not compressions. Summaries are for triage and breadth; depth still requires reading the original document.

Consume on Demand, Not on Schedule
#

Push consumption, reading whatever arrived in your feed today, optimizes for the producer’s schedule. Pull consumption, reading what a current problem requires, optimizes for yours.

Most of what you “need to know” about a new model or tool only matters once you have a task that touches it. Until then, the information is inventory. When the task arrives, the information is usually still there, and a focused hour of just-in-time learning will beat ten hours of distracted pre-reading. Knowing where to find something when you need it is a more durable skill than knowing it now.

This approach feels uncomfortable, because it requires trusting that you will not miss something critical. You will miss some things. You will also miss things by spending your day reading instead of doing, and those misses are silent.

Pick a Few Sources and Defend Them
#

There are more newsletters, podcasts, and feed channels than any person can sample, and most of them recycle the same primary sources. Find the small set that consistently adds signal rather than volume, and defend that set against additions. Every new subscription should displace an existing one, not stack on top of it.

The same applies to people. A few colleagues or communities that share your context will filter better than any algorithm, because they know what you already know and what you are trying to do.

The Skill That Compounds
#

Fighting the volume of AI content makes it easy to miss what actually compounds.

Your current knowledge of AI is a depreciating asset. Specific model behaviors, tool APIs, and leaderboard rankings decay within months. What does not depreciate is the rate at which you can learn a new tool when you need it, the quality of your filter, and your understanding of the durable layer beneath the releases. These compound, and they are the only things in this cycle that do.

A developer who has internalized the theory of constraints, the structure of an LLM pipeline, and the difference between evaluation and marketing can pick up this week’s framework in an afternoon. A developer who chased every release for two years but never built that foundation knows a hundred tool names and cannot reason about any of them. The first developer can adapt to the pace of change. The second is controlled by it.

The Bottleneck Moves, Again
#

The deeper pattern is the one described in The Shifting Bottleneck. When code generation stopped being the bottleneck, review became it. When review is automated, specification and judgment become it.

Information consumption has its own version. Once reading everything stops being possible, triage becomes the bottleneck. Once triage is delegated to AI, choosing what to care about, at the level of goals and taste, becomes the bottleneck. Each time you solve one layer, the constraint moves up to a more human, more judgment-heavy layer. The judgment layer is where the durable work happens, and it is also the layer that reading faster helps least.

What to Actually Do
#

Stop trying to keep up. Pick a small set of high-signal sources and ignore the rest. Overweight durable concepts over ephemeral releases. Build a funnel that discards most things. Use LLMs to compress the stream to your bandwidth, then read primary sources for anything you will act on. Switch from push to pull: learn on demand, when an actual task requires it. And spend the time you reclaim on the layer that compounds, your filter, your learning rate, and your judgment.

You will miss things. So will the person who reads all day, and they will also have missed the chance to build anything with what they read.

References
#

Information overload - the long-standing name for the underlying problem, predating the current AI cycle
Half-life of knowledge - frames why specific facts decay while fundamentals hold
Just-in-time learning - the pull-based alternative to scheduled, fear-driven consumption
arXiv usage statistics - makes the production side of the asymmetry concrete

Loops as Files: The Scheduling Layer Skills Forgot

tom@tomrochette.com (Tom Rochette) — Sun, 21 Jun 2026 00:00:00 +0000

Skills as files solved one half of the automation problem. They told the model how to do a task, versioned and reviewable, loaded into context on demand. They did not solve the other half. They told the model nothing about when to run. A skill is inert until something invokes it, and in practice that something is almost always a human typing a command.

That leaves the most experienced agent in your system doing nothing until you remember to ask it. It also leaves every event in your environment, the issue that was just opened, the Slack thread that just became active, the dependency that just shipped a security patch, waiting for a human to notice and forward it to the right skill. The human has become the scheduler.

The fix is the same form as the fix for the variance problem in Bringing Everyone to the Same Level: take the invisible process out of someone’s head and make it a file. Except the process to extract now is not “how do I triage an issue,” it is “when do I triage issues, and what triggers that decision.” That belongs in a file too, and that file is a loop.

The Asymmetry Between How and When
#

Skills files normalized a useful idea. The prompt is the asset, the asset is text, text is versioned in git, and versioned text is reviewed, diffed, shared, and reused like code. The same model that made skills valuable applies cleanly to the trigger layer, but the trigger layer is still being treated as an implementation detail. It lives in crontabs nobody reads, in GitHub Action YAMLs that drift away from the skills they invoke, in shell scripts that bake agent invocations into system paths.

The result is that the two halves of an autonomous workflow are managed in different places. The prompt is curated. The trigger is improvised. When the prompt changes, the trigger does not, and when the trigger breaks, nobody who understands the prompt finds out until the agent has been silent for a week.

The schedule is part of the behavior. A skill that runs on /deploy and the same skill that runs at 02:00 every Tuesday are not the same skill. They have different blast radius, different cost profile, and different failure modes, and they deserve to be specified, reviewed, and owned together.

What a Loop File Is
#

A loop file is a markdown document with two parts. The frontmatter declares when it runs and under what constraints. The body declares what it does, almost always by composing skills that already exist.

In form it is the closest existing analog to a GitHub Actions workflow file, except the unit of work is not a shell command, it is an agent invocation with a loaded skill.

A minimal example:

---
name: hourly-issue-triage
description: Triage new issues as they appear, every hour.
on:
  schedule:
    cron: "0 * * * *"
skills: [triage-issue]
budget:
  max-runs-per-day: 24
  max-cost-usd-per-run: 0.50
---

# Hourly Issue Triage

For every issue opened since the last run, invoke `/triage-issue`.
Defer to the skill for all classification logic.
Stop when the budget for this run is exhausted and resume on the next tick.

That is the whole artifact. The skill owns the how. The loop owns the when, the how-often, the how-much, and the what-to-do-when-it-breaks. Each concern is in its own file, each file is reviewable, and changes to one do not silently invalidate the other.

The Frontmatter Is the Contract
#

The reason the frontmatter matters more than the body is that the frontmatter is the part the runtime actually parses. It is the contract between the human writing the loop and the system executing it.

A skill with no frontmatter is still useful as a document. A loop with no frontmatter is a skill with no trigger. So the fields that go in the frontmatter are not cosmetic metadata, they are the trigger specification, and they should be designed the way any interface is designed, with the smallest set of concepts that covers the realistic workload.

The field I want to anchor on is on, borrowed deliberately from GitHub Actions because the mental model is already widely understood. on says what causes this loop to fire, and its value can be one or many of three things.

Time
#

on:
  schedule:
    cron: "0 * * * *"

Cron is the obvious first case, and there is no reason to invent a new syntax for it. Cron is ugly, but it is universally understood, parseable, and already supported by every scheduler the reader is likely to have. Most loops that need to run on a clock are well expressed as a single cron expression, and loops that need more complex recurrence can compose multiple loop files.

A secondary form worth supporting is an interval, for cases where wall-clock alignment does not matter:

on:
  interval:
    every: 15m

Interval is easier to read and easier to distribute across a fleet, since N agents with every: 15m will naturally desynchronize in a way that cron will not.

Events
#

Time is the easy case. The interesting case is event-driven, which is where the word “loop” undersells what is going on. A loop that fires on a schedule is just a cron job with a markdown file on top. A loop that fires on an event is something genuinely new: a versioned, reviewable handler for things that happen in the world.

on:
  events:
    - type: github.issues.opened
      repo: "owner/repo"
      filter: "labels.length == 0"

    - type: slack.mention
      channels: ["#support"]
      filter: "text contains 'sev1'"

    - type: github.pull_request.opened
      repo: "owner/repo"
      filter: "author.trust < 'trusted'"

    - type: file.changed
      paths: ["pyproject.toml", "uv.lock"]

    - type: metric.threshold
      metric: api.error_rate
      window: 5m
      op: ">"
      value: 0.01

The pattern is the same in every case: a typed event source, an optional scope, and an optional filter expression. The types themselves are namespaced by source (github.*, slack.*, file.*, metric.*) so that adding a new integration is additive rather than a schema change.

A single loop can declare multiple events, and the runtime treats them as a logical OR. That covers the common case of “I want this skill to fire on a cron or when a human pokes it,” which is exactly the pattern of most operational loops.

Webhooks
#

The third trigger is a catch-all for events the runtime cannot subscribe to directly. A webhook is an event source the runtime exposes rather than consumes.

on:
  webhook:
    path: /loops/deploy-staging
    secret: ${DEPLOY_WEBHOOK_SECRET}

Anything that can hit an HTTP endpoint, from a monitoring tool to a ChatOps button to a physical device, can now trigger a skill, and the access control is defined next to the prompt it gates.

The Frontmatter That Prevents the Loop From Eating Your Wallet
#

Time and events say when to start. The loop also needs to say when to stop, and this is the part that existing skill files do not need and loop files cannot exist without.

budget:
  max-runs-per-day: 24
  max-cost-usd-per-run: 0.50
  max-concurrent: 1
concurrency: cancel-previous  # cancel-previous | queue | drop
timeout: 10m
on-failure: alert      # alert | retry | escalate | ignore
escalation:
  skill: notify-on-call
  after: 3 failures

I argued in The Self-Evolving Repository that cost runaway is one of the defining failure modes of autonomous systems, and a loop without a budget is one bad while True away from a runaway incident. Every loop file should be able to answer three questions without ambiguity: how often can this run, how much can each run spend, and what happens when it fails. If a loop cannot answer those questions, the runtime should refuse to start it.

The concurrency field is the other one that proves necessary early. A loop that runs every five minutes and takes six minutes to finish will, without a concurrency policy, slowly consume every slot the runtime has. cancel-previous, queue, and drop cover the realistic cases, and the right default is cancel-previous for anything stateless.

Loops Compose Skills, They Do Not Replace Them
#

There is a temptation, once you have a loop format, to start inlining the prompt into the loop body. Resist it. A loop file should read like an orchestrator, not like a skill, because it is one.

The body of a loop is typically a short sequence of skill invocations, with just enough glue logic to express ordering, branching, and handoff.

# Nightly Dependency Review

1. `/audit-dependencies` against the current lockfile.
2. If it reports any `severity >= high`, `/create-issue` with the audit output.
3. `/notify-on-call` summarizing counts and the worst offender.

Three skills, one paragraph of orchestration, fully readable. The logic that is hard (what counts as a high-severity vulnerability, how to phrase an issue, who the on-call is) lives in the skills it invokes, where it can be improved independently, tested independently, and reused from other loops.

This also keeps the loop file focused on its job. A loop file that grows past a screen of text is probably doing the work of a skill and should be split. The same length discipline that keeps skills effective, which I borrowed from the “lost in the middle” argument in Bringing Everyone to the Same Level, applies to loops. If the runtime has to parse a long preamble before it even reaches the trigger, the trigger is no longer the contract.

Why Loops Have to Be Files
#

Every argument for skills as files applies, with minor edits, to loops as files, and one new argument applies only to loops.

Versioning. A trigger change is a behavior change. “Run triage on every new issue” and “run triage on every new issue except those from outside contributors” are different policies with different consequences. A trigger that lives in a crontab or a GitHub Actions YAML that nobody reviews is a policy that nobody reviewed, and reviewing it matters because the consequences of a trigger bug (silently not running, or silently running too often) are usually larger than the consequences of a prompt bug.

Reviewability. A loop file in git means every change goes through a pull request, which means the blast radius of the change is visible to the people who will be paged when it goes wrong. This is the same point I made, about code, in The Codebase Gardener: a standard that exists only in someone’s head is lost when that person goes on vacation. A loop that exists only in someone’s crontab will be forgotten just as quickly.

Portability. A loop file describes what should happen, not where it runs. The same file can be executed by a local scheduler during development, by a team-shared runner in production, and by a CI provider that wants to dry-run it on every commit. That portability is what makes loops shareable across teams the way skills are shareable, and it is what makes a “loop library” a coherent concept in a way that a “crontab library” never was.

Diffability. The single most useful property of a file is that you can git blame it. When the on-call gets paged at 03:00 because the deployment loop has been firing every two minutes for an hour, the first question is “who changed the trigger, when, and why,” and the answer should be one git log away, not a long manual search through a CI settings UI.

The argument that applies only to loops is co-location with the skill. A skill file and the loop that schedules it are describing two facets of the same behavior, and when they live in the same repository, in the same format, in the same review pipeline, they evolve together. A skill change that should have changed the trigger (say, “this skill is now expensive, run it less often”) is a change that can actually be made in the same pull request by the same person who understood the consequence.

What the Runtime Owes You
#

A loop format without a runtime is only a proposal. The runtime is what makes loops safe to leave running, and it owes the operator a small, specific set of behaviors that are not optional.

Idempotency by default. A loop will be double-triggered. The cron will fire twice during a clock skew. The webhook will be retried. The runtime must be willing to run the same loop with the same inputs twice and treat the second run as a no-op, which means the skills it invokes must be idempotent, which is a property worth designing into skills whether they are loop-driven or not.

Per-run state. Every run writes a state file, in the same form I described in Managing Many Concurrent LLM Agent Sessions: what fired, what ran, what it produced, what it cost, what it will do next time. Without this, debugging a misbehaving loop is reading logs, and reading logs is what we used to do before we had files.

A kill switch. There must be one command, one CLI flag, one environment variable, that stops every running loop and disables every scheduled trigger. The cost of not having this is the cost of not having a circuit breaker in your electrical panel.

Observability that is not optional. A loop that fails silently is strictly worse than no loop at all, because no loop at least fails loudly when a human expected it. Every run emits run-started, run-succeeded, run-failed, run-budget-exceeded events, and the runtime ships them to whatever sink the operator already trusts.

Dry run. --dry-run evaluates the trigger, selects the skill, expands the inputs, and prints what it would have done, without invoking the model. This is the cheapest possible way to debug a trigger filter, and it should exist on every loop runner.

What Goes Wrong
#

Loops inherit the failure modes of any autonomous system and add two of their own.

Drift toward the measurable. A loop that fires on github.issues.opened will, over time, optimize the project for issue-driven signals, because those are the signals that cause work to happen. The project stops reacting to anything that does not show up as an event the loop can see. This is Goodhart’s law applied to ops automation, and the defense is the same as in The Self-Evolving Repository: keep a human-edited roadmap, and reserve a small number of loops for periodic “what should we be working on” reflection that is not event-driven.

Loops stepping on loops. Once loops are cheap to write, people write a lot of them. Two loops that both touch the same issue tracker, both with their own opinions about labels and priorities, will quietly conflict with each other, and the issue tracker’s state will become inconsistent. The runtime needs loop-level isolation (separate working directories, separate state files, separate rate limits) and a registry that makes it easy to answer “which loops currently fire on this event,” the same way a codebase makes it easy to answer “which tests currently exercise this function.”

Trigger rot. A loop that worked when it was written will silently stop working when the thing it triggers on changes form, the GitHub webhook payload gains a field, the Slack channel gets renamed, the metric gets relabeled. Loops need the same periodic sweep that code needs, and the sweep is mechanical: for each loop, fire its trigger in dry-run, confirm the skill still runs, retire the loops that nobody owns.

Cost runaway, again. Worth saying twice. An event-driven loop with no budget, attached to a busy event source, can turn a busy Slack day into a four-digit API bill. The budget field in the frontmatter exists for exactly this reason, and the runtime must enforce it hard, not warn softly.

The Naming Question
#

I have used “loop” throughout because it captures the simplest mental model: something that runs again and again. But “loop” undersells the format. A loop that fires only on slack.mention is not really looping. It is reacting.

The more accurate name is probably “routine,” “trigger,” or “automation,” and the reason none of those quite works is that each one emphasizes one of the two trigger classes at the expense of the other. “Loop” emphasizes time. “Trigger” emphasizes events. “Routine” emphasizes the work. The format itself does not care. The on: field is the source of truth, and the file is whatever its trigger says it is.

In practice, teams that adopt this will settle on one word and use it for both, the same way “skill” is now used for files that range from one-line hints to multi-page workflows. The word matters less than the format, and the format is: markdown, frontmatter, on, a budget, a short body.

What to Do Next
#

You do not need a runtime to start.

Find the one task that you do on a cadence and keep doing manually because it is “too small to automate.” Triage the overnight issue queue. Summarize the Slack channel at end of day. Check whether dependencies have shipped patches. That task is your first loop.

Write it as a loop file, even if the runtime that will execute it does not exist yet. Write the frontmatter faithfully, the trigger you want, the budget you would accept, the skill it should invoke. If the skill does not exist yet, write its stub too.

You now have two artifacts that describe the behavior you want, in the same repository, in the same format, reviewable in the same pull request. When a runtime arrives (and several already will, given how cheaply existing coding agents can be wrapped in a scheduler), your loop is ready to drop in.

Then do it again with the next task, and the next. Each loop file is a piece of operational judgment that stops being a private habit and starts being a shared, owned, versioned standard. The team that wins in this era is not the one with the most skills. It is the one whose skills run, on time and on event, without anyone remembering to ask them to.

References
#

Wikipedia, “Cron” - the time-based job scheduler whose syntax the on.schedule.cron field borrows wholesale, because there is no value in inventing a new one
GitHub Actions documentation, “Events that trigger workflows” - the on: mental model and event taxonomy this format deliberately mirrors, so readers do not have to learn a new concept
Wikipedia, “Idempotence” - the mathematical property that makes loops safe to re-trigger, and therefore the property every skill invoked by a loop must be designed to have
Wikipedia, “Goodhart’s law” - why an event-driven loop will optimize for whatever its events measure, and why a non-event-driven reflection loop must exist alongside it
Wikipedia, “The Checklist Manifesto” - Atul Gawande’s case that disciplined, written checklists outperform expert memory, which is the same argument for trigger files as it was for skill files

When a Closed Decision Reopens: Breaking the Scope Relitigation Cycle

tom@tomrochette.com (Tom Rochette) — Sun, 21 Jun 2026 00:00:00 +0000

A decision reached with your principal did not actually close the question. It closed the question in the room where it was made. When a new manager met the senior leader for the first time, the shared understanding that took weeks to build did not transfer, and the original ambiguity returned. The cycle you cannot escape is not a scope problem. It is a context-transfer problem that looks like a scope problem.

The Decision Didn’t Reopen. The Context Didn’t Transfer.
#

When leadership says “build this feature” without saying what “this” means, they have not given you a requirement. They have given you a vague goal, and asked you to find a concrete target inside it. You did the right thing. You built a demo to make the vague goal concrete enough to react to, you sat with the principal, and you negotiated a concrete, buildable target. That work was genuine, and it was correct.

Then a person who was not in the room walked into a different room with the senior leader, and the target changed.

The target moving feels like betrayal, or like a failure of the new manager, or like leadership changing its mind. It is usually none of those. It is the predictable consequence of a decision that was never written down in a form that could travel. A decision that exists only in the memory of the people who were present is a decision that cannot hold when it reaches anyone who was absent. Your organization keeps generating absent people: new hires, new managers, new conversations, new quarters. Every unwritten decision remains valid only until one new person enters the chain.

The senior leader was never actually aligned with you on a specific scope. They were aligned with a feeling, which is that the feature should be impressive and should exist. The specific, feasible compromise you reached with the principal was never transferred back to the person whose vague wish started the whole thing. So when the topic came up again, the leader returned to the only thing they still had, which was the original wish, unmodified by everything you had since learned was impossible.

You Have Two Problems, Not One
#

The conversation keeps switching between two positions because two genuinely different questions have been mixed together into one discussion, and the two questions keep conflicting.

The first question is the north star: what would the ideal version of this feature look like, if the tools caught up and the constraints disappeared? That vision is valuable. It tells you which direction to take, and it is the thing that excites leadership in the first place.

The second question is the milestone: what will we actually ship this quarter, with the tools we have today? That answer is necessarily smaller, uglier, and more compromised than the north star, and it is the only thing you can actually build.

The cycle happens when leadership talks about the north star and hears your milestone answer as a refusal, and when you talk about the milestone and hear their north star answer as scope creep. You are both correct, about different questions, and the conflict continues entirely because nobody has written the two answers on the same page and separated them.

The fix is to separate the questions, explicitly and in writing. Keep the north star. Document it, reference it, and let it do the work of inspiring people. Then, underneath it, write separately what you are committing to build now, why that subset and not another, and what specifically would have to change for the next increment to become feasible. The north star is a direction. The milestone is a contract. Confusing the two is what makes every meeting feel like the last meeting, again.

“That’s Impossible” Is Not an Answer a Leader Can Process
#

Here is the cruelest part of the situation, and the one most likely to block progress.

When you tell leadership “we can’t build the full vision, the tools aren’t there yet,” you are reporting a technical fact, and you expect it to be received as a boundary. It does not. It is received as an opinion, and a suspicious one, because every leader has heard engineers declare things impossible that later turned out to be merely hard. The word “impossible” carries no information a decision-maker can act on. It sounds like reluctance, and so it invites the very relitigation you are trying to end.

The move that actually ends the cycle is to convert impossibility into a set of specific, dated, falsifiable claims. Not “we can’t do X,” but “X requires capability Y, which does not exist in our stack; the closest vendor offering is at stage Z; building it ourselves is an estimated N months of work from the platform team, which is not currently funded.” Now the leader is not arguing with your willingness. They are looking at a menu, and the menu has prices on it. They can choose to accept the limit, fund the enabler, or descope, but whatever they choose, they are choosing with information instead of against a feeling.

Saying “impossible” stops the decision. An itemized list of what it would take lets the decision move forward. Leaders cannot act on a flat refusal, but they will act on an itemized list, and often they will fund the capability that enables the next step. This reframing also protects you. The day the tools do catch up, your document already names the capability you were waiting for, and reaching the north star becomes a matter of executing a plan you wrote months ago instead of restarting the conversation from scratch.

A Verbal Decision Is Just an Opinion That Hasn’t Been Overwritten Yet
#

The single highest-leverage thing you can do to stop the cycle is to insist that decisions get written down the moment they are made, in a place that outlives the meeting.

This is what Architecture Decision Records were invented for, as Michael Nygard argued when he proposed the format. The record is a short document that captures the context, the decision, the alternatives considered, and the status, so that a person who arrives later can understand not just what was decided but why. The same discipline applies to scope decisions, which are every bit as consequential as architectural ones. A one-page record that says “we will build this subset, not the full vision, because of these specific constraints, and we agreed this on this date with these people” is worth more than any number of follow-up meetings.

The reason writing matters more than talking is that writing behaves differently from speech. A conversation degrades the instant it ends. The memory of it degrades faster, and as it passes through more mouths it distorts, the way the children’s game of telephone turns a clean phrase into nonsense in a few retellings. A document does not degrade. It says the same thing to the new manager on their first day as it said to the principal on the day it was written. It says the same thing to the senior leader in their next one-on-one as it said in the room where the compromise was struck.

If a decision is worth making, it is worth making durable, and a decision is only as durable as the artifact it is recorded in. The cost of writing it down is ten minutes. The cost of not writing it down is the cycle you are currently in, repeated every week, forever.

The New Manager Is Not the Enemy. They Are a Missing Node.
#

It is easy, and emotionally satisfying, to blame the new manager for reopening the settled question. Resist that interpretation. Almost certainly, they walked into their first meeting with the senior leader underprepared, because nobody had handed them the history. They improvised from the leader’s enthusiasm, which pointed at the north star, not at your milestone compromise. That is not sabotage. That is a new person doing their best with the information they were given, which was not enough.

The deeper structural issue is that information in an organization flows along its communication paths, and an org that just gained a new link between the team and the senior leader has, in effect, rewired those paths. A decision that was stable under the old wiring may be unstable under the new wiring, because the new path bypasses the node where the context was stored. This is why onboarding a new manager is not a courtesy, it is a defensive necessity. Within their first week, they need to receive, in writing, the current decisions, the reasons behind them, and the constraints that produced them. A new manager who has read the decision records cannot accidentally contradict them, because they know they exist.

There is also a principal-agent dynamic here that is worth naming. The senior leader, the new manager, the principal, and you all have different information, different incentives, and different audiences they are trying to satisfy, the classic pattern of the principal-agent problem. The new manager may be, reasonably, trying to demonstrate value to their new boss, and an enthusiastic “we can do more” lands better in that first meeting than a cautious “actually, we already agreed to less.” They are not wrong to want to look good. The system is wrong to have left them no shared record to align to. Fix the system and the manager will follow it, because the record gives them something safer to bring to the leader than improvisation: a documented plan they can defend.

A Playbook for Breaking the Cycle
#

When you find yourself back at the start of a scope conversation you thought was over, do the following, in order.

First, stop re-arguing the scope in the meeting where it resurfaced. Relitigating under pressure produces worse decisions than the original ones, and it taxes the same finite decision-making energy that you need for the work itself. Gain time. Say that you want to make sure the conversation reflects everything the team has already learned, and that you will come back with a written summary. That sentence is free, and it stops the cycle.

Second, write the decision record, if it does not already exist. Context, the north star, the agreed milestone, the specific technical constraints that forced the compromise, the people who agreed, and the date. This is the artifact that should have existed all along, and creating it now is not empty procedure, it is what makes every later step work.

Third, convert every “we can’t” into a priced option. For each piece of the vision that is out of reach, write what it would take to reach it: which capability, which team, which rough timeline, which dependency. Give leadership the itemized options, not a flat refusal.

Fourth, brief the new manager before the next senior-leader conversation. Walk them through the record in person, make sure they understand the constraints, and explicitly invite them to bring their own objections now rather than in the room with the leader. Make them a co-author of the record, and they will defend it instead of overturning it.

Fifth, re-present to the senior leader, on your terms, with the record in hand. Acknowledge the north star openly, because dismissing the vision is what makes leaders resist. Then show the milestone, show the priced options, and ask for a single explicit decision: accept the current scope, fund an enabler, or descope. Whatever they choose, write the new decision down before anyone leaves the conversation. A meeting that ends without a written decision is a meeting that will have to be held again.

Finally, schedule the next scope review in advance, on a date you control, instead of waiting for the topic to come up on its own. Scope conversations are not avoidable, and they are not the enemy. The enemy is surprise relitigation, the version that catches you by surprise in someone else’s calendar. A standing quarterly review where the north star, the milestone, and the priced options are revisited together turns the cycle into a rhythm, and a rhythm is something a team can plan around.

The Lesson
#

You cannot build something that is impossible today, and you should not promise that you can. But you also cannot expect a vague wish, transmitted through a changing set of people, to ever stop generating the scope conversation you dread. The way out is not to win the argument one more time, harder. It is to change the medium in which the argument happens. Write the vision. Write the milestone. Write the prices of the gaps between them. Put all of it where the next person can find it. The conversation that reopens next month will reopen against a record instead of against your memory, and records settle those questions.

Decisions that are written, priced, and shared do not need to be relitigated, because they travel to the rooms you are not in and make your case for you.

References
#

Michael Nygard, “Documenting Architecture Decisions” - the origin of the Architecture Decision Record format, the lightweight written record this article recommends for scope decisions
Wikipedia, “Telephone (game)” - the canonical model for how information distorts as it passes through a chain of people, which is what happened when the decision crossed the new manager
Wikipedia, “Conway’s law” - why a reorganization that adds a communication link can destabilize a decision that was stable under the old structure
Wikipedia, “Principal-agent problem” - the incentive and information asymmetries between a leader, a manager, and a team that make a shared written record necessary
Wikipedia, “Decision fatigue” - why re-arguing settled scope under pressure degrades the quality of the decision and should be deferred to a written process

The Codebase Gardener: Keeping a Codebase Sane When Teammates and Their Agents Pull in Every Direction

tom@tomrochette.com (Tom Rochette) — Sat, 20 Jun 2026 00:00:00 +0000

You cannot review your way to a sane codebase when the code is being produced faster than you can read it. That mismatch is the new arithmetic of the LLM era, and it is brutal for the one engineer on the team who cares about consistency. The strategy that actually works is to stop fighting at the pull request and start fighting at the layer everyone, and every agent, is forced to pass through.

The Math Changed Under Us
#

For most of software history, one careful engineer could hold a codebase together by reviewing most of what landed in it. The volume was human. A teammate produced code at roughly the rate you could read it, and a determined reviewer could keep the drift in check. That equilibrium is gone, and two things killed it.

First, throughput. A teammate driving an LLM agent now opens in an afternoon the pull requests that used to take a week. The unit of work did not change; the rate at which units appear did.

Second, plurality. Each teammate may be driving a different agent, loaded with different skills, different conventions, a different mental picture of what “good” means for this codebase. The codebase does not converge on a single style through argument anymore. It fragments into as many dialects as there are agents producing it, and each dialect looks plausible, because plausibility is exactly what an LLM optimizes for. A function can be internally coherent, consistent with nothing around it, and wrong about the domain all at once.

You, alone, reading diffs, are now the slowest station in a pipeline that was designed to outrun you. Per-unit review scales linearly with your hours, and the entropy is being produced exponentially. No amount of discipline closes that gap.

Reviewing Harder Is the Trap
#

The instinct of the engineer who cares is to review more, longer, more strictly. Reviewing harder is exactly the wrong move, for reasons I laid out in Rethinking Code Review in the Age of LLMs. Every hour you spend line-editing someone else’s agent output is an hour the next three pull requests go unread. You become the bottleneck, and bottleneck reviewers do not stay bottleneck reviewers for long. Teammates start tagging each other for approvals, slicing changes to slip under your threshold, or simply waiting you out until you tire.

You end up exhausted, quietly resented, and still losing ground to the codebase. The worst part is that the work feels virtuous while you do it. Catching a misnamed variable in review feels like defending the standard. It is not. It is fixing one small problem while the codebase drifts as a whole.

Review is a per-unit activity, and per-unit activity cannot match entropy that is being produced faster than you can read it. If your entire strategy is “I will catch the problems at review,” the strategy has already lost. The question is not how to review better. The question is how to make most of the review unnecessary.

Move the Leverage From Review to Infrastructure
#

The way one person defends a codebase against many producers is to stop operating on the units and start operating on the system that produces them. This strategy is the theory of constraints applied to code quality: if you cannot keep up at the review station, do not add more reviewers. Change the station.

Concretely, it means every standard you care about has to live in one of the few places work is forced to pass through, rather than in your head or in your review comments. There are only a handful of such places, and together they are the entire leverage surface available to a single engineer.

The skill and rule files every agent loads at the start of a task. The CI gates every pull request must clear before it can merge. The templates and scaffolds every new module begins from. The default configuration the linters, formatters, and analyzers ship with. The hooks that run on commit, on push, and on merge.

If your standard is encoded in any of these, it executes on every change, forever, without you being present. If it lives only in your review comments, it executes only when you are awake, looking, and willing to argue about it. Running without you is the whole difference between a standard and an opinion. A standard runs whether or not anyone agrees with it. An opinion dies the moment you go on vacation.

The same point is made, from the team’s perspective, in Bringing Everyone to the Same Level: the senior engineer’s edge was always a process they ran in their head, and a process in a head does not scale. Here the stakes are higher, because you are not trying to lift the team to your level. You are trying to keep the standard in place while the team is actively, if innocently, drifting from it. The mechanism is the same. Encode the process, and let the encoding do the defending.

Make the Right Thing the Path of Least Resistance
#

Most code in a codebase is the way it is because that was the easiest thing to type at the time. This predictability is an advantage, not a problem, for someone trying to steer a codebase alone. If the easiest path also happens to be the correct path, conformity is free, and nobody has to be persuaded of anything.

This alignment is the paved road idea, and it is the single highest-leverage intervention available to a solo defender. You do not get compliance by arguing for it. You get it by making the compliant thing the thing that happens when nobody is thinking.

Ship a project template that already has the test harness, the lint config, the migration format, and the observability scaffolding wired in, and a teammate who spins up a new service produces conforming code by default, without ever reading your standards document. Wire the migration linter into CI so that a non-backward-compatible migration fails to merge, and the question of whether backward compatibility is “our standard” stops being a question at all. Friction for the wrong thing, zero friction for the right thing. That asymmetry does more work than any amount of documentation, because it operates on the path of least resistance rather than against it.

The reverse matters just as much. Remove friction from the behavior you want. If you want small, reversible changes, make small changes trivially easy to merge. If reviewing is expensive, people batch, and batching is exactly what produces the large, entangled, unreviewable pull requests that defeat you. Add friction to what you want less of, and remove friction from what you want more of, and do both in the tooling rather than in the standup.

Invariants, Not Preferences
#

Most review wars never end because most of what people fight over are preferences. Tabs versus spaces. Single exit versus early return. One assertion per test. Preferences are arguable, and in an LLM-saturated codebase, arguable means unwinnable, because the other engineer’s agent was told the exact opposite of what yours was told, with equal confidence.

The move is to convert as many preferences as possible into invariants before they can become arguments. An invariant is a property the system will enforce whether or not anyone agrees with it. Database migrations must be backward compatible. New dependencies require an audit record. Public API changes require a feature flag. Cyclomatic complexity above a threshold fails the build. These are not opinions. They are machine-checkable constraints, and a constraint that a machine checks is a constraint you never have to argue about again.

Every preference you promote to an invariant is one fewer conversation you have to win, and one fewer place the codebase can drift while you are not looking. Reserve your remaining human attention for the small set of things that genuinely cannot be encoded: taste, architectural direction, whether a feature should exist at all. Everything else should be a gate or a default, silently doing the work you used to do by hand.

Garden in Sweeps, Not in Diffs
#

Per-PR review is not the only way to fight decay, and in this era it is no longer even the best way. Some drift will always get through, because no gate is perfect and because some of what rots a codebase is not visible in any single diff. Naming conventions slide. Duplication accumulates. A module that was clean in isolation becomes tangled once three teammates have each extended it in a different direction.

The answer is to operate the Boy Scout rule at the codebase level rather than at the commit level: run regular maintenance sweeps instead of trying to catch everything one pull request at a time. Once a week, run the dead-code analysis. Run the duplication detector and look at the new clusters. Pull the complexity trend report and see which functions crossed a threshold this week. Skim a list of newly added dependencies.

A sweep lets you fix the eighty percent of drift that no individual pull request would have surfaced, and it lets you fix it in a way that does not require winning an argument on each one. You are not blocking anyone’s work. You are tidying, in batches, on your own time, against objective signals from the tools. The gardener does not follow every leaf as it falls. The gardener rakes.

Sweeping is also the frank acknowledgment that some entropy is the cost of speed, and that the goal is not zero drift. The goal is a drift rate low enough that your weekly sweep runs net positive, so that over months the codebase gets cleaner rather than dirtier even as it grows. A codebase that gets slowly cleaner under load is a codebase you are successfully defending. A codebase that gets slowly dirtier no matter how hard you review is one you are losing, and the review is not the fix.

Write the Decisions That Outlast You
#

One of the cheapest, highest-leverage things a solo defender can do is write things down in a form that survives without them. Architecture decision records, one page each, capturing what was decided, what alternatives were rejected, and why. A short conventions document that is explicitly the source of truth the lint config is derived from. A “why this exists” header on the modules most likely to be misunderstood.

The point of writing it down is not to win today’s argument. Today’s argument will be re-litigated regardless, because the engineer on the other side, or their agent, has not read it. The point is to ensure that the same argument does not have to be re-won from the beginning every time, by you, as it happens.

A decision that lives in a file is a decision the next agent can be pointed at. A decision that lives only in your head dies the moment you switch teams, or take a week off, or simply get tired of explaining it for the fiftieth time. When your defenses are encoded as files, the codebase keeps its structure without you maintaining it. When they are encoded only as your vigilance, the codebase is one two-week vacation away from drift you will spend a month undoing.

Pick the Battles That Are Actually One-Way Doors
#

You cannot defend every standard, and trying to is the fastest route to burnout. The discipline is to decide, in advance, which fights are worth your scarce attention, and the useful frame is the distinction between one-way and two-way doors, which I wrote about in When Engineers Disagree on Best Practices.

A one-way door is a decision that is hard or impossible to reverse. Choosing a primary database. Committing to a service boundary that will be expensive to move later. Adopting a framework that will permeate every file. Dropping a database column. These deserve your full attention, and as the defender of the codebase these are where you should spend it. Block them, slow them, write the decision record, make the team justify the trade-off.

A two-way door is a decision you can undo in an afternoon. A naming convention. A helper function in the wrong package. A test that could have been structured better. Let these go, or fix them in a sweep later. The solo defender who treats every diff as a one-way door exhausts themselves on reversible things and has nothing left for the decisions that actually compound.

This discipline is also the cure for the resentment that otherwise makes this role unsustainable. You will see things every day that are not how you would have done them. Most of them do not matter. Learn to recognize which decisions are irreversible, let the reversible ones pass, and you will last long enough to actually defend the things that count.

The Limit
#

Sometimes the team will not align, and no amount of infrastructure will fully save you. A teammate may insist on driving their own agent with their own skills, their own conventions, their own picture of the codebase, and treat your paved road as a suggestion rather than a default. A manager may value shipping velocity over every standard you have encoded, and quietly override the gates that matter.

At that point your job is no longer to win. It is to make the cost of the drift visible. Keep the trend reports. Keep the complexity numbers. Keep the record of which decisions were one-way doors that got walked through without the decision being made. Do this not to build a case against anyone, but because the most powerful thing a defender can produce, when defense fails, is a clear record of what was lost and when, so that the next attempt at sanity starts from evidence rather than from impressions.

And know when to stop defending a particular part of the codebase. A codebase is not worth your health, and a team that has decided, collectively, to let the codebase rot will rot it with or without you. Your leverage is highest at the start of a codebase’s life and lowest once the rot is structural. If you have encoded what you can, written down what you know, and the drift is still winning, the rational move is to spend less energy fighting and more energy deciding whether this is still the codebase you want to be responsible for.

What to Do Next
#

You do not need permission, and you do not need a migration. Pick the single standard that is being violated most often, the one that costs you the most review time, and convert it from a review comment into a gate. A lint rule. A CI check. A line in the skill file every agent loads. Run it on every pull request, including the ones you do not personally review.

Then do it again, next week, with the next most expensive standard. Each conversion is a piece of vigilance that stops being yours and starts being the system’s. Over a quarter, the surface you have to defend manually shrinks to the small set of genuinely judgment-laden calls, and the volume of entropy you face stops mattering quite so much, because most of it is being caught upstream of you, by machinery that does not tire.

The solo defender who wins is not the one who reviews the most. The solo defender who wins is the one who has made themselves, slowly and deliberately, the part of the pipeline that is no longer strictly necessary.

A sane codebase in this era is not one that a heroic reviewer holds together by force of attention. It is one whose standards have been pushed so far upstream, into the skills and gates and defaults and templates, that the code arrives mostly correct, and the reviewer is left doing the small amount of work that only a human can do. Build that, one encoded standard at a time, and the direction the rest of the team is pulling in starts to matter a great deal less.

References
#

Wikipedia, “Theory of Constraints” – Goldratt’s framing for why you change the bottleneck station rather than adding effort at it, the basis for moving leverage from review to infrastructure
Wikipedia, “Paved road” – the principle of making the compliant path the easiest path, which lets a single engineer steer a codebase without persuading anyone
Wikipedia, “Technical debt” – the metaphor for accumulated drift that a weekly gardening sweep is meant to keep net-negative
Wikipedia, “Broken windows theory” – why visible decay accelerates further decay, and why keeping the drift rate below the sweep rate matters disproportionately
tomzx/agents – a working library of the skill files and review gates that implement the infrastructure-first defense described here

The Self-Evolving Repository: Automating a GitHub Project End to End with LLMs

tom@tomrochette.com (Tom Rochette) — Sat, 20 Jun 2026 00:00:00 +0000

The question is not whether an LLM can write code for your project. It already can. The question is whether a project can continue to evolve, fix its own bugs, add its own features, and improve its own quality without you ever opening a terminal, writing a prompt, or reviewing a pull request.

This is the self-evolving repository: a GitHub project where every function of the maintainer has been replaced by an automated loop driven by LLMs. No human control. No human-in-the-loop. The maintainer sets it up once, then does not intervene, and the project keeps making progress.

I want to be precise about what a self-evolving repository means, what it requires, and where it breaks.

What Full Automation Means
#

Most LLM-assisted development today is interactive. A developer describes a task, the LLM writes code, the developer reviews, requests changes, and merges. The developer controls what the LLM works on. The LLM does the work.

Full automation removes the developer’s control. The project must decide for itself what to work on, implement the work, verify it, and ship it. The maintainer who set it up does not intervene in the loop.

Full automation is a fundamentally different problem from “use an LLM to write faster code.” It is the problem of encoding every judgment a maintainer makes into a system that can execute that judgment autonomously, reliably, and indefinitely.

A maintainer of an active project does many things. They triage bug reports. They decide which feature requests align with the project’s direction. They prioritize competing work. They review contributions. They fix CI when it breaks. They update dependencies. They write documentation. They make architectural decisions. They decline changes that would make the codebase worse.

Each of these duties is a decision that currently requires human judgment. Full automation means building a system that makes each of these decisions without the human.

The Autonomous Loop
#

A self-evolving repository runs a continuous loop.

Observe → Decide → Implement → Verify → Ship → Learn

Each stage must be fully automated.

1. Observe
#

The system continuously monitors signals about the project’s state. Open issues and their content. Pull requests from external contributors. CI failures and test results. Dependency vulnerability alerts. User feedback in discussions. Stack Overflow questions mentioning the project. Download and usage statistics. Error reports from production telemetry if the project is a library or service.

The system uses these signals to understand its state. Without them, the project does not know what needs attention. The richer the signal sources, the better the system can prioritize.

A project that only monitors its own issue tracker misses much of what needs attention. A project that also monitors community discussions, ecosystem health, and downstream breakage has much more information about where to invest effort.

2. Decide
#

The decide stage is the hardest, and I will return to it.

Given the observed signals, the system must decide what to work on next. Deciding what to work on is not just “pick the highest priority issue.” It is a sequence of judgments: which problems are worth solving, which are urgent, which can wait, which should be declined, which require architectural changes versus incremental fixes.

The decision stage encodes the maintainer’s judgment about what matters. If the system encodes the maintainer’s judgment poorly, the project will be busy but not productive, shipping changes that do not move the project in a meaningful direction.

3. Implement
#

The system decomposes the chosen work into tasks and generates code. Implementation is the part that LLMs are already good at. Given a clear specification and sufficient context about the codebase, current models can produce working implementations for most routine tasks.

The implementation stage benefits from the same patterns that work in interactive LLM development: competitive generation (multiple attempts, best one selected), iterative refinement (generate, evaluate, regenerate), and specification-driven development (the spec is authored before the code).

The difference is that in the autonomous loop, the specification is also generated by the system, not by a human.

4. Verify
#

Before any change ships, it must pass automated verification. This is the quality gate that replaces human code review.

The verification pipeline should include: the existing test suite, static analysis and linting, security scanning, type checking, and scenario-based validation where an LLM evaluates whether the implementation satisfies the specification.

As I argued in Rethinking Code Review in the Age of LLMs, human code review of LLM-generated code is the lowest-value activity in the pipeline. Automated verification is not just faster, it is more consistent and more reliable for the kinds of checks that matter at this stage.

The critical requirement is that verification criteria are defined before implementation, not after. If the system writes tests to match what it already implemented, the tests prove nothing. The specification and its acceptance criteria must exist first.

5. Ship
#

Verified changes are merged and released. This stage is mostly mechanical: merge the pull request, run the release pipeline, publish the package, update the changelog.

The one non-obvious requirement is a rollback mechanism. If a shipped change introduces a regression that the verification pipeline missed, the system needs to detect the regression in production telemetry and automatically revert. Without an automatic rollback, errors compound.

6. Learn
#

The system records what worked and what did not. Every failed implementation, every reverted change, every missed bug is an input to future decisions.

This learning takes several forms. Failed prompts and their corrections become few-shot examples for future implementations. Bugs that escaped verification become new test cases. Decisions that led to regressions update the prioritization model. Architectural patterns that caused repeated problems become constraints the system avoids.

Over time, the system accumulates institutional knowledge the way a human maintainer does, but in a form that is explicit, versioned, and transferable.

The Direction Problem
#

The hardest problem in a self-evolving repository is not implementation. It is not verification. It is not even CI automation.

It is direction.

When a human maintainer decides what to work on, they are applying judgment that is difficult to articulate. They know the project’s trajectory, the community’s needs, the competitive landscape, and the technical debt that is becoming critical. They have taste. They have a vision for what the project should become.

Encoding the maintainer’s judgment into an autonomous system is the central challenge.

The roadmap as a steering mechanism
#

The maintainer’s initial setup must include a machine-readable roadmap. Not a vague vision statement, but a structured document that defines: the project’s purpose and non-goals, the target user and their needs, the quality bar for changes, the architectural principles that must be respected, and the current priorities ranked by importance.

This roadmap is the project’s governing document. Every autonomous decision is evaluated against it. When the system decides what to work on, it checks the decision against the roadmap. When the system reviews a contribution, it checks whether the contribution moves the project toward a roadmap goal.

The roadmap does not need to be exhaustive. It needs to be sufficient to distinguish work that matters from work that does not. This is a lower bar than most people assume. Most of a maintainer’s triage decisions are not subtle architectural judgments. They are straightforward: this bug affects users, fix it; this feature request is out of scope, decline it; this dependency has a security vulnerability, update it.

Direction from external signals
#

The roadmap provides static direction. External signals provide dynamic direction.

If the system observes that a particular error message is appearing frequently in community discussions, that is a signal to improve the error message or fix the underlying issue. If the system observes that a downstream project broke after a recent release, that is a signal to fix the breaking change. If the system observes that a dependency released a major version, that is a signal to evaluate the migration.

These signals allow the project to evolve in response to its environment without a human pointing the way. The system reacts to what is actually happening rather than to what someone predicted would happen.

The drift problem
#

Signal-driven direction carries a fundamental tension. A self-evolving repository that only reacts to external signals will optimize for whatever those signals measure. If the signals are bug reports, the system will become excellent at fixing bugs and terrible at anything else. If the signals are feature requests, the system will accumulate features and lose coherence.

This drift is Goodhart’s law applied to software maintenance: when a measure becomes the target of an autonomous system, it ceases to be a good measure.

The roadmap exists to counteract this drift. It is the fixed point that keeps the project aligned with its original purpose even as the system optimizes for observable signals. But the roadmap itself can become stale. A project’s context changes over time. User needs shift. The ecosystem evolves. A roadmap written in January may be wrong by July.

A fully autonomous system needs a mechanism for updating its own roadmap. Updating the roadmap is where the direction problem becomes genuinely difficult. Updating the roadmap means making a judgment about what the project should become, and that judgment requires understanding the project’s users, ecosystem, and competitive position at a level that current LLMs can approximate but not fully replicate.

The pragmatic solution is not to solve the stale-roadmap problem perfectly but to bound it. Let the system make small roadmap adjustments based on observed signals, but require large directional changes to go through a human review. This keeps the system autonomous for 95% of decisions while preserving human oversight for the 5% that determine the project’s long-term trajectory.

Quality Without a Human
#

The quality question is the one most people get stuck on. “How do you trust code that no human reviewed?”

The answer is the same one I gave in The Future of Code Review: you do not trust the code, you trust the verification system.

A self-evolving repository needs a verification pipeline that is more rigorous than what most human-maintained projects have today. Not because the code is worse, but because there is no human fallback.

The pipeline should have multiple independent layers, each catching different classes of problems.

Unit and integration tests catch functional regressions. These should be comprehensive and fast. The system should be able to run the full suite in minutes, not hours.

Property-based testing catches edge cases that example-based tests miss. For pure functions and data transformations, property tests can generate thousands of inputs automatically, surfacing bugs that a human would never think to test.

Static analysis catches type errors, security vulnerabilities, and common anti-patterns. Tools like Semgrep, CodeQL, and language-specific analyzers should run on every change.

Mutation testing verifies that the test suite is actually meaningful. If you can mutate the code and the tests still pass, the tests are not testing what you think they are. Mutation testing is especially important when the tests themselves are LLM-generated.

Scenario-based validation uses an LLM to evaluate whether the implementation satisfies its specification. Scenario-based validation is the layer that catches semantic problems that automated tests miss: the code works, but it solves the wrong problem.

Adversarial verification has a separate agent actively try to break the implementation. This agent writes tests designed to fail, probes edge cases, and attempts to find inputs that produce incorrect behavior. It is the automated equivalent of a hostile code reviewer.

The key insight is that each layer should be independent. If the same LLM that wrote the code also wrote the tests and also ran the review, the correlated failure rate is high. The system will make the same mistake in implementation, tests, and review because they all share the same blind spots.

Diversity of verification methods reduces correlated failures. Static analysis does not share blind spots with property testing. Mutation testing does not share blind spots with scenario validation. The layers are strongest when they are structurally different, not just different invocations of the same model.

What Can Go Wrong
#

A self-evolving repository is a complex autonomous system. Complex autonomous systems have failure modes that are hard to predict.

Silent quality decay
#

Silent quality decay is the hardest failure mode to notice. The system ships changes that pass all verification layers but gradually degrade the codebase’s quality. Each individual change is defensible. The cumulative effect is a codebase that is harder to maintain, slower to evolve, and full of subtle interactions that no one understands.

Silent quality decay happens when the verification pipeline measures immediate quality (does this change pass tests?) but not systemic quality (does this change make the codebase healthier?). Metrics like cyclomatic complexity, coupling, and test coverage can help, but they are proxies, not ground truth.

The complexity spiral
#

Without a human saying “this is too complex, simplify it,” the system may accumulate complexity over time. Each new feature adds code. Each bug fix adds special cases. Each dependency update adds compatibility layers. The codebase grows without bound because nothing in the autonomous loop says “stop adding, start removing.”

A self-evolving repository needs an explicit simplification loop. The system should periodically identify the most complex parts of the codebase and attempt to simplify them, even if no bug is forcing the change. The simplification loop is technical debt reduction as an automated process.

Specification drift
#

When the system writes its own specifications, the specifications can drift from what users actually need. The system optimizes for specifications it can satisfy, not specifications that matter. Over time, the project accumulates well-implemented features that nobody uses.

Specification drift is the autonomous version of the problem I described in The Shifting Bottleneck: when implementation becomes free, deciding what to implement becomes the hard part. In a self-evolving repository, the decision problem is fully automated, which means the drift can go unnoticed for longer.

Cascading failures
#

A single bad change that passes verification can break downstream functionality in ways that the verification pipeline does not catch. The system then generates fixes for the symptoms rather than reverting the cause. Each fix introduces new changes, each of which can introduce new problems. The system enters a fix loop, shipping more patches that make the situation worse.

The defense against cascading failures is blast radius limitation. Changes should be small, merged incrementally, and monitored for downstream impact. The system should have a threshold: if more than N changes in a row require fixes, stop and flag for human attention rather than continuing to patch.

Cost runaway
#

Every iteration of the autonomous loop costs money: API calls for generation, verification, and decision-making. A system that is stuck in a fix loop, or that is attempting overly ambitious changes, can spend a large amount of compute before anyone notices.

The system needs explicit budgets. A maximum number of iterations per change. A maximum cost per change. A maximum number of changes per day. When a budget is exceeded, the system pauses and logs the situation rather than continuing to spend.

What the Maintainer Does Once
#

The maintainer’s role in a self-evolving repository is concentrated entirely in the setup phase. Everything that happens after setup is automated.

The setup has five components.

The roadmap. A structured document defining the project’s purpose, non-goals, priorities, quality standards, and architectural principles. The roadmap is the single most important artifact. It determines whether the autonomous system makes good decisions or busy decisions.

The verification pipeline. The combination of test suites, static analysis, property tests, mutation tests, scenario validation, and adversarial verification that gates every change. This pipeline must be in place and passing before the autonomous loop starts. If the verification pipeline is weak, the autonomous system will ship low-quality code.

The decision policy. The rules that govern how the system prioritizes work. What signals does it monitor? How does it rank competing tasks? When does it work on bugs versus features versus technical debt versus documentation? This policy encodes the maintainer’s judgment about how to allocate attention.

The guardrails. Budget limits, blast radius constraints, escalation triggers, and rollback mechanisms. These are the safety systems that prevent the autonomous loop from causing damage when something goes wrong.

The learning infrastructure. The mechanisms by which the system records outcomes and feeds them back into future decisions. This includes the few-shot example library, the bug-to-test pipeline, and the decision evaluation framework.

Once these five components are in place, the autonomous loop can run. The maintainer’s ongoing involvement is limited to reviewing escalation reports, the small percentage of decisions that the system flags as requiring human judgment.

When This Makes Sense
#

Not every project should be a self-evolving repository.

This approach makes sense for projects with: clear specifications and measurable quality criteria, active user bases generating feedback signals, maintenance-heavy codebases where most work is bug fixes and incremental improvements, and well-established architectures where most decisions are routine.

It makes less sense for projects that are: in early exploration where direction changes frequently, in domains where correctness is safety-critical, in codebases with poor test coverage or unclear specifications, or where the competitive advantage is design taste that is hard to encode.

The threshold question is simple: can you write down the rules a competent maintainer would follow, well enough that following them mechanically produces good outcomes? If yes, the system can work. If no, the system will be autonomous but not effective.

The Deeper Question
#

A self-evolving repository raises a question that I explored in Scaling the LLM Agent Company: when the system is its prompts, its pipelines, and its proprietary context, what is the project?

The project is no longer its code. The code is a byproduct of the system that generates it. The project is the roadmap, the verification pipeline, the decision policy, the guardrails, and the accumulated learning data. These are the artifacts that determine what the project becomes.

This reframes what it means to maintain a project. The maintainer’s most important work is not writing code, reviewing pull requests, or fixing bugs. It is designing the system that does all of those things autonomously. The maintainer becomes an architect of processes rather than an executor of tasks.

The project that outlives this setup is the one where the autonomous system makes decisions the maintainer would have made, ships quality the maintainer would have approved, and evolves in a direction the maintainer would have chosen.

The question is whether you can encode your judgment well enough to make yourself unnecessary.

If you can, the project evolves without you. If you cannot, no amount of automation will compensate for the missing taste.

Bringing Everyone to the Same Level: How Skills and LLMs Collapse Code Quality Variance

tom@tomrochette.com (Tom Rochette) — Wed, 17 Jun 2026 00:00:00 +0000

Every team has the same structure. A few engineers ship clean, well-tested, well-scoped work, and the rest ship work that mostly works. The gap between them is not typing speed. It is everything that happens before and after the typing: the steps they remember to run, the checks they know to perform, the conventions they learned by fixing past failures. That knowledge has always been the most valuable asset, and it has never scaled, because it existed in the heads of a small number of people.

LLMs alone do not fix this. They make everyone faster, which is a different thing from making everyone produce the same quality. Done naively, they widen the variance, because an LLM is a multiplier on the quality of the instructions it receives. The fix is to give every engineer, and every model, the same instructions. A shared set of instructions is what a skill is, and it is why skills are the mechanism that finally brings everyone to the same level.

The Variance Problem Has Always Been a Knowledge Problem
#

Ask yourself what actually separates the output of your strongest engineer from your weakest. It is rarely the language syntax. Both of them can write a function.

The difference is that the strong engineer, before touching code, performs a long list of steps they never write down. They look for an existing solution before building a new one. They write down what “done” means before they implement. They check whether the change can be undone. They name things the way the rest of the codebase names things. They write the edge case the junior would have forgotten. They run the linter, and they run it before opening the pull request, not after a reviewer asks.

Each of these is a step, and a step can be written down. For most of the history of software, these steps were passed on informally, by watching and working alongside others. You learned them by pairing with someone better, by getting review comments on your seventh PR, by breaking production once and remembering forever. This is mentorship, and it works, but it is slow, expensive, and uneven. It cannot keep up with a team that is hiring, and it cannot keep up with a codebase that is changing. The senior engineer’s advantage was always a process they followed in their head, and a process in a head does not scale.

LLMs Raise the Floor but Not the Ceiling
#

Drop an LLM into this situation and the naive expectation is that it makes everyone equal. It does not, at least not on its own.

What an LLM actually does is amplify whatever it is given. Give it a vague one-line prompt and you get back plausible, generic code that does not match your conventions and forgets your edge cases. Give it a precise specification, the relevant files, the patterns to reuse, and the checks to satisfy, and you get back code that is hard to distinguish from your best engineer’s output. The model is the same in both cases. The difference is entirely in the context, which, as I argued in The Importance of Context When Interacting with LLMs, is the entire mechanism by which a frozen set of weights produces behavior relevant to your situation.

The amplification effect has an uncomfortable implication. Before skills, the LLM made the senior engineer better and the junior engineer faster, and the gap between them stayed roughly the same. The senior engineer instinctively provides the context the model needs, because they know what good work requires. The junior engineer does not know what they do not know, so they ask for less, and they get less back. The tool that was supposed to democratize quality quietly reproduced the existing hierarchy, because it rewarded the same hidden knowledge that had always separated them.

A Skill Is the Senior Engineer’s Process, Made Executable
#

A skill is a versioned file, usually markdown, that tells an LLM agent exactly how to perform a task. Not a vague hint. The steps, in order, the checks to run before declaring success, the gates the output must pass, and the format the output should take. When the agent loads the skill, it stops improvising and follows the encoded process instead.

The difference between a skill and advice is where the comparison to a human matters. A junior engineer told to “go implement the feature” forgets half the steps, because they never fully learned them. A junior engineer, or even an autonomous agent, told to implement the feature through a skill cannot forget the steps, because the steps are in the prompt the model reads on every run. The skill is not advice the engineer might ignore. It is part of the execution path.

Think of it as the checklist idea from medicine and aviation, with one critical upgrade. A surgical checklist still depends on a tired human choosing to read it and choosing to follow it. A loaded skill does not depend on anyone’s discipline. The model follows it because the skill is the instruction, and following instructions is what the model does.

Why This Collapses the Variance
#

Run the same task through two engineers with two different LLMs, but the same skill, and watch what happens to the output. Both implementations start from the same specification step. Both run the same “have you checked for an existing solution?” step. Both end at the same verification step, with the same gates. The code they produce is not identical, but it converges toward a common standard, because the process that produced it is identical.

The thing that used to vary, the unwritten checklist inside each engineer’s head, is now constant. What varies is only the judgment applied at each step, and even that is bounded by the gates the skill enforces. Skills do not make everyone equally brilliant. They make everyone equally unable to skip the steps that matter, and skipping the steps that matter is what produced most of the variance in the first place.

The convergence logic is the same one I described, from the other direction, in Developer Trust Profiles. There I argued the ideal end state is one where “every contributor, senior engineer or new hire, funnels their work through agents that enforce the same standards,” so that authorship stops carrying signal and “the output converges into something homogeneous.” The trust profile was a transitional step, and the point was to make itself obsolete. Skills are the mechanism that completes that transition. They are the shared, enforced pipeline that makes the variance shrink in the first place.

The Leverage Moves Up, Again
#

If the junior engineer can now produce work that follows the senior engineer’s process, what is left for the senior engineer to do?

The answer is the same one that keeps appearing everywhere AI touches the development pipeline. The bottleneck moves up the decision chain, as in The Shifting Bottleneck, and the leverage moves with it.

The new seniority is not in running the skills. Anyone, and any agent, can do that. The new seniority is in writing them. Deciding what the process should be in the first place. Deciding which gate matters and which only looks like a gate. Deciding what “done” means for this kind of task, precisely enough that a model can enforce it. The judgment that used to be applied privately, one pull request at a time, is now applied once, at the skill level, where it benefits every future execution.

This shift is why a good skill library is one of the most valuable assets a team can hold. It is the institutional memory of how the team does things well, written in a form that executes itself instead of sitting in a wiki nobody reads. When a senior engineer leaves, the skills stay, and the standard stays with them. When a new engineer joins, they do not spend a year absorbing the conventions through code review. They load the skills on day one, and their first pull request already follows the team’s process.

What a Skill Has to Get Right to Actually Level the Field
#

Not every file labeled “skill” collapses the variance. Most do not. Writing a skill that raises everyone to the same level requires a few specific disciplines.

Encode the steps that are actually forgotten, not the steps everyone already does. A skill that says “write clean code” is worthless, because nobody sets out to write dirty code and the phrase carries no executable instruction. A skill that says “before implementing, run a search for existing solutions and list what you found” changes behavior, because that is exactly the step people skip when they are in a hurry.

Make the gates concrete enough for a model to evaluate. “Make sure it is well tested” is an opinion. “Write tests for the empty input, the maximum value, and the concurrent case, then run the suite and confirm it passes” is a gate. The whole mechanism depends on the model being able to check its own work, and it can only do that against criteria it can test. The need for testable criteria is the same reason I argued, in Rethinking Code Review in the Age of LLMs, that quality is a property of your constraints, not of your reviewers. The constraints in a skill are where the quality actually lives.

Keep the skill shorter than the attention it will receive. As the “lost in the middle” work showed, a model’s reliability degrades when a context fills with noise. A skill that tries to encode every possible consideration becomes a skill the model half-follows. Prefer several focused skills over one giant document, and cut anything the model would do correctly without being told.

Version and maintain it like the code it produces. A skill that encodes a convention from two years ago is worse than no skill, because it enforces a stale standard on every run. Treat the skill library as part of the codebase, with owners, review, and the same “does this still justify its cost?” scrutiny you would give any dependency.

The Realistic Limits
#

Skills only work for the part of the job that is describable, and it is worth being clear about where that stops.

Skills cannot encode taste that the writer cannot articulate. If your best engineer’s advantage is a feel for when an abstraction is about to collapse, and they cannot explain the signals they are reading, that advantage does not survive the translation into a file. It stays in their head, and the skill without it will produce work that is competent but not inspired. For the routine majority of software, which is most of software, the describable process is enough. For the genuinely hard design calls, it is not.

Skills can also lock in mediocrity. A skill that encodes a mediocre process enforces that mediocrity on everyone, consistently, forever. The mechanism is morally neutral. It collapses the variance in whichever direction the skill points, so a careless skill library can quietly lower a strong team to a lower common standard instead of raising the rest. The remedy is that the skills themselves have to be written by the people whose process you actually want to reproduce, and revisited when the process improves.

Finally, skills raise the standard for producing code, but producing code was never the only bottleneck. As Software Engineering Teams in the Age of AI argues, deciding whether a feature should exist, and writing a precise specification for it, remain human and valuable. Skills make the execution layer homogeneous. They do not decide what to execute.

What to Do Next
#

You do not need a grand migration to start closing the gap.

Pick the one task where your team’s output varies the most, the one where the senior engineer’s pull request looks nothing like the junior’s. Write down the steps your strongest engineer actually takes when they do it well, the steps they would never admit to because they seem obvious to them. Turn that into a skill, and run the next instance of that task through it, regardless of who is doing it.

Watch the output converge toward the standard. Then do it again for the next task. The variance does not close all at once. It closes one encoded process at a time, and each skill you add moves a piece of seniority from a private habit to a shared standard.

The team that wins in this era is not the one with the most powerful model. It is the one whose best engineer’s process runs, unchanged and unskipped, in every other engineer’s session.

References
#

tomzx/agents - a working library of the skills this article describes, including the create-implementation and quick-pr-review skills referenced throughout the blog
Brown et al., “Language Models are Few-Shot Learners” - established in-context learning, the capability that lets a loaded skill alter a model’s behavior without retraining
Liu et al., “Lost in the Middle: How Language Models Use Long Contexts” - why a skill must stay focused, since model reliability degrades as context fills with noise
Wikipedia, “The Checklist Manifesto” - Atul Gawande’s case that disciplined checklists outperform expert memory, the human analogue to the skills mechanism

When Engineers Disagree on Best Practices: Surviving the Forming Stage

tom@tomrochette.com (Tom Rochette) — Wed, 17 Jun 2026 00:00:00 +0000

A new team’s first disagreement about best practices is not a warning sign. It is the moment the team actually starts becoming a team. What separates teams that survive this phase from those that stall is not which practices they adopt, but how they resolve the disagreement.

Why the Forming Stage Produces Disagreement
#

Every engineer arrives with a set of practices that worked somewhere else. The testing strategy that saved your last team from weekly regressions. The code review checklist that caught the security bug before it shipped. The branching model that kept releases sane. These are not random preferences. They are lessons from actual failures, and the engineer who brings them believes, correctly, that they matter.

The problem is that every other engineer on the new team arrives with their own set of practices, learned from different failures. When these differing practices meet, you get the pattern Bruce Tuckman described in his 1965 study of small-group development: forming, storming, norming, performing. Teams do not skip from forming straight to performing. They pass through storming, the phase where members test each other, surface conflicting assumptions, and negotiate how work should be done.

The forming stage is uniquely prone to practice disagreements for three reasons.

First, there is no shared history. On an established team, conventions are settled and invisible. The team just does things a certain way because that is how it has always been done. A new team has no “always,” so everything is up for debate at once.

Second, there is no established trust. Disagreeing about code style feels low-stakes on a team where everyone has shipped together for a year, because everyone knows the argument is about the style, not about competence. On a new team, the same disagreement can feel like a judgment of someone’s expertise, because no one has yet proven anything to anyone else.

Third, there is no shared vocabulary for resolving conflict. An established team has accumulated meta-norms: how they make decisions, who decides what, when to escalate, when to let something go. A new team has none of this. So every disagreement is also, simultaneously, a negotiation about how disagreements get resolved.

Most “Best Practice” Debates Are Preference Debates
#

The first thing to recognize is that the phrase “best practice” misleads. A best practice is a practice that is demonstrably better than its alternatives across most contexts. Very few software engineering practices meet that standard.

Consider the debates that take up the most discussion time on a new team. Tabs versus spaces. Git Flow versus trunk-based development. Story points versus no estimates. Unit tests versus integration tests as the primary signal. Commit message conventions. These are not best practices. They are conventions, and a convention’s value comes almost entirely from being shared, not from being optimal. The team that uses the second-best testing framework consistently will outperform the team that uses the best one inconsistently.

This does not mean all practices are equal. Some debates involve genuine principles where the choice has lasting consequences: whether to build or buy a critical dependency, how much to invest in observability before shipping, whether a monolith or services is the right starting architecture. These deserve careful deliberation. The skill is in telling the convention debate from the principle debate, because they require completely different resolution mechanisms.

Reversible Versus Irreversible Decisions
#

A distinction that Jeff Bezos drew in his 2016 letter to shareholders maps directly onto the convention-versus-principle problem. Some decisions are one-way doors. Once you walk through, you cannot come back. Choosing a primary database, committing to a cloud provider, or picking a framework that will permeate your codebase are one-way door decisions. These deserve heavy deliberation, because the cost of being wrong is high and the cost of reversing is higher.

Most practice debates on a new team are two-way doors. You can adopt trunk-based development, try it for six weeks, and switch back if it is not working. You can pick a linter configuration, discover it fights your codebase, and change it. Two-way door decisions should be made quickly, because the fastest way to learn is often to try.

A new team that treats every practice debate as a one-way door will spend its first two months in meetings and produce nothing. A team that treats a genuine one-way door as reversible will make a choice it regrets for years. The discipline is in classifying the decision before debating it.

The Experiment Mindset
#

The single most effective frame for resolving practice disagreement during forming is to treat practices as hypotheses, not as identities.

When two engineers disagree about whether to require code review before merge, the unproductive version of that conversation is an argument about whether code review is good. Both people hold their position, cite their favorite blog posts, and the discussion becomes about winning.

The productive version converts the disagreement into an experiment. You require code review for the next month, track how many defects it catches in review versus in production, and look at the data together at the end. Now the two engineers are not opponents. They are co-investigators running the same experiment.

The experiment works because it removes the requirement that someone be wrong. An engineer who advocated for mandatory review does not lose standing if the experiment shows it adds little value, because they ran the test in good faith. An engineer who opposed it does not lose standing if the experiment shows it catches actual bugs, because they agreed to look at the evidence.

A few rules make experiments work.

Time-box them. An open-ended experiment is just a delayed argument. Four to six weeks is usually enough to see signal without exhausting the team’s patience.

Define success criteria before you start. If you wait until the experiment is over to decide what would count as success, you will re-litigate the original disagreement with data instead of opinions, which is only marginally better.

Keep the cost of reversal low. If switching back after the experiment is expensive, the experiment is an irreversible decision.

Write down the result. A one-paragraph note recording what you tried, what you observed, and what you decided turns a single resolution into institutional memory that saves the next new team member from repeating the same debate.

How You Decide Matters More Than What You Decide
#

Here is the point that is easy to miss when you are in the middle of a heated debate about, say, whether to use feature branches or trunk-based development.

The specific answer matters less than you think. What matters enormously, especially during the forming stage, is that the team builds a repeatable process for reaching decisions together.

A team that resolves its first disagreement well, with a clear process, shared evidence, and a decision everyone can live with, has just created something more valuable than the practice it chose. It has created the template for the next disagreement, and the one after that. Each resolved disagreement makes the next one easier, because the meta-process is now familiar.

A team that resolves its first disagreement badly, by letting the loudest person win, or by avoiding the conflict until it grows worse, or by escalating to a manager who picks a winner, has also created a template. That template will repeat. The first disagreement a new team faces sets the pattern for every disagreement that follows.

That template is why the forming stage deserves deliberate attention rather than the hope that things will sort themselves out. The norms a team establishes in its first weeks tend to persist. They become “how we do things here,” and once that identity forms, it is far harder to change later than to set well at the start.

A Playbook for the First Disagreement
#

Concretely, when the first genuine practice disagreement surfaces on a new team, the following sequence works.

Name it. Say out loud that this is a disagreement about practice, that disagreements are expected, and that the goal is to find a resolution the team can commit to, not to identify who is right.

Classify it. Ask whether this is a convention debate, where value comes from consistency, or a principle debate, where the choice has lasting consequences. Ask whether it is a one-way door or a two-way door.

For conventions and two-way doors, decide fast. Default to whoever has to live with the consequence most directly, or to the option that is easiest to change, or to the existing convention if one already exists. Time-box the decision to one conversation, not three.

For principles and one-way doors, slow down. Write a short decision record capturing the options, the trade-offs, and the reasoning. Get the right people in the room, which usually means the people who will own the consequences, not necessarily the people with the strongest opinions.

Either way, record the outcome. A one-page architecture decision record or a paragraph in the team handbook turns a fragile verbal agreement into something a new hire can read six months later.

And then commit. The principle of disagree and commit applies here. Once the team has decided, even those who argued otherwise support the decision fully. A practice executed with full commitment and an imperfect choice beats a better practice executed with resentment and inconsistency.

When Someone Refuses to Commit
#

There is a failure mode worth naming.

Occasionally an engineer treats a practice debate as something they will not concede under any circumstance, refuses to accept the team’s decision, and continues working the old way. This is no longer a disagreement about practice. It is a disagreement about whether the team’s decision-making process has legitimacy.

This must be addressed directly, and early. A team that tolerates a member who overrides collective decisions after they are made has no process at all. It has a veto by the most stubborn person. The conversation is no longer about the practice. It is about participation in a shared system.

In a healthy forming team, this conversation is rare, because the process itself was fair enough that losing a debate does not feel like losing status. When it does happen, resolving it cleanly, with empathy but without accommodation, is one of the most important trust-building acts the team will undertake. Underneath that trust is psychological safety, the shared belief that you can speak up, dissent, and even be wrong without being humiliated, which Google’s Project Aristotle identified as the single strongest predictor of team effectiveness. A team cannot storm productively without it.

The Payoff
#

A team that navigates its forming-stage disagreements well emerges with two assets.

The first is a set of shared conventions, probably imperfect, that let the team move fast without relitigating every choice. The second, and more important, is a shared process for handling the next thing they do not yet agree on.

New disagreements never stop. The codebase grows, the team grows, technology changes, and yesterday’s settled practice becomes tomorrow’s debate. The teams that handle this well are not the ones that picked the best practices on day one. They are the ones that learned, during forming, how to disagree productively, decide efficiently, and commit fully.

That skill compounds for the life of the team.

References
#

Wikipedia, “Tuckman’s stages of group development” - the forming-storming-norming-performing model that explains why early friction is structural, not pathological
Wikipedia, “Disagree and commit” - documents the one-way/two-way door distinction and the disagree-and-commit principle for group decision-making
Google re:Work, “Guide: Understand team effectiveness” - Project Aristotle’s finding that psychological safety is the top predictor of team performance

Managing Many Concurrent LLM Agent Sessions

tom@tomrochette.com (Tom Rochette) — Tue, 16 Jun 2026 00:00:00 +0000

When one person can spawn a dozen LLM agent sessions in parallel, the bottleneck is no longer the agents. It is the human trying to keep track of them all. Your working memory holds a handful of items at best, your context switching cost is measurable, and every interruption leaves residue that degrades the next task you pick up. The question is not whether you can run 20 sessions simultaneously. The question is whether you can remain effective while doing so.

The Cognitive Bottleneck
#

Before discussing strategies, it helps to understand what actually limits a human supervisor.

Working memory is tiny. George Miller’s foundational work suggested that humans can hold approximately seven plus or minus two items in short-term memory. Later research by Nelson Cowan revised this estimate down to about four chunks for young adults. Either way, the number is small. If each agent session requires you to remember its goal, its current state, its blockers, and the decision you were about to make, you hit the ceiling at three to five sessions, not twenty.

Context switching has a measurable cost. Research on task switching in cognitive psychology shows that switching between tasks incurs a time penalty, sometimes called “switch cost.” This cost ranges from fractions of a second to several minutes depending on task complexity. When you switch from agent session A to agent session B, you must offload A’s context from your working memory, load B’s context, and reconstruct where you left off. The more complex each session’s context, the more expensive the switch.

Attention residue accumulates. When you switch from one task to another without fully completing the first, part of your attention remains stuck on the previous task. The Zeigarnik effect describes how unfinished tasks persist in memory, consuming cognitive resources even when you are trying to focus on something else. With multiple agent sessions running concurrently, many are perpetually unfinished, creating constant attention residue.

Decision fatigue compounds. Each agent session requires you to make decisions: approve this output, redirect this approach, answer this clarifying question. Research on decision fatigue shows that the quality of decisions degrades after a long session of choice-making. Supervising many sessions means making many decisions, and the later decisions in the day will be worse than the earlier ones unless you manage the load.

Working memory, switch cost, attention residue, and decision fatigue together define the ceiling on how many sessions you can manage. Every strategy below works by attacking one or more of them.

Strategy 1: Externalize All Session State
#

The single most powerful principle is to stop relying on your brain to hold session state. If it is not written down, it is consuming working memory.

Maintain a state file per session. Every agent session should produce a machine-readable and human-readable state file that captures its current status, goal, progress, blockers, and next steps. When you return to a session after an hour or a day, you read the file, not your memory. The file is the single source of truth. This state file is the agent equivalent of the workstack concept applied at scale.

Use structured status summaries. The state file should follow a consistent template across all sessions. A format like the following works well:

Session: fix-auth-bug
Goal: Fix OAuth callback failing on production
Status: blocked
Progress: Identified root cause (clock skew on load balancer)
Blocker: Need production access to verify fix
Next: Deploy fix to staging, verify callback works

When every session uses the same structure, you can scan a dashboard of twenty sessions in under a minute. The consistency eliminates the cognitive parsing overhead that comes from varied formats.

Write decisions to a log. Every decision you make about a session should be written to the session’s log file with a timestamp and rationale. Writing to the log serves two purposes. First, when you return to the session, you can see not just where it is but why it is there, without reconstructing the reasoning. Second, the log becomes an audit trail that other humans (or agents) can consume.

Checkpoint before switching. Before switching away from any session, write a one-line “resume hint” that tells your future self exactly where to pick up. This takes five seconds and saves minutes of reconstruction time. The hint should be specific enough that you can act on it without re-reading the entire session history.

Strategy 2: Standardize All Interactions
#

Variability prevents scaling. Every difference between how sessions operate is a new thing your brain must parse, increasing cognitive load and switch cost.

Use a uniform session protocol. Every session should follow the same lifecycle: initialization, execution, checkpointing, escalation, and completion. The protocol defines what the agent does at each stage, what it reports, and how it signals that it needs human input. When the protocol is uniform, switching between sessions costs less because you always know what to expect.

Standardize output formats. If session A reports progress in a bulleted list and session B writes a paragraph and session C uses a table, your brain must context-switch not just on content but on format. Pick one format and enforce it everywhere. Markdown headers, numbered lists, and consistent section ordering let your eyes scan quickly without parsing structure.

Establish a shared vocabulary. Define the terms agents use to communicate status: “blocked,” “waiting-for-human,” “in-progress,” “complete,” “failed.” Every agent uses the same words to mean the same things. A shared vocabulary reduces ambiguity and eliminates the need to translate between sessions.

Create session naming conventions. A session named “auth-fix-3” tells you nothing when you have twenty sessions. A session named “fix-oauth-callback-prod-bug” tells you exactly what it is doing. Descriptive names reduce the time to identify and triage sessions, which reduces the overhead of switching between them.

Strategy 3: Make Interactions Asynchronous and Batched
#

Synchronous interaction with agents prevents parallelism. If you must respond to each agent within seconds, you can only effectively manage one at a time.

Let agents run to a natural stopping point. Instead of watching each agent in real-time and responding to each question as it arises, configure agents to work until they hit a genuine blocker. At that point, they checkpoint their state and wait. You then process the batch of blocked agents at your convenience.

Batch your decisions. When multiple sessions need human input, collect all the requests and process them in a single sitting. Batching is more efficient than context-switching for each one individually, because you stay in the same cognitive “mode” for the entire batch. Five decisions made in one focused session will be faster and higher quality than the same five decisions made across five interruptions.

Time-box your session reviews. Instead of monitoring sessions continuously, check them at fixed intervals: every 30 minutes, every hour, twice a day. This creates predictable rhythm and eliminates the reactive, interrupt-driven pattern that fragments attention. Between check-ins, agents work autonomously and you focus on other things.

Coalesce interruptions. If you have three sessions that will each need input within the next 15 minutes, do not handle them one at a time. Wait until all three are ready, then handle them together. Interruption coalescing is a well-known technique in operating systems and it applies equally to human attention management.

Strategy 4: Make Agents Resolve Their Own Ambiguities
#

Every question an agent asks you is a context switch. The fewer questions it asks, the more sessions you can manage.

Provide rich default resolution rules. Instead of letting agents escalate every ambiguity, give them standing instructions for common situations. “If the test suite fails, attempt to fix it before escalating.” “If a dependency is missing, install it from the lockfile.” “If a naming convention is unclear, follow the pattern used in the nearest file.” These defaults eliminate a large fraction of questions that would otherwise interrupt you.

Define escalation thresholds explicitly. Agents should escalate to you only when they cross a defined threshold: they have tried multiple approaches and failed, they need access they do not have, or they are about to make an irreversible decision. Everything else should be handled autonomously. The clearer the threshold, the fewer unnecessary escalations.

Allow agents to ask other agents. If you have multiple sessions running, agents can sometimes resolve each other’s questions. An agent that needs to understand how another part of the system works can query the agent working on that part. This peer-to-peer resolution keeps you out of the loop for routine coordination.

Use confidence-based escalation. Agents that can express confidence in their outputs can be configured to escalate only when confidence drops below a threshold. High-confidence work proceeds without interruption. Low-confidence work pauses for review. Confidence-based escalation naturally filters your attention toward the sessions that need it most.

Strategy 5: Use Hierarchical Orchestration
#

The most effective way to manage many agents is to not manage them all directly.

Introduce orchestrator agents. Instead of you supervising 20 worker agents, have 4 orchestrator agents each supervise 5 workers. You interact only with the orchestrators, who aggregate and summarize their workers’ status. This reduces your direct interaction count by a factor of 5 and lets you operate within your working memory limit. This mirrors the pattern described in Scaling the LLM Agent Company, where the orchestration layer replaces the human management layer.

Fan-out and fan-in. Give an orchestrator a single high-level task. It decomposes the task, assigns subtasks to workers, collects results, and presents you with a synthesized output. You never interact with the individual workers. Your cognitive load is the same whether the orchestrator manages 3 workers or 30.

Assign team leads per domain. If your agents work across multiple domains (frontend, backend, infrastructure, testing), assign one orchestrator per domain. Each domain lead reports to you with a one-paragraph summary. You manage four domain leads instead of twenty individual contributors.

Layer the hierarchy as needed. For very large numbers of agents, add another layer. A chief orchestrator manages domain orchestrators, who manage team leads, who manage workers. Each layer compresses information, so you always deal with a manageable number of direct reports.

Strategy 6: Practice Progressive Disclosure
#

You should never need to understand everything about every session to make a decision. Information should arrive in layers, from summary to detail, on demand.

Lead with the one-line summary. Every session status should begin with a single sentence that tells you whether action is needed: “Session blocked, needs your decision on X” or “Session running normally, 60% complete.” If the summary says no action needed, you move on. You never read the details unless the summary demands it.

Provide drill-down on request. Behind the one-line summary is a paragraph. Behind the paragraph is the full session log. Behind the log are the raw outputs. Each layer is available but not shown by default. Progressive disclosure keeps your default view clean and your cognitive load low.

Use severity indicators. Color-code or tag sessions by urgency: red for “needs immediate human input,” yellow for “proceeding but with a risk you should know about,” green for “all clear.” Your eye scans for red first, yellow second, and ignores green. This triage happens in seconds, not minutes.

Summarize at the right granularity. An orchestrator reporting “all five workers are making progress” is useless if one of them is about to make a critical mistake. An orchestrator reporting every token from every worker is noise. The right granularity is: what is done, what is in progress, what is blocked, and what decision you need to make next.

Strategy 7: Isolate Sessions from Each Other
#

Interference between sessions is a major source of cognitive load. When sessions share state, a change in one can invalidate your understanding of another.

Enforce session independence. Each session should operate in its own workspace, with its own file tree, its own dependencies, and its own state. Sessions should not mutate shared resources that other sessions depend on. Session independence prevents the “I changed something in session A that broke session B” problem, which is one of the most expensive debugging scenarios when managing many sessions.

Use separate branches or worktrees. If sessions work on the same repository, each should use its own git worktree or branch. Separate worktrees ensure that the output of one session does not corrupt the working state of another. When you are ready to integrate, you merge branches deliberately, not accidentally.

Scope tools and permissions per session. Each session should have access only to the tools and resources it needs. A session fixing a frontend bug does not need database write access. Scoping permissions reduces the impact of errors and eliminates cross-session interference.

Make session boundaries explicit. When you switch from session A to session B, the boundary should be clear. Close session A’s workspace, open session B’s. The physical or virtual separation reinforces the cognitive separation.

Strategy 8: Build a Session Dashboard
#

When managing more than three or four sessions, you need a single view that shows all of them at once. Switching between terminal tabs or IDE windows to check on each session is itself a form of context switching.

Create a single pane of glass. A dashboard that lists all active sessions with their status, progress, and severity indicators lets you assess every session in one glance. This dashboard can be as simple as a generated text file or as sophisticated as a web UI. The key is that it presents all sessions in a uniform, scannable format.

Surface only actionable information. The dashboard should show you what needs your attention, not everything that is happening. Sessions running normally should be collapsed or summarized. Sessions that need input should be highlighted. The dashboard is a triage tool, not a log viewer.

Automate status collection. The dashboard should be generated automatically from the state files that each session produces. No manual updates. If a session’s state file changes, the dashboard reflects it. Automatic generation eliminates the overhead of manually polling each session for status.

Add alerting for critical events. Instead of watching the dashboard continuously, configure alerts for events that genuinely require immediate attention: a session failed, a session is about to make an irreversible change, a session has been blocked for more than N minutes. Everything else can wait for your next scheduled review.

Strategy 9: Use AI to Triage AI
#

One of the most effective ways to manage many agent sessions is to use an LLM to help you manage them.

AI-assisted summarization. Before you look at a blocked session, have an LLM read the session log and produce a one-paragraph summary of what happened, what the blocker is, and what decision you need to make. The summary saves you from reading potentially hundreds of lines of conversation history. The summary gets you to the decision point faster.

AI-assisted triage. When you return from a break and find 12 sessions waiting for input, have an LLM rank them by urgency and group similar requests. “Sessions 3, 7, and 12 all need the same decision about database schema, you can answer them together.” “Session 9 is urgent, it is blocked on a production deploy.” This pre-processing reduces your cognitive load and helps you batch effectively.

AI-assisted decision drafting. For each blocked session, have an LLM propose a decision with rationale. You review the proposal, accept it or modify it, and move on. Reviewing a well-formed proposal is faster and less cognitively demanding than constructing a response from scratch, especially for the tenth session of the day.

AI-assisted state reconstruction. When you return to a session after days away, have an LLM produce a “previously on” summary that reconstructs the relevant context. A reconstructed summary is faster and more reliable than reading the full log yourself, and it handles the long-gap resumption problem that pure state files struggle with.

Strategy 10: Manage Your Own Cognitive Resources
#

The human supervisor is a finite resource. Strategies that optimize agent throughput while ignoring human cognitive limits will fail.

Chunk sessions into clusters. Instead of treating 20 sessions as 20 independent items, group them into 4 clusters of 5. Each cluster shares a domain, a goal, or an orchestrator. You manage 4 clusters, not 20 sessions. This grouping leverages chunking, the same memory technique that lets experts recall complex board positions in chess.

Dedicate focus blocks. Reserve uninterrupted blocks of time for session supervision. During a focus block, you process the queue of blocked sessions, make decisions, and unblock agents. Outside of focus blocks, you do other work. Focus blocks prevent the constant low-level attention drain that comes from monitoring sessions while trying to do other things.

Reserve decision budget for high-stakes sessions. Not all decisions are equal. A decision about whether to deploy to production matters more than a decision about variable naming. Allocate your decision budget accordingly. Make the important decisions when you are fresh. Batch the trivial decisions and make them in a low-energy slot.

Take recovery breaks. Context switching and decision-making are cognitively expensive. After a heavy session of supervising multiple agents, take a deliberate break to let attention residue dissipate. This is not laziness, it is maintenance of the resource that matters most: your judgment.

Strategy 11: Reduce Session Count Through Better Task Definition
#

The easiest session to manage is the one you never needed to start.

Write precise specifications. A well-specified task runs autonomously and produces fewer questions. A vaguely specified task generates constant clarifying questions, each of which is a context switch. Investing in specification quality before launching a session benefits the session for its entire lifetime. This is the same principle described in The Importance of Context When Interacting with LLMs: the quality of the context determines the quality of the output.

Merge related tasks. If two tasks touch the same code or the same domain, combine them into one session instead of running two. One session managing a coherent area is easier to track than two sessions with overlapping scope.

Eliminate unnecessary sessions. Before launching a new session, ask whether the task is worth the supervision overhead. Some tasks are faster to do yourself than to delegate to an agent and then supervise. The shifting bottleneck principle applies: as agent supervision becomes the bottleneck, the optimal strategy shifts from spawning more agents to being more selective about which tasks to delegate.

Pre-compute common answers. If you find yourself answering the same type of question across multiple sessions, encode the answer once in a shared resource that all sessions can access. A shared FAQ, a coding standards document, or a decision tree eliminates a category of future questions.

Strategy 12: Version and Review Session Patterns
#

Managing many sessions is a skill that improves with deliberate practice.

Record what worked. When a session runs smoothly from start to finish, note what made it smooth. Was the specification clear? Were the escalation thresholds well-calibrated? Did the status format make triage easy? These observations compound into better patterns over time.

Post-mortem failed sessions. When a session drifts from its instructions, review why. Did the agent lack critical context? Did the escalation threshold let it run too long without checking in? Did the state file fail to capture the information you needed to intervene effectively? Each failure is a data point for improving the protocol.

Iterate on the protocol. The session protocol, the status format, the escalation rules, and the dashboard design should all evolve as you learn what works. Treat your agent management system as a product that you are continuously improving. The goal is not to find the perfect system on day one but to get a little better every week.

Share patterns across teams. If multiple people in your organization supervise agent sessions, share what works. The patterns that reduce cognitive load for one person will likely help others. This is the same knowledge-sharing principle that makes software engineering teams effective: institutional knowledge compounds when it is explicit and shared.

The Ceiling: How Many Can You Actually Manage?
#

There is no single number, but the constraints are concrete.

With no system, no tooling, and synchronous interaction, a human can effectively manage 1 to 2 concurrent agent sessions. The cognitive overhead of tracking each session’s state in working memory and responding to questions in real time is too high to scale further.

With externalized state files, standardized protocols, and asynchronous batching, 4 to 6 concurrent sessions become feasible. You are no longer holding state in your head, and you batch your interactions to reduce switch cost.

With hierarchical orchestration, progressive disclosure, and a dashboard, 10 to 15 concurrent sessions are manageable. The orchestrators compress information, the dashboard provides a single view, and you interact with a manageable number of direct reports.

With AI-assisted triage, tight escalation thresholds, and well-specified tasks, 20+ concurrent sessions are achievable for a human who has invested in the workflow. At this scale, you are no longer managing individual sessions. You are managing a system that manages sessions.

The progression mirrors the task-stack philosophy: you push interruptions onto a stack, handle them in batches, and pop them off when done. The difference is that the stack now contains not just your own tasks but the states of dozens of autonomous workers, and the stack is externalized rather than in your head.

The Meta-Principle
#

Every strategy in this article reduces to one of four operations on the cognitive constraints:

Reduce working memory load by externalizing state, standardizing formats, and chunking sessions into clusters.

Reduce switch cost by standardizing protocols, batching interactions, and isolating sessions.

Reduce attention residue by letting sessions reach natural stopping points, taking recovery breaks, and using focus blocks.

Reduce decision fatigue by having agents resolve their own ambiguities, using decision templates, and reserving decision budget for high-stakes choices.

The agents are not the bottleneck. Your brain is. Every hour you spend engineering the workflow around your own cognitive limits is worth ten hours of trying to work through them.

References
#

Miller, “The Magical Number Seven, Plus or Minus Two” – established the working memory capacity limit that constrains how many sessions a human can track mentally
Zeigarnik effect – explains attention residue from unfinished tasks, a core problem when many sessions run concurrently
Decision fatigue – describes how decision quality degrades over a session, relevant to supervising many agents
Chunking (psychology) – the memory technique that enables grouping sessions into manageable clusters
Scaling the LLM Agent Company – established the orchestration layer as the replacement for human management in agent systems
The Importance of Context When Interacting with LLMs – established that specification quality determines agent autonomy, reducing the need for human intervention
The Shifting Bottleneck – established the pattern of bottlenecks moving up the decision chain, applicable to the human supervisor as the new bottleneck
Workstack – the note-taking concept that externalizes task state, the basis for session state files
Task-stack – the persistent task tracking tool that models the push/pop pattern for interruptions

slack-cached - Cache Slack threads, channels, and users to a local SQLite database

tom@tomrochette.com (Tom Rochette) — Tue, 16 Jun 2026 00:00:00 +0000

Note (2026-07-02): slack-cached has been renamed to slackx.

Slack is where your team’s decisions live, but the data doesn’t belong to you. Search is slow, threads become hard to find, and the moment you leave a workspace the history is gone. There’s no official CLI, and the web client is the only first-class way to read anything.

I built slack-cached to fix this. It’s a small Python CLI that caches Slack threads, channel messages, users, and channels to a local SQLite database. Once cached, the data is yours: query it with SQL, grep it, feed it to an LLM, or just read it offline.

The problem
#

Slack makes exporting and archival surprisingly hard. Export tools exist for admins, but most members aren’t admins. The search box returns messages, but not in a form you can slice, join, or version. Important decisions get lost in threads that nobody scrolls back to.

The problem gets worse when you want to do anything programmatic. Building a knowledge base, summarizing a channel, or tracking decisions all require raw access to the messages. Hitting the Slack API on demand works, but you incur the latency and rate-limit cost every time, and edits disappear if you only ever fetch live.

How slack-cached works
#

$ uv sync
$ uv run slack-cached --help
usage: slack-cached [-h] {fetch,show,fetch-users,fetch-channels,show-users,show-channels,poll} ...

Cache Slack threads to a local SQLite database.

Cache a thread from a URL (no stdout, just a one-line summary on stderr):

$ slack-cached fetch https://acme.slack.com/archives/C0123ABCDEF/p1700000000123456
cached 3 messages (3 new/updated, full) for C0123ABCDEF/1700000000.123456

Or by explicit channel and timestamp; run it again and it only asks Slack for what changed:

$ slack-cached fetch --channel C0123ABCDEF --ts 1700000000.123456
cached 3 messages (3 new/updated, full) for C0123ABCDEF/1700000000.123456

$ slack-cached fetch --channel C0123ABCDEF --ts 1700000000.123456   # run again
cached 4 messages (1 new/updated, incremental) for C0123ABCDEF/1700000000.123456

Read it back, human-readable by default:

$ slack-cached show https://acme.slack.com/archives/C0123ABCDEF/p1700000000123456
Thread C0123ABCDEF/1700000000.123456
3 message(s)

[2023-11-14T22:13:20+00:00] Alice Smith (alice)
    Has anyone tried the new deploy script?

[2023-11-14T22:15:12+00:00] Bob Lee (bob)
    Yes, but you need to bump the token first.

[2023-11-14T22:16:45+00:00] Alice Smith (alice)
    Thanks!

show auto-fetches if the thread isn’t cached yet, and renders display names like Alice Smith (alice) instead of raw user ids once you’ve cached users. Pass --json to get the raw records for piping into other tools:

$ slack-cached show --json https://acme.slack.com/archives/C0123ABCDEF/p1700000000123456
{
  "channel": "C0123ABCDEF",
  "channel_name": "deploys",
  "thread_ts": "1700000000.123456",
  "message_count": 3,
  "messages": [
    {
      "ts": "1700000000.123456",
      "user": "U1",
      "text": "Has anyone tried the new deploy script?",
      "payload": { "ts": "1700000000.123456", "user": "U1", "type": "message" },
      "user_name": "Alice Smith (alice)"
    },
    {
      "ts": "1700000112.000200",
      "user": "U2",
      "text": "Yes, but you need to bump the token first.",
      "payload": { "ts": "1700000112.000200", "user": "U2", "type": "message" },
      "user_name": "Bob Lee (bob)"
    },
    {
      "ts": "1700000205.500300",
      "user": "U1",
      "text": "Thanks!",
      "payload": { "ts": "1700000205.500300", "user": "U1", "type": "message" },
      "user_name": "Alice Smith (alice)"
    }
  ]
}

Channels, users, and polling
#

Cache every top-level message in a channel:

$ slack-cached fetch --channel C0123ABCDEF
cached 142 messages for C0123ABCDEF (38 fetched)

Add --full-threads to also pull every reply thread, so you get the full conversation tree:

$ slack-cached fetch --channel C0123ABCDEF --full-threads
cached 318 messages for C0123ABCDEF (214 fetched, 47 threads with replies fetched)

For continuous capture, poll watches multiple channels and fetches new messages on a schedule. Each entry in --channels can be a channel id, a bare name (general), or a #-prefixed name (#general); names are resolved against the cached channels, which is why the per-cycle summary below reports ids. Progress goes to stderr, and (because of --json) one compact JSON object per cycle goes to stdout. Ctrl+C stops it gracefully:

$ slack-cached poll --channels #general,#engineering,#deploys --interval 5m --last 5m --full-threads --json
polling 3 channel(s) every 5m (lookback: 5m, full_threads: True, concurrency: 3)
{"cycle": 1, "elapsed_seconds": 1.234, "channels": [{"channel": "C001", "fetched": 3, "total": 312}, {"channel": "C002", "fetched": 4, "total": 188}, {"channel": "C003", "fetched": 0, "total": 27}]}
cycle 1: 7 new message(s) across 3 channel(s) in 1.2s
^C
poll stopped after 1 cycle(s)

That stdout stream is easy to wire into a downstream pipeline or a knowledge-base builder.

Finally, cache the workspace’s users and channels so threads can be rendered with display names:

$ slack-cached fetch-users
processed 184 users (184 added, 184 total in db)
$ slack-cached fetch-channels
processed 37 channels (37 added, 37 total in db)

$ slack-cached show-users
184 user(s)

U1  alice - Alice Smith
U2  bob - Bob Lee
...

$ slack-cached show-channels --json
{
  "channel_count": 37,
  "channels": [
    {
      "id": "C1",
      "name": "general",
      "is_private": false,
      "fetched_at": 1700000260.0,
      "payload": { "id": "C1", "name": "general", "is_channel": true }
    },
    ...
  ]
}

The refresh strategy
#

fetch always contacts Slack, but it’s incremental. On a re-fetch, it calls conversations.replies with oldest=<latest_cached_ts>, so the API returns only new replies and any edits at the boundary. Messages are upserted by ts, which means edits replace the old text in place instead of creating duplicates.

Rate limits are handled for you. HTTP 429 / ratelimited responses are retried with exponential backoff, up to five attempts, respecting the Retry-After header. That matters for --full-threads and poll, where you can easily make hundreds of calls against a busy channel.

Where the cache lives
#

The database defaults to $XDG_CACHE_HOME/slack-cached/threads.db (typically ~/.cache/slack-cached/threads.db). Override it per command with --db /path/to/file.db. Because it’s plain SQLite, you can open it directly and ask it anything Slack’s search box can’t:

$ sqlite3 ~/.cache/slack-cached/threads.db \
    "SELECT (u.real_name || ' (' || u.name || ')') AS who, COUNT(*) AS msgs
     FROM messages m JOIN users u ON m.user = u.id
     WHERE m.channel = 'C0123ABCDEF'
     GROUP BY who ORDER BY msgs DESC LIMIT 5;"
Alice Smith (alice)|142
Bob Lee (bob)|87
Carol Ng (carol)|53

That query is the main point of the tool. The cache is not an opaque blob; it’s a table of messages you can SELECT from, join against users and channels, and export however you like.

Authentication
#

Credentials load from environment variables first, then a config file at $XDG_CONFIG_HOME/slack-cached/config:

SLACK_TOKEN=xoxb-...
SLACK_COOKIE=...
SLACK_API_BASE_URL=https://slack.com/api

SLACK_COOKIE is there for xoxc- web-client tokens, which need the matching cookie to authenticate. Every command also accepts --api-base-url, which is how the built-in fake Slack server plugs in.

A fake Slack server, for free
#

The repo includes slack-fake-server, a deterministic fake Slack API for testing:

$ uv run slack-fake-server --port 8199 --num-threads 50 --rate-limits
2026-06-15T12:00:00Z [info     ] fake_slack_server_starting   host=127.0.0.1 port=8199 seed=42 users=8 channels=5 threads=50 rate_limits=True

It serves conversations.list, conversations.replies, conversations.history, and users.list, and can simulate Slack-tier rate limiting. Point slack-cached at the fake server and you can develop and test against a realistic API without touching your own workspace:

$ slack-cached fetch --api-base-url http://localhost:8199/api --channel C0123ABCDEF --full-threads
cached 318 messages for C0123ABCDEF (214 fetched, 47 threads with replies fetched)

When this is useful
#

Knowledge bases and channel summaries. Poll a set of channels, then build monthly digests or feed the SQLite cache to an LLM.
Decision tracking. Important calls often happen in threads. Cache them so they survive workspace churn and account turnover.
Offline access and archival. Keep a readable copy of the conversations you actually care about, independent of Slack’s retention window.
Bulk analysis. Once the data is in SQLite, you can answer questions with a query that Slack’s search box can’t express.

What to Do Next
#

$ git clone https://github.com/TomzxCode/slack-cached
$ cd slack-cached
$ uv sync
$ export SLACK_TOKEN=xoxb-...
$ slack-cached fetch-channels
processed 37 channels (37 added, 37 total in db)
$ slack-cached fetch --channel C0123ABCDEF --full-threads
cached 318 messages for C0123ABCDEF (214 fetched, 47 threads with replies fetched)
$ slack-cached show https://acme.slack.com/archives/C0123ABCDEF/p1700000000123456
Thread C0123ABCDEF/1700000000.123456
3 message(s)

[2023-11-14T22:13:20+00:00] Alice Smith (alice)
    Has anyone tried the new deploy script?

[2023-11-14T22:15:12+00:00] Bob Lee (bob)
    Yes, but you need to bump the token first.

[2023-11-14T22:16:45+00:00] Alice Smith (alice)
    Thanks!

Repository and source code, documentation.

References
#

TomzxCode/slack-cached README – primary source for features, commands, and behavior.
slacrawl – related prior art referenced by the project.

Developer Trust Profiles: Earned Scrutiny for Automated Code Review

tom@tomrochette.com (Tom Rochette) — Mon, 15 Jun 2026 00:00:00 +0000

When you automate code review, the obvious design is to treat every pull request identically. Same checks, same threshold, same outcome, regardless of author. This obvious design is wrong.

A reviewer that applies the same scrutiny to a developer who has shipped two hundred clean PRs and to a stranger on their first contribution is either too strict for the first or too lax for the second. It is a blunt instrument, and bluntness prevents autonomy. The more you rely on automated approval to unblock work, the more you need a mechanism that varies scrutiny by evidence.

I built that mechanism as a pair of skills in my agent library, developer-trust-profile and initialize-developer-trust-profile. This is the idea behind them, and why I believe it is the missing primitive for autonomous code review.

The problem with a reviewer that has no memory
#

Most automated review tools are stateless. They look at a diff, run their checks, and emit a verdict. Next PR, they start over, as if they had never seen the author before.

Stateless review is not how any experienced human reviewer works. When a trusted colleague opens a PR, you skim it, confirm the tests pass, and approve. When someone with a history of breaking the build opens one, you read every line. You already know who tends to forget tests, who mixes unrelated refactors into a single commit, who writes the clearest descriptions. That knowledge is not bias to be eliminated; it is signal, accumulated over hundreds of reviews, that tells you where to spend your attention.

A stateless automated reviewer throws all of that signal away. It re-derives, badly and from scratch, what a human reviewer simply remembers. The result is a system that either approves indiscriminately (unsafe) or applies maximum suspicion to everyone (slow, and damaging to trust).

The trust profile is the answer to a direct question: how does an automated reviewer remember?

What a trust profile stores
#

Each developer gets a single file, ~/.developer-trust/{github_username}.md, and the whole directory is a git repository. The file accumulates observations across every review.

Four trust levels exist, and each one maps to a different behavior, not just a different label:

Level	Meaning	Effect on the automated reviewer
`trusted`	Consistently clean, high-quality PRs	Standard checks, lean toward approval on borderline cases
`neutral`	Unknown or mixed track record	Standard checks, default behavior
`cautious`	History of issues, missed edge cases, unclear PRs	Stricter interpretation, flag marginal cases as failures
`always_reject`	Persistent quality or policy issues	Skip entirely, never auto-approve, require manual review

Beyond the level, the profile keeps a running overview, lists of strengths and weaknesses observed across PRs, recurring PR patterns, and a full review history table with dates, repos, outcomes, and a one-line note per review.

Crucially, it is plain markdown in a git repo. That makes the system’s memory auditable, diffable, and portable. You can see the exact review that tipped an author from neutral to cautious, and the reasoning behind it. For a mechanism that gates code into production, that written record is not a nice-to-have; it is a requirement.

How earned trust changes review behavior
#

The levels are not decorative. They modify how the automated reviewer interprets its own checks.

The reviewer I run, quick-pr-review, evaluates a fixed set of gates: significant public interface changes, security-sensitive code, new dependencies, reversibility, passing CI, alignment with the linked issue’s acceptance criteria. For a neutral author, each gate is binary. For a trusted author, a borderline call (is this small new export a “significant” public interface change?) leans toward passing. For a cautious author, that same borderline call is treated as a failure.

This is differential scrutiny, and it is the whole point. The checks are identical; the threshold moves with evidence. A trusted author gets unblocked faster because the reviewer stops re-examining cases it has effectively already resolved. A cautious author gets caught earlier, before a recurring weakness reaches production again.

And then there is always_reject, the hard stop. When an author sits at that level, the reviewer does not fetch the diff, does not post a comment, does not approve. It reports that the PR was skipped and that a human needs to look. This is the system saying: I have enough evidence to know I should not be making this decision.

The loop closes
#

The profile is not a static config file that a human maintains by hand. It is both consumed and produced by the review pipeline.

Before a review, quick-pr-review reads the author’s profile to set its thresholds. After the review, it writes back: it appends a row to the history, merges new observations into the strengths and weaknesses, and reconsiders the trust level if the accumulated evidence warrants it. Each profile update is committed to the local git repo with a message like Update alice trust profile (approved: acme/api#42).

This makes the system learn gradually rather than judge. A single review does not move the trust level, unless it is egregious. Trust degrades through recurring patterns observed across many PRs, and the level only shifts when the weight of evidence demands it. That hysteresis is deliberate. It prevents one poor review from permanently labeling a developer, and it prevents one PR that passed by chance from granting unwarranted autonomy.

Bootstrapping without survivorship bias
#

The hardest part of any reputation system is the cold start. A new contributor, or a contributor new to the system, starts at neutral with an empty file. That is safe but unhelpful; you want a profile based on actual history, not an empty file that takes months to fill.

The initialize skill bootstraps a profile from history by scanning the author’s last N pull requests across every repository the token can see. The detail that separates this from a naive implementation is that it samples both merged and rejected PRs.

Sampling only merged PRs is survivorship bias in its purest form. It would make every developer look good, because the failures were quietly closed and forgotten. By pulling closed-without-merge PRs as well, and by deriving the outcome from actual review data (was there a changes-requested that was never superseded?) rather than assuming merge equals approval, the bootstrap produces a profile that reflects how a developer actually works, not just their wins.

Processed oldest-first, each historical PR feeds into the same update pipeline as a live review, so a freshly initialized profile looks exactly like one that was built up review by review over time.

Limitations
#

The design has genuine trade-offs, and they are worth naming.

Profiles live on the reviewer’s machine and are not shared. This is a feature (no global reputation database, no public scoring of humans) and a cost (each reviewer builds a different picture, and the memory does not transfer). For a single operator running their own agents, that is the right trade. For an organization, you would want a shared, access-controlled store, and the design does not claim otherwise.

There is a risk that a reputation becomes fixed and a developer cannot escape it. The skills mitigate this by removing observations that recent evidence contradicts and by reconsidering the level on every update. But any system that summarizes a human into a label can trap them in that label. The fix is transparency (everything is in a diffable file) and a human who can edit the file when the summary is wrong.

There is also a gaming risk. Once authors know a trust system exists, they can optimize for it. On balance this is fine: optimizing for clean, well-tested, well-scoped PRs that reference their issues is exactly the behavior you wanted anyway. The system fails safe, because the worst case is that people produce better PRs.

Why this matters more in the age of LLM-authored code
#

I have written elsewhere about why human review of LLM-generated code is a poor use of attention (see The Future of Code Review). The short version is that the human’s leverage has moved upstream, to specifying the problem, while machines verify compliance.

But that argument is incomplete. Even after you accept automated review, you are left with a follow-up question: should the automated reviewer treat every author identically? The answer is no, and for a reason that is sharper now than it was five years ago.

In an LLM-heavy workflow, the “author” of a PR is increasingly a human paired with a model, or an agent operating on a human’s behalf. The trust profile stops measuring just a developer’s coding skill and starts measuring something more valuable: the quality of a human’s oversight of their tools. Two developers can submit PRs that an LLM wrote. One vets the output carefully, keeps PRs atomic, links the spec, and ships reversible changes. The other rubber-stamps whatever the model produced, mixes concerns, and breaks public interfaces. A stateless reviewer cannot tell them apart. A reviewer with a trust profile can, and it calibrates its scrutiny accordingly.

Seen this way, the trust profile supports the automated reviewer: the checks define what “good” looks like, and the profile decides how much to trust that a given author is delivering that standard.

But that framing also points at the profile’s eventual obsolescence, which is the goal.

A bridge, not a destination
#

The trust profile is a mechanism I want to make obsolete.

The ideal end state is not a finely calibrated reputation system that perfectly sorts developers into tiers. The ideal end state is that there is nothing to sort. Every contributor, senior engineer or new hire, funnels their work through agents that enforce the same standards: atomic PRs, tests that pass, interfaces that do not break, changes that are reversible and tied to a spec. The output converges into something homogeneous, and by the time it reaches the code stage it is, for all practical purposes, perfect. Authorship stops carrying signal, because every author is producing the same uniform quality through the same disciplined pipeline.

In that world the reviewer’s checks still run, but they never flag anything, because the problems were engineered out upstream rather than caught downstream. And the trust profile, with nothing left to differentiate, collapses: everyone sits at trusted, the level never moves, and the file stops being worth reading.

That is the accurate framing for the trust profile. It is not the destination; it is the bridge. Today’s reality is heterogeneous, a mix of careful and careless, hand-written and agent-generated, vetted and rubber-stamped, and the profile does useful work precisely because that variance exists. As the variance shrinks, so does the profile’s job, until the most successful outcome is that no one, me included, needs it anymore.

The Importance of Context When Interacting with LLMs

tom@tomrochette.com (Tom Rochette) — Mon, 15 Jun 2026 00:00:00 +0000

Most interactions with LLMs fail not because the model lacks capability, but because the user fails to provide enough context for the model to succeed. Context is not a prompt engineering trick. It is the entire mechanism by which a frozen set of weights produces behavior relevant to your specific situation.

What Context Means for an LLM
#

A large language model is a fixed function at inference time. Its weights were determined during training and do not change. Everything you want the model to know about your current task, your constraints, your codebase, your domain, and your preferences must be communicated through the context window.

This window has three conceptual regions.

The system prompt establishes persistent instructions and persona.
The conversation history provides the back-and-forth of the interaction.
The retrieved or injected context supplies external knowledge that the model was not trained on.

When people say “prompt engineering,” they are usually talking about the system prompt and a handful of few-shot examples. When people say “RAG,” they are talking about dynamically injecting retrieved documents into the third region. When people say “context engineering,” they are talking about the deliberate design of all three regions together.

In-Context Learning: Why This Works at All
#

The GPT-3 paper demonstrated something surprising: a sufficiently large language model can learn new tasks from examples provided in the prompt, without any gradient updates. This is in-context learning, and it is the reason context matters so much.

A model that has never seen your internal API conventions can follow them perfectly if you show it three examples. A model that does not know your company’s style guide can adopt it verbatim if you paste it in. The model is not truly “learning” in the statistical sense. The model is recognizing patterns in the provided context and extending them.

In-context learning means the quality of the context is the quality of the output. Vague context produces vague output. Contradictory context produces contradictory output. Missing context produces plausible-sounding output that is wrong in ways specific to your situation.

The Spectrum of Context Strategies
#

Context can be provided along a spectrum, from minimal to extensive.

Zero-shot prompting relies entirely on the model’s pre-trained knowledge. Zero-shot prompting works for generic tasks (summarize this text, translate this sentence) because the training data likely contained millions of similar examples. Zero-shot prompting fails for domain-specific tasks (generate a query against our proprietary schema, review code against our internal standards) because the model has never seen your specific conventions.

Few-shot prompting injects examples into the context window. The original GPT-3 evaluation showed that performance scales with the number of examples, but with diminishing returns. Three to five high-quality examples often capture 80% of the benefit. Example quality matters more than example quantity. One example that perfectly demonstrates the desired behavior outperforms ten mediocre ones.

Retrieval-augmented generation (RAG) dynamically fetches relevant documents and injects the documents into the context. The original RAG paper showed that combining a parametric model with non-parametric retrieval produces better grounded answers than either alone. RAG addresses the fundamental limitation that a model’s training data is a snapshot in time and cannot contain proprietary or recent information.

Long-context ingestion bypasses retrieval by stuffing everything into a large context window. Models such as Gemini with million-token context windows make the approach technically feasible. The question is whether dumping everything into the window actually works. Liu et al. demonstrated that models suffer from a “lost in the middle” effect: information at the beginning and end of the context is retrieved more reliably than information in the middle. Simply increasing the window does not linearly increase the model’s ability to use the information.

Context engineering is the emerging discipline of orchestrating all of these strategies deliberately. Context engineering recognizes that context is not just “what you put in the prompt,” but a system that includes retrieval logic, example selection, conversation management, and information ordering.

Where Context Breaks Down
#

Understanding the failure modes of context is as important as understanding how to provide context.

Attention dilution. Every token in the context window competes for the model’s finite attention. Adding irrelevant context does not just waste tokens. Adding irrelevant context actively degrades performance on the relevant portions. Liu et al.’s “Lost in the Middle” showed that even when the relevant information is present in the context, retrieval accuracy drops when the context is cluttered with noise. The lesson: more context is not always better. The right context, curated and ordered, outperforms a dump of everything that might be relevant.

Instruction following degrades at scale. System prompts and instructions are more reliably followed when the instructions are prominent in the context. As the context window fills with retrieved documents, conversation history, and examples, the model’s adherence to its original instructions weakens. Weakening adherence is why many production systems re-inject key instructions at the end of long contexts, not just the beginning.

Stale context. In a long agent session, early conversation turns become increasingly irrelevant. The model continues to weigh the early turns in its attention computation. The result is drift, where the model brings up constraints or preferences from turn 3 that are no longer applicable at turn 30. Effective agent systems summarize or prune earlier context to maintain relevance.

Implicit context gaps. The most dangerous context failures are the ones you do not notice. You assume the model knows that your API returns snake_case JSON, that your timestamps are in UTC, that your user IDs are integers not strings. The model does not know any of these things unless you tell it. Each implicit assumption is a potential bug in generated code or a hallucinated fact in generated text.

Practical Context Design
#

For engineers building with LLMs, context design is the highest-impact activity. Here are concrete patterns that work.

Layer your context deliberately. Start with a system prompt that defines the task, constraints, and output format. Follow with retrieved documents that are directly relevant to the current query. Then provide conversation history, pruned to the most recent and relevant turns. End by restating the specific question or instruction. This ordering respects the model’s attention patterns, which weight the beginning and end of context most heavily.

Curate your examples. A few-shot example should demonstrate the hardest case, not the easiest. If your task involves edge cases (empty inputs, special characters, ambiguous queries), show examples of those edge cases. Showing five variations of the happy path teaches the model less than one example of each difficult variant.

Use structured context. When injecting retrieved information, format the information consistently. Markdown headers, delimited sections, and numbered lists give the model explicit boundaries between pieces of information. A blob of unstructured text forces the model to spend attention on parsing structure rather than reasoning about content.

Separate context from instruction. Mixing “here is some reference information” with “now do this task” in the same unstructured block reduces reliability. Explicitly mark where context ends and instructions begin. Many production systems use XML tags or special tokens for this purpose.

Test your context independently. Before deploying an LLM pipeline, test whether the model can answer simple factual questions based solely on the provided context. If the model cannot reliably retrieve a fact that is clearly present in the context, the context is too long, too noisy, or poorly structured. The test is a fast diagnostic that catches many context problems before the context problems become production incidents.

Context Engineering as a Discipline
#

The shift from “prompt engineering” to “context engineering” reflects a maturation in how we think about LLM interactions. Prompt engineering suggests that the right wording produces better performance. Context engineering recognizes that the entire information environment determines the output.

The distinction matters because it changes where you invest effort. If you believe that the right words are what matters, you spend your time iterating on wording. If you believe in context engineering, you invest in retrieval systems, example libraries, context ordering, and information architecture.

The results from Anthropic’s work on contextual retrieval illustrate the payoff well. By adding a small amount of context to each retrieved chunk (explaining how the chunk relates to the broader document), Anthropic reduced retrieval failure rates by 67%. Not by changing the model. Not by changing the prompt. By changing how context was prepared and presented.

Chain-of-thought prompting is another example. The model’s reasoning improves not because you asked the model to “think step by step”, but because you expanded the context window with intermediate reasoning steps. The model uses its own generated context as additional input for subsequent tokens. Context is not just what you provide. Context is also what the model generates and then consumes.

The Uncomfortable Implication
#

If context determines output quality, the ceiling on LLM performance in production is not the model’s capability but the quality of the context pipeline feeding the model.

The conclusion is uncomfortable because the hardest engineering problem in LLM applications turns out not to be model selection or fine-tuning. The hard problem is information retrieval, information architecture, and information presentation. These are old problems from search engineering and information science, now applied to a new interface.

The engineers who build the best LLM products will not necessarily be the ones who understand transformer architectures most deeply. The best LLM products will be built by the engineers who can design systems that surface the right information, at the right time, in the right format, and place the information where the model will actually attend to it.

Context is not a feature you add to an LLM application; it is the application.

References
#

Brown et al., “Language Models are Few-Shot Learners” – established in-context learning as a core capability of large language models
Lewis et al., “Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks” – introduced RAG as a method for grounding LLM outputs in retrieved documents
Liu et al., “Lost in the Middle: How Language Models Use Long Contexts” – demonstrated positional bias in how models attend to long contexts
Wei et al., “Chain-of-Thought Prompting Elicits Reasoning in Large Language Models” – showed that intermediate reasoning steps in context improve model performance
Anthropic, “Contextual Retrieval” – demonstrated that context preparation significantly reduces retrieval failure rates

The Merge Gate: Do You Need a Human to Approve Your Pull Requests?

tom@tomrochette.com (Tom Rochette) — Mon, 15 Jun 2026 00:00:00 +0000

My previous piece was about code review: a human reading code before it ships. This one is narrower, and more direct. It is about the merge gate, the specific act of requiring a human to click “approve” before code can land in a codebase.

People treat review and approval as the same thing. They are not. You can review code without being able to block it. You can approve code without reading it. The valuable act (reading) and the gating act (merging) have been combined by our tooling, and that combination is worth separating.

Most arguments for keeping a human in the merge loop collapse once you ask a single question. What does the approval click certify that the automated gates did not?

What the Approval Click Actually Certifies
#

Watch what happens when a pull request gets approved.

The approver sees a green checkmark from CI. They see a passing test suite. They scan the diff for a few seconds. They click approve.

Ask them, afterward, what they certified. They will struggle to answer.

They did not re-run the tests; CI already did that. They did not verify the implementation against the spec; they assumed someone else did. They did not reason about every edge case; the diff was too long to reason about in three minutes. They did not assess whether the change could be undone; that is not what diffs show.

The approval click, in most teams, certifies exactly one thing: that a specific human was awake and present at the moment the PR was merged. That is a low-information event, and it is doing almost no safety work.

The actual safety is being produced by the systems around the gate. The test suite. The linter. The static analyzer. The deployment pipeline. The rollback path. The human approval is layered on top, credited with safety it did not generate.

The Cost of the Gate
#

A gate that does little safety work still imposes a cost. Several costs, in fact, and they add up.

Latency. Every pull request waits for a human. That human is in a meeting, asleep, on another team, or simply not looking at their inbox. Cycle time stretches from minutes to hours to days. Work that could ship this morning ships next Tuesday.

Batch amplification. Batch amplification is the subtlest and most damaging cost. When approval is expensive to obtain, people batch. They hold three small changes until they have a fourth, because each approval is a fixed-cost interruption. The gate incentivizes the exact thing it should discourage: larger, riskier changes. A mechanism designed to keep changes safe ends up making them less safe, because the unit of review grows to fill the cost of getting reviewed.

Context switching. Every approval is an interruption for the approver. Their work is paused, their context is swapped, their focus is interrupted. You are taxing your most experienced engineers to perform a low-information ritual.

Single point of failure. If only two people can approve a given area and both are out, the pull request stalls. Approval authority concentrates, and concentration creates bottlenecks and bus factors.

Soft target. The approver is the cheapest attack surface in the entire pipeline. You can harden CI, pin dependencies, and scan for secrets, but a tired approver who clicks approve on a social-engineered change defeats all of it. A human gate is a human vulnerability.

What Actually Makes a Merge Safe
#

Remove the ritual and ask what keeps a merge safe. It is a short list, and the human approver is not on it.

A comprehensive test suite that runs on every change. Static analysis that catches the classes of bugs tests miss. A deployment pipeline that canaries before it fully rolls out. Feature flags so new behavior can be disabled without a redeploy. A rollback path that has actually been tested, not assumed. Blast-radius limits that cap how much any single change can touch.

Each of these operates on reality, not on a human’s prediction of reality. A canary either surfaces the problem or it does not. An approver might notice the problem, or might be thinking about lunch.

The gate is credited with safety the system produces. Once you see this, you cannot ignore it.

The Accountability Objection
#

The first objection is accountability. Without a human approval, who is responsible for the code that ships?

I made this argument in the previous piece, and I will not repeat all of it here. The short version is that a human glancing at a diff was never truly responsible for what shipped. Responsibility starts upstream, with who decided the problem was worth solving and who wrote the specification.

The approval signature adds nothing to that account. It is a name on a line, demanded because it feels like accountability. When a change breaks production, the approver is not the one who gets blamed, disciplined, or even consulted. The signature exists to allocate blame after the fact, not to prevent harm before it.

What remains, once you accept this, is the audit and compliance framing. That is the stronger case for keeping a human signature, and it deserves its own answer.

The Compliance Objection
#

“But regulation requires human approval.”

Sometimes it does. More often, regulation requires traceability, a named owner, a documented decision, an auditable path. Those are not the same thing as a tired human clicking approve at four in the afternoon on a Friday.

When a rule says a change must be “reviewed and approved”, it is trying to ensure that someone with authority consciously decided the change was acceptable. That intent can be satisfied several ways. A named owner who signed off on a specification. An automated gate whose rules were themselves approved by a human. A risk classification that a human defined and a machine enforces consistently.

The function is accountability and traceability. The form is “a human clicks a button”. Teams satisfy the form and skip the function all the time. The sound path is the reverse: satisfy the function rigorously, and let the form follow.

If your auditor insists that safety depends on a specific human keystroke, you have an education problem, not an engineering one.

The Binary Mistake
#

The deeper error is treating approval as binary. Either every pull request needs a human, or no pull request does.

The binary view is wrong, and it is not how anyone actually behaves. A README typo and a production schema migration are both pull requests. They do not need the same gate. Treating them the same is not caution; it is a failure to think about risk.

The right unit of gating is not “is this a pull request”. It is “what is the blast radius of this change, and is it reversible”.

A one-line documentation fix is low blast radius and trivially reversible. Let it merge on green. No human needs to see it.

A change that drops a database column is high blast radius and may be irreversible. That deserves a human looking at it, carefully, with time.

A change that alters an authentication boundary is medium blast radius but high trust impact. That deserves a human, and probably more than one.

The properties that should trigger a human gate are properties of the change: irreversibility, blast radius, trust-boundary crossing, external commitment. They are not properties of the artifact. When you gate on the change instead of the artifact, the fraction of changes that need a human collapses to a small minority.

The Small Set Where a Human Gate Genuinely Adds Value
#

Frankly, there is a set of changes where a human in the merge loop actually adds value. It is small, but it exists.

Irreversible changes. Data destruction, schema drops, deletions of public content, sending actual money, publishing to external systems. Once these execute, you cannot call them back. A human who understands the irreversibility should look at them, because the automated gates can only verify forward correctness, not undo impossibility.

Trust-boundary changes. Authentication, authorization, permission models, security-sensitive code paths. These are exactly where a subtle mistake is both likely and catastrophic. A human reviewer adds value here, not because they will catch every bug, but because the cost of a miss is high enough to justify the latency.

Changes to the gating system itself. You do not want the merge gate to auto-approve changes to the merge gate. That is the one place where circular logic causes harm. A human reviews the rules that the machine enforces.

External commitments. Public API changes, contractually obligated behaviors, compliance-relevant logs. These have consequences outside the codebase, and a human should confirm the external surface is intentional.

Note what is not on this list. Styling. Refactors within a single module. New tests. Documentation. Internal-only features. Dependency bumps that pass audit. These are the overwhelming majority of pull requests. They do not need a human gate. They need the automated gates, and then they need to merge.

The Transition
#

You do not get to “no human gate for most changes” by decree. You get there by making the default path safe.

Start by making the low-blast-radius path auto-merge on green. Documentation, tests, internal-only changes within a single module. CI passes, the merge happens, nobody clicks anything.

Then compute blast radius automatically. Which files changed. Did the change touch the public API. Did it touch the database schema. Did it add a dependency. Did it change infrastructure or deployment configuration. Did it cross a security boundary.

Each of these is a machine-checkable property. Route the change to the human gate only when it crosses a threshold.

When a change does reach the human gate, change what the human is actually doing. They are no longer reviewing code line by line. They are reviewing risk. Is this change as irreversible as the system thinks it is? Is the rollback plan genuine? Is the blast radius acceptable? Does the external commitment match what was approved upstream?

Reviewing risk is high-leverage work. Reviewing diffs for style is not. The transition moves the human from the low-leverage activity to the high-leverage one, and it frees the rest of the pipeline to move at the speed the machines can sustain.

This is not a proposal. It is a description of the workflow from the previous piece, where a pull request is checked against concrete gates: does it introduce security-sensitive changes, add dependencies, change public interfaces, is it reversible, do the tests pass, does it satisfy the acceptance criteria. What this article adds is the principle behind that workflow. The human gate is the exception, selected by the properties of the change, not the default triggered by the existence of a pull request. The skills that implement it are publicly available.

The Merge Button Is a Ritual
#

The merge button exists because our tools gave us a button. We built a workflow around it, assigned it meaning, and then treated the meaning as structural.

It is not. The safety of a codebase is produced by the systems around the merge, not by the merge approval itself. The click certifies almost nothing those systems did not already certify. And it imposes an actual cost: latency, batched risk, interrupted focus, concentrated bus factors, and a soft target for anyone who wants to push a change through unnoticed.

The defensible position is not “no humans in the loop”. It is “humans in the loop where they add value, out of the loop where they do not”.

Most pull requests do not need a human to approve them. A small, identifiable minority do. The mistake of the current default is that it treats every change as if it belonged to that minority.

Free the majority to merge on green. Reserve the human gate for the changes where it actually certifies something the machine cannot. And stop pretending the button is what keeps you safe.

The gate was never the safety. The system was.

Rethinking Code Review in the Age of LLMs

tom@tomrochette.com (Tom Rochette) — Fri, 12 Jun 2026 00:00:00 +0000

Code review is a bottleneck. I am no longer convinced it is a useful one.

This is not a conclusion I arrived at lightly. Code review has been one of the most reliable quality gates in software engineering for decades. But the assumption underlying code review, that a human reading code before it ships catches meaningful problems, is worth re-examining when most of that code was written by an LLM.

What Code Review Was Supposed to Do
#

Code review served several purposes simultaneously.

It caught bugs before they reached production. It enforced consistency across a codebase. It spread knowledge between team members. It forced the author to organize their thoughts before presenting them to a peer.

Each of these purposes assumed something important: that the person who wrote the code and the person reviewing it were both human, that the author had thought carefully about each line, and that the reviewer could rely on the author’s intent as context.

When an LLM writes the code, these assumptions break.

The LLM did not think carefully about each line. The LLM does not have intent in the way a human does. The reviewer cannot ask the author “what were you trying to do here?” and get a meaningful answer, because the author is a statistical model that generated the most probable next token.

The loss of a human author changes the nature of the review fundamentally, and not in the direction most people assume.

Why Reviewing LLM Code Is Different
#

When a human writes code, code review is a conversation between two people who share a mental model. The reviewer can trust that the author made deliberate choices, even imperfect ones. Differences between what the reviewer expects and what the code does are informative, because they represent a difference between two human understandings of the same problem.

When an LLM writes code, there is no shared mental model. The code is the output of a pattern-matching process. Sometimes it is correct. Sometimes it is subtly wrong in ways that look correct. Sometimes it is obviously wrong.

The reviewer’s job shifts from “does this match the author’s intent?” to “does this do what I want?” This sounds like the same question, but it is not. The first question allows the reviewer to leverage the author’s reasoning. The second question requires the reviewer to independently verify every assumption the code makes.

This is harder, more tedious, and less effective than reviewing human-written code. The reviewer cannot use the author’s thinking. They are reconstructing it from the beginning, line by line.

The Bottleneck Argument
#

Here is the practical problem.

LLMs can generate code orders of magnitude faster than humans can review it. A developer who used to spend six hours implementing a feature might now spend thirty minutes prompting an LLM and one hour reviewing the output.

The ratio of review time to implementation time has inverted. Where review used to be a small fraction of the development cycle, it is now the dominant fraction.

And the quality of that review is worse, not better, because reviewing code you did not write is cognitively different from reviewing code you understand deeply.

This creates a specific kind of bottleneck: one where the throughput-limiting step is also the lowest-quality step. You are spending most of your time on the part of the process where you add the least value.

What I Would Rather Be Doing
#

If I am going to spend my limited cognitive budget, I want to spend it on the decisions that matter most.

Deciding which problems to solve. Understanding whether a feature should exist at all. Designing the boundary between components. Choosing the right abstraction for the domain. Thinking about how users will actually interact with what we build.

These are high-leverage activities. They determine whether the code that gets written is useful, not just correct.

Reviewing LLM-generated code for style, naming conventions, and obvious bugs is low-leverage work. An automated tool can do it faster and more consistently than I can. A linter does not get tired. An automated test suite does not lose focus after the third function.

The hours I spend reviewing code that an LLM wrote are hours I am not spending on the problems that only a human can solve. That trade-off did not used to exist, because writing code and reviewing code were both human activities and the time allocation was roughly balanced. Now the balance has shifted, and the opportunity cost of review is much higher.

Why Automatic Review and Approval Make Sense
#

I have no objection to automated code review. I have no objection to automated PR approval.

The instinct to involve a human in every change is driven by fear, not by a rational assessment of what the human actually contributes at that point in the process.

Consider what a good code reviewer does today. They check that tests pass. They look for obvious bugs. They verify naming conventions. They ensure the change aligns with the stated goal.

Every one of these checks can be automated. Tests pass or they do not. Static analysis tools catch bugs more reliably than tired humans scanning diffs. Linters enforce style more consistently than any reviewer. Alignment with the stated goal can be checked by having an LLM compare the PR description with the actual changes.

The Wrong Stage to Catch Subtle Issues
#

The remaining argument for human review is that humans catch subtle issues that automated tools miss: architectural problems, subtle security vulnerabilities, misunderstandings of the domain.

These are legitimate concerns, but they are not best addressed at the PR level. They are best addressed at the specification level. If you write a precise specification, automated verification can confirm the implementation matches it. If the specification is vague, no amount of human review will save you from building the wrong thing.

Some would argue that catching these issues during review is better than not catching them at all. This is hard to disagree with in isolation. Of course a subtle bug caught at review is better than the same bug reaching production.

But the better-late-than-never framing conceals the actual trade-off. The question is not whether review catches some problems. It is whether review is the best place to catch them, and whether the time spent reviewing could catch more problems if spent elsewhere.

When you catch an architectural flaw at review time, the code is already written. Fixing it means rework, rebase, re-test, re-review. Catching the same flaw during specification costs a conversation. The later you catch it, the more expensive it is, and code review is one of the latest stages in the pipeline.

More importantly, relying on review to catch subtle issues is unreliable by design. A human reviewer catches what they happen to notice, when they happen to be alert, on the changes they happen to read carefully. Some issues get caught. Many do not. You are depending on luck and attention, not on a system.

The alternative is to build the catching into the system itself. A precise specification catches architectural misunderstandings before code exists. A comprehensive test suite catches behavioral bugs on every run, not just when a reviewer is paying attention. Static analysis catches security patterns deterministically. Each of these catches issues systematically, on every change, forever.

Review catches issues once, for the reviewer who happens to be in front of the diff. A good test catches the same class of issue every time it runs, for as long as the codebase exists. If you find the same kind of subtle issue during review more than once, the answer is not to keep reviewing harder. The answer is to encode that check into your automated gates so it never depends on a human noticing again.

“Catching it late is better than not catching it” is true. It is also an argument for accepting a process that catches too little, too late, at the highest possible cost.

The review should happen before the code is written, not after. Spend the human effort on the spec. Let the machines verify compliance.

The Quality Maximization Myth
#

Some would argue that this misses the point. The goal of code review is not just to check gates, it is to make the code the best it can be. A good reviewer suggests a cleaner abstraction, spots a performance issue the author missed, proposes a name that communicates intent better. Review is quality maximization, not just verification.

This sounds right until you examine what “the best it can be” actually means.

It is subjective. It is unbounded. There is always a cleaner abstraction, a faster algorithm, a better name. The pursuit has no natural stopping point, which is why code reviews so often devolve into bikeshedding over style preferences that do not measurably improve the outcome.

When the code was written by a human, a second perspective genuinely improved the implementation. Two people could find a better approach than one person. But when the code is generated by an LLM, the reviewer is the only human involved, and their suggestions compete with the option of simply regenerating the code against a better specification.

If the code is not good enough, the answer is not to have a human improve it line by line during review. The answer is to improve the specification, the test suite, or the generation prompt, and let the machine produce a better version. That scales. Human suggestions on a diff do not.

The quality of the code is bounded by the quality of the specification that produced it. If you want better code, write a better spec. Reviewing the output is the most expensive, least scalable way to improve it.

The Reallocation
#

Here is what I am proposing.

Instead of spending 30% of development time on code review, spend 5% on automated verification and reallocate the saved hours to specification, problem selection, and domain understanding.

The quality of the software will not decrease. The tests still run. The linters still lint. The static analysis still analyzes. What changes is where the human attention goes.

Right now, human attention is concentrated at the end of the pipeline, reviewing output. It should be concentrated at the beginning of the pipeline, defining what the output should be.

This is not a radical idea. It is the same principle behind test-driven development: define what you want first, then build it. The difference is that now the builder is a machine, and the definition is the only place where human judgment is irreplaceable.

This Is Not Hypothetical
#

None of this is a prediction about the future. I run this approach today.

My development workflow front-loads human effort into specification, requirements, and problem selection. Before any code is written, there is an issue with acceptance criteria, a requirements document, and a technical specification, each reviewed and approved. That is where my judgment gets spent.

Code generation happens against that specification. When a pull request is opened, an automated review pipeline checks it against concrete gates. Does it introduce security-sensitive changes? Does it add new dependencies? Does it change public interfaces? Is the change reversible? Do the tests pass? Does the diff actually satisfy the acceptance criteria from the linked issue?

If all gates pass, the PR is approved automatically. No human reads the diff. No human clicks approve.

When the gates flag something, the PR is held for manual review. This is not the same as reviewing every change. It is reviewing the changes that carry genuine risk, which is a much smaller set.

The distinction matters. I am not advocating for shipping unreviewed code. I am advocating for shipping code that has been verified by systems more reliable than a tired human scanning a diff, and reserving human attention for the small fraction of changes where it actually adds value.

The infrastructure for this exists. The gates are concrete. The approach works because the specification does the work that code review used to do poorly. The skills that implement this workflow are publicly available.

Who Is Responsible
#

The first objection is accountability. If no human reads the code before it ships, who owns the problems it creates?

The answer is that a human reviewing a pull request for ten minutes was never truly responsible for that code. They provided a rubber stamp. They glanced at the diff, checked that the tests passed, and clicked approve. When that code caused an outage six months later, nobody blamed the reviewer. They blamed the author, the test suite, the deployment process, or the requirements.

What about the reviewer who spends thirty minutes, or an hour? They are doing substantive work, not rubber-stamping. The characterization above does not apply to them. They genuinely understand the change, question the design, and catch actual issues.

But the argument against mandatory review does not depend on reviews being shallow. It depends on where that hour of expert attention is best spent.

An hour of review catches issues once, for one change, depending on that reviewer being alert that day. An hour spent improving the specification prevents the entire class of issue from reaching implementation. An hour spent writing a regression test catches the bug on every future run, not just the one time a human happened to read the code.

The thorough review is genuine work. It is just not the highest-leverage work that person could be doing with that hour. And at scale, it is unsustainable: if every PR requires an hour of human review and the LLM produces ten PRs a day, you need ten hours of review to keep up. That is not a process that scales.

Code review creates an illusion of accountability without delivering it. The signature on the PR is a formality.

Responsibility belongs upstream. The person who decided this problem was worth solving owns the outcome. The person who wrote the specification owns whether the implementation matches intent. The person who designed the deployment pipeline owns how quickly a bad change can be contained.

Removing human review does not remove responsibility. It forces you to locate responsibility where it actually belongs: in the decisions that guided the work, not in the person who scanned it at the end.

What About Outages
#

The second objection is safety. What if the LLM makes a decision that takes down production?

This is a genuine risk, but code review is the wrong tool to mitigate it.

Most production outages are not caused by bugs that a reviewer would catch. They are caused by configuration changes, unexpected data formats, load patterns, dependency failures, and integration issues that only surface under actual traffic. A human reading a diff is making a guess about what might happen. Production behavior is the ground truth.

If you want to prevent outages, invest in the systems that observe and contain actual behavior.

Feature flags so a change can be turned off without a redeploy. Canary deployments so a bad change reaches 1% of traffic before it reaches 100%. Monitoring and alerting so a regression is detected in minutes, not hours. Fast, tested rollback paths so recovery does not depend on someone remembering how the old version worked.

These tools are more reliable than code review because they operate on reality rather than prediction. A reviewer might miss a subtle interaction. A canary deployment will surface it.

What About Reversibility
#

A related concern is that an LLM might produce changes that are hard to undo. A sprawling refactor, a database migration that is not backward compatible, a change that entangles two previously independent systems.

This is a serious problem, but again, human review is not the safeguard people think it is.

Reviewers focus on forward correctness. They ask “does this do what it should?” They rarely ask “can we undo this cleanly?” Even when they do, reversibility is hard to assess by reading a diff. It depends on what happens in production after the change is deployed, on data migrations that have already run, on other changes that depend on it.

The solution is to make reversibility a structural property of how changes are made, not a property enforced by review.

Keep changes small and independent. Require database migrations to be backward compatible, deployed before the code that depends on them. Use feature flags so new behavior can be disabled without reverting code. Treat large, entangling refactors as high-risk changes that warrant extra process, not as the default mode of operation.

These are constraints you encode in your pipeline and your specification process. They do not require a human to read every line of every PR. They require discipline at the level where decisions are made.

What About Code Quality and Maintainability
#

A third concern is that without human review, LLM-generated code will degrade into slop. Inconsistent naming, duplicated logic, unnecessary abstractions, dead code, patterns that do not match the rest of the codebase. Each individual change passes its tests, but the codebase slowly degrades.

This is a genuine risk, and it deserves a serious answer. The answer is not that review prevents it. The answer is that review catches it inconsistently, after the fact, one PR at a time.

Most of what we call code quality is measurable. Cyclomatic complexity is a number. Duplication is detectable. Dead code is identifiable by static analysis. Naming conventions are enforceable by linters. File length, function length, import depth, test coverage gaps, all of these are machine-checkable properties.

If you care about maintainability, encode the constraints that produce it. Set complexity limits that fail the build. Run duplication detectors on every PR. Require test coverage above a threshold. Lint aggressively. Block PRs that introduce unused exports or dead code.

These checks run on every change, consistently, without getting tired or distracted. A human reviewer might flag a function that is too complex. A complexity gate will flag every function that exceeds the threshold, every time, for as long as the rule exists.

Slop also has an upstream cause. When the specification is vague about architecture, naming, and patterns, the LLM fills in the missing details with whatever it has seen most often in its training data. That output is generic by default. It will not match your codebase’s conventions unless the specification tells it what those conventions are.

This means slop is prevented at the specification level, not at the review level. A specification that includes the patterns to follow, the existing abstractions to reuse, and the naming conventions to respect produces cleaner code than a vague spec plus a human reviewer cleaning up the output.

For whatever the automated gates miss, frequent maintenance sweeps catch accumulated decay. Run a dead code analysis weekly. Run a duplication detector weekly. Review complexity trends after every merge. This is a more systematic approach than hoping each PR’s reviewer notices the slow accumulation of mess.

Code quality is a property of your constraints, not of your reviewers.

What I Am Not Saying
#

I am not saying all code review should be eliminated tomorrow. Legacy codebases, critical security infrastructure, and domains where correctness is life-or-death may still benefit from human review.

I am not saying code review was never useful. It was, for decades, one of the best tools we had. I am saying the tool’s value has changed because the context has changed.

I am not saying I trust LLMs to always produce correct code. I am saying that human code review is not the best way to ensure correctness when the code was machine-generated. Automated verification, comprehensive test suites, and precise specifications are better tools for that job.

The Question Worth Asking
#

The next time you open a pull request full of LLM-generated code and start reviewing it line by line, ask yourself: what am I actually checking?

If you are checking style, a linter does it better. If you are checking correctness, tests do it better. If you are checking whether the code solves the right problem, you should have answered that question before the code was written.

Code review made sense when humans wrote all the code. It makes less sense when humans define the problem and machines implement the solution. The bottleneck has moved. Our processes should move with it.

Scaling the LLM Agent Company

tom@tomrochette.com (Tom Rochette) — Sun, 31 May 2026 00:00:00 +0000

In Exponential growth software company I explored the constraints that make scaling a human company hard: onboarding bottlenecks, culture dilution, coordination overhead, institutional knowledge decay. Each of these constraints grows with the number of people you employ. A company where the workforce is entirely composed of LLM agents inverts most of these problems. The old constraints disappear, but new ones replace them.

What Disappears
#

Onboarding becomes instantiation. An LLM agent starts productive the moment it is created. There is no training period, no ramp-up, no senior employee pausing their work to bring a new hire up to speed. Spawning 100 agents costs roughly the same operational effort as spawning 1. The ratio of onboarded to onboarders that mattered for human companies becomes irrelevant.

Culture is exactly what you specify. Agents follow their instructions. If you want 1,000 agents to behave identically, you give them the same system prompt. There is no culture clash, no informal norms developing in opposition to the official ones, no gradual drift as new hires bring outside habits. The culture is the prompt.

Coordination scales differently. Agents do not have cognitive limits on the number of peers they interact with. A single orchestration agent can coordinate with hundreds of worker agents without getting overwhelmed. Communication between agents is structured, lossless, and near-instantaneous. The team structures, single points of contact, and redundancy tradeoffs that human organizations require are replaced by protocol design.

Institutional knowledge does not decay. Everything an agent knows is explicit in its instructions, tools, and retrieved context. There is no tacit knowledge that exists only in someone’s memory, no risk of losing the person who understands the legacy system. When you replace an agent, the replacement has access to exactly the same information.

What Replaces It
#

The fundamental principle from the original article still holds: anything that scales linearly or superlinearly with itself needs to be optimized to grow sublinearly. The bottleneck has moved, but it has not disappeared.

Unit economics
#

Each agent invocation costs compute and API calls. At scale, the marginal cost of an additional agent is small but not zero. If your revenue per task is lower than the cost of the compute required to complete it, you have the same fundamental problem as an unprofitable human company. A human company that loses money on every employee-hour goes bankrupt. An agent company that loses money on every inference call goes bankrupt just as fast, it just happens in milliseconds instead of months.

Correlated failures
#

With humans, errors are diverse and partially cancel out through independent judgment. Two engineers given the same task will produce different bugs. With agents sharing the same prompt, errors are correlated and systemic. A single flawed instruction propagated across 1,000 agents produces 1,000 instances of the same mistake at scale. Consistently wrong is worse than inconsistently right. Correlated errors make quality control the central bottleneck. You need evaluation pipelines, guardrails, and feedback loops that themselves must scale. The testing infrastructure becomes the company’s most critical asset, more important than the agents it tests.

Orchestration complexity
#

While individual agents do not get overwhelmed, the system as a whole can still produce emergent failures. Agents acting on stale information, conflicting instructions, or subtle misinterpretations of their goals can cascade into problems that are hard to diagnose because the system operates at a speed and scale humans cannot directly oversee. The orchestration layer is the new management layer. Its complexity grows with the number of agents and the richness of their interactions. Unlike human management, where adding managers adds judgment and adaptability, adding orchestration logic adds rigidity. Every new rule is a new potential point of failure.

Infrastructure brittleness
#

A human can work around a broken tool with creativity. An agent generally cannot. If an API goes down, every agent depending on it stalls. If a database schema changes unexpectedly, every agent writing to it produces corrupted data. The brittleness of automated systems means that reliability engineering and observability become more important, not less, as you scale. The company that cannot detect a degrading agent within seconds will compound the damage across its entire workforce simultaneously.

Model dependency
#

Your company’s capacity is bounded by what the underlying models can do. If the model provider changes behavior, degrades performance, or raises prices, your entire workforce is affected at the same time. This is a vendor dependency unlike any single human employee leaving. It is more like all your employees depending on the same external model that a third party operates. Diversifying across models is a partial hedge, but it introduces the same coordination complexity as a multilingual workforce.

Where the Moat Lives
#

When anyone can spawn an equally capable agent workforce, the advantage is no longer in having employees. The moat shifts to the quality of your instructions (prompts as institutional knowledge), the design of your orchestration (workflows as management), your data flywheels (evaluation data as competitive advantage), and domain-specific tools and integrations (proprietary capabilities the agents use). The company is no longer its people. It is its prompts, its pipelines, and its proprietary context.

The Pattern
#

The original article concluded that human scaling requires optimizing every linear cost down to sublinear. The same conclusion applies here, but the costs are different. Human companies optimize hiring, onboarding, and culture. Agent companies optimize inference cost, error correlation, orchestration complexity, and infrastructure reliability. The companies that scale exponentially in this era will be the ones that treat their agent workforce as a system to be engineered, not a team to be managed.

References
#

Exponential growth software company – original article on human company scaling constraints
The Shifting Bottleneck – how AI moves bottlenecks up the decision chain
Software Engineering Teams in the Age of AI – team design implications of AI-assisted development

ghx - A CLI for agentic code reviews on GitHub

tom@tomrochette.com (Tom Rochette) — Wed, 27 May 2026 00:00:00 +0000

I’ve been building AI agents that review pull requests, and the official gh CLI doesn’t have what they need. Agents can’t leave inline comments on specific lines, can’t manage pending reviews, and can’t edit or delete comments. These are basic operations for any code review workflow, and they’re only accessible through the GitHub web UI or the raw GraphQL API.

So I built ghx, a CLI designed to make agentic code reviews practical.

What ghx does that gh doesn’t
#

Inline comments on files and lines. The most fundamental operation for a code review agent: comment on a specific line of a diff.

$ ghx pr comment 42 --file src/main.go --line 10 --body "Nit: use fmt.Errorf"
Created inline comment on src/main.go:10 (thread PRRT_kwDOC0I7As5vKgVn)

$ ghx pr comment 42 --file src/main.go --line 10-15 --body "Consider extracting this"
Created inline comment on src/main.go:10-15 (thread PRRT_kwDOC0I7As5vKgVq)

File-level comments (without --line), top-level PR comments, and replies to existing threads are all supported.

Pending reviews. Accumulate review comments without submitting them immediately, then approve or comment when ready:

$ ghx pr comment 42 --file src/main.go --line 10 --body "Nit" --pending
Added pending inline comment on src/main.go:10 (thread PRRT_kwDOC0I7As5vKgVz, review PRR_kwDOC0I7As4B9Y2z)

$ ghx pr review submit 42 --event APPROVE --body "LGTM"
Submitted review PRR_kwDOC0I7As4B9Y2z as APPROVE

Edit and delete comments. Fix a typo or remove a comment. Use ghx pr threads 42 --ids to list IDs:

$ ghx pr threads 42 --ids
PRRT_kwDOC0I7As5vKgVn  src/main.go:10  [open]
  PRC_kwDOC0I7As5TKxYc  reviewer  Nit: use fmt.Errorf

  PRC_kwDOC0I7As5TKxYd  author  Good catch, will fix.

Then edit or delete the comment:

$ ghx pr comment edit PRC_kwDOC0I7As5TKxYc --body "Use fmt.Errorf instead of errors.New"
Updated comment PRC_kwDOC0I7As5TKxYc

$ ghx pr comment delete PRC_kwDOC0I7As5TKxYc
Deleted comment PRC_kwDOC0I7As5TKxYc

Review thread management. List, filter, and inspect review threads:

$ ghx pr threads 42
src/main.go:10  [open]
  reviewer  Nit: use fmt.Errorf
  author    Good catch, will fix.

src/main.go:45-52  [resolved]
  reviewer  Consider extracting this into a helper
  author    Done in 3a1b2c4

Filter by state with --state open, --state resolved, or --state all.

Issue comments and viewing. Add, edit, and delete issue comments, and view issues with their full comment history:

$ ghx issue view 42
Fix race condition in worker pool  [open]  author

The worker pool has a race condition when multiple goroutines access
the shared counter without proper synchronization.

2 comment(s):

  contributor  I can reproduce this with `go test -race ./...`
  author       Fixed in #50

$ ghx issue comment 42 --body "This is fixed in #50"
Created comment IC_kwDOC0I7As5TKxZa on issue #42

The stash system
#

ghx has a local stash system for review comments, modeled after git stash.

The main use case is enabling agents to batch many comments at once before submitting them all as a single review. Instead of making individual API calls per comment, an agent can stash comments locally and pop them into a pending review in one operation:

$ ghx pr comment 42 --file src/main.go --line 10 --body "Nit" --stash
Stashed comment on src/main.go:10 (stash@{0} now has 1 threads)

$ ghx pr comment 42 --file src/main.go --line 20-25 --body "Extract this" --stash
Stashed comment on src/main.go:20-25 (stash@{0} now has 2 threads)

$ ghx pr review stash list 42
stash@{0}:  2 threads, 2 comments
  src/main.go   10      1 comment(s)
  src/main.go   20-25   1 comment(s)

$ ghx pr review stash pop 42
Popped stash@{0} (2 threads, 2 comments) into review PRR_kwDOC0I7As4B9Y2z

The stash also solves a GitHub API constraint: you can’t mix immediate comments with pending review comments on the same PR. When you submit an immediate comment on a PR that has a pending review, ghx automatically stashes the pending review, submits the comment, and restores the pending review. The stash lets agents use a push-pop workflow (stash, comment, comment, pop) instead of repeating push-comment-pop for every immediate comment.

The stash supports multiple entries, just like git stash: push, pop, drop, and list.

Getting started
#

ghx is a single Go binary. Download the latest release from GitHub, or install with Go:

go install github.com/tomzxcode/ghx@main

ghx picks up your existing GH_TOKEN, GITHUB_TOKEN, or gh auth login credentials. No extra configuration needed. All commands accept --repo OWNER/REPO or auto-detect from the current git remote.

ghx is MIT-licensed and written in Go with no runtime dependencies beyond the GitHub API.

The Backlog Is Not a Dumping Ground: Managing the Backlog of a Large Software Product

tom@tomrochette.com (Tom Rochette) — Sun, 24 May 2026 00:00:00 +0000

A well-managed backlog is the single most useful artifact in product development. When it works, teams ship the right things at a sustainable pace. When it doesn’t, the organization accumulates stale tickets, conflicting priorities, and endless planning meetings. For large software products, where dozens of teams feed from the same corpus of work, the cost of poor backlog hygiene is enormous and mostly invisible.

The Backlog at Scale Behaves Differently
#

On a small team, the backlog is a conversation. The product owner and a handful of engineers look at a list, discuss what matters most, and pick up work. At scale, the backlog becomes an information system. It mediates between strategy and execution, between stakeholders who want things and teams who build things, and between the present state of the product and its future state.

The Scrum Guide defines the product backlog as “an emergent, ordered list of what is needed to improve the product” and notes that it is the single source of work for the team. That definition is clean and useful, but in practice, large organizations layer in program backlogs, initiative backlogs, discovery backlogs, and technical debt backlogs. The first challenge is deciding what structure you need and resisting the urge to create a new list every time someone feels their priorities aren’t getting enough visibility.

Marty Cagan, “Inspired” argues that the strongest product teams maintain a clear distinction between product discovery (figuring out what to build) and product delivery (building it), and that conflating the two is a root cause of bloated backlogs. Items enter the backlog before anyone has validated that they are worth building. The backlog becomes a list of desires rather than a commitment queue.

Four Principles That Change Everything
#

Most backlog problems come from violating one of four principles.

1. The Backlog Is Ordered, Not Merely Prioritized
#

“Prioritized” suggests labels like “high,” “medium,” and “low.” Those labels are nearly useless because everything ends up “high.” Ordered means the backlog is a ranked list: item 1 is more important than item 2, which is more important than item 3. A strict ordering is harder to produce, and that difficulty is deliberate. Forcing a strict ordering surfaces the trade-offs that stakeholders would otherwise avoid.

Woody Zuill’s approach of “pulling” work rather than “pushing” it is relevant here. When the backlog is strictly ordered, teams pull from the top. No selecting favored items, no lobbying for a personal favorite feature. The rank order is the contract.

At scale, this principle applies at every level. Initiatives within a program are ordered. Epics within an initiative are ordered. Stories within a sprint are ordered. If you cannot say which of two items matters more, you are not ready to put both in the backlog.

2. Only Refined Items Belong in the Delivery Backlog
#

Jeff Patton’s user story mapping technique provides a framework for separating discovery from delivery. The “backbone” of user activities and the stories beneath them form a map of the product’s possible future. Only stories that have been discussed, estimated, and accepted by the team belong in the sprint-level delivery backlog. Everything else lives in a discovery or discovery-adjacent artifact.

Separating discovery from delivery is a critical structural choice. Many organizations dump every idea, bug report, customer request, and technical improvement into the same GitHub project. Within months, that project contains thousands of items in no particular order. The team treats it as a write-only data structure.

A practical pattern: maintain two lists. The product backlog contains everything the team might ever work on, loosely grouped by theme. The sprint backlog (or “ready” queue) contains only items that meet a definition of ready: they have acceptance criteria, they are small enough to complete in a single sprint, and the team has discussed them. Nothing moves from the product backlog to the sprint backlog without passing through a refinement session.

The Scrum Guide calls this ongoing activity “backlog refinement,” and regular sessions where the team reviews the top portion of the backlog, splits large items, and ensures alignment with the product goal are essential. The key discipline is not the meeting itself but the agreement that unrefined items will not be scheduled.

3. Prioritization Frameworks Are a Means, Not an End
#

Several frameworks exist to help teams rank backlog items:

Framework	Mechanism	Best suited for
RICE (Reach, Impact, Confidence, Effort)	Numerical score combining reach, impact, confidence, and effort	Product teams comparing features across different domains
WSJF (Weighted Shortest Job First)	Cost of delay divided by job size	Organizations using SAFe or managing program-level backlogs
Opportunity Scoring	Measures importance and satisfaction for each outcome	Discovery-phase prioritization when outcomes are unclear
ICE (Impact, Confidence, Ease)	Lightweight scoring for rapid triage	Fast-moving teams that need quick decisions

These frameworks are useful because they make the prioritization criteria explicit. They are dangerous when teams treat the resulting score as the final answer. A RICE score is only as good as the estimates that feed it, and those estimates are often wrong.

The right approach is to pick one framework that matches your organization’s needs, use it consistently, and revisit the scoring regularly. The conversation that happens when two stakeholders disagree about a score is where the value lives. The number itself is a forcing function, not a decision.

4. Say No Early and Often
#

The most important word in backlog management is “no.” Every item in the backlog carries a cognitive tax. Engineers scroll past it in planning. Product managers feel obligated to explain why it hasn’t been done. Stakeholders check on it periodically. The larger the backlog, the more time the team spends managing the backlog instead of working from it.

Derek Sivers’ “hell yeah or no” heuristic applies here. If an item does not clearly advance the product’s current goals, decline it, archive it, or move it to a separate “someday” list that nobody is expected to maintain. A product backlog with 30 well-ordered items is more useful than one with 300 loosely grouped items.

At scale, this principle requires organizational courage. Every stakeholder believes their request is important. The product manager’s job is to say no to the things that are less important than the current top priority, even when that is uncomfortable. Cagan frames this as the difference between product teams (who are empowered to solve problems) and feature teams (who are handed a list to implement). Empowered teams can say no because they understand the problem they are solving and can judge whether a given request advances the product’s goals.

Structural Patterns for Large Products
#

When a product involves multiple teams, shared infrastructure, and cross-cutting concerns, the backlog structure needs to accommodate complexity without collapsing under it.

The Tiered Backlog
#

Large products benefit from a tiered backlog structure:

Strategic tier: Outcomes, OKRs, or product goals for the quarter. Owned by leadership and product management. Updated quarterly.
Initiative tier: Named efforts that advance a strategic outcome. Owned by product managers. Updated monthly.
Delivery tier: Epics and stories that decompose an initiative. Owned by individual teams. Updated continuously.

Each tier feeds the one below it. The strategic tier determines which initiatives enter the initiative tier. The initiative tier determines which epics and stories appear in the delivery tier. Information flows up through demos, retrospectives, and metrics.

The critical rule: no item in a lower tier can exist without a parent in the tier above it. Orphaned work is the primary source of backlog bloat. If someone wants to add a story that doesn’t map to an active initiative, the answer is either to create an initiative (which triggers the prioritization process) or to decline the story.

The Obeya Room Pattern
#

Borrowed from lean manufacturing and popularized by Toyota, the Obeya (“big room”) is a physical or virtual space where cross-functional representatives meet regularly to review the state of the product. The backlog is visualized on the wall (or in a shared tool), and the group discusses priorities, blockers, and dependencies as they happen.

For large products, the Obeya pattern addresses a problem that no tool solves: alignment. When eight teams are pulling from the same backlog, local optimization is the default. Each team optimizes for its own velocity and its own priorities. The Obeya creates a forum where global optimization can happen.

The Regular Grooming Rhythm
#

A weekly or biweekly refinement session where the product manager and the team review the top 10-15 items in the backlog is a widely recommended practice. The goal is not to estimate everything but to ensure that the next two to three sprints’ worth of work is well understood.

For large products, this rhythm needs to exist at every tier. Leadership reviews the strategic tier quarterly. Product managers review the initiative tier monthly. Teams refine the delivery tier weekly. The cadence prevents the backlog from becoming stale and ensures that the most important items are always the most visible.

Common Failure Modes
#

The infinite backlog. A backlog that never shrinks is not a backlog; it is a suggestion box. If the backlog has more than a few hundred items, most of them are irrelevant. Archive aggressively.

The stakeholder lobby. In large organizations, stakeholders learn to mark everything as “critical” or to escalate items directly to engineering managers. The ordered backlog is the defense against the stakeholder lobby. If the item is not in the top of the ranked list, it does not get worked on, regardless of who asked for it.

The technical debt blind spot. Product backlogs tend to favor features because features have visible stakeholders. Technical debt has no natural advocate. The solution is to allocate a fixed percentage of capacity (often 20-30%) to technical improvement and to make that allocation explicit in the backlog.

Pointless early estimation. Spending hours estimating items that are months away from being worked on is waste. Estimate just enough to support prioritization, and re-estimate when the item moves into the delivery backlog. Ron Jeffries, “Story Points Revisited” argues, as one of the originators of story points, that estimation should support planning, not become a goal in itself.

Conflating bugs and features. A bug is a commitment to fix something that was promised. A feature is a new investment. Mixing bugs and features in the same backlog without distinguishing between them leads to either under-investment in new value (because bugs always seem urgent) or neglect of quality (because features always seem more strategic). Separate them, fund them differently, and track them separately.

What to Do Next
#

If your backlog is currently a mess, here is a sequence that works:

Archive everything older than six months that has not been touched. If it mattered, someone would have advocated for it. You can always pull items out of the archive.
Identify the current product goal. If you cannot state it in one sentence, you are not ready to prioritize the backlog.
Map every remaining item to the goal. Items that don’t map go to a separate “someday” list.
Force-rank the top 20 items. No ties. This exercise will reveal every disagreement about priorities, which is exactly what you need.
Refine the top 5-10 items until they meet your definition of ready. Only these items are eligible for the next sprint.
Set a weekly refinement cadence and protect it. The backlog becomes stale without maintenance.

A healthy backlog is small, ordered, and refined. It reflects a clear product goal and a shared understanding of what matters most. Maintaining the backlog is not glamorous work, but it is the work that makes everything else possible.

What I've built and what I need: May 2026

tom@tomrochette.com (Tom Rochette) — Sun, 24 May 2026 00:00:00 +0000

The past month has been about turning repetitive workflows into reusable skills, and the gaps that remain are mostly about making those skills smarter, not more numerous.

What I Have Been Working On
#

Built a full SDLC skill pipeline. I shipped a comprehensive software development lifecycle orchestrator in agents that chains over 20 sub-skills, from issue creation through learnings capture. It handles phase contracts, backtracking when upstream artifacts are incomplete, and fast paths for small work like bug fixes and config changes. The pipeline tracks artifact status via YAML frontmatter and stores everything under .sdlc/ with a consistent directory structure.

Made issue tracking actually useful. I have been using create-issue heavily over the past month to track gaps in the software I am building. It is not perfect, but it is better than not tracking the work, and it captures more context than I would take the time to write by hand.

Automated PR descriptions. I use create-pr-description to generate PR descriptions based on code changes and intent. Writing those manually was slow and inconsistent; now the descriptions reflect what changed without the manual effort.

What I Currently Need
#

Test the SDLC pipeline on real work. The SDLC skill is built but has not been stress-tested end to end on real feature work. I need to run it through enough varied scenarios to surface the gaps between the design and practical use.

Scheduled issue-to-PR automation in openchamber. Openchamber can already create a worktree per directory and execute a prompt, but it does not run on a regular schedule. I need it to pick up new issues, execute the full pipeline, and open PRs without manual triggering.

Automated issue triaging in open source projects. I built a triage-issues skill but have not used it on my own repositories. The goal is to reduce the burden of going through issues to identify duplicates and decide whether they should be acted on.

Memory that agents manage automatically. Right now memory requires explicit reads and writes. I need agents to store, retrieve, and decay knowledge across sessions without me prompting them to do it.

Contextual Slack support. I need a way for users asking for help on Slack to receive contextually relevant information, and for the system to learn from human-to-human interactions and the answers people give each other. I started building slack-cached to cache and query Slack conversations.

Automatic context clearing between execution and review. Running implementation and review in the same context introduces bias. I need a mechanism, likely using forked subagents, to /clear between execution and review automatically so the reviewer starts fresh.

Accuracy pass on daily summaries. I have accumulated daily summaries that contain inaccuracies. I need something to go through them and correct what is wrong, rather than letting bad data compound over time.

Incremental PR description updates. When I update a PR after the description is written, I need create-pr-description to adjust minimally, appending or amending what changed, rather than regenerating the whole thing from scratch.

Skill usage tracking. I need to know how often each skill is invoked and when. Without that data, I cannot tell which skills are worth keeping and which I never use.

Replying to inline PR comments. gh does not support replying to inline review comments programmatically. Tools like gh-pr-review exist but feel awkward for what should be a straightforward operation. I need a clean way to post inline replies as part of the review and feedback skills. I started building ghx to address this gap.

Software Engineering Teams in the Age of AI: Smaller, Sharper, Intentionally Imperfect

tom@tomrochette.com (Tom Rochette) — Mon, 18 May 2026 00:00:00 +0000

LLM-powered coding assistants have changed what an individual engineer can produce in a day. The harder question is what this means for how teams should be organized, how they should work together, and which of their existing processes are still worth keeping. My answer is counterintuitive: the teams that thrive will not be the ones that adopt AI fastest or eliminate the most process. They will be the ones that correctly distinguish between friction that wastes time and friction that prevents mistakes.

What Actually Changed
#

AI-assisted development compresses the time from idea to working code. An engineer with a capable LLM can prototype a feature in hours that used to take days. Boilerplate, tests, documentation scaffolding, and CRUD endpoints all cost less and less time.

But the things that remain expensive have not changed at all. Deciding whether to build a feature, choosing the right abstraction, understanding the domain deeply, and aligning technical work with business goals are as hard as they ever were. In many ways the expensive parts are harder now, because the temptation to just generate and ship without deciding is stronger.

This creates a specific tension for teams. When individuals can produce more code, the bottleneck shifts from production to coordination and judgment. Team design has to account for this shift, not ignore it.

Team Size: Follow the Problem Boundary
#

There is a persistent urge to declare an ideal team size. Amazon popularized the “two-pizza team” rule. Agile methodology settled on 3 to 9. Various management frameworks have their own magic numbers.

AI does not provide a new magic number, but it does shift the trade-off toward smaller teams.

Here is why. Communication overhead scales quadratically with team size. A team of 4 has 6 communication channels. A team of 8 has 28. When each individual ships faster because of AI assistance, the team reaches its coordination limit sooner. The output added by the fifth or sixth engineer stops covering the cost of keeping everyone aligned.

Smaller teams also benefit from clearer ownership. When three people own a service, it is clear who is responsible for it. When ten people own a service, everyone assumes someone else is handling the monitoring, the tests, the deployment pipeline.

But smaller is not always better, and this is where the nuance matters.

A team that is too small for its domain will fragment its attention across too many concerns. Three engineers trying to own a payments system, a notification platform, and a data pipeline will do none of them well. They will produce code quickly with AI assistance, but they will produce the wrong code, in the wrong abstractions, because no one has the time to think deeply about any one domain.

The rule I would use is not a fixed number. It is the smallest team that can own a coherent domain end-to-end. In practice this often lands between 3 and 5 people, but the number should follow the problem boundary, not the other way around.

A team of 3 that owns a single well-bounded service is better than a team of 8 that owns six loosely related ones. But a team of 6 that owns a tightly integrated platform is better than splitting that platform across two teams of 3 that now have to coordinate across a boundary that should not exist.

Friction: Some of It Is Structural
#

The instinct when a new efficiency tool arrives is to use it to remove every source of friction. AI makes code review faster, so why not automate it? AI can summarize meetings, so why not eliminate them? AI can write documentation, so why not stop requiring it?

This instinct is partially right. A lot of process friction is pure waste. Waiting three days for a manager to approve a deployment that could be automated. Holding a 30-minute standup where eleven people say “yesterday I worked on tickets, today I will work on tickets.” Filing a Jira ticket for a one-line config change.

But some friction serves a purpose, and removing that friction silently degrades the team’s output quality over time.

Code review is the clearest example. Before AI, code review served multiple functions: catching bugs, enforcing style, sharing knowledge, and forcing the author to think about their code one more time before it shipped. AI can handle the style and formatting portion completely. It can catch obvious bugs. What AI cannot do is evaluate whether the code solves the right problem, whether the abstraction will survive the next feature request, or whether the approach is consistent with how the rest of the system works.

In fact, code review becomes more important with AI-generated code, not less. When a human writes every line, you can assume the author thought about each line at some level, even if imperfectly. When an LLM generates code, the author may not have read every line carefully. The reviewer can no longer rely on the author’s intent as a safety check. The reviewer has to verify both correctness and intent independently.

This is harder work than traditional code review. It means reviews should be slower, not faster. The process should have more friction, not less. What should change is what the friction is applied to: less time on style, more time on substance.

The same principle applies to other forms of deliberation.

Sprint planning, done well, is the moment when the team asks “are we working on the right things?” That is productive friction. Sprint planning, done poorly, is an hour of reading ticket descriptions aloud. That is waste.

Architecture discussions are productive friction when they prevent the team from building on a flawed foundation. Architecture discussions are waste when they become philosophical debates that never converge on a decision.

The discipline is in telling the difference. The test I use: does a given process force someone to think about something they would otherwise skip? If yes, keep the process, even if it feels slow. If no, automate the process or remove it.

Processes Worth Keeping
#

Beyond code review, a few processes become more valuable in an AI-accelerated environment.

Architecture decision records (ADRs). When code is cheap to produce, the cost of building on the wrong abstraction is disproportionately high. A one-page document that captures what was decided, why, and what alternatives were considered is worth more than the five minutes it takes to write. AI can draft these from a conversation, but the team still needs to have the conversation.

Incident retrospectives. Retrospectives are one of the few processes that compound knowledge over time. When a production incident occurs, the team that writes down what happened, why, and what the team will change makes fewer repeat mistakes over time. The team that fixes the bug and moves on repeats the same class of mistake forever. AI can assist with drafting the timeline from logs and alerts, but the insight about what to change has to come from the people who were in the room.

Onboarding. Onboarding is paradoxically harder in AI-heavy teams. Historically, junior engineers built deep familiarity with a codebase by writing code in it, working through its conventions, and learning its quirks through repetition. When AI handles much of the writing, that repeated work disappears, and with it, the learning. Teams need to be more intentional about how they transfer knowledge. Structured pairing, documented design decisions, and explicit mentorship become more important, not less.

Specification before implementation. The ability to write a clear specification is now the highest-leverage skill in software engineering. A precise spec turns an LLM from a mediocre pair programmer into a highly effective one. A vague spec makes the LLM hallucinate. Teams that invest in specification quality will produce more than teams that skip straight to prompting.

Processes Worth Eliminating
#

Some processes continue only out of habit. AI gives teams a reason to rethink them.

Status meetings that are not decisions. If a standup is just a round-robin of activity reports, replace the standup with an AI-generated summary of yesterday’s commits, PRs, and tickets. Reserve synchronous time for discussions that require back-and-forth. Most status updates do not require back-and-forth.

Granular task estimation. When AI can generate implementation drafts, estimating individual tasks in story points becomes less accurate and less useful. The time spent decomposing work into one-point, two-point, and three-point tickets is time not spent on the actual work. Replace granular estimation with outcome-level planning: what do we want to ship this cycle, and are we on track?

Manual test writing for boilerplate. AI handles test scaffolding well. Engineers should focus on test design (what cases matter, what edge cases exist, what invariants must hold) and let the tooling handle the mechanical work of writing assertions and setup code. The test plan is the valuable artifact. The test file is increasingly interchangeable.

Elaborate approval workflows. If a change passes CI, passes automated security scanning, and passes peer review, the change should not also need approval from a manager who has not read the code. Every gate that does not add information is pure delay.

The Structure of a Team That Gets This Right
#

Here is the team I would design for this era.

Four or five people who own a clear domain. They spend less time writing boilerplate and more time debating trade-offs. Their code reviews are rigorous about intent and brief about style. They write ADRs for non-obvious decisions and skip ADRs for obvious ones. They do not hold meetings that could be a paragraph of text. They write specifications before they prompt.

They treat AI as a way to apply more judgment, not a replacement for it. The judgment is still the team’s job. The tooling just makes acting on that judgment faster.

What Does Not Change
#

For all the shifts, some things do not change.

Trust between team members cannot be generated by a language model. Psychological safety, the ability to say “I think this approach is wrong” without fear, remains the single strongest predictor of team performance. A team of average engineers who trust each other will outperform a team of brilliant engineers who do not trust each other, with or without AI assistance.

Shared understanding of the problem domain cannot be delegated to tooling. If no one on the team deeply understands the business context, the code will be technically correct and strategically wrong, faster than ever.

And the discipline to build less, not more, remains the hardest skill. When implementation costs almost nothing in time, the temptation to overbuild is constant. The teams that thrive will be the ones where someone at the table says “we don’t need this,” and the rest of the team listens.

The case for static priorities

tom@tomrochette.com (Tom Rochette) — Mon, 18 May 2026 00:00:00 +0000

Most teams that adopt a P0-P5 priority scale make the same mistake: they treat priority as a ranking, not a classification. The moment all P0s are resolved, someone suggests “promoting” P1s to P0. This feels logical. It is wrong, and in this article I want to defend the alternative: a static system where a priority label describes the work itself and never moves just because the queue in front of the work emptied.

Priority is a property of the work, not its position in the queue
#

P0 means something specific: the production database is corrupted, customers cannot check out, a security vulnerability is being actively exploited. P0 work has an operational definition. The label describes the nature and consequence of the task.

A P1 task is important work that should be done this quarter: a feature the largest customer has been requesting, a refactor that will unblock two teams, a performance optimization that will cut infrastructure costs by 30%. Completing the P0s does not transform a P1 into an existential crisis. The task has not changed. The task’s urgency has not changed. Calling the task P0 adds no information and removes the ability to distinguish the task from actual emergencies.

If everything becomes P0, nothing is P0
#

Priority inflation is the fastest way to destroy a prioritization system. Once a team learns that P0 simply means “next thing we’re working on,” the label stops meaning anything. When a genuine P0 arrives, such as a corrupted production database, the team needs everyone to drop what they are doing, but the word no longer signals urgency because promotion has weakened the word.

Consider what happens when you tell a team “this is P0” in a healthy system: people stop what they are doing, context-switch, and focus on the emergency. That response depends on P0 being rare and meaningfully different from everything else. If the backlog contains forty items that were “promoted” to P0, the next genuine emergency gets the same response as a feature request.

A static system is a shared vocabulary
#

The value of a priority scale is communication. When an engineer files a bug as P1, a product manager should immediately understand the rough timeframe and severity without reading the full description. When a support rep escalates a ticket to P0, the on-call engineer should know to wake up.

This shared understanding requires stable definitions. If P0 means “site is down” on Monday but “most important remaining backlog item” on Wednesday, the label communicates nothing about the work itself, only about where the work sits relative to other work. That is what a sorted list already tells you. The priority label should add something a list cannot: the kind of impact the task has.

Why not use importance × urgency?
#

The Eisenhower Matrix (important/urgent, important/not urgent, not important/urgent, not important/not urgent) is the most common alternative to a priority scale. The matrix is appealing because the matrix is simple: two dimensions, four quadrants, done. But the matrix breaks down in practice for several reasons.

Everything a team is asked to do is important. If a task were truly unimportant, the task would not be in the backlog. As a result, most tasks cluster in the “important” row, and the entire burden of differentiation falls on the urgency axis. The matrix has effectively collapsed back to a single dimension, but with less granularity than P0-P5.

Four buckets are too coarse. Within “important and not urgent” sits everything from “refactor the authentication system this quarter” to “update the README someday.” The quadrant gives you no way to distinguish these. P0-P5 gives you six levels, each with an attached timeframe and commitment level. The matrix tells you “schedule it.” The priority scale tells you “schedule it this quarter.”

Urgency is ambiguous at the boundaries. Is a customer feature request urgent because the customer is asking today, or not urgent because there is no deadline? Is a tech debt refactor urgent because the refactor slows down every sprint, or not urgent because nothing is currently broken? These edge cases generate the same kind of debate that multi-dimensional systems create, but the matrix offers only two positions: urgent or not. P0-P5 lets you express degrees of time sensitivity without a separate axis.

The matrix is a decision framework, not a communication protocol. “Important and urgent” describes a reasoning process. P0 describes a shared organizational response: drop everything, wake people up, ship a fix today. The priority label carries both classification and implied action. The matrix carries only classification, leaving the action unspecified.

The Eisenhower Matrix is a good tool for personal time management. For team-scale prioritization of a shared backlog, a single priority scale with pre-agreed definitions communicates faster and differentiates better.

Why not decompose into impact, urgency, and risk?
#

A related objection: instead of a single P0-P5 label, why not rate each task on multiple dimensions? If each dimension only has two or three values, assessment is quick.

Assessment is indeed quick. The problem is the decision rule. Once you have impact × urgency × risk, you need a policy for how the dimensions combine. Does high impact + medium urgency + low risk come before medium impact + high urgency + low risk? Every disagreement becomes a debate about weights instead of a quick “this is P1” call.

The P0-P5 scale is that policy, decided in advance. Someone already decided the mapping. The team classifies and moves on.

That said, if a team consistently disagrees on priority labels, the disagreement itself is useful. The disagreement surfaces the underlying dimensions naturally. The debate about impact, urgency, and risk is the conversation you have when the single label fails, not the default workflow. A single priority label is the fast path. Decomposed dimensions are the escalation path.

Working on P1s does not require calling them P0
#

Here is the practical concern: after the P0s are done, what should the team work on? P1s, obviously. Nothing needs to be renamed to start working on the P1s.

A static priority system separates two decisions:

What is this task? (classification: P0 through P5)
What should we work on next? (scheduling: pick the highest-priority task that is unblocked and aligned with current goals)

Dynamic systems conflate the two decisions. By making priority a function of backlog state, a dynamic system loses the ability to classify independently of schedule. A task’s priority no longer tells you what kind of work the task represents. The label only records where the task ranked at the moment of labeling.

Re-labeling has a cost
#

Every time items are promoted after higher-priority work completes, the team pays a coordination cost. Someone has to decide which P1s become P0s. That decision requires a meeting, or at least a Slack thread, or a product manager’s judgment call. The larger the team, the more expensive the relabeling becomes.

In a static system, this cost is zero. The team finishes the P0s, picks up the next highest-priority task, and keeps building. No ceremony, no relabeling, no debate about whether a P1 has “earned” its promotion.

Static priorities enable proportional allocation
#

Healthy teams do not just work on the highest-priority item. These teams allocate capacity across priority levels: 10% on P0 (emergencies, when they arise), 60% on P1 (core roadmap), 20% on P2 (improvements), 10% on P3-P5 (maintenance, tech debt, experiments).

This kind of planning is only possible with stable definitions. If P1s keep becoming P0s, the team cannot reason about where the team’s time is going. Velocity metrics become meaningless because the definition of each bucket shifts under the team.

Truthful labeling forces truthful conversations
#

A static system forces the team to be realistic about what the team is not doing.

In a dynamic system, everything important eventually becomes P0, so nothing is ever explicitly deprioritized. A stakeholder asks “when will you do X?” and the answer is “it’s P1, we’ll get to it after the current P0s.” The answer is accurate but uncomfortable. The discomfort is the point.

When a P2 feature stays P2 for three quarters, the organization has a clear signal: this work is not important enough to displace P1 work. That signal triggers a useful conversation: should we increase staffing, should we drop the feature, or should we accept that the feature will not happen soon?

In a dynamic system, the same feature would have been promoted to P1, then P0, and done without anyone confronting the question of whether the feature was worth doing at all.

When priorities should change
#

A static system does not mean priorities are frozen forever. Priorities should change when the task itself changes, not when the backlog above the task empties.

A P2 performance issue becomes P1 when a major customer threatens to churn over the issue. The task’s context changed. A P3 experiment becomes P1 when early results show the experiment could replace a critical dependency. New information arrived. A P1 feature becomes P0 when a competitor launches the feature and the sales team starts losing deals. The market shifted.

These are legitimate priority changes because the nature and consequence of the work actually changed. These changes are not promotions based on queue position.

The scale
#

For reference, a well-defined static scale looks something like this:

P0: Critical. Production is down, data is at risk, or customers are blocked. Drop everything.
P1: High. Important work with clear business impact. Should be done this quarter.
P2: Medium. Valuable but not time-sensitive. Should be done within the next two quarters.
P3: Low. Nice to have. Will do if capacity allows.
P4: Minimal. Logged for consideration. No commitment to do.
P5: Rejected or deferred indefinitely. Kept for historical reference.

Each level describes a timeframe, a level of commitment, and a resource allocation. None of the definitions reference other tasks in the backlog.

What to do instead of promoting
#

When the P0s are finished and work moves on to P1s, do not relabel. Instead:

Sort P1s by dependencies and impact. Within a priority level, use a secondary criterion to decide order.
Pick the top P1 and start. No ceremony needed.
If the P1s run out, start on P2s. The system is working as intended.

The priority label told you the task was important-but-not-critical work. It still is. The fact that nothing more urgent remains does not change the nature of the work.

The one-sentence version
#

Priority describes what a task is, not when you will get to the task. Keep the label stable, sort within levels, and let the schedule be the schedule.

The Shifting Bottleneck: From Writing Code to Questioning Everything

tom@tomrochette.com (Tom Rochette) — Tue, 12 May 2026 00:00:00 +0000

Every time AI removes a bottleneck in software development, the next one appears one level higher up the decision chain. The constraint never disappears, it just moves.

The Five Stages
#

1. Producing code
#

For decades, the bottleneck was typing. Writing code was slow. Understanding codebases was slow. Every feature required a human to translate intent into syntax, one keystroke at a time. We built IDEs, autocompletion, linters, and refactoring tools to speed up writing code, but the fundamental constraint remained: humans had to write the code.

Then LLMs arrived and removed that constraint almost overnight. GitHub Copilot, Cursor, Claude Code, and a dozen other tools made it trivial to generate working code from a description. The bottleneck moved.

2. Verifying generated code
#

When code writes itself, your job shifts from author to reviewer. You no longer ask “how do I implement this?” but “does this implementation do what I want?”

Verification is a fundamentally different skill. Reviewing code you didn’t write requires reading critically. Every function could contain a subtle bug, a hallucinated API call, or a plausible-sounding but incorrect assumption. The code looks right, the tests pass, but does it actually solve the problem?

The verification bottleneck is harder than the production bottleneck because verification is an underconstrained problem. There are infinitely many ways code can be wrong, and no finite checklist catches them all.

3. Deciding what to implement
#

Once you can generate and verify code quickly enough, a new question comes up: should we build this feature at all?

Not every feature deserves implementation. Not every bug deserves a fix. The cost of writing code approaches zero, but the cost of maintaining code, shipping code, and supporting code does not. Every line of code is a liability. Every feature increases the chance of bugs, increases cognitive load, and constrains future decisions.

The bottleneck shifts from “can we build it?” to “should we build it?” Deciding what to implement is product thinking, not engineering. Engineers who spent careers optimizing for execution speed now find themselves needing to develop judgment about what is worth executing.

4. Deciding what to build
#

Push further: should this product exist at all?

Before LLMs, the cost of building a product was a natural filter. If it took six months and a team of five to build an MVP, you had to be reasonably confident the market wanted it. Now that an MVP can be built in an afternoon, the cost of building is no longer the filter. The filter is the cost of being wrong about product-market fit.

The bottleneck now sits in strategy. Understanding users, identifying genuine problems, and choosing which market to enter are now the scarce skills. Anyone can build the product. Figuring out which product to build is the hard part.

5. Questioning automation itself
#

And then you arrive at the final question: should we have automated ourselves at all?

This is not a joke. Every layer of automation removes human involvement from a layer of decision-making. When code writes itself, verifies itself, decides what to build, and decides whether to build it, what is left for the human?

There is a genuine question about whether the end state of this trend is human irrelevance. Not because AI became malevolent, but because we systematically removed every reason for a human to be involved. Each step was rational. Each bottleneck existed. Each automation was justified. And yet the cumulative effect is a gradual loss of human agency in the creative process.

The Bottleneck Elevator
#

This pattern has a name in systems thinking: the theory of constraints. In any system, improving one stage of a pipeline exposes the next bottleneck downstream. In software development, the pipeline runs upward through abstraction layers:

Existential → Product → Feature → Verification → Production

AI has been climbing this stack from the bottom. Each time it solves one level, the next level becomes the limiting factor. The work doesn’t decrease, it transforms.

What to Do Next
#

If you are a software developer today, your career trajectory is moving up this stack whether or not you want it to.

If you are still at Stage 1 (producing code), you are already behind. Adopt AI coding tools now. The gap between developers who use LLMs and those who don’t is widening every month.

If you are at Stage 2 (verifying code), invest in specification skills. The ability to write precise, testable requirements is what separates effective AI-assisted developers from those who spend all day reviewing hallucinated nonsense.

If you are at Stage 3 (deciding what to implement), develop product judgment. Understanding trade-offs, opportunity cost, and the difference between “can build” and “should build” is your leverage.

If you are at Stage 4 (deciding what to build), you are in the right place for now. Strategy, market understanding, and user empathy are the current frontier.

If you are at Stage 5, you have seen the full picture. The question is not whether automation will continue climbing, it will. The question is what humans should do with the freedom that comes from not being the bottleneck.

The Answer
#

I don’t have a clean answer for Stage 5. Neither does anyone else. The optimists say we will find new creative work that we cannot yet imagine, the same way we always have after every technological revolution. The pessimists say this time is different because AI doesn’t just replace manual labor, it replaces cognitive labor, and eventually all of it. Both positions are old positions in the technological unemployment debate, and neither side has settled it.

What I can observe is that the bottleneck will keep shifting. Whatever you think the final constraint is, solving it will reveal another constraint. The work of a developer is not to write code, it is to stand at the current bottleneck and push.

The bottleneck will move. Your job is to move with it.

Code Factories: The RollerCoaster Tycoon Perspective

tom@tomrochette.com (Tom Rochette) — Mon, 04 May 2026 00:00:00 +0000

You start with an empty plot of land, a small bank loan, and an objective to attract 600 guests by the end of year two.

That’s RollerCoaster Tycoon. It’s also your first day as a startup founder.

In RollerCoaster Tycoon, you build a theme park from nothing. You lay down paths, construct rides, hire staff, set prices, manage finances, and try to keep thousands of guests happy simultaneously. You watch little pixelated people queue for attractions, complain about litter, get sick on rides, and leave when they’ve had enough.

Building a software product is the same game with different sprites. The question is whether your park guests are leaving happy or leaving forever.

Ride Design: Feature Development
#

In RollerCoaster Tycoon, every ride is a design problem.

A roller coaster starts as blank track on a canvas. You choose the lift hill height, the drop angle, the number of inversions, the banking on turns. Each decision affects three metrics: excitement, intensity, and nausea.

Excitement is what attracts guests. Intensity is the thrill level: some guests love it, some won’t ride. Nausea is the cost: too much and guests vomit on your paths.

Feature development has the same three metrics.

Excitement is user value, the feature that solves a genuine problem, delivers a delightful experience, or unlocks new capability. Intensity is complexity, the learning curve, the configuration surface, the cognitive load on users. Nausea is maintenance burden, the edge cases, the performance overhead, the support tickets.

A roller coaster with high excitement and moderate intensity is the ideal ride. Guests line up for it, enjoy it, and ride again. A feature with high value and manageable complexity is the ideal feature. Users adopt it, benefit from it, and recommend it.

A roller coaster with maximum intensity and maximum nausea empties the queue. Guests try it once, throw up, and never return. A feature with maximum complexity and maximum maintenance burden empties the user base. Users try it once, get confused, and never return.

The RollerCoaster Tycoon lesson: optimize for excitement, manage intensity, minimize nausea. In software: optimize for value, manage complexity, minimize burden.

Park Layout: Information Architecture
#

In RollerCoaster Tycoon, path layout determines everything.

Guests follow paths. They can only reach rides that are connected to the path network. If a ride is hidden behind another ride with no path leading to it, it might as well not exist. If the path network is a tangled mess, guests get lost, frustrated, and leave.

Your information architecture is your path layout.

Users follow navigation. They can only find features that are connected to the navigation flow. If a feature is buried three menus deep with no link to it, it might as well not exist. If the navigation is a tangled mess, users get lost, frustrated, and leave.

RollerCoaster Tycoon teaches a specific layout pattern: the hub-and-spoke.

A central plaza connects to several themed areas. Each themed area contains related rides. Signs guide guests from the hub to the areas they want. The layout is intuitive, discoverable, and scalable: add a new spoke when you add a new area.

Good information architecture is hub-and-spoke.

A homepage or dashboard connects to major feature areas. Each area contains related functionality. Breadcrumbs and search guide users to what they need. The layout is intuitive, discoverable, and scalable: add a new section when you add a new feature area.

Parks with random path layouts have low guest counts and low ratings. Products with random navigation have low engagement and low retention.

Guest Happiness: User Satisfaction
#

Every guest in RollerCoaster Tycoon has a happiness meter.

It starts high when they enter the park. Every good ride increases it. Every long queue decreases it. Every piece of litter they see decreases it. Every overpriced item decreases it. When happiness drops below a threshold, the guest leaves and the park rating drops.

User satisfaction works the same way.

Every smooth interaction increases it. Every loading spinner decreases it. Every confusing error message decreases it. Every unexpected price increase decreases it. When satisfaction drops below a threshold, the user churns and the review rating drops.

RollerCoaster Tycoon teaches that guest happiness is a composite of many small factors, not one big one.

No single ride makes guests happy. Happiness is the combination of good rides, short queues, clean paths, reasonable prices, attractive scenery, and available amenities. Fix one problem while ignoring the others and happiness barely moves.

User satisfaction is equally composite. No single feature makes users happy. Satisfaction is the combination of useful features, fast performance, clear error messages, fair pricing, good design, and responsive support. Fix one problem while ignoring the others and satisfaction barely moves.

The park with the highest rating isn’t the one with the best roller coaster. It’s the one where everything works well together. The product with the highest satisfaction isn’t the one with the best feature. It’s the one where everything works well together.

Queue Management: Performance Optimization
#

In RollerCoaster Tycoon, queues are the visual indicator of a problem.

A long queue means guests are waiting. Waiting guests are unhappy guests. Unhappy guests leave bad reviews and reduce the park rating.

The solutions are straightforward: increase ride capacity, add more rides, or optimize throughput. Run three trains instead of two. Synchronize the dispatch timing. Build a second coaster nearby to distribute the load.

Performance bottlenecks are queues.

A slow API response means requests are waiting. Waiting requests are unhappy users. Unhappy users abandon carts, close tabs, and leave bad reviews.

The solutions are equally straightforward: increase capacity, add more instances, or optimize throughput. Scale horizontally with more servers. Cache frequently requested data. Build a read replica to distribute the load.

RollerCoaster Tycoon also teaches a subtler lesson about queues: the perception of waiting matters as much as the actual wait.

Rides with themed queue lines (tunnels with decorations, TV screens playing videos, interactive elements) have higher guest satisfaction than rides with bare concrete queues, even when the wait time is identical.

The software equivalent is perceived performance.

A page that loads a skeleton UI immediately and fills in content progressively feels faster than a page that shows nothing for two seconds and then renders everything at once. The actual load time is the same. The perceived load time is dramatically different.

Theme your queue lines. Show progress indicators, skeleton screens, and optimistic updates. The wait is the same. The experience is better.

Staff Management: Team Operations
#

Your park needs staff.

Handymen sweep litter and empty trash cans. Mechanics inspect and repair broken rides. Security guards catch vandals and keep the peace. Entertainers make guests happy in queue lines.

Each staff member has a patrol zone. Set the zone too large and they can’t cover it all; litter accumulates in the corners. Set the zone too small and they cluster in one area while the rest of the park deteriorates. Hire too few and the park falls apart. Hire too many and the payroll drains your budget.

Engineering teams have the same dynamics.

SREs are mechanics: they inspect, repair, and prevent production failures. Support engineers are handymen: they clean up tickets, triage issues, and keep the user experience tidy. Security engineers are security guards: they find vulnerabilities, respond to incidents, and keep the codebase safe. Developer advocates are entertainers: they engage the community, write documentation, and make the developer experience enjoyable.

The patrol zone problem is the on-call rotation problem.

Give an on-call engineer too many services and they can’t respond to incidents fast enough; errors accumulate. Give them too few and they sit idle while other on-call engineers are overwhelmed. Too few engineers on rotation and the team burns out. Too many and context is spread thin.

RollerCoaster Tycoon also teaches that staff training matters.

A trained mechanic repairs rides faster. A trained handyman cleans more efficiently. In software, the equivalent is runbooks, incident playbooks, and onboarding documentation. A trained on-call engineer resolves incidents faster because they’ve seen the failure modes before and know the recovery steps.

Invest in your staff or watch your park deteriorate.

Ride Breakdowns: Production Incidents
#

Every ride in RollerCoaster Tycoon has a reliability rating.

New rides are highly reliable. As they age, reliability drops. The more a ride runs, the more likely it breaks down. A broken ride closes. Guests in the queue leave unhappy. The mechanic has to walk across the park, inspect the ride, and repair it.

During the downtime, the queue grows, the guests complain, and the park rating drops.

Production incidents are ride breakdowns.

New services are highly reliable. As they age, complexity accumulates. The more a service runs, the more likely an edge case triggers a failure. A failed service goes down. Users in the middle of a workflow are interrupted. The on-call engineer has to investigate, diagnose, and fix the issue.

During the downtime, error rates spike, users complain, and the product reputation drops.

RollerCoaster Tycoon’s solution to breakdowns is preventive maintenance.

Mechanics can be assigned to inspect rides before they break. Regular inspections increase reliability and reduce the frequency of breakdowns. The cost is the mechanic’s time; time spent inspecting is time not spent repairing. But the net effect is positive: fewer breakdowns, shorter downtimes, happier guests.

The software equivalent is proactive reliability engineering.

Chaos engineering, load testing, dependency auditing, and synthetic monitoring are preventive inspections. The cost is engineering time; time spent testing reliability is time not spent building features. But the net effect is positive: fewer incidents, shorter outages, happier users.

Parks that skip inspections have spectacular breakdowns at the worst moments. Services that skip reliability testing have spectacular outages during peak traffic.

Research: Technical Exploration
#

RollerCoaster Tycoon has a research system.

You allocate funding to research and over time, new rides, scenery, and improvements become available. More funding accelerates research. Less funding slows it. No funding means you’re stuck with what you have.

The tension is genuine: every dollar spent on research is a dollar not spent on building rides right now. But without research, you can’t build the rides that attract guests later.

Technology exploration is research.

Every hour spent evaluating a new framework, prototyping a new architecture, or experimenting with a new tool is an hour not spent shipping features right now. But without exploration, you can’t build the features that attract users later.

RollerCoaster Tycoon teaches that research should be funded consistently, not in bursts.

A player who sets research to maximum at the start and then cuts it to zero runs out of new content mid-game. A player who funds research at a moderate, steady rate unlocks new rides throughout the game.

The software equivalent: invest in exploration consistently, not just when the team is between projects.

A team that dedicates 10% of every sprint to technical exploration (trying new tools, reading papers, prototyping ideas) continuously discovers improvements. A team that only explores during quarterly hackathons discovers nothing for three months at a time.

Consistent research wins. Burst research wastes the intervals between bursts.

Scenario Objectives: Sprint Goals and OKRs
#

Every RollerCoaster Tycoon scenario has an objective.

“Have 600 guests in your park by the end of year two.” “Achieve a park rating of 700 by October, year three.” “Build ten roller coasters with an excitement rating above 6.00.” “Repay your loan and achieve a monthly profit of $1,000.”

The objectives are specific, measurable, and time-bound. They force you to prioritize; you can’t do everything, so you do what matters for the objective.

Sprint goals and OKRs are scenario objectives.

“Ship the new checkout flow by end of sprint.” “Reduce p95 latency below 200ms by end of quarter.” “Increase test coverage to 80% by end of year.” “Reduce onboarding time for new engineers by 50%.”

RollerCoaster Tycoon teaches something critical about objectives: the scenario ends.

When you achieve the objective, the scenario is complete. You can keep playing (most players do) but the pressure is off. The objective gave the gameplay structure. Without it, you’d build aimlessly and the park would suffer.

Sprint goals give development structure. Without them, teams build aimlessly and the product suffers.

But RollerCoaster Tycoon also teaches that the wrong objective leads to the wrong park.

An objective that demands 1,000 guests by year one forces you to build cheap, low-quality rides to attract crowds fast. The park fills up but the rating is terrible. An objective that demands a park rating of 900 forces you to build slowly and carefully. The rating is excellent but the guest count is low.

Software objectives have the same distortion effect.

An objective that measures lines of code produces lots of code. An objective that measures features shipped produces lots of features. Neither guarantees quality, user satisfaction, or business value. The metric you optimize is the park you get.

Choose your scenario objective carefully. It will determine everything you build.

Loan Management: Technical Debt
#

Many RollerCoaster Tycoon scenarios start you in debt.

You’ve borrowed money to buy the land and build the first rides. The loan accrues interest every month. The longer you carry it, the more it costs.

You can invest in rides to generate revenue and pay it off slowly. Or you can cut spending, build cheap rides, and pay it off quickly. The first strategy grows the park but increases the total interest paid. The second strategy limits growth but reduces the financial burden.

Technical debt is a loan.

You borrowed time by taking shortcuts, skipping tests, ignoring architecture, hardcoding values. The debt accrues interest every sprint. The longer you carry it, the more it costs in debugging, refactoring, and developer frustration.

You can invest in features to grow the product and pay down debt slowly. Or you can pause features, refactor aggressively, and pay it down quickly.

RollerCoaster Tycoon teaches that the optimal strategy depends on the interest rate.

A low-interest loan is fine to carry; the revenue from new rides exceeds the interest cost. A high-interest loan is an emergency: it consumes revenue faster than the park can generate it.

Low-interest technical debt (a slightly messy module that rarely changes) is fine to carry. The velocity gained by shipping features exceeds the cost of the debt. High-interest technical debt (a critical module that breaks every sprint) is an emergency. It consumes velocity faster than the team can generate it.

Know your interest rate. Manage accordingly.

Park Value: Technical Assets
#

RollerCoaster Tycoon tracks your park value, the combined worth of all your rides, scenery, and infrastructure.

It’s not the same as cash in the bank. You can have high park value and no cash if you spent everything on construction. You can have high cash and low park value if you haven’t built anything.

Park value represents what you’ve built, not what you have. It compounds: every ride you build increases the value, and the more valuable the park, the more guests it attracts, which generates more revenue for building more rides.

Technical assets are park value.

Your component library, your CI/CD pipeline, your monitoring infrastructure, your documentation, your test suite: these are rides you’ve built. They represent what you’ve constructed, not what you have in the backlog.

A team with high technical assets and an empty backlog is well positioned: they can build anything quickly. A team with low technical assets and a full backlog is in trouble: everything they try to build requires starting from scratch.

Park value compounds the same way. A park with ten rides attracts more guests than one with two, generating more revenue to build more rides. A codebase with ten reusable components ships faster than one with two, generating more time to build more components.

The RollerCoaster Tycoon lesson: invest in park value, not just cash flow. Build rides that attract guests. Build infrastructure that attracts velocity.

Scenery and Theming: Design and UX
#

In RollerCoaster Tycoon, scenery affects guest happiness.

Trees, fountains, gardens, statues, themed decorations: guests notice them. A ride surrounded by matching scenery gets an excitement bonus. A path lined with trees and benches keeps guests happy while they walk. A park with no scenery is functional but joyless.

Design and UX are scenery.

A functional interface without thoughtful design is a park without trees. Users can complete their tasks but they don’t enjoy them. There’s no delight, no personality, no sense that someone cared about the experience.

RollerCoaster Tycoon teaches that scenery is most effective when it’s themed.

A pirate-themed roller coaster surrounded by pirate scenery (ships, treasure chests, palm trees) gets a higher excitement bonus than the same ride surrounded by random, unrelated decorations. Consistency matters more than quantity.

Design systems are theming.

A consistent design system (typography, colors, spacing, components) creates a cohesive experience. Users don’t have to relearn the interface on every page. The product feels intentional, polished, professional.

A product with random design choices (different button styles, inconsistent spacing, clashing colors) is a park with random scenery. Each element might look fine on its own. Together, they’re incoherent.

Theme your park. Theme your product.

Marketing: Developer Relations and Product Marketing
#

RollerCoaster Tycoon lets you run marketing campaigns.

Advertising for the park increases guest count. You can target local, national, or international audiences at increasing cost. More marketing brings more guests, but if the park isn’t ready for them, they arrive to long queues, dirty paths, and broken rides. They leave unhappy and the marketing was wasted.

Product marketing and developer relations work the same way.

A successful marketing campaign brings users. But if the product isn’t ready (if the onboarding is rough, the documentation is thin, the performance is slow) users arrive to a bad experience. They leave unhappy and the marketing was wasted.

RollerCoaster Tycoon teaches the sequence: build the park first, then market it.

Players who spend their initial budget on marketing instead of rides attract guests to an empty park. The guests find nothing to do and leave. The money is gone and the park rating is worse than if they’d never marketed at all.

Startups learn this the hard way. Marketing before product-market fit brings users to a product that doesn’t serve them. The users leave, the analytics look terrible, and the brand is damaged.

Build the ride first. Then put up the billboard.

Terrain Constraints: Legacy Systems
#

Some RollerCoaster Tycoon scenarios give you a blank, flat parcel of land. These are the easy scenarios. You build what you want, where you want, with no constraints.

Most scenarios aren’t like that.

You get a mountainous plot with a river running through it. Or a partially built park with existing paths and rides you can’t remove. Or an underground cavern with limited space. The terrain constrains every decision. You can’t build a flat coaster on a mountain. You can’t extend a path across a river without a bridge. You have to work with what you’ve got.

Legacy codebases are constrained terrain.

The ideal software project starts from nothing: blank repository, no dependencies, no constraints. Most projects aren’t like that.

You inherit a codebase with a decade of decisions baked in. A database schema that can’t be changed without migrating millions of rows. An API contract that external clients depend on. A build system that nobody fully understands. The legacy constrains every decision.

RollerCoaster Tycoon teaches that constrained terrain isn’t a disadvantage: it’s a design prompt.

The best coasters in the game are built on mountains, using the elevation changes to create drops and turns that flat terrain can’t support. The constraint forces creativity. The result is better than what flat terrain would have produced.

The best software architectures emerge from constrained codebases. The legacy forces you to think carefully about abstractions, boundaries, and migration paths. The result is often more robust than a greenfield design that never faced actual constraints.

Don’t wish for flat terrain. Build better coasters on the mountain.

Ride Synchronization: Service Coordination
#

In RollerCoaster Tycoon, you can build ride sequences.

A log flume that ends near a roller coaster entrance. A transport ride that shuttles guests from the back of the park to the front. A path that naturally guides guests through a series of attractions in order.

When rides are well-connected, guests flow through the park naturally, experiencing each attraction in sequence. When rides are disconnected, guests wander, backtrack, and miss attractions they would have enjoyed.

Microservice coordination is ride synchronization.

A well-orchestrated service mesh lets data flow through the system naturally, each service processing requests in sequence. A poorly connected architecture forces data to backtrack, retry, and miss services that should have been involved.

RollerCoaster Tycoon also teaches that you can’t force guests through a sequence.

You can build a path that leads from Ride A to Ride B, but if the guest is tired, hungry, or has already ridden Ride A, they’ll skip Ride B and look for food instead. The sequence must be optional, not mandatory.

Service orchestration must be the same. Each service should work independently. Coordination is an optimization, not a requirement. If Service A is down, Service B should still function, even if degraded.

Guests who are forced through a sequence they don’t want rebel. Services that are forced into tight coupling fail together.

Build the path. Let the guest choose.

The Late Game: Software Factories
#

In RollerCoaster Tycoon’s late game, something shifts.

Your park is established. Rides are built, staff is hired, research is funded, guests are flowing. You stop placing individual track pieces and start thinking about the park as a system.

You notice that the path near the pirate coaster always gets congested, so you widen it. You notice that guests cluster near the food court at noon, so you add another food stall. You notice that the park rating dips every time it rains, so you build more indoor attractions.

You’re no longer building rides. You’re optimizing a system.

Software factories are the late game of development.

Your CI/CD pipeline is established. Your monitoring is running. Your team is staffed, your architecture is sound, your users are flowing. You stop writing individual functions and start thinking about the development process as a system.

You notice that deploys always cause a spike in errors, so you add automated smoke tests. You notice that code review is the bottleneck, so you add AI-assisted review tooling. You notice that onboarding takes too long, so you build interactive tutorials.

You’re no longer writing code. You’re optimizing a system that writes code.

In RollerCoaster Tycoon, the late game players build mega-parks, sprawling empires with dozens of rides, thousands of guests, and perfect ratings. They didn’t get there by building one perfect ride. They got there by building a system where every ride supports every other ride.

In software, the late game teams build software factories, sprawling systems where AI agents write code, tests run automatically, deployments ship continuously, and incidents heal themselves. They didn’t get there by writing one perfect feature. They got there by building a system where every tool supports every other tool.

The park guest who walks into a mega-park sees rides. The developer who walks into a software factory sees features. Neither sees the decades of system optimization that made it all possible.

The Lesson
#

RollerCoaster Tycoon is a game about building something that delights people.

You start with empty land and an objective. You end with a park that thousands of guests enjoy. The satisfaction isn’t in any single ride: it’s in the system that makes every ride better.

Software development is the same game.

You start with an empty repository and a requirement. You end with a product that thousands of users rely on. The satisfaction isn’t in any single feature: it’s in the system that makes every feature better.

In RollerCoaster Tycoon, the parks that endure aren’t the ones with the tallest coaster or the most rides. They’re the ones where everything works together: the paths flow, the queues are short, the staff is attentive, the scenery is beautiful, and every guest leaves happy.

In software, the products that endure aren’t the ones with the most features or the latest technology. They’re the ones where everything works together: the architecture is clean, the performance is fast, the support is responsive, the design is consistent, and every user leaves satisfied.

If you’re still building rides one track piece at a time, it’s time to think about the park. If you’re still writing features one line at a time, it’s time to think about the factory.

The park is open.

Code Factories: The Stock Market Perspective

tom@tomrochette.com (Tom Rochette) — Mon, 04 May 2026 00:00:00 +0000

You open your terminal, pull the latest commit, and run the test suite.

Some pass. Some fail. You investigate.

That’s software development. It’s also trading.

In the stock market, you analyze data, place orders, and manage risk. You develop strategies, backtest them, and deploy capital. You react to earnings reports, economic data, and competitor moves. The market never sleeps. The ticker never stops.

Building a software factory is the same game with different instruments. The question is whether you’re trading or being traded.

IPO: Your First Deploy
#

A company goes public through an initial public offering. Months of preparation (financial audits, legal filings, roadshow pitches) all leading to the moment the ticker appears on an exchange and anyone can buy shares.

Your first production deploy is your IPO.

You’ve spent months writing code, running tests in staging, doing code reviews. None of it matters until users touch the software in production. The moment you deploy to production, you’re public. Users will do things you never expected. Edge cases you never imagined will surface. The market (your users) will render its verdict.

Companies that rush their IPO get hammered. The valuation drops. The stock tanks. The reputation suffers. Teams that rush their first deploy get paged at 3 AM. The errors spike. The users complain. The reputation suffers.

The lesson is the same in both: prepare thoroughly, but don’t wait for perfection. There is never a perfect time to go public. There is never a perfect time to ship. The companies that wait too long get beaten by faster competitors. The teams that wait too long get beaten by faster teams.

Ship. Then iterate.

Market Capitalization: Lines of Code
#

A company’s market cap (share price times shares outstanding) is the simplest measure of its size. It tells you how much the market values the company right now. It tells you nothing about whether the company is well-run, profitable, or sustainable.

Lines of code is the market cap of software.

It tells you how big the codebase is. It tells you nothing about whether the code is well-written, tested, or maintainable. Just as a company with a billion-dollar market cap can be hemorrhaging cash, a codebase with a million lines can be hemorrhaging bugs.

Investors learned long ago that market cap is a starting point, not a conclusion. They look deeper: revenue, margins, growth rate, debt levels. Software teams need to look deeper too: test coverage, deployment frequency, mean time to recovery, change failure rate.

The stock that doubles on hype and collapses on earnings is the codebase that doubles in size on features and collapses under technical debt.

Bull and Bear Markets: Feature Velocity
#

Bull markets are euphoric. Stocks go up. Everyone is a genius. Companies raise money easily, hire aggressively, and expand recklessly. Risk appetite is high. Valuations detach from fundamentals.

Bear markets are brutal. Stocks go down. Nobody is a genius. Companies lay off workers, cut projects, and conserve cash. Risk appetite vanishes. Valuations collapse below reasonable levels.

Software projects have the same cycles.

In a bull phase, the product is winning. Features ship fast. Users are happy. Management approves every hire and every request. The team grows. Velocity increases. Everything feels possible.

In a bear phase, the product is struggling. Bugs pile up. Deadlines are missed. Hiring freezes. The team shrinks. Velocity decreases. Everything feels impossible.

The best investors don’t change their strategy based on the market. They have a strategy that works in both environments. They buy quality companies in bull markets and hold them through bear markets. They use bear markets to accumulate positions in companies they believe in.

The best software teams do the same. They invest in infrastructure during bull phases so they can survive bear phases. They maintain code quality when it’s tempting to cut corners. They use slow periods to pay down technical debt, refactor, and build the foundation for the next bull run.

Teams that only build features during the good times and cut everything during the bad times are like investors who buy at the top and sell at the bottom.

Diversification: Your Tech Stack
#

Financial advisors agree on almost nothing, but they agree on this: diversify your portfolio. Don’t put all your money in one stock, one sector, or one asset class. If that one bet fails, you lose everything.

Technology diversification works the same way.

A team that only knows one language, one framework, and one database is a portfolio with one stock. If that technology becomes obsolete, the team becomes obsolete. If that framework has a critical vulnerability, every service is vulnerable. If that database hits a scaling wall, every feature hits the wall.

But diversification has a cost. A portfolio with 200 stocks is harder to manage than one with 20. A codebase with 15 programming languages is harder to maintain than one with 3.

The best investors hold enough positions to be diversified but few enough to understand each one deeply. The best software teams use enough technologies to avoid single points of failure but few enough to develop deep expertise in each.

The index fund approach (owning a little bit of everything) works in finance. In software, it’s called using industry standards: well-supported languages, proven databases, widely adopted frameworks. You don’t pick the most exciting technology. You pick the one that won’t go to zero.

Short Selling: Technical Debt
#

Short selling is borrowing a stock, selling it, and hoping the price drops so you can buy it back cheaper. You profit from decline. The risk is unlimited; the stock can theoretically go to infinity, and your losses grow with it.

Taking on technical debt is short selling your future productivity.

You borrow time now (by skipping tests, ignoring architecture, hardcoding values) and you pay it back later with interest. If the project gets cancelled or rewritten before the debt comes due, you profit. If the project succeeds and grows, the debt compounds. Every feature becomes harder to ship. Every bug becomes harder to fix. Every new engineer takes longer to onboard.

Like short selling, technical debt can be rational. Traders short overvalued stocks. Engineers take on debt when the feature must ship this week or the company might not exist next month. The trade is calculated: the survival benefit of shipping now outweighs the cost of the debt later.

But just as most short sellers lose money in the long run, most teams that habitually take on technical debt ship slower in the long run. The interest payments (debugging, refactoring, working around hacks) consume an ever-larger share of development time.

The markets have a saying: the market can remain irrational longer than you can remain solvent. Software has an equivalent: the codebase can remain broken longer than your team can remain patient.

Dividends: Documentation and Tests
#

Dividends are payments a company makes to its shareholders from its profits. They’re not flashy. They don’t make headlines. But they compound. A stock that pays a 3% dividend and reinvests it grows dramatically over decades. Dividends are the quiet engine of long-term wealth.

Documentation and tests are dividends.

They don’t ship features. They don’t impress stakeholders in demos. But they compound. Every test written makes the next refactor safer. Every document written makes the next onboarding faster. Every API description written makes the next integration smoother.

Companies that cut dividends to fund growth sometimes succeed. More often, they lose the trust of long-term investors and find it harder to raise capital when they need it. Teams that skip documentation and tests to ship features sometimes succeed. More often, they lose the ability to make changes confidently and find every feature takes longer than the last.

The best dividend stocks aren’t the ones with the highest yield. They’re the ones with the most consistent, most reliable, most growing dividends. The best codebases aren’t the ones with the most tests. They’re the ones with the most consistent, most reliable, most growing test coverage.

Compound interest is the eighth wonder of the world. Compound documentation is the ninth.

Market Orders vs Limit Orders: Deployment Strategies
#

A market order says: buy this stock now, at whatever price the market is offering. Fast. Guaranteed execution. No price guarantee.

A limit order says: buy this stock, but only if the price is at or below my limit. Slower. Not guaranteed to execute. Price guaranteed.

A market order is deploying to production on a Friday afternoon. Fast. The feature is live. No safety guarantee.

A limit order is deploying through a canary release: route 5% of traffic to the new version, monitor for errors, and only proceed if everything looks good. Slower. Not guaranteed to finish today. Safety guaranteed.

Most retail investors use market orders because they’re simple and immediate. Most retail developers deploy all at once because it’s simple and immediate.

Professional traders use limit orders to control their risk. Professional engineering teams use progressive deployments to control theirs.

The stock that gaps down 10% on bad earnings is the deploy that errors 10% of requests on a bad commit. The trader who used a limit order avoided the gap. The team that used a canary deployment avoided the outage.

Earnings Season: Sprint Reviews
#

Every quarter, public companies report earnings. Revenue, profit, guidance. Analysts dissect every number. The stock moves based on whether the results meet, beat, or miss expectations.

It doesn’t matter whether the company is doing well in absolute terms. It matters whether the company is doing well relative to expectations. A company that doubles revenue but was expected to triple it sees its stock drop. A company that loses money but loses less than expected sees its stock rise.

Sprint reviews are earnings season.

Every sprint, the team reports what it shipped. Stakeholders dissect every feature. Morale moves based on whether the results meet, beat, or miss expectations.

It doesn’t matter whether the team is productive in absolute terms. It matters whether the team is productive relative to expectations. A team that ships five features but committed to seven feels like it failed. A team that ships three features but committed to two feels like it succeeded.

The earnings lesson for companies is straightforward: underpromise and overdeliver. The sprint lesson for teams is the same. The company that guides conservatively and beats expectations rewards its shareholders. The team that commits conservatively and beats its sprint rewards its morale.

Companies that inflate guidance to pump the stock eventually miss and crash. Teams that inflate commitments to impress stakeholders eventually miss and burn out.

Volatility: Production Incidents
#

Volatility is how much a stock’s price moves up or down. High volatility means large, unpredictable swings. Low volatility means small, predictable movements.

Traders love volatility: it creates opportunity. Investors hate volatility: it creates anxiety. Both are describing the same phenomenon from different perspectives.

Production incidents are volatility.

High incident volatility means the system swings between working and broken with little warning. The on-call engineer gets paged at random hours. The deploy button feels like a slot machine. Nobody knows whether today will be a quiet day or a fire-fighting day.

Low incident volatility means the system is stable and predictable. Deploys are boring. Pages are rare. The team can plan its work with confidence.

The paradox of volatility is that it’s both a risk and a reward. Traders who can predict volatile movements profit handsomely. Engineers who can diagnose and fix incidents quickly become heroes. But predictability is worth more than heroism. The trader who consistently earns 10% a year beats the trader who swings between +50% and -40%. The team that consistently ships without incidents beats the team that heroically recovers from weekly outages.

The VIX (the stock market’s volatility index) is often called the fear index. Your incident frequency is your VIX. If it’s high, your team is afraid to deploy. If it’s low, your team deploys confidently.

Fundamental Analysis vs Technical Analysis: Code Reviews
#

Fundamental analysts study the company, its financials, its management, its competitive position, its growth prospects. They believe the stock price will eventually reflect the company’s true value.

Technical analysts study the chart, price movements, volume, trends, patterns. They believe the price already reflects everything worth knowing and the pattern predicts what comes next.

Both approaches have merits. Both have blind spots.

Code review has the same split.

The fundamental reviewer reads every line, understands the design decisions, evaluates the architecture, and checks whether the implementation matches the specification. They’re thorough but slow.

The technical reviewer looks at the diff, the changes, the patterns, the test coverage, the style. They’re fast but can miss design flaws that aren’t visible in the diff.

The best investors combine both. They use technical analysis for timing and fundamental analysis for selection. The best code reviewers combine both too. They look at the diff for quick feedback and the architecture for deeper understanding.

Investors who only use technical analysis get caught in pump-and-dump schemes. Reviewers who only look at diffs get caught by changes that look correct in isolation but break the system in context.

Insider Trading: Knowledge Silos
#

Insider trading is trading on information that isn’t public yet. It’s illegal in finance because it’s unfair: the insider has an advantage that ordinary investors don’t.

Knowledge silos are insider trading in software.

The engineer who has been on the team for five years and knows every quirk of the legacy system has information that new team members don’t. They can diagnose problems faster, estimate tasks more accurately, and avoid pitfalls that would trap anyone else. They have an unfair advantage.

Unlike the stock market, this isn’t illegal. But it is dangerous.

When the insider leaves (the senior engineer quits, the architect retires, the founding developer moves on) the team loses access to all that private information. The stock drops. The system becomes incomprehensible.

The solution in finance is regulation: insiders must disclose their trades. The solution in software is documentation: experts must disclose their knowledge. Run books, architecture decision records, onboarding guides, code comments: these are the SEC filings of software. They give everyone the same information.

Teams that don’t document are teams where insider trading is the norm. And when the insider leaves, everyone else inherits the undocumented system.

Market Crashes: Cascading Failures
#

On October 19, 1987, the Dow Jones dropped 22.6% in a single day. No single event caused it. Program trading, portfolio insurance, and panic selling created a feedback loop. Each drop triggered more selling, which triggered more drops. The system destroyed itself through its own feedback loop.

Cascading production failures are market crashes.

A database slows down, which causes API timeouts, which cause retry storms, which overload the load balancer, which drops health checks, which trigger auto-scaling, which overwhelms the database further. No single component failed. The system destroyed itself through its own feedback loop.

The 1987 crash led to circuit breakers, automatic trading halts when the market drops too fast. They don’t prevent the underlying problem. They prevent the feedback loop. They give humans time to intervene.

Circuit breakers in software work the same way. Rate limits prevent retry storms. Bulkheads prevent failures from spreading between services. Timeouts prevent cascading hangs. They don’t prevent the database from being slow. They prevent the slowness from becoming an outage.

Markets without circuit breakers crash faster and recover slower. Systems without circuit breakers fail faster and recover slower.

Index Funds: Standardized Infrastructure
#

Index funds track a market index, the S&P 500, the NASDAQ, the total market. They don’t try to beat the market. They try to be the market. Low fees. Broad diversification. Consistent returns. They’ve outperformed most actively managed funds over any reasonable time period.

Standardized infrastructure is the index fund of software.

You don’t try to build the most optimized database layer, the most custom CI/CD pipeline, the most custom-built deployment system. You use the standard: Kubernetes for orchestration, GitHub Actions for CI/CD, Terraform for infrastructure as code. Not because they’re the best in every dimension. Because they’re good enough in every dimension and they free your team to focus on what actually differentiates your product.

Actively managed funds charge higher fees for the promise of beating the market. Most don’t. Custom infrastructure demands more maintenance for the promise of better performance. Most of the time, it isn’t worth it.

The index fund lesson: stop trying to be clever. Accept market returns and spend your energy where it matters. The infrastructure lesson: stop building custom solutions for solved problems. Accept industry standards and spend your engineering effort on the product.

Warren Buffett’s advice to most investors is to buy a low-cost index fund and do nothing. The equivalent advice to most engineering teams is to adopt standard tooling and focus on shipping.

Margin Trading: Overcommitment
#

Margin trading is borrowing money from your broker to buy more stock than you can afford. It amplifies gains when you’re right. It amplifies losses when you’re wrong. If the position moves against you enough, you get a margin call: the broker demands more collateral or forces you to sell at a loss.

Overcommitting your team is margin trading.

You borrow future capacity (by promising more features than the team can deliver) to please stakeholders now. When the estimates are right, the team delivers and everyone is happy. When the estimates are wrong (and they’re often wrong) the team gets a margin call. Deadlines are missed. Quality drops. People burn out.

The margin call in software is the sprint where nothing ships. The team spent two weeks paying back the borrowed time from the previous three sprints. They were debugging instead of building. Refactoring instead of featuring. Recovering instead of advancing.

Professional traders use margin carefully, with strict risk limits. Professional engineering managers use overcommitment carefully, with buffers and contingency plans.

Amateur traders get wiped out by margin calls. Amateur teams get burned out by death marches.

Warren Buffett: The Principal Engineer
#

Warren Buffett has been investing for over seven decades. He doesn’t trade. He doesn’t use leverage. He doesn’t chase trends. He reads annual reports, understands businesses deeply, and makes a few large, concentrated bets on companies he understands.

Then he waits.

His holding period, he famously said, is forever. His edge isn’t speed or information. It’s patience and judgment.

The principal engineer is the Warren Buffett of software.

They don’t chase the latest framework. They don’t rewrite systems that work. They read codebases deeply, understand the architecture completely, and make a few large, concentrated decisions about the systems that matter most.

Then they wait.

Their edge isn’t typing speed or commit frequency. It’s judgment and patience. They know which changes are worth making and which changes will look foolish in six months. They know which abstractions will last and which will be torn out next quarter.

Buffett’s company, Berkshire Hathaway, has outperformed the market for decades by doing less, not more. The principal engineer outperforms the rest of the team not by writing more code, but by writing the right code.

The market rewards activity in the short term and wisdom in the long term. Software rewards the same.

Market Efficiency: The Myth of the Perfect System
#

The efficient market hypothesis says that stock prices reflect all available information. If a stock is undervalued, someone will buy it and push the price up. If it’s overvalued, someone will sell it and push the price down. In an efficient market, you can’t consistently beat the market because the market already knows everything you know.

Markets aren’t perfectly efficient. They’re efficient enough to humiliate most people who think they can beat them.

Software systems aren’t perfectly reliable. They’re reliable enough to humiliate most teams who think they’ve eliminated all failure modes.

The efficient market hypothesis teaches investors to be humble. No matter how smart you are, the collective wisdom of millions of market participants has already been priced in. Your edge, if you have one, is small and temporary.

The software equivalent teaches engineers to be humble. No matter how well you design the system, the collective chaos of users, dependencies, networks, and hardware will find the gaps. Your reliability, if you’ve achieved it, is temporary and requires constant maintenance.

Investors who believe they’ve found a system that can’t lose discover that markets change. Engineers who believe they’ve built a system that can’t fail discover that failure modes evolve.

The market adapts. The system adapts. Stay humble or get humbled.

The Late Game: Algorithmic Trading
#

In modern markets, the majority of trading volume comes from algorithms. Machines that analyze data, identify patterns, and execute trades in microseconds. They don’t sleep. They don’t panic. They don’t get greedy or fearful. They follow their programming with mechanical precision.

The humans who built these algorithms don’t trade. They design the systems that trade. They monitor the systems, adjust parameters, and intervene when the algorithms encounter situations they weren’t designed for. But they don’t place orders themselves.

Software factories are algorithmic trading.

AI agents write code, run tests, deploy services, and respond to incidents with increasing autonomy. They don’t get tired. They don’t get bored. They don’t introduce off-by-one errors at 5 PM on a Friday.

The engineers who built these systems don’t write code for production. They design the systems that write code. They monitor the agents, adjust prompts, and intervene when the AI encounters problems it wasn’t trained for. But they don’t write the production code themselves.

Algorithmic trading didn’t eliminate human traders overnight. The first algorithms were simple: arbitrage, market making, basic pattern recognition. They handled the routine and left the complex decisions to humans. Over time, the algorithms got better and handled more of the complexity.

Software factories won’t eliminate human engineers overnight. The first AI agents are simple: boilerplate generation, test writing, basic bug fixes. They handle the routine and leave the complex decisions to humans. Over time, the agents will get better and handle more of the complexity.

The traders who survived the algorithmic revolution were the ones who learned to work with the algorithms, not against them. They moved up the stack, from executing trades to designing strategies. The engineers who will survive the AI revolution are the ones who learn to work with AI agents, not against them. They’ll move up the stack, from writing code to designing systems.

The Lesson
#

The stock market is a system for allocating capital to its most productive use. Prices emerge from millions of participants making independent decisions based on incomplete information. Nobody controls the market. Everyone participates in it.

Software development is a system for allocating engineering effort to its most productive use. Priorities emerge from teams making decisions based on incomplete information about users, technology, and the future. Nobody controls the outcome. Everyone contributes to it.

The market doesn’t care about your feelings. Your codebase doesn’t care about your intentions. Both respond to what you do, not what you mean to do.

In both domains, the winners are the ones who manage risk, compound knowledge, stay humble, and play the long game. The losers are the ones who chase hype, take on debt they can’t repay, confuse activity with progress, and believe this time is different.

This time is never different.

The market remains. The codebase remains. The best you can do is show up every day, make good decisions, and let compounding do its work.

If you’re still hand-trading in a world of algorithms, it’s time to automate. If you’re still hand-coding in a world of software factories, it’s time to build.

The market is open.

Code Factories: The World of Warcraft Perspective

tom@tomrochette.com (Tom Rochette) — Mon, 04 May 2026 00:00:00 +0000

I create a character, spawn in a starting zone with a rusty sword and a vague quest to kill boars.

That’s World of Warcraft. It’s also my first day as a software developer.

In World of Warcraft, I choose a race and a class, then spend hundreds of hours leveling through zones, running dungeons, completing quests, and eventually organizing twenty-five people to coordinate a raid boss fight where one mistake kills everyone. The game is about progression, from nothing to something, from solo to coordinated, from chaos to precision.

Software development follows the same arc. The question is what level my team is playing at.

Leveling: Developer Growth
#

In WoW, every character starts at level 1. I have two abilities, no gear, and no idea what I’m doing. I kill wolves for experience. I die to enemies I’ll later defeat in one hit. I slowly unlock new abilities, talent points, and gear slots.

The leveling process isn’t a tutorial: it’s the actual game. Every level teaches me something about my class. By the time I reach the level cap, I’ve internalized dozens of mechanics through repetition.

Developer onboarding is leveling.

Junior developers start with two abilities: write code and Google errors. They fix simple bugs. They write basic functions. They die to merge conflicts they’ll later resolve in seconds.

Each project, each codebase, each production incident is experience points. Nobody becomes a senior developer by reading about architecture. People become senior developers by leveling through enough bad architectures to recognize a good one.

The WoW lesson: there are no shortcuts to the level cap. Boosted characters (players who pay to skip leveling) arrive at max level without understanding their class. Developers who skip fundamentals (jumping straight into frameworks without understanding the language, or into architecture without understanding systems) are boosted characters. They have the gear but not the skill.

Talent Trees: Specialization
#

At level 10, WoW lets me choose a specialization. A Paladin can be a tank, a healer, or a damage dealer. A Mage can specialize in fire, frost, or arcane. Each talent tree changes how the class plays entirely.

Career specialization is the same.

The backend talent tree: databases, distributed systems, API design, performance optimization. The frontend talent tree: UI components, state management, accessibility, rendering performance. The DevOps talent tree: CI/CD, container orchestration, monitoring, infrastructure as code.

In WoW, I can respec: pay gold, reset my talent points, and pick a new tree. In software, I can respec too. A backend developer can learn frontend. A frontend developer can learn DevOps. The cost isn’t gold: it’s time.

But WoW teaches something important about talent trees: depth beats breadth early on.

A player who spreads talent points across all three trees is weaker than one who commits to one. A developer who tries to master everything is weaker than one who goes deep on one domain first, then branches out later.

Specialize. Then generalize.

Questing: Tickets and Tasks
#

Quests in WoW are simple: accept task, complete objective, turn in for reward.

Kill ten wolves. Collect fifteen herbs. Escort an NPC across a danger zone. The objectives are clear. The rewards are predictable. The difficulty scales with level.

Tickets are quests.

A Jira ticket says: implement this feature, fix this bug, refactor this module. The objective is clear, or it should be. The reward is a shipped product.

But WoW also teaches that not all quests are worth doing.

Some quests send players across the map for minimal experience. Some quest chains look tedious but unlock a dungeon. The experienced player knows which quests to skip and which to prioritize.

The experienced developer knows the same thing. Not every ticket deserves the same investment. Some are quick wins with high impact. Some consume days for negligible value. The skill isn’t in completing the quest: it’s in choosing the right quests.

Dungeons: Sprint Delivery
#

At level 15, I enter my first dungeon.

Five players. One tank. One healer. Three damage dealers. A dungeon is a structured challenge that cannot be completed alone. I need a group, each performing their role, communicating through pulls and boss fights.

Dungeons are sprints.

A small team, a defined scope, a clear objective, a fixed timeframe. The tank sets the pace, pulling groups of enemies, controlling the flow. The healer keeps everyone alive, handling the unexpected, patching mistakes. The damage dealers execute, killing targets, following priority, managing resources.

A sprint works the same way.

The tech lead is the tank: they scope the work, set priorities, manage risk. The more senior developers are the healers: they catch issues in review, patch architectural problems, keep the codebase healthy. The team executes, writing features, fixing bugs, shipping code.

WoW teaches a critical dungeon lesson: the group moves at the pace of its weakest coordinated member.

One player who doesn’t know the strategy, doesn’t listen to the leader, or attacks the wrong target can wipe the group (get everyone killed). In a sprint, one developer who misunderstands the requirement, skips code review, or deploys without testing can derail the whole release.

Communication isn’t optional. It’s the difference between a smooth run and a wipe.

Raids: Large-Scale Projects
#

Raids are WoW’s endgame content.

Ten, twenty, or forty players coordinating to defeat bosses with complex mechanics. One person stands in the wrong spot and the entire raid dies. One healer misses a healing rotation and the tank falls. One damage dealer ignores a mechanic and the boss enrages.

Raids are large-scale projects.

Multiple teams coordinating across a shared objective. One service goes down and the whole product suffers. One team misses their deadline and the launch slips. One undocumented dependency surfaces and everything breaks.

The raid leader is the engineering manager.

They don’t play the game for the team: they coordinate. They call out mechanics before they happen. They adjust the strategy when something goes wrong. They decide who sits out when the group is too large.

Good raid leaders don’t micromanage individual players. They trust each player to execute their role while they focus on the overall plan. Good engineering managers do the same: they set direction, remove blockers, and let engineers engineer.

WoW raids also teach preparation.

I don’t walk into a raid unprepared. I bring flasks, food buffs, enchanted gear, and consumables. I’ve studied the boss mechanics on forums and in videos. I’ve done the prerequisite attunement quests.

Large projects require the same preparation. I don’t walk into a rewrite without understanding the current system. I don’t migrate a database without load testing. I don’t launch a product without a rollback plan.

Underprepared raids wipe. Underprepared projects fail.

Tank, Healer, DPS: Team Roles
#

WoW’s holy trinity (tank, healer, damage dealer) is the foundation of every group activity.

The tank takes the hits. They stand in front of the boss, absorb damage, and keep threat so nobody else gets attacked. Without a tank, the group dies instantly.

The healer keeps everyone alive. They undo damage, cleanse debuffs, and resurrect the dead. Without a healer, the tank dies and the group follows.

The damage dealers kill the boss. They do the actual work of reducing the boss’s health to zero. Without damage dealers, the encounter never ends.

Engineering teams have the same trinity.

The incident responder is the tank: they take the hits when production goes down. They absorb the pressure, communicate with stakeholders, and keep the problem focused so others can work.

The code reviewer is the healer: they catch bugs before they ship, suggest improvements, and mentor through feedback. They keep the codebase healthy.

The feature developer is the damage dealer: they write the code that ships the product. They push the project forward, sprint after sprint.

Every role is essential. Every role is underappreciated by the other roles. Damage dealers complain about long queue times because there aren’t enough tanks and healers. Tanks and healers complain that damage dealers are replaceable.

In software, everyone has complained about both sides. Feature developers complain that code review is slow. Code reviewers complain that features are rushed. The truth is the same as in WoW: a team needs all three, and disrespecting any role is how the team wipes.

Gear and Item Level: Tools and Experience
#

In WoW, gear matters. A level 60 character in quest greens (common-quality gear from quests) loses to a level 55 character in raid epics (rare-quality gear from raids). Item level (the numerical representation of gear quality) determines whether I’m invited to groups, accepted into raids, or competitive in PvP.

But gear is a multiplier, not a substitute.

A player in the best gear who doesn’t know their rotation (the optimal sequence of abilities) does less damage than a skilled player in mediocre gear. The game rewards both (players need skill to earn gear, and gear amplifies skill) but skill is the foundation.

Developer tools and experience are gear.

A senior engineer with modern tooling (AI-assisted IDEs, comprehensive test frameworks, powerful debuggers) ships faster than one without. But a senior engineer with bad tools still outperforms a junior engineer with the best tools.

The mistake teams make is treating tools like gear drops (equip them and instantly get stronger).

Tools don’t work that way. Neither does gear.

In WoW, I earn gear through repeated runs, understanding mechanics, and gradual improvement. In software, I earn proficiency with tools through repeated use, understanding trade-offs, and gradual improvement.

Buying the most expensive IDE doesn’t make anyone a better developer. Equipping raid gear doesn’t make anyone a better player. Using the gear effectively does.

Boss Mechanics: Complex Bugs
#

Every raid boss in WoW has mechanics.

Don’t stand in the fire. Switch targets when extra enemies spawn. Spread out during the explosion. Stack up during the healing phase. Each mechanic is a rule. Break a rule and the group takes damage. Break enough rules and the group wipes.

Complex bugs have mechanics too.

The race condition only triggers under concurrent load. The memory leak only appears after 48 hours of uptime. The null pointer only occurs when the user has an empty cart and clicks checkout twice. Each condition is a rule. Satisfy the right combination and the bug reproduces.

WoW teaches a specific approach to boss mechanics: learn the fight, don’t brute-force it.

I don’t defeat a boss by throwing myself at it repeatedly, hoping for better luck. I study the mechanics, adjust my strategy, and execute precisely. A boss that takes 50 wipes to learn might die in a single attempt the next week with the right approach.

Debugging complex bugs is the same.

I don’t fix a bug by randomly changing code until it works. I read the logs, reproduce the issue, identify the conditions, and fix the root cause. A bug that takes a week to diagnose might be fixed in one line once I understand the mechanic.

The raid strategy for new bosses: watch a guide, learn the phases, practice the execution. The debugging strategy for new bugs: read the stack trace, identify the phase, fix the condition.

Wipe Recovery: Incident Response
#

In WoW, a wipe means everyone dies.

The boss resets. The group runs back. The resurrection timer ticks. I repair my damaged gear, rebuff, and try again.

What separates good raid groups from bad ones isn’t whether they wipe; everyone wipes. What separates them is how they recover.

Bad groups rage in voice chat. They blame the healer, the tank, the damage dealers. They argue about whose fault it was while the respawn timer counts down. They waste five minutes on blame before trying again. And they wipe again, because they didn’t learn anything.

Good groups skip the blame. Someone calls out what went wrong (“the healer got silenced during the area-of-effect phase”) and the group adjusts. They try again in thirty seconds. They might wipe again, but they wipe to a different mechanic, which means they’re learning.

Incident response is wipe recovery.

A production outage is a wipe. Something broke. Users are affected. The system needs to recover.

Bad incident responses are blame-heavy. “Who deployed this?” “Why wasn’t this tested?” “Who approved this change?” The questions are valid but the timing is wrong. The team is still in combat. Fix the issue first. Do the post-mortem later.

Good incident responses are diagnostic. “What changed?” “What’s the error rate?” “When did it start?” The group focuses on understanding and fixing, not assigning fault. The post-mortem comes after the system is healthy (in WoW terms, after the boss is dead).

The WoW lesson: wipe, learn, adjust, try again. The speed of iteration determines the speed of progression.

Guilds: Engineering Organizations
#

In WoW, guilds are persistent groups of players who raid together, share resources, and build social bonds.

A good guild has clear leadership, a shared culture, and mutual respect. Players show up on time, prepared, and committed to the group’s success. They help each other gear up. They share strategies. They celebrate kills together.

A bad guild has drama. Loot disputes. Attendance problems. Players who show up unprepared, demand carries, and leave when they get what they want.

Engineering organizations are guilds.

The good ones have clear technical direction, a culture of code review, and mutual respect between teams. Engineers share knowledge, mentor juniors, and celebrate launches. They invest in shared infrastructure that benefits everyone.

The bad ones have politics. Turf wars over services. Engineers who hoard knowledge and resist review. Teams that optimize for their own metrics at the expense of the product.

WoW players know: the guild determines the experience more than the game.

A great guild makes mediocre content fun. A bad guild makes great content miserable. The same is true in software. A great team makes a boring product interesting. A toxic team makes an exciting product unbearable.

Choose the guild carefully. Or in hiring terms: choose the team carefully.

The Auction House: Package Registries
#

The Auction House is WoW’s economy. Players buy and sell items (crafting materials, gear, consumables) in an open market. Prices fluctuate based on supply and demand. Some players spend more time on the Auction House than in raids.

Package registries are the Auction House.

npm, PyPI, Maven Central, RubyGems: open markets where developers distribute code. Most of it is free, but the economics are the same. Supply and demand determine which packages thrive. Quality varies wildly.

WoW teaches caution with the Auction House. That cheap flask might be underpriced for a reason. That epic bind-on-equip item might be a scam.

npm teaches the same caution. That package with 10,000 weekly downloads might have a security vulnerability. That library with the slick README might be abandonware. The left-pad incident was an Auction House crash: a critical commodity disappeared and the market panicked.

The WoW player’s defense: know the market, check prices, don’t buy suspicious deals. The developer’s defense: audit dependencies, check maintenance history, don’t install packages with three stars and no recent commits.

Addons: Developer Tooling
#

WoW’s addon system lets players customize their UI and extend their gameplay. Damage meters, boss mod warnings, raid frames, loot council tools: the default UI works, but serious players run dozens of addons.

Developer tooling is the addon ecosystem.

Linter, formatter, pre-commit hooks, custom IDE snippets, shell aliases, tmux configurations: the default development environment works, but serious developers customize extensively.

In WoW, the player who refuses to install boss mods dies to mechanics they could have seen coming. In software, the developer who refuses to use a debugger steps through logs they could have inspected visually.

But WoW also teaches addon discipline.

Too many addons cause conflicts, crashes, and performance problems. Players who install every addon they find spend more time configuring their UI than playing the game. The best players use a focused set of addons that solve specific problems.

Developer tooling needs the same discipline. A developer who spends more time configuring tools than writing code has forgotten the purpose of the tools. The best toolchains are minimal, focused, and reliable.

Professions: Side Projects and Tooling
#

In WoW, characters can learn professions: blacksmithing, enchanting, engineering, alchemy. These secondary skills let players craft items, enhance gear, and create consumables.

Professions don’t advance the main quest. They don’t give experience. But they make the main quest easier.

Internal tooling is professions.

CLI tools, build scripts, code generators, monitoring dashboards: they don’t ship features, but they make shipping features faster. A team that invests in professions (that builds internal tools) levels faster than one that doesn’t.

The WoW lesson: max professions early.

A blacksmith who starts crafting at level 1 has far better gear than one who starts at max level. A team that builds tooling from day one has far better productivity than one that starts tooling after the crunch.

Threat and Aggro: On-Call and Incident Management
#

In WoW, every NPC enemy has a threat table. Whoever generates the most threat gets attacked. Tanks generate threat intentionally. Damage dealers generate threat as a side effect of dealing damage. Healers generate threat by healing.

If a damage dealer generates too much threat, the boss turns and kills them. This is called pulling aggro. It’s almost always fatal.

Production incidents have threat tables.

The on-call engineer is the tank. They absorb the pressure, pages, alerts, user complaints, Slack messages. They hold threat so the rest of the team can work without distraction.

But just like in WoW, if someone pulls aggro (if a non-on-call engineer starts making changes in production, or a manager starts demanding real-time updates every thirty seconds) the incident gets worse. The wrong person has the boss’s attention.

The WoW solution: let the tank hold threat. The incident solution: let the on-call engineer own the response. Everyone else supports (provides context, runs commands when asked, stays available) but doesn’t grab aggro.

A damage dealer who pulls aggro doesn’t just kill themselves. The boss might cleave and kill the healer too. A developer who pushes an untested fix during an incident doesn’t just fail to resolve the issue: they might make it worse and take down another system.

Let the tank tank.

Enrage Timers: Deadlines
#

Many raid bosses have an enrage timer. After a fixed duration, the boss enters an enraged state: damage increases dramatically, new mechanics activate, and the raid will wipe within seconds.

The message is simple: be good enough, fast enough.

Software deadlines are enrage timers.

The quarterly OKR deadline. The conference demo. The enterprise client’s contract renewal date. These are fixed points in time after which the consequences escalate sharply.

WoW teaches that enrage timers create two strategies: out-gear the fight or out-skill the fight.

Out-gearing means coming back with better stats and burning the boss down before the timer. In software, out-gearing means adding more engineers, more resources, more hours to hit the deadline.

Out-skilling means executing perfectly, minimizing wasted time, and maximizing output with the resources at hand. In software, out-skilling means good architecture, clean code, and efficient processes.

The WoW meta has swung between both strategies across expansions. In software, the meta swings between hiring blitzes and efficiency drives. The answer, as always, is both: enough gear to survive, enough skill to execute.

Grinding: Maintenance Work
#

In WoW, some activities are just grinding.

Reputation grinds. Daily quests. Material farming. Running the same dungeon for the thirty-seventh time because the trinket won’t drop. Nobody enjoys grinding. But grinding is how players progress.

Software maintenance is grinding.

Updating dependencies. Fixing flaky tests. Rotating credentials. Cleaning up log files. Refactoring code that works but is hard to read. Nobody launches a software career to update dependency versions. But the grind is how the factory keeps running.

WoW players who skip the grinding find themselves under-geared when new content drops. They can’t participate in the new raid because they didn’t do the preparatory work.

Teams that skip maintenance find themselves unable to ship when new features are needed. The dependency tree is two years out of date. The test suite takes forty minutes. The deployment process is manual and error-prone. They can’t ship because they didn’t do the preparatory work.

The grind isn’t glamorous. But it’s what separates the prepared from the unprepared.

Expansions: Major Rewrites
#

Every few years, WoW releases an expansion.

A new continent. New systems. New mechanics. Sometimes, old systems are completely rebuilt. Stats are squished. Abilities are pruned. The talent tree is redesigned. The game I knew is fundamentally changed.

Some changes are loved. Some are hated. Every expansion has players who threaten to quit and players who return after years away.

Major platform rewrites are expansions.

A migration from monolith to microservices. A transition from on-premise to cloud. A framework upgrade from v2 to v3. The system I knew is fundamentally changed.

Like WoW expansions, major rewrites are risky. They take enormous investment. They disrupt existing workflows. They might attract new users or they might alienate existing ones.

WoW’s approach to expansions is instructive: the core identity stays the same. Despite every expansion’s changes, WoW is still about questing, dungeons, raids, and gear. The systems change. The core doesn’t.

Successful rewrites do the same. The core business logic is preserved. The deployment infrastructure might change, the data store might change, the frontend framework might change, but the product’s purpose stays the same.

Don’t change what the game is about. Change how the game plays.

Heirloom Gear: Reusable Components
#

In WoW, heirloom items are special pieces of gear that scale with a character’s level.

I earn them on my max-level character and mail them to my alts, my alternate characters. A level 1 alt wearing heirloom gear is dramatically stronger than a level 1 character in normal gear. The investment I made on my main character benefits every alt.

Design systems and shared libraries are heirloom gear.

A component library built by one team makes every subsequent team faster. A shared authentication module, a common logging framework, a standardized deployment pipeline: these are investments that benefit the entire organization.

The WoW lesson: invest in heirlooms early.

Players who acquire full heirloom sets for their alts level twice as fast. Organizations that invest in shared infrastructure ship twice as fast. The upfront cost is significant (farming the currency to buy heirlooms, or building a design system instead of shipping features) but the compound return is enormous.

The Late Game: Software Factories
#

In WoW’s late game, the most efficient guilds stop running content manually.

They sell raid carries, experienced groups that carry less-skilled players through content for gold. They run GDKP splits, systematic distribution of loot based on a bidding system. They have addon rotations that automate cooldown tracking, buff management, and consumable usage.

The game transitions from playing to orchestrating.

Software factories are the late game of development.

I stop writing code manually. I write specifications that AI agents implement. I stop running tests manually. I design verification systems that run automatically. I stop deploying manually. I build pipelines that ship code continuously.

Like WoW’s late game, running a software factory requires an enormous investment in infrastructure.

A guild can’t sell raid carries without first clearing the raid dozens of times. A team can’t run a software factory without first building the CI/CD, the testing infrastructure, the monitoring, and the AI tooling.

Guilds that try to skip to carry runs without learning the mechanics get exposed when the buyer notices they’re failing. Teams that try to skip to software factories without the infrastructure get exposed when the AI-generated code doesn’t work, doesn’t test, and doesn’t deploy.

Clear the raid first. Then sell the carry.

The Lesson
#

World of Warcraft is a game about progression through coordination.

I start alone, killing boars in a starting zone. I end in a raid of twenty-five, executing a complex sequence of mechanics that requires every player to perform their role flawlessly. The satisfaction isn’t in the gear: it’s in the coordination.

Software development is the same game.

We start alone, fixing bugs in a codebase we don’t understand. We end in organizations of hundreds, shipping systems that require every team to perform their role flawlessly. The satisfaction isn’t in the code: it’s in the coordination.

In WoW, every expansion resets the gear but not the skill. The players who clear content first aren’t the ones with the best loot: they’re the ones who’ve been playing longest, who understand the mechanics deepest, who coordinate most tightly.

In software, every project is different but the fundamentals are the same. The teams that ship fastest aren’t the ones with the most tools: they’re the ones who’ve been building longest, who understand the trade-offs deepest, who coordinate most tightly.

If I’m still solo questing, it’s time to join a guild. If I’m still running dungeons, it’s time to raid. If I’m still equipping greens, it’s time to earn my epics.

For the Horde. Or the Alliance. Just pick a side.

Code Factories: Or How I Learned to Stop Worrying and Build the Belt

tom@tomrochette.com (Tom Rochette) — Sun, 03 May 2026 00:00:00 +0000

I land on an alien planet with nothing but a pickaxe and a furnace.

That’s Factorio. It’s also my first day as a software developer.

In Factorio, I crash-land and must build a rocket to escape. I start by hand-mining iron ore, smelting it in a stone furnace, and crafting simple items. Within hours, I’ve built conveyor belts that carry ore automatically, assemblers that craft without me, and trains that shuttle materials across the map. The factory grows. I go from doing everything myself to watching machines do everything for me.

Software development is following the same trajectory. The question is whether I’m still hand-mining iron ore.

The Belt: The CI/CD Pipeline
#

In Factorio, the conveyor belt is the first automation I build. Instead of walking back and forth carrying ore, I lay down a belt and let it move resources while I do something else.

The CI/CD pipeline is the belt. Every time I push code, tests run, builds compile, deployments ship. I don’t walk the ore to the furnace anymore. The belt carries it.

Teams without CI/CD are the players who never unlock belts. They’re still carrying ore by hand, one commit at a time, manually deploying to servers, manually running tests. It works when the team is small. It doesn’t scale.

Assemblers: The Build System
#

After belts come assembling machines. I feed them ingredients and they output a product. I don’t craft gears by hand anymore (the assembler does it, faster and without mistakes).

Compilers, bundlers, transpilers: these are the assemblers. I feed them source code and they output runnable software. I used to manage dependencies by hand, include scripts individually, and pray the versions matched. Now the assembler handles it.

The parallel goes deeper. In Factorio, I quickly learn that one assembler isn’t enough. I need a chain: iron ore becomes iron plates, iron plates become gears, gears become transport belts. Each step is its own assembler, fed by belts from the previous one.

The build pipeline works the same way. Source code becomes transpiled code, transpiled code becomes bundled assets, bundled assets become container images, container images become deployed services. Each stage is an assembler in a chain. If one assembler is slow, the whole chain backs up. If one assembler breaks, nothing after it gets built.

Inserters: The Integration Points
#

Inserters are the quiet heroes of Factorio. They take items from belts and put them into assemblers, furnaces, and chests. They’re the glue between every machine.

Integration points in software are the inserters. APIs, webhooks, message queues, event streams: they move data between services. Nobody talks about them at conferences. But when an inserter stops working in Factorio, the assembler starves. When an integration point breaks in production, the service starves.

Most production outages aren’t caused by a broken assembler. They’re caused by a broken inserter, a misconfigured webhook, a timed-out API call, a corrupted message in a queue. The machines were fine. The connection between them failed.

The Main Bus: The Monorepo
#

As my Factorio factory grows, I face a critical design decision: how to organize my belts. Most experienced players converge on the same solution, the main bus.

A main bus is a wide highway of parallel belts carrying every resource I need, running in a straight line across my factory. I branch off production lines from the bus, pull what I need, and return byproducts. It’s not the most space-efficient design. It’s not the fastest. But it’s the most understandable, and in a game where my own factory can become incomprehensible, understandability is survival.

A monorepo is the main bus. All the code, all the services, all the shared libraries in one place, organized in a predictable structure. Teams branch off to build their services, pull shared dependencies from the bus, and contribute back. Like Factorio, the monorepo isn’t optimal in every dimension. But when a new developer joins and needs to understand how everything connects, they follow the bus. No archaeology required.

Teams that reject the main bus in Factorio end up with spaghetti, belts crisscrossing everywhere, impossible to trace, impossible to modify without breaking something. Teams that reject the monorepo end up the same way: dozens of microservices with undocumented dependencies, where nobody knows which service calls which, and changing one API breaks three things nobody knew existed.

Logistics Bots: The AI Agents
#

At some point in Factorio, I unlock logistic robots. Flying drones that carry items anywhere in my network. They don’t need belts. They don’t follow paths. I request an item, and a bot brings it.

AI coding agents are the logistics bots. I ask for a function, and the agent writes it. I ask for tests, and the agent generates them. I ask for a bug investigation, and the agent traces the stack. They don’t need me to lay down a belt first. They go directly to the source and bring back what I need.

But here’s what Factorio teaches about bots: they don’t replace belts. Players who try to run everything on bots discover that bots have a capacity limit. When the network gets busy, bots queue up, delivery times spike, and the factory starves. The best factories use bots for the weird, one-off requests and keep belts for the high-throughput, predictable flows.

The best engineering teams do the same. AI agents handle the ad-hoc tasks, the one-off scripts, the bug investigations, the documentation updates. But the core pipeline (the build system, the CI/CD, the deployment process) runs on belts. Predictable. Reliable. Fast.

The Ratios: The System Architecture
#

In Factorio, every recipe has precise ratios. To produce one science pack per second, I need exactly 1.25 assemblers making gears and 0.8 assemblers making copper cable. The math is deterministic. If I get the ratios wrong, I get bottlenecks. One belt backs up while another starves. Resources pile up where they’re not needed and run dry where they are.

System architecture has the same dynamics, just less precise. Every service has throughput limits. Every database has connection pool limits. Every queue has a maximum depth. If the authentication service can handle 100 requests per second but the API gateway is sending 200, there’s a bottleneck. The requests pile up. Timeouts cascade. Users see errors.

Factorio players solve ratio problems with calculators and spreadsheets. They plan their factory before they build it. Software engineers solve the same problems with load testing and capacity planning, or they should. Too many teams build first and measure later, then wonder why production is slow.

Biters: The Production Incidents
#

The alien natives in Factorio are called biters. They attack the factory in increasing waves, drawn by the pollution the machines produce. The more I build, the more they attack. I can ignore them for a while, but eventually they’ll overwhelm my defenses.

Production incidents are the biters. They come in waves, drawn by the complexity of the system. The more services I deploy, the more dependencies I add, the more incidents I attract. I can ignore them for a while, patch the symptom, restart the service, move on. But eventually they’ll overwhelm me.

In Factorio, the solution isn’t to stop building. It’s to build defenses: walls, turrets, artillery. In software, the solution isn’t to stop deploying. It’s to build defenses: monitoring, alerting, automatic rollback, chaos engineering.

The best Factorio players don’t just react to biter attacks. They proactively clear nests before they evolve. The best engineering teams don’t just react to incidents. They proactively eliminate failure modes before they cause outages.

Throughput vs Latency: The Eternal Trade-off
#

Factorio players eventually discover that throughput and latency are different things. A belt with 100 items per minute has high throughput but items take time to travel from one end to the other. A bot delivery is low throughput (one item at a time) but low latency (it goes straight there).

Microservices vs monoliths is the same trade-off. A monolith has high throughput; everything runs in the same process, no network calls. But change latency is high; I deploy the whole thing even if I changed one function. Microservices have low change latency; I deploy one service independently. But throughput suffers from network overhead, serialization, and distributed coordination.

Factorio doesn’t judge me for choosing bots over belts or belts over bots. It just shows me the consequences. Software architecture should work the same way. I choose my trade-offs, but I stay clear about what I’m trading.

The Rocket: Shipping
#

The goal of Factorio is to launch a rocket. Everything I build (every belt, every assembler, every defense) exists to launch that rocket. The goal is easy to forget. Players spend hundreds of hours optimizing a single belt intersection, perfecting a circuit network, or making their factory look pretty. Meanwhile, the rocket sits unbuilt.

Software teams do the same thing. They refactor code that works fine. They migrate to the latest framework. They rebuild systems that don’t need rebuilding. Meanwhile, the product sits unshipped. The users sit unserved. The business sits unimproved.

Factorio teaches a simple lesson: the factory exists to launch the rocket, not the other way around. The code exists to ship the product. Every optimization that doesn’t serve the product is a belt to nowhere.

The Map: The Unknown Unknowns
#

When I start Factorio, the map is covered in fog. I don’t know where the iron is, where the oil is, or where the biters are nesting. I explore by walking into the fog, revealing terrain piece by piece. Sometimes I find a massive ore patch right next to my base. Sometimes I walk into a biter nest and die.

Software development is exploring a fog of war. I don’t know what the users want until I ship. I don’t know what the legacy system does until I try to change it. I don’t know what the dependency actually does until it breaks in production.

The Factorio solution to the fog of war is radar. I build radar stations that slowly reveal the map around them. Not all at once, but gradually, giving me visibility without requiring me to walk everywhere.

Observability is the radar. Logging, metrics, tracing, dashboards: they don’t eliminate the unknown, but they reveal it gradually. I can’t see everything. But I can see enough to make good decisions.

Pollution: Technical Debt
#

Every machine in Factorio produces pollution. Pollution spreads across the map and triggers biter attacks. More machines, more pollution, more attacks. Pollution is the cost of growth.

Technical debt is pollution. Every shortcut, every hack, every “we’ll fix it later” generates debt. Debt spreads through the codebase, making changes harder, triggering bugs, slowing development. More code, more debt, more incidents.

I can’t eliminate pollution in Factorio without eliminating production. I can’t eliminate technical debt without eliminating software. The key is management: build efficiently, clean up regularly, and invest in infrastructure that reduces the debt per feature shipped. Electric furnaces produce less pollution than steel furnaces. Good abstractions produce less technical debt than bad ones.

The Late Game: Software Factories
#

In the late game of Factorio, something interesting happens. I stop building things myself entirely. Instead, I design blueprints, templates for entire sections of factory. I place a blueprint and construction bots build the whole thing automatically. I’m no longer an assembler. I’m an architect.

Software factories are the late game of software development. I don’t write code. I write specifications. I don’t review code. I design verification systems. I don’t debug. I design healing systems.

Like Factorio’s late game, the software factory requires an enormous upfront investment. I need to have built the belts, the assemblers, the bots, the logistics network before I can stamp down blueprints. Software factories require CI/CD, testing infrastructure, monitoring, and AI agents before they can operate autonomously.

Players who try to skip to blueprints in Factorio without building the infrastructure first find that their construction bots can’t reach the build site, don’t have materials, or build the wrong thing. Teams that try to skip to software factories without the infrastructure find that their AI agents produce broken code, can’t deploy, and create more problems than they solve.

The Spidertron: Autonomous Agents
#

The Spidertron is Factorio’s ultimate vehicle. A walking base that I can remote-control, equip with rockets, and send into dangerous territory. It’s the end result of everything I’ve built: it uses the tech I researched, the weapons I crafted, the logistics network I established.

Autonomous AI coding agents are the Spidertron of software development. They roam the codebase, make changes, run tests, deploy code, all while I watch from the map. But like the Spidertron, they’re only as good as the infrastructure behind them. A Spidertron without researched weapons is a walking target. An AI agent without a testing infrastructure is a liability.

The Lesson
#

Factorio is a game about building something that builds itself. I start by doing everything manually. I end by watching machines do everything for me. The satisfaction isn’t in the automation itself: it’s in designing a system that works, that’s elegant, that grows.

Software development is the same game. I start by writing code manually. I end by designing systems that write, test, and deploy code without me. The satisfaction isn’t in the code: it’s in the factory.

If I’m still hand-crafting every iron gear, it’s time to build my first assembler. If I’m still carrying ore by hand, it’s time to lay down a belt. If I’m still reviewing every line of code myself, it’s time to build a verification system.

The factory must grow.

Code Factories: The StarCraft Perspective

tom@tomrochette.com (Tom Rochette) — Sun, 03 May 2026 00:00:00 +0000

You start with four workers, a command center, and fog of war in every direction.

That’s StarCraft. It’s also your first day at a startup.

In StarCraft, you command one of three races (Terran, Protoss, or Zerg), each with radically different economies, armies, and strategies. You gather minerals and vespene gas, build structures, research upgrades, and produce units. You scout the opponent, react to their strategy, and try to win through superior economy, tactics, or both. The clock never stops. The other player never waits.

Building a software organization is the same game with different units. The question is which race you’re playing and whether you know it.

APM: Developer Productivity
#

In StarCraft, APM (actions per minute) is the raw measure of how fast a player can issue commands. Pros sustain 300+ APM over games that last 20 to 40 minutes. Beginners hover around 30.

But high APM doesn’t win games. Efficient APM does. A pro spends most of those actions on macro (building workers, expanding, producing units) and only the necessary actions on micro, controlling individual units in combat. A beginner wastes APM clicking the same unit six times or panicking during a fight.

Lines of code per day is the APM of software development. It measures activity, not impact. A developer who writes 500 lines in a day isn’t necessarily more productive than one who writes 50. The 50-line developer might have deleted 200 lines, simplified an abstraction, or prevented a week of debugging.

The StarCraft lesson: optimize for effective actions, not total actions. In code, optimize for value shipped, not code written.

Worker Production: Hiring
#

In StarCraft, the single most important thing a new player can learn is to never stop making workers. Workers gather resources. Resources fund everything else: units, buildings, upgrades. A player who stops producing workers at the five-minute mark will be economically crushed by one who didn’t, regardless of army composition or tactical skill.

Hiring is your worker production. Every engineer you add increases your resource gathering rate, the rate at which your team can design, build, and ship software. A team that stops hiring after its founding engineers will be outpaced by a team that kept recruiting, even if the founding team was brilliant.

But StarCraft also teaches that worker production has a ceiling. You can only send so many workers to a mineral patch before they queue up and waste time. In software, the ceiling is communication overhead. Add too many engineers to a project and they spend more time coordinating than building. Brooks said it decades ago in The Mythical Man-Month: adding people to a late project makes it later. StarCraft players learn it every game: there’s an optimal number of workers per base, and exceeding it wastes resources.

Expanding: New Teams and Services
#

In StarCraft, one base isn’t enough. The mineral patches deplete. Gas geysers run dry. To keep growing, you must expand, build a new command center, nexus, or hatchery at a new resource location.

Each expansion is a bet. It costs resources to build. It takes time to become profitable. And the expansion is vulnerable: spread across the map, harder to defend, exposed to attack.

Starting a new team or service is expanding. You invest resources (hiring, onboarding, infrastructure) in exchange for future throughput. The first team’s codebase, like a mineral patch, eventually becomes congested. Too many engineers working on the same service creates merge conflicts, deployment bottlenecks, and architectural compromises. A new team with its own service spreads the load.

But like StarCraft expansions, new teams are vulnerable. They don’t yet know the codebase, the domain, or the culture. They’ll make mistakes the first team already learned from. They’ll build things that duplicate or conflict with existing systems. And they require protection (mentoring, clear interfaces, architectural guidance) or they’ll be overrun by the complexity the first team already tamed.

StarCraft players know: expand when your main base is saturated, not when you’re under attack. Software leaders should know: create new teams when the current team is at capacity, not when the project is already late.

The Supply Cap: Organizational Scaling
#

In StarCraft, you can’t just build an infinite army. Every unit costs supply. Terran supply depots, Protoss pylons, Zerg overlords: each race has its own mechanism for increasing the supply cap. If you hit the cap, production halts. Your factories, barracks, and starports sit idle until you build more supply.

Organizational scaling has supply caps too. They just aren’t as explicit.

The first cap is communication. A team of 5 people has 10 communication channels. A team of 15 has 105. At some point, people spend more time talking than building, and adding another engineer actually decreases output.

The second cap is architecture. A monolith can support a certain number of contributors before merge conflicts, test suite times, and deployment coordination become unbearable. You need to split the monolith (build a pylon, if you will) to increase the cap.

The third cap is process. A small team doesn’t need sprint planning, architecture review boards, or release managers. A large team does. Each process is a supply depot: it costs resources to build but increases the number of people who can work together productively.

Teams that ignore the supply cap wonder why their army is small despite having plenty of factories. The factories are there. The supply isn’t.

Build Orders: Project Plans
#

Every StarCraft game begins with a build order, a planned sequence of actions for the first few minutes. Build a supply depot at 10 supply. A barracks at 12. A refinery at 13. Expand at the natural at 20.

Build orders aren’t rigid scripts. They’re opening principles, a sequence that has been proven to lead to a strong mid-game position. Players deviate when they scout something unexpected, but they always have a plan to return to.

Project plans are build orders. You don’t start building features randomly. You have a sequence: set up the repository, configure CI/CD, build the core domain model, add the API layer, implement authentication, deploy to staging. The order matters because each step depends on the previous one.

But just like in StarCraft, the build order only covers the opening. After the first few minutes, the game becomes dynamic. You react to what you see. You adapt to the opponent’s strategy. The build order gave you a strong position: it didn’t win the game.

Agile methodology is the StarCraft mid-game. You’ve executed your build order; the project is set up, the architecture is sound. Now you play reactively, adjusting to user feedback, market changes, and technical surprises. The build order got you here. Reaction wins the game.

Scouting: User Research
#

In StarCraft, if you don’t scout, you die. Period. A player who builds the wrong units because they didn’t know the opponent was going air gets crushed. A player who expands into a choke point the opponent already controls loses the expansion. Information is more valuable than any unit.

User research is scouting. If you don’t talk to users, watch them use your product, read their support tickets, and analyze their behavior, you’re building blind. You might be building the perfect counter to a strategy the opponent isn’t using. You might be expanding into territory nobody wants.

StarCraft players send a worker to scout at supply 13. They sacrifice a unit to gain information. Good software teams do the same: they sacrifice development time to talk to users, run usability tests, and analyze metrics. The cost of scouting is always less than the cost of building the wrong thing.

Tech Trees: Technology Choices
#

Every StarCraft race has a technology tree. You can’t build battlecruisers without a starport, a fusion core, and an armory. You can’t research stimpack without a tech lab on your barracks. Each technology unlocks new capabilities but requires investment in the prerequisite technologies.

Technology stacks are tech trees. You can’t deploy containers without a container runtime. You can’t run Kubernetes without understanding networking, DNS, and certificate management. You can’t implement real-time features without WebSockets, which requires understanding persistent connections, which requires understanding your load balancer’s timeout settings.

The StarCraft lesson about tech trees is simple: don’t tech too fast and don’t tech too wide.

Teching too fast means skipping army production to rush advanced technology. In StarCraft, this loses to an early attack. In software, this means spending months building infrastructure while shipping nothing. The business can’t wait for your perfect Kubernetes setup. Ship something with simpler tech and upgrade later.

Teching too wide means researching every upgrade simultaneously. In StarCraft, this commits resources to too many upgrades at once and leaves you weak everywhere. In software, this means adopting every new framework, database, and tooling option. Your team can’t be experts in everything. Pick a path through the tech tree and commit to it.

Unit Composition: Team Composition
#

In StarCraft, army composition matters more than army size. A player with 50 marines loses to a player with 10 banelings and 20 zerglings. A player with 20 stalkers loses to a player with 10 immortals. Each unit has strengths and weaknesses, and the right combination is stronger than any individual unit.

Team composition works the same way. Ten frontend developers can’t build a backend service. Ten senior engineers can’t ship quickly without junior engineers handling the simpler tasks. Ten generalists can’t match a team with specialized expertise in security, performance, and DevOps.

The ideal StarCraft army mixes unit types that cover each other’s weaknesses. Marines deal high damage but are fragile; medivacs keep them alive. Zealots are strong in close combat but slow; sentries create force fields to trap enemies.

The ideal software team mixes skills the same way. Backend engineers build the services. Frontend engineers build the interfaces. DevOps engineers build the infrastructure. Security engineers build the defenses. No single role can win the game alone.

Multitasking: Context Switching
#

StarCraft demands multitasking. While your army fights at the front, your economy must keep producing at home. While you scout the enemy, your upgrades must keep researching. Neglect one task and the whole performance suffers.

Software development demands the same. While you write code, production issues arise. While you debug a problem, meetings are scheduled. While you plan the next sprint, the current sprint falls behind.

StarCraft players learn to use control groups, binding units and buildings to hotkeys so they can jump between tasks instantly. Press 1, manage the army. Press 2, build workers. Press 3, research upgrades. The hotkeys don’t reduce the number of tasks, but they reduce the cost of switching between them.

In software, your control groups are your tools and workflows. A good IDE setup lets you switch between files instantly. A good terminal setup lets you switch between environments instantly. A good project management tool lets you switch between tasks instantly.

But StarCraft also teaches that there’s a hard limit to multitasking. Even pros can’t manage five simultaneous drops, a base race, and an upgrade timing all at once. They prioritize. They let minor fights play out automatically while they manage the critical ones.

Software developers need to learn the same lesson. You can’t context-switch between five tasks and do any of them well. Prioritize the critical path. Let minor tasks wait. Not everything is a drop in your mineral line.

Creep Spread: Codebase Quality
#

The Zerg provide the clearest metaphor for codebase quality. Creep is the organic substance that Zerg structures generate, spreading across the ground. Zerg units move faster on creep. Zerg structures can only be built on creep. Creep tumors extend the network, and a well-spread creep carpet gives the Zerg player vision, mobility, and territorial control.

Codebase quality is creep spread. Good test coverage, clear documentation, consistent naming conventions, and well-defined interfaces: these are your creep tumors. Each one extends the area where future development moves faster. New engineers onboard more quickly on a well-documented codebase. Refactoring is safer with comprehensive tests. Features ship faster when the interfaces are clean.

Terran and Protoss players hate creep. It gives the Zerg vision and speed in territory that should be neutral. Technical debt is the reverse: it gives bugs and confusion territory that should be clean. Every hardcoded value, every undocumented assumption, every god class is an area where development slows down and more bugs appear.

The Zerg lesson: invest in creep spread early and often. A Zerg player who tumors aggressively in the first five minutes controls the map in the tenth. A team that invests in code quality early ships faster in the long run. Not because quality is its own reward, but because quality compounds.

Ladder Anxiety: Imposter Syndrome
#

Every StarCraft player knows ladder anxiety. That feeling before clicking the “Find Match” button, the fear of losing, of being exposed as a fraud, of dropping a league and having everyone see.

The anxiety is universal. Grandmasters feel it. Day9 famously talked about how terrified he was to play his placement matches, and he was one of the best players in the world.

Imposter syndrome in software is ladder anxiety. The fear of submitting a pull request because your code might be wrong. The fear of speaking up in an architecture meeting because your idea might be bad. The fear of applying for a senior role because you might not be good enough.

StarCraft players overcome ladder anxiety the same way every time: by playing. Not by studying build orders. Not by watching replays. By clicking the button and playing the game. Losses stop hurting after the hundredth one. Wins start feeling earned.

Software developers overcome imposter syndrome the same way. Submit the pull request. Speak up in the meeting. Apply for the role. The fear doesn’t go away. You just learn that it’s not predictive of outcome.

Cheese: Shortcuts and Hacks
#

Every StarCraft player has been cheesed. A cannon rush in your mineral line. A proxy barracks outside your base. A six-pool of zerglings that arrives before you have any defense.

Cheese strategies are high-risk, high-reward. They win quickly against unprepared opponents and lose decisively against prepared ones. Nobody wins a tournament with cheese alone. But everyone encounters it, and everyone has to learn to defend against it.

Technical shortcuts are cheese. Copy-pasting code from Stack Overflow without understanding it. Deploying directly to production without tests. Hardcoding a configuration value because you’re in a hurry.

Like StarCraft cheese, technical shortcuts work in the short term. The code runs. The feature ships. The deadline is met. But the opponent (in this case, future you or your teammate) is unprepared for the consequences. The hardcoded value becomes a production incident. The untested code breaks in an edge case. The copy-pasted solution has a security vulnerability.

StarCraft players learn to scout for cheese early and defend against it. Software developers need to do the same. Code review catches shortcuts before they merge. Linting and static analysis catch them before they deploy. The defense doesn’t have to be elaborate, just present.

The Late Game: Software Factories
#

In the late game of StarCraft, something shifts. Individual battles matter less than economy and production. The player with more bases, more production facilities, and better upgrades wins through attrition. They replace losses faster. They tech-switch faster. They recover from setbacks faster.

Software factories are the late game of software development. Individual code contributions matter less than the systems that produce them. The team with better CI/CD, better testing infrastructure, better monitoring, and better AI tooling ships faster. They recover from incidents faster. They adapt to changing requirements faster. They replace departing engineers faster.

In StarCraft, the late game rewards the player who invested in economy during the early and mid game. The player who cut workers to build a bigger army might win a battle, but they lose the war. In software, the late game rewards the team that invested in infrastructure when it would have been faster to just ship features. The team that skipped tests to hit a deadline might ship faster this quarter, but they slow down every quarter after.

Playing the Race: Choosing Your Stack
#

In StarCraft, race selection defines everything. Terran is positional and mechanical (siege tanks, bunkers, planetary fortresses). Protoss is elegant and powerful (expensive units, warp-in mechanics, force fields). Zerg is swarm-like and reactive (expendable units, rapid reinforcement, creep spread).

Each race rewards a different mindset. A player who tries to play Terran like Zerg (aggressive, expendable, swarm-like) loses. A player who tries to play Protoss like Terran (defensive, positional, slow) loses. You have to play your race’s strengths.

Technology stacks are races. A Python/Django stack rewards rapid development and convention-over-configuration (Protoss-like elegance). A Java/Spring stack rewards enterprise robustness and type safety (Terran-like positional strength). A Go microservices stack rewards simplicity, concurrency, and operational efficiency (Zerg-like speed and resilience).

Teams that try to fight their stack’s nature lose. Using Python for high-performance computing. Using Java for rapid prototyping. Using Go for enterprise business logic. Each can work, but each is fighting the race’s design.

Play your race. Or in StarCraft terms: pick Random, learn all three, and choose the one that fits the game you’re playing.

The GG: Knowing When to Refactor
#

In StarCraft, there’s a moment every player must learn to recognize: the game is lost. Your economy is destroyed. Your army is gone. Your opponent has three bases to your one. Fighting on is admirable but wasteful.

Good players type “gg” (good game) and leave. Not because they’re quitters. Because the time spent losing a doomed game is better spent starting a new one where they can apply what they learned.

The software equivalent is knowing when to rewrite. Not every codebase can be saved. Sometimes the technical debt is so deep, the architecture so convoluted, the assumptions so wrong, that incremental improvement is slower than starting fresh.

But here’s where the StarCraft analogy gets tricky. In StarCraft, a new game starts clean. In software, a rewrite inherits the constraints of the existing system: the users, the data, the integrations. The “gg” in software isn’t abandoning the project. It’s recognizing that the current implementation has reached the point of diminishing returns and a new approach will serve everyone better.

StarCraft players learn to recognize the threshold through experience. They don’t quit at the first setback. They quit when recovery becomes impossible. Software teams need the same judgment. Don’t rewrite at the first sign of technical debt. Rewrite when the debt makes every change slower than a fresh start would be.

The Lesson
#

StarCraft is a game of simultaneous decisions under time pressure. You manage economy, technology, army composition, map control, and reconnaissance all at once, while an opponent does the same and tries to disrupt you. The best players aren’t the ones with the fastest hands: they’re the ones who make better decisions about where to invest their attention.

Software development is the same game. You manage features, infrastructure, team composition, code quality, and user feedback all at once, while the market changes and competitors advance. The best teams aren’t the ones who write the most code: they’re the ones who make better decisions about where to invest their resources.

In StarCraft, every game is different. The map changes, the opponent changes, the meta shifts. But the fundamentals remain: workers gather resources, buildings unlock technology, scouting reveals information, and good decisions win games.

In software, every project is different. The domain changes, the team changes, the technology shifts. But the fundamentals remain: engineers build features, infrastructure enables scale, user research reveals needs, and good decisions ship products.

If you’re still playing single-player, it’s time to scout the map. If you’re still on one base, it’s time to expand. If you’re still manually producing every unit, it’s time to set a rally point.

GL HF.

task-stack - A persistent task stack that lives in your system tray

tom@tomrochette.com (Tom Rochette) — Sat, 02 May 2026 00:00:00 +0000

I’ve been using the workstack concept for years to track what I’m working on and where I got interrupted. task-stack is the natural evolution: a small system tray app that keeps a persistent, reorderable stack of tasks always one hotkey away.

The top of the stack is your current task. Everything below the top entry is queued. Press Ctrl+Shift+T from anywhere and a compact window appears where you can add, reorder, promote, and remove tasks. Close the window and the app stops taking screen space. The tray icon always shows the current task as its tooltip.

Why a stack, not a list
#

Todo lists are flat. Kanban boards carry more overhead. When you’re deep in flow and get interrupted, you don’t want to prioritize a backlog: you want to push something on top of what you’re doing and pop it off when you’re done.

A stack models interruptions naturally:

Push: a new urgent task goes on top and becomes the current task.
Pop: mark the task done and the next task becomes current automatically.
Reorder: something can wait? move the task down. Something urgent? promote the task to the top.

No projects, no tags, no due dates. Just a stack of things to do, in order.

Features
#

System tray icon with the current task as tooltip and a “Mark Done (pop)” action.
Global hotkey (default: Ctrl+Shift+T, configurable) to bring the stack window forward from any application.
Keyboard-driven editing: add tasks with Enter, reorder with arrow keys, promote with /, remove with Backspace. Full shortcut table in the README.
Persistent state in ~/.task-stack.yaml. Easy to inspect, back up, or version control.
Soft deletes: removed tasks stay in the YAML file with a deleted_at timestamp, so you keep a full history.
Timestamps: each task tracks created_at, started_at (first time the task became current), and last_current.
Cross-platform: works on macOS, Linux, and Windows.

Quick start
#

git clone https://github.com/TomzxCode/task-stack.git
cd task-stack/python
uv sync
uv run task-stack

The app starts in the system tray. Press the hotkey or pick “Open Stack” from the tray menu.

Data format
#

Tasks are stored in ~/.task-stack.yaml as a simple YAML list:

- text: Write blog post about task-stack
  created_at: '2026-05-02T10:00:00+00:00'
  started_at: '2026-05-02T10:00:00+00:00'
  last_current: '2026-05-02T10:30:00+00:00'
- text: Review pull requests
  created_at: '2026-05-02T09:00:00+00:00'
  deleted_at: '2026-05-02T09:45:00+00:00'

Active tasks come first in stack order. Soft-deleted tasks are appended at the end with a deleted_at timestamp. Settings (window geometry, hotkey) live in ~/.task-stack.settings.yaml.

Configure the hotkey
#

Edit ~/.task-stack.settings.yaml:

hotkey: ctrl+shift+t
# hotkey: alt+space
# hotkey: cmd+shift+space

Restart the app to apply the new hotkey. The current hotkey is shown in the tray menu.

When task-stack is useful
#

Developers context-switching between code reviews, bug fixes, and feature work. Push the interruption on the stack, pop the interruption when done, resume what you were doing.
Anyone who works with interruptions and wants a lightweight way to track pending work without opening a full project management tool.
Time tracking enthusiasts who want started_at / last_current timestamps to reconstruct what they worked on during the day.

gh-cached - Browse GitHub issues and PRs without burning through your API rate limit

tom@tomrochette.com (Tom Rochette) — Thu, 30 Apr 2026 00:00:00 +0000

Note (2026-07-02): gh-cached has been merged into ghx.

I use the GitHub CLI (gh) heavily, and I kept hitting the API rate limit. The pain is worst when I’m triaging issues across multiple repos or reviewing a backlog of PRs. Every gh issue list, every gh pr view, every comment fetch costs API calls I don’t need to spend.

I built gh-cached to solve the rate limit problem. gh-cached is a standalone Go binary that wraps the GitHub GraphQL API and caches every response to disk, so subsequent commands read from the local cache instead of hitting GitHub again.

The problem
#

The official gh CLI is excellent, but it’s designed for live, one-off interactions. There’s no built-in caching layer. Running gh issue list twice in five minutes makes two API calls. Browsing hundreds of issues with their comments in a large repository burns through the rate limit fast.

The problem gets worse when AI coding assistants query GitHub on my behalf. Multiple agents, multiple tools, all hitting the same API. The rate limit becomes a bottleneck.

How gh-cached works
#

go install github.com/tomzxcode/gh-cached@latest

The cache lives at ~/.cache/gh-cached/<host>/<owner>/<repo>. Each issue and PR is stored as its own JSON file, including all comments.

Pre-populate the cache:

gh-cached cache                          # current repo
gh-cached cache --repo cli/cli           # any repo
gh-cached cache --cache-duration 120     # fresh for 2 hours

Browse issues and PRs from cache:

gh-cached issue list                     # open issues
gh-cached issue list --state all         # everything
gh-cached issue list --label bug         # filter by label
gh-cached issue list --author alice      # filter by author
gh-cached issue view 42 --comments       # view with comments

gh-cached pr list --state merged         # merged PRs
gh-cached pr list --draft                # draft PRs only
gh-cached pr view 10 --comments          # view with comments

When the cache is fresh, all filtering happens in-memory with zero API calls. When the cache is stale, gh-cached falls back to the GitHub API and updates the cache.

Why a separate tool instead of a gh extension?
#

Two reasons.

First, gh-cached uses GraphQL under the hood, which lets the tool fetch issues and PRs with their comments in fewer round trips than the REST API the official CLI defaults to. The cache-then-filter pattern also means one pre-fetch can be queried many ways without going back to GitHub.

Second, independence. gh-cached works with just a GH_TOKEN environment variable, or falls back to gh auth token if the GitHub CLI is already installed. No plugin registration, no extension marketplace, just a binary you put in your PATH.

The caching strategy
#

The tool uses different strategies depending on the command:

cache fetches everything (all states, with comments) and writes one JSON file per item. Skips items already cached within the --cache-duration window (default: 60 minutes).
issue list / pr list reads cached files and filter in-memory when fresh. Falls back to the API with server-side filters when stale.
issue view / pr view serves from the individual cached file if less than 60 minutes old. Otherwise fetches from the API and updates the cache.

A single gh-cached cache run gives fast, offline-capable access to all issues and PRs for the next hour.

Authentication
#

Set the token in the environment:

export GH_TOKEN=ghp_...
or
export GITHUB_TOKEN=ghp_...

Or just have gh installed and authenticated: gh-cached will use gh auth token as a fallback.

When gh-cached is useful
#

AI coding assistants that query GitHub repeatedly. Pre-populate the cache once and let tools read from disk instead of making redundant API calls.
Repository triage where hundreds of issues need scanning with different filters. One cache fetch, then instant in-memory filtering.
Working with multiple repositories where context switches are frequent. Cache each repo once and browse offline.
Rate-limited environments like CI pipelines or shared machines where every API call is limited.

What to Do Next
#

go install github.com/tomzxcode/gh-cached@latest
# or download a binary from https://github.com/TomzxCode/gh-cached/releases/tag/latest
gh-cached cache --repo your-org/your-repo
gh-cached issue list --state all
gh-cached pr list --state all

Profit-as-a-Service

tom@tomrochette.com (Tom Rochette) — Sat, 18 Apr 2026 00:00:00 +0000

Software-as-a-Service gave us recurring revenue. Platform-as-a-Service gave us managed infrastructure. The next abstraction is obvious in hindsight: Profit-as-a-Service.

The Pattern
#

Every major shift in the software industry has been about abstracting away complexity.

On-premise servers became cloud infrastructure. Custom software became SaaS subscriptions. Manual operations became automation.

Each layer removes something the customer previously had to manage themselves. Each layer turns a cost center into a service. Each layer makes the underlying complexity someone else’s problem.

Profit-as-a-Service is the logical conclusion of this trend. Instead of selling software that helps you make money, you sell the money-making itself.

What It Looks Like
#

A traditional SaaS company sells you a tool. You still need to figure out how to use it to generate revenue.

A Profit-as-a-Service company sells you an outcome. The tool is invisible. The process is invisible. You pay for the result.

Examples already exist:

Algorithmic trading platforms that let you deploy capital and collect returns without understanding the underlying strategies.
AI-powered dropshipping services that handle product selection, listing, pricing, and fulfillment while you provide the capital.
Automated content farms that generate SEO-optimized articles, monetize them with ads, and split the revenue with you.
AI sales agents that prospect, qualify, and close deals on your behalf, charging only a commission on closed revenue.
Robo-advisors that manage investment portfolios algorithmically, charging a fraction of traditional advisory fees.

In each case, the customer provides capital or data. The service provides everything else. Revenue is shared, not subscribed to.

Why Now
#

Three forces are converging to make Profit-as-a-Service viable at scale.

1. AI can now execute complex business processes autonomously
#

Large language models can write marketing copy, analyze markets, negotiate with customers, and generate code. Multi-agent systems can coordinate these capabilities into end-to-end business workflows. What previously required a team of specialists can now be done by a single API call chain.

2. Infrastructure is fully commoditized
#

Starting a business used to require incorporating, hiring, building software, and navigating regulations. Now you can spin up a fully operational e-commerce store in an afternoon using off-the-shelf tools. The barrier to entry for almost every digital business has collapsed to near zero.

3. Distribution is algorithmic
#

Social media algorithms, search engines, and ad platforms have made customer acquisition a math problem. If you can compute the expected value of an impression, you can acquire customers profitably at scale. AI is better at computing expected value than humans.

The Economics
#

The unit economics of Profit-as-a-Service are deceptively simple.

The service provider operates a system that generates revenue. The customer provides the input: capital, data, or access to a market. Revenue is split between the provider and the customer.

For the customer, the arrangement is attractive because:

No upfront investment in tools or expertise.
Risk is aligned (the provider only makes money if you make money).
Scalability is built in (the system can run 24/7 without human intervention).

For the provider, the arrangement is attractive because:

Revenue scales with customer success (no ceiling from fixed subscriptions).
Customer acquisition is easier (pay-for-performance is an easy sell).
Margins improve with scale (the same system serves many customers).

The critical metric is the spread between what the system generates and what it costs to operate. If a system generates $10,000/month per customer and costs $2,000/month to run, the provider can keep $4,000 and give the customer $4,000. Both parties are happy. The system scales linearly in cost but exponentially in value.

The Risks
#

Profit-as-a-Service is not without significant risks.

Alignment risk
#

When you outsource profit generation, you also outsource decision-making. The provider’s optimization target may diverge from yours, a textbook principal-agent problem. A trading algorithm might maximize short-term returns at the cost of long-term stability. A content farm might optimize for clicks at the cost of your brand reputation.

Concentration risk
#

If the service provider goes down, your revenue goes to zero. There is no fallback when the entire business process is a black box. Diversification across multiple providers becomes essential but difficult.

Regulatory risk
#

Financial services are heavily regulated. When you abstract away the details of money-making, you may also abstract away compliance. The line between “software service” and “financial service” is thin and getting thinner.

Race to the bottom
#

When the barrier to entry is low, competition drives margins toward zero. The first provider to offer automated dropshipping captures most of the value. The hundredth provider competes on price until nobody makes money.

Dependency trap
#

Once a business relies on Profit-as-a-Service, transitioning away is extremely difficult. The provider owns the process, the data, and the relationships. Switching costs are not just technical but operational and strategic.

The Spectrum
#

Profit-as-a-Service is not binary. It exists on a spectrum of how much of the profit-generating process is abstracted away.

Level 0: You do everything. You buy tools and operate them yourself. Traditional software.

Level 1: AI assists you. You use AI tools to accelerate specific tasks. Copilots and assistants.

Level 2: AI operates under your supervision. You define strategy, AI executes tactics. Current state of most AI-powered businesses.

Level 3: AI runs the process, you provide direction. You set constraints, AI handles the rest. Emerging today.

Level 4: AI runs everything, you provide capital. You fund the operation, AI decides how to deploy it. Algorithmic trading, robo-advisors.

Level 5: AI runs everything, including capital allocation. Fully autonomous business entities. None exist yet, but the trajectory is clear.

Most businesses today operate at Level 0 or 1. The opportunity is in moving up the spectrum.

Who Wins
#

The winners in the Profit-as-a-Service economy will be:

Platform providers who own the infrastructure that makes Profit-as-a-Service possible. If you operate the AI system that generates profit for thousands of businesses, you capture a slice of every dollar earned.

Capital providers who can efficiently allocate resources across multiple Profit-as-a-Service offerings. When starting a business requires no expertise, access to capital becomes the primary competitive advantage.

Specialists who can handle the edge cases that AI cannot. Regulatory compliance, strategic partnerships, and brand building remain human-dominated activities.

Arbitrageurs who identify Profit-as-a-Service opportunities before they become commoditized. The window between “novel” and “saturated” is shrinking, but the rewards for being early are enormous.

Who Loses
#

The losers will be:

Middlemen whose value proposition was information asymmetry. When AI can access and process all available information, intermediaries add no value.

Consultants who sold expertise that can now be codified. If your consulting practice can be reduced to a prompt, it will be.

SaaS companies that failed to move up the value chain. A CRM that helps you track sales will lose to an AI that makes sales for you.

Employees whose jobs consisted of executing repeatable business processes. This is the uncomfortable truth that applies across industries.

The Question
#

Profit-as-a-Service is not a prediction. It is a description of what is already happening.

The question for any business is not whether this trend will affect you. The question is whether you will be the provider or the customer.

If your business processes can be automated by AI, they will be. If you are the one automating them, you are the Profit-as-a-Service provider. If you are the one whose processes are being automated, you are about to become a customer.

Choose wisely.

The Future of Code Review: How AI Makes Human Review Obsolete

tom@tomrochette.com (Tom Rochette) — Sat, 18 Apr 2026 00:00:00 +0000

The traditional code review is ending. Not because it is unnecessary, but because it is becoming unnecessary.

For decades, code review has been a central practice of software engineering. Pull requests, peer reviews, endless rounds of comments: these practices are how we have maintained code quality. But AI is fundamentally changing that practice. In my view, the question is not whether AI will replace human code review, but how quickly.

The Problem With Human Code Review
#

Human code review suffers from three fatal flaws:

It does not scale. As teams grow, review backlogs grow. Developers wait days or weeks for feedback, blocking progress.
It is inconsistent. Reviews vary widely based on who is reviewing, when they are reviewing, and how tired they are.
It is expensive. Senior engineers spend significant time reviewing code instead of building features. In high-cost engineering organizations, this adds up to millions of dollars annually.

The alternative, no reviews at all, is not viable either. Shipping unreviewed code leads to security vulnerabilities, bugs, and technical debt.

The AI Solution: Software Factories
#

A new paradigm is emerging: the Software Factory. Instead of humans reviewing code, AI systems verify, test, and heal code autonomously. The Software Factory is not theoretical, it is already running in production.

Consider StrongDM’s Software Factory, which launched in July 2025. A team of three people (a CTO, a senior manager, and a new hire) built a system that autonomously clones core products like Okta, Jira, and Slack. Their target: $1,000 per day per engineer in tokens. That sounds expensive until you realize what they are shipping.

How It Works
#

The Software Factory approach replaces human review with six verification layers:

1. Competitive Generation
#

Instead of one AI writing code, run three in parallel. Three models run in parallel, each generating a different implementation. An automated evaluator selects the best output based on passing tests, minimal diffs, and fewer dependencies. The cost of running three models is trivial compared to the quality gain.

2. Iterative Refinement (Trycycle)
#

Define the problem, write a plan, ask “is it perfect?” If not, try again. Implement, then ask “is it perfect?” If not, try again. Trycycle runs this loop autonomously for hours.

3. Scenario-Based Validation
#

Treat scenarios like machine learning holdout sets. Store acceptance scenarios outside the codebase, then have an LLM judge whether the implementation satisfies them. Instead of a binary “tests pass”, you get a probabilistic satisfaction score measuring trajectory toward success.

4. Observability and Healing
#

Every interaction in the system gets logged to an execution database (CXDB). A Healer agent monitors this database, clusters similar problems, and writes prescriptions. No human bug reports. No human triage. Just autonomous detection and fixing.

5. Digital Twin Testing
#

Clone critical external dependencies: Google Sheets, Slack, Jira, authentication providers. Build replicas that AI agents cannot distinguish from production. Test in the most realistic environment possible without touching actual production systems.

6. Adversarial Verification
#

Separate the coding agent from the verification agent. Have a third agent actively try to break what was built. Enforce that verification criteria are authored before code, not after. This separation prevents the common anti-pattern of writing tests to match implementation rather than specify behavior.

The Economic Case
#

This approach is not just about quality, it is about economics.

StrongDM’s team reports seeing 21% more tasks completed and 98% more pull requests shipped. One case study: Nubank migrated an eight-year ETL monolith (six million lines, one thousand engineers) from an 18-month timeline to weeks. That is an 8-12x efficiency improvement with 20x cost savings.

The breakeven point is 50-70 pull requests per month. Above that threshold, the AI factory costs less than human review while delivering higher velocity.

The Five-Level Evolution
#

Dan Shapiro at StrongDM describes five levels of AI-assisted development:

Level 0: Manual (you write everything) Level 1: Offloading discrete tasks (ChatGPT for regex) Level 2: AI-native tools (90% of “AI” developers today) Level 3: Human-in-the-loop manager (reviewing all code) Level 4: You are now a product manager (spec, argue, craft skills, check tomorrow) Level 5: Dark Factory (black box: specs → software)

Most teams today are stuck at Level 2 or 3. The future is Levels 4 and 5, where humans specify constraints and AI handles everything else.

What This Means for Engineers
#

Your job is not to write code. Your job is not to read code. Your job is to solve quality problems so the factory can run.

This approach requires a philosophical shift. Instead of “how do I review this code?”, ask “why am I doing this?” If you can describe what is wrong, you can automate it. If you can describe what quality looks like, you can codify it as a verification rule.

The era of human-centric development is ending. AI compilers will transform specifications into deployed software. Teams will consist of AI business analysts, AI DevOps engineers, AI QA specialists, and AI compilers.

What to Do Next
#

The transition does not happen overnight. A realistic 16-week roadmap:

Weeks 1-2: Install Trycycle skill and competitive generation pattern Weeks 3-4: Build execution database and scenario framework Weeks 5-6: Implement Healer agent for autonomous fixes Weeks 7-8: Build digital twins for critical integrations Weeks 9-12: Migrate existing codebase to spec-driven workflow Weeks 13-16: Fine-tuning and compounding learning

The results compound. Weeks 1-4 might yield 5-10x velocity on simple tasks. By week 16, teams report 2x monthly speed improvements with compounding gains continuing.

Open Questions
#

The transition is not a solved problem. Key research questions remain:

Is $1,000/day per engineer in tokens realistic or an outlier?
How do patterns learned in one domain transfer to another?
When does fine-tuning cost outweigh compounding benefits?
What specific patterns trigger unavoidable human review?
How do you validate security without human review of auth logic?

These questions are not blockers, they are opportunities for teams to pioneer solutions.

The End of an Era
#

The traditional code review served us well. But like manual testing before automated test suites, its time is passing. The future is not humans reviewing AI code. It is humans designing verification systems that make human review unnecessary.

The question is no longer whether your team will adopt this approach. The question is whether your competitors will adopt it first.

References
#

Primary Sources

StrongDM Software Factory. Production deployment of autonomous code generation systems. https://factory.strongdm.ai/

Kilroy. Open-source CLI for running StrongDM-style pipelines locally. https://github.com/danshapiro/kilroy

Attractor. Provider-agnostic framework for autonomous code generation. https://github.com/strongdm/attractor

Trycycle. Simple skill for iterative refinement loops. https://github.com/danshapiro/trycycle

Devin. AI-powered software engineering platform with fine-tuning capabilities. https://devin.ai/

Analysis and Commentary

Willison, Simon. “Software Factory.” https://simonwillison.net/2026/Feb/7/software-factory/

Shapiro, Dan. “The Five Levels.” https://www.danshapiro.com/blog/2026/01/the-five-levels/

Shapiro, Dan. “Dark Factories.” https://www.danshapiro.com/blog/2026/03/dark-factories/

Shapiro, Dan. “You Don’t Write the Code.” https://www.danshapiro.com/blog/2026/02/you-dont-write-the-code/

LukePM. “The Software Factory.” https://lukepm.com/blog/the-software-factory/

Latent Space. “Reviews Dead.” https://www.latent.space/p/reviews-dead

Case Studies

Nubank ETL Migration. Eight-year monolith migrated in weeks using Devin. https://devin.ai/

StrongDM Security Software. Autonomous cloning of Okta, Jira, and Slack. https://factory.strongdm.ai/

The Survival of the Smartest: Exploring Darwinian Software Development

tom@tomrochette.com (Tom Rochette) — Sun, 22 Feb 2026 00:00:00 +0000

Prompt
#

Write an article about Darwinian software development, the use of LLM swarms to identify the best solution to a problem.

Answer
#

In traditional software development, software is “built.” An architect designs a blueprint, and developers write the code. But with Generative AI, we are moving toward a paradigm where software is evolved.

Darwinian Software Development is an emerging methodology that uses “swarms” of Large Language Models (LLMs) to iterate, compete, and select the most efficient code through a process mirroring natural selection.

How the Swarm Works
#

Instead of asking a single AI to write a function, Darwinian development deploys a multi-agent system (a swarm) to tackle the same problem from different angles. The process generally follows four biological phases:

Variation (The Mutation): Multiple LLM agents are given the same prompt but with different system instructions. One might prioritize memory efficiency, another readability, and a third raw speed.
Competition (The Struggle for Life): The agents generate dozens of potential solutions. The solutions aren’t just checked for syntax; they are run in a “sandbox” against unit tests and edge cases.
Selection (Fitness Function): An automated “Judge” agent (or a specialized testing suite) evaluates the outputs. Only the code that passes the most tests with the lowest latency or resource consumption “survives.”
Heredity (Refinement): The winning code is then used as the “DNA” for the next generation. The swarm takes the best-performing snippet and attempts to optimize it further until a “perfect” solution is reached.

Why Swarms Outperform Single Models
#

The “Darwinian” approach solves the two biggest problems in AI-assisted coding: hallucinations and getting stuck on a single approach.

Error Correction: If one agent introduces a bug, the likelihood that five other agents will make the exact same error is low. The swarm acts as a self-healing mechanism.
Diverse Architectures: One LLM might get stuck on a specific logic path. A swarm explores many possible solutions across the fitness landscape, finding creative solutions a human (or a single AI) might never consider.
Performance Benchmarking: By racing agents against each other, the system naturally optimizes for performance.

Feature	Traditional Development	Single LLM Coding	Darwinian Swarm
Speed	Slow (Human-paced)	Very Fast	Fast (Iterative)
Reliability	High (Human-vetted)	Medium (Hallucination risk)	Very High (Cross-vetted)
Optimization	Manual	Basic	Automated/Evolutionary

The “Fitness Function” Problem
#

The biggest challenge in Darwinian development isn’t the AI; it’s the criteria. For natural selection to work, the environment must be rigorous. If your “fitness function” (the tests you use to judge the code) is poorly written, the AI can evolve to pass the tests while the code remains broken. This failure mode is known as reward hacking. To counter reward hacking, modern swarms often include “Adversarial Agents” whose only job is to write difficult unit tests that expose the flaws in the code generated by the other agents.

The Future: Software That Self-Improves
#

We are approaching a point where software won’t be static. Imagine a server that monitors its own performance and, upon detecting a bottleneck, spawns a Darwinian swarm to rewrite its own inefficient modules immediately. In this new world, the developer’s role shifts from writer to naturalist. You aren’t typing the lines; you are defining the environment in which the best code can emerge.

What Changes When Coding Agents Are Infinitely Parallel

tom@tomrochette.com (Tom Rochette) — Wed, 18 Feb 2026 00:00:00 +0000

Imagine you can run hundreds or thousands of coding agents in parallel. How would you use them? The interesting answer is not “do everything faster”, but rather what fundamentally changes when parallelism is cheap.

From Sequential Exploration to Parallel Search
#

When you have one agent, you think carefully before acting, because going down dead ends is expensive. With thousands of agents, the trade-off reverses. Exploration becomes cheap, and convergence becomes the hard problem. Your job shifts from “what should I try?” to “how do I synthesize thousands of results?”

High-Leverage Use Patterns
#

Speculative execution on decisions. At every architectural fork, such as “should this be a queue-based system or polling?”, you do not decide, you branch. Two fleets of agents build both options, and you evaluate the results, borrowing the processor idea of speculative execution. This pattern is very useful for situations where you genuinely do not know which approach is better until you have tried it.

Mutation testing at scale. Spin up hundreds of agents making targeted changes to a codebase, each trying a different hypothesis about why a bug exists or how to optimize something. It is like fuzzing, but semantically directed: instead of random inputs, each change probes a specific theory.

Full-stack consistency checking. Have agents simultaneously maintain the contract between every pair of services in your system, constantly verifying that implementations match specs, that error handling is symmetric, and that naming is consistent. Sequential review often misses these checks.

Competitive benchmarking of approaches. For a problem like network latency or caching strategy, you could have 50 agents implement 50 different approaches against the same test harness, and just pick the winner. No reading papers and reasoning about tradeoffs, you settle the question empirically.

Living documentation. Agents continuously reconcile docs, comments, and code. Every pull request triggers agents that check for documentation drift, update runbooks, and surface inconsistencies.

The Harder Problems Cheap Parallelism Creates
#

Synthesis is the bottleneck. If 1,000 agents each produce a pull request, you are back to being the serial bottleneck reviewing them. You need meta-agents whose job is to evaluate and rank the output of other agents, with clear scoring functions.

State and conflict. Agents working in parallel on the same codebase will conflict. You probably want agents working in isolated sandboxes (branches, ephemeral clusters, test environments) with a merge or tournament layer on top.

Task decomposition quality matters more, not less. Bad task specs mean 1,000 agents going confidently in the wrong direction simultaneously. The skill of writing tight, evaluable task specs becomes enormously valuable.

Evaluation functions become critical. “Did the agent succeed?” needs a concrete, automated answer. You cannot manually review 1,000 outputs. That constraint pushes you toward test-driven development.

What This Implies For Infrastructure Work
#

The most compelling application is parallel experimentation on actual infrastructure parameters. Spin up ephemeral environments, have agents try different configurations or scheduling strategies, measure actual performance, then tear the environments down. What makes infrastructure hard is that you normally cannot afford to run 50 experiments simultaneously. With cheap parallel agents managing the scaffolding, that constraint disappears.

The practical limit ends up being compute and money, not ideas, which is a fundamentally different world than the one most engineering workflows were designed for.

Learning - 2026

tom@tomrochette.com (Tom Rochette) — Mon, 19 Jan 2026 00:00:00 +0000

Things I want to learn about in 2026.

Continuous learning

tom@tomrochette.com (Tom Rochette) — Sun, 04 Jan 2026 00:00:00 +0000

Continuous learning only works for me when I treat it as a small set of manual habits repeated every day. Waiting for free time or motivation does not work, because busy weeks always win. Five simple practices are enough to keep learning moving.

My learning process
#

The process has five practices, and all of them are manual. Each practice is small enough to fit into a normal workday.

I collect articles shared on Slack that may be relevant to read. Shared links disappear quickly under newer messages, so grabbing the promising ones when I see them is the only reliable way to keep a reading pile.

I identify tools and resources that can help me improve my skills. A better tool or a better explanation lets me learn more from the same amount of learning time.

I set aside dedicated time for learning each day. The reserved time is what turns collected links and found resources into actual learning, because neither gets read or used without a protected slot in the day.

I experiment with new technologies and ideas. Trying an idea myself is the fastest way to find out whether the idea deserves more of my attention.

I identify areas for improvement in my current skills and knowledge. The identified gaps tell the other practices what to focus on, so my effort goes to actual weaknesses instead of to whatever topic happens to be easiest to find.

What to Do Next
#

Start with the smallest version of the process and grow it from there:

Collect the next relevant article link you see shared on Slack, before the link scrolls away.
Reserve a short, fixed block of time for learning every day, and treat the block as booked.
Pick one gap in your skills, then find one tool, resource, or small experiment aimed at that gap this week.

Daily routine

tom@tomrochette.com (Tom Rochette) — Sun, 04 Jan 2026 00:00:00 +0000

This is the routine I follow on every work day, from catching up in the morning to planning the next day in the evening. Most steps are manual, but LLMs assist at fixed points: summarizing yesterday, writing code, and closing the day.

Trigger
#

Every day at the beginning of the (work) day.

Duration
#

8h.

Steps
#

Start of day
#

Review and correct LLM generated summaries of yesterday’s activities
Catch up on Slack messages (manual)
Review PRs (manual)
Standup (manual)

Throughout the day
#

Go to meetings (some days) (manual)
1:1 (some days) (manual)
Write code (mainly LLM assisted)
Reply to Slack messages (manual)
Review PRs (mainly manual, slightly LLM assisted)

End of day
#

Continuous learning (manual)
Generate an end of day summary using LLMs (LLM)
Daily review (manual)
Review weekly plan and align (manual)
Plan next day (manual)

Weekly routine

tom@tomrochette.com (Tom Rochette) — Sun, 04 Jan 2026 00:00:00 +0000

The weekly routine opens and closes the work week with LLM-generated summaries. I correct last week’s summaries at the start of the week and generate a new one at the end.

Trigger
#

At the beginning of every work week.

Duration
#

5 days.

Steps
#

Start of week
#

Review and correct the LLM-generated summaries of last week’s activities.
Weekly planning

Through the week
#

Daily routine

End of week
#

Ouroboros: An Autonomous Self-Improving AI Agent

tom@tomrochette.com (Tom Rochette) — Fri, 02 Jan 2026 00:00:00 +0000

What is Ouroboros?
#

Ouroboros is an autonomous AI agent that works on the tasks you give it and continuously improves itself. It is named after the ancient symbol of a serpent eating its own tail (representing infinity and cyclic renewal), and it implements a continuous loop of Do → Learn → Improve → Retry.

Unlike traditional AI assistants that wait for commands and forget context between sessions, Ouroboros:

Runs indefinitely without human intervention
Maintains persistent memory of everything it has done
Reflects on its performance regularly
Modifies its own code to improve over time
Can incorporate human feedback when provided

Previously I wrote about GlobaLLM, an AI agent that autonomously contributes to open source projects. While GlobaLLM’s primary objective is project and task prioritization at scale, Ouroboros focuses on task implementation and self-improvement. Ouroboros is thus one component of GlobaLLM’s solution.

How It Works
#

The Core Loop
#

Ouroboros follows a structured nine-step cycle that repeats continuously:

Read goals: fetches tasks from agent/goals/active.md
Select goal: picks one to work on, or defaults to self-improvement
Plan: uses an LLM to create a step-by-step plan
Execute: carries out the plan using available tools
Journal: writes results to a daily log
Reflect: analyzes what happened and identifies improvements, both task-related and self-related
Self-modify: edits its own source code if improvements are found
Journal again: records reflection and modification results
Repeat: starts the cycle again

The separation between execution and self-modification is crucial. The agent will not modify its code while working on a task; reflections and improvements happen only during dedicated reflection cycles.

Architecture
#

┌─────────────────────────────────────────────────────────┐
│                      Agent Core                         │
│  (coordinates the loop, handles signals, manages state) │
└─────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│   Memory     │    │  LLM Layer   │    │   Tools      │
│              │    │              │    │              │
│ • Working    │    │ • Anthropic  │    │ • run_cmd    │
│ • Journal    │───▶│   Claude     │───▶│ • read_file  │
│ • Goals      │    │ • Token      │    │ • write_file │
│ • Feedback   │    │   tracking   │    │ • search_*   │
└──────────────┘    └──────────────┘    └──────────────┘

Memory System
#

Ouroboros uses a three-tiered memory architecture:

Tier	Description	Location
Working memory	Current goals, immediate context	In-process
Short-term	Daily journals (notes, reflections, feedback)	`agent/journal/YYYY/MM/DD/`
Long-term	Git history with descriptive commits	Git repository

Everything is logged in human-readable markdown, which makes it easy to inspect what the agent has been up to.

Tool Registry
#

The agent comes with built-in tools for common operations:

run_command: execute shell commands
read_file: read file contents
write_file: write to files
search_files: find files by pattern
search_content: search within files

Crucially, Ouroboros can create, register, and use new tools that it writes itself.

Tools are implemented as CLI commands of the ouroboros CLI, which the agent can invoke during execution.

Design Principles
#

Safety Through Structure
#

The execution/reflection separation prevents runaway self-modification. The agent can change code only during a dedicated reflection phase, and all changes are committed to git with descriptive messages that explain the reasoning behind each change.

Transparency
#

Every action is logged. Want to know what the agent did? Check the daily journal:

agent/journal/YYYY/MM/DD/notes.md: what it did
agent/journal/YYYY/MM/DD/reflections.md: what it learned
agent/journal/YYYY/MM/DD/user-feedback.md: human input received

Autonomy with Optional Guidance
#

Ouroboros needs no human intervention, but it welcomes it. It incorporates feedback, adjusts course based on user suggestions, and explains its reasoning when asked.

What Makes It Interesting
#

Self-improvement: the agent can and does modify its own implementation based on reflection
Persistent memory: git commits serve as a permanent, queryable history of everything tried
Graceful degradation: failed modifications can be reverted; the agent learns and tries again
Tool extensibility: new tools can be created dynamically as needs arise
Idle improvement: when no goals are active, it works on making itself better

The Vision
#

Ouroboros represents an experiment in autonomous AI agents. Can an agent improve itself over time without human intervention, or with only limited intervention? By maintaining a detailed journal, reflecting on its actions, and having the freedom to modify its own code, Ouroboros aims to answer this question.

The name is fitting: the serpent eating its tail represents the continuous cycle of doing, learning, and improving that drives the agent forward. Each reflection builds on the last; each modification makes the agent slightly more capable.

Ouroboros is open source. Check out the repository to see the code, contribute, or run your own self-improving agent.

GlobaLLM: Automated Open Source Contribution at Scale

tom@tomrochette.com (Tom Rochette) — Sat, 27 Dec 2025 00:00:00 +0000

Introduction
#

Consider the following dilemma: you have unlimited access to state-of-the-art LLMs, but finite compute resources.

How do you maximize positive impact on the software ecosystem?

GlobaLLM is an experiment in autonomous open source contribution which attempts to address this question.

It’s a system that discovers repositories, analyzes their health, prioritizes issues, and automatically generates pull requests - all while coordinating with other instances to avoid redundant work.

The core insight isn’t just that LLMs can write code; it’s that strategic prioritization combined with distributed execution can multiply that capability into something genuinely impactful.

This article explains how GlobaLLM works, diving into the architecture that lets it scale from fixing a single bug to coordinating across thousands of repositories.

The GlobaLLM Pipeline: A High-Level View
#

GlobaLLM follows a five-stage pipeline:

Discover -> Analyze -> Prioritize -> Fix -> Contribute

1. Discover
#

The system begins by finding repositories worth targeting.

Using GitHub’s search API, it filters by domain, language, stars, and other criteria.

Current methodology uses domain-based discovery with predefined domains (ai_ml, web_dev, data_science, cloud_devops, mobile, security, games), each with custom search queries combining relevant keywords.

The system then applies multi-stage filtering:

Language filtering: Excludes non-programming languages (Markdown, HTML, CSS, Shell, etc.)
Library filtering: Uses heuristics to identify libraries vs applications (checks for package files like pyproject.toml, package.json, Cargo.toml; filters out “awesome” lists and doc repos; analyzes descriptions and topics)
Quality filtering: Language-specific queries include testing indicators (pytest, jest, testing)
Health filtering: Applies health scores to filter out unmaintained projects
Dependent enrichment: Uses libraries.io API to fetch package dependency counts for impact scoring

Results are cached locally (24hr TTL) to avoid redundant API calls and respect rate limits.

The goal isn’t to find every repository - it’s to find libraries where a contribution would matter.

2. Analyze
#

Once a repository is identified, GlobaLLM performs deep analysis to determine whether contributing is worthwhile.

This gate prevents wasting resources on abandoned projects, hostile communities, or repositories where contributions won’t have impact.

It calculates a HealthScore based on multiple signals:

Commit velocity: Is the project actively maintained?
Issue resolution rate: Are bugs getting fixed?
CI status: Does the project have passing tests?
Contributor diversity: Is there a healthy community?

It also computes an impact score - how many users would benefit from a fix, based on stars, forks, and dependency analysis using NetworkX.

Repositories with low health scores or minimal impact are deprioritized or skipped entirely.

3. Prioritize
#

The system fetches open issues from approved repositories and ranks them using a sophisticated multi-factor algorithm.

Each issue is analyzed by an LLM to determine:

Category: bug, feature, documentation, performance, security, etc.
Complexity: 1-10 scale (how difficult to solve)
Solvability: 0-1 score (likelihood of automated fix success)
Requirements: affected files, breaking change risk, test needs

The prioritization then combines four dimensions:

Health (weight: 1.0): Repository health adjusted for complexity.

A healthy repository with simple issues scores higher than an unhealthy repository with complex ones.

Impact (weight: 2.0): Based on stars, dependents, and watchers.

Uses log-scale normalization (stars / 50,000, dependents / 5,000).

Solvability (weight: 1.5): LLM-assessed likelihood of successful resolution.

Documentation and style issues (~0.9) rank higher than critical security (~0.3) due to automation difficulty.

Urgency (weight: 0.5): Category multiplier × age × engagement.

Critical security bugs get 10× multiplier, documentation gets 1×.

The final formula:

priority = (health × 1.0) + (impact × 2.0) + (solvability × 1.5) + (urgency × 0.5)

Budget constraints filter the ranked list:

Per-repository token limit (default: 100k)
Per-language issue limit (default: 50)
Weekly token budget (default: 5M)

Results are saved to the issue store with full breakdowns for transparency.

4. Fix
#

GlobaLLM claims the highest-priority unassigned issue and generates a solution.

This is where LLMs do the heavy lifting.

The CodeGenerator class sends a structured prompt to Claude or ChatGPT with:

The issue title and description
Repository context (code style, testing framework)
Language-specific conventions
Category-specific requirements (bug vs feature vs docs)

The LLM responds with a complete solution:

Explanation: Step-by-step reasoning
File patches: Original and new content for each modified file
Tests: New or modified test files

The system tracks tokens used at every step for budget management.

5. Contribute
#

The final stage uses PRAutomation to create a well-structured pull request with context, tests, and documentation.

For trivial changes (typos, version bumps), it can even auto-merge.

Where LLMs Are Used
#

LLMs are the engine that powers GlobaLLM, but they’re used strategically rather than indiscriminately.

Stage 3 - Prioritize: The IssueAnalyzer calls an LLM to categorize each issue.

Input: title, body, labels, comments, reactions.

Output: category, complexity (1-10), solvability (0-1), breaking_change, test_required.

This costs ~500 tokens per issue and feeds directly into the priority scoring.

Stage 4 - Fix: The CodeGenerator uses an LLM to generate complete solutions.

Input: issue details, repository context, language style guidelines.

Output: explanation, file patches (original + new content), test files.

This costs 1k-10k tokens depending on complexity.

The key insight: LLMs are only used for tasks requiring intelligence.

Discovery, health scoring, impact calculation, and PR automation use deterministic algorithms.

Scaling GlobaLLM
#

The real power of GlobaLLM emerges when you run multiple instances in parallel.

Distributed Agent Architecture
#

Each GlobaLLM instance has a unique AgentIdentity.

When it’s ready to work, it calls:

globallm assign claim

This atomically reserves the highest-priority unassigned issue.

The assignment is stored in PostgreSQL with a heartbeat timestamp.

Issue Assignment System
#

To prevent multiple agents from working on the same issue:

Issues are marked assigned with an agent ID and timestamp
Heartbeats update every 5 minutes
If a heartbeat expires (30 minutes), the issue is reassigned

This allows crash recovery: if an agent crashes mid-work, another will pick up the issue.

Crash Recovery
#

The heartbeat system is elegant in its simplicity:

# Agent side
while working:
    update_heartbeat(issue_id, agent_id)
    do_work()

# Recovery side
expired = get_issues_with_expired_heartbeats()
for issue in expired:
    reassign(issue)

No distributed consensus needed - PostgreSQL’s row-level locking handles contention.

Database Design
#

PostgreSQL is the central state store:

Connection pooling: 2-10 connections per process (psycopg pool)
JSONB columns: Flexible schema for repository/issue metadata
Indexes: On frequently queried fields (stars, health_score, assigned status)
Migrations: Versioned schema

Future Work
#

GlobaLLM is an evolving experiment. There are numerous challenges that developers face on a daily basis that a system such as GlobaLLM will also encounter and would need to deal with in order to be more effective:

Parallelizing work across multiple agents without conflicts or redundant effort.
Producing “mental models” of repositories to better understand their goals, architecture, dependencies and trajectories.
Have a higher-level decision-making system that can reason about which repositories to focus on based on broader trends in the open source ecosystem.
Make decisions such as which programming languages to focus on.
Have the ability to work with closed source repositories which may not have the same signals as open source ones (e.g., forks, stars, dependency count).

Conclusion
#

GlobaLLM is an experiment in what’s possible when you combine LLM code generation with principled decision-making and distributed execution.

The goal isn’t to replace human contributors - it’s to handle the long tail of maintenance work that no one has time for, freeing up humans to focus on the interesting problems.

The system is actively developed and evolving.

Current work focuses on better prioritization heuristics, more sophisticated validation, and integration with additional LLM providers.

If you’re interested in contributing or just want to run it yourself, the code is available on GitHub.

This system is far from perfect, but it’s a step toward harnessing AI to make open source software healthier and more sustainable at scale.

It’s also a way to explore what it looks like to have to make decisions at the scale of millions of repositories and billions of issues.

The last commit

tom@tomrochette.com (Tom Rochette) — Wed, 24 Dec 2025 00:00:00 +0000

Dr. Aris Thorne stared at the shimmering temporal rift, its edges flickering like a corrupted display. He wasn’t just looking at a gateway through time – he was looking at a living, breathing Git repository of reality itself.

“Status check,” he muttered, fingers dancing across the holographic interface. “Current branch: timeline-main. Last commit: ‘Catastrophe at Point Zero’ by User:Humanity.”

Three days ago, humanity had triggered the Cascade Event – a chain reaction of temporal paradoxes that threatened to unravel existence. Now Aris, the last Temporal Archivist, was attempting something never before conceived: git revert on reality itself.

“Creating new branch: ‘fix-attempt-1’,” he announced to the empty lab. The temporal rift stabilized, showing a parallel timeline branching off from moments before the disaster.

Aris stepped through, materializing in the control room of the Chronos Facility, right as the ill-fated experiment was about to begin. He knew the command sequence by heart – the one that would prevent the Cascade.

But as he approached the console, he froze. His younger self was there, looking determined but naive. If Aris intervened, would he create a merge conflict with his own existence?

“Branching again,” he decided, retreating to the safety of the temporal nexus. “Creating ‘fix-attempt-2’ from an earlier commit.”

This time he arrived hours earlier, when the facility was still empty. He carefully modified the experiment parameters, ensuring the Cascade could never occur. Satisfied, he returned to his present.

The lab was unchanged. The rift still showed the corrupted timeline.

“Failed merge,” Aris realized with dawning horror. “Reality rejected the patch.”

Days turned into weeks as Aris created dozens of branches, each attempting to fix the timeline. He tried git cherry-pick of successful moments from history, git rebase of civilization’s achievements, even git bisect to isolate the exact commit that had broken everything.

Nothing worked. Each attempt was rejected by the cosmic repository, leaving him with countless abandoned branches floating in temporal limbo.

Exhausted, Aris collapsed before the interface. “Git log –oneline –graph,” he whispered, watching the tree of failed attempts bloom across the display. It was beautiful in its complexity – a constellation of what-ifs and could-have-beens.

That’s when it hit him. He’d been trying to fix the timeline, to restore a previous commit. But what if the solution wasn’t to revert, but to evolve?

“Creating new branch: ’transcendence’,” he declared with renewed energy. “Not from any previous commit, but from the current corrupted state.”

He stepped through into the fractured timeline, where temporal paradoxes manifested as impossible architecture and shifting landscapes. Instead of fighting the chaos, he embraced it. He worked with the anomalies, finding patterns in the madness.

Aris discovered that the Cascade wasn’t an error – it was evolution. Humanity had outgrown its linear timeline, and reality was attempting to branch into a multidimensional existence.

“Merge request,” he transmitted to the temporal repository. “Not to fix, but to complete the transformation.”

The rift stabilized, its chaotic energy resolving into something new and coherent. Aris watched as all his abandoned branches began to merge into this new reality, each failed attempt contributing something essential to the final design.

When he returned to his lab, everything was different yet familiar. The temporal rift was gone, replaced by a window showing infinite timelines coexisting harmoniously.

Aris smiled at the new interface displaying the transformed reality. “Current branch: timeline-multiverse. Last commit: ‘Embrace the Chaos’ by User:Humanity.”

He had learned the ultimate lesson of temporal manipulation: sometimes the best commit isn’t a fix, but a feature.

LLM conversations viewer

tom@tomrochette.com (Tom Rochette) — Sun, 21 Dec 2025 00:00:00 +0000

I built something I’ve wanted for a while within an hour using Claude Code (Sonnet 4.5). It’s a LLM conversations viewer, available for everyone to use at https://tomzxcode.github.io/llm-conversations-viewer. It is a single page application, 100% client-side. You can use it to view conversations exported from various LLM platforms (e.g., ChatGPT, Claude, etc.) in a nice interface. It can also be used to share conversations with others so that they can view them, using https://tomzxcode.github.io/llm-conversations-viewer/?url=url-to-json-or-zip (such as a raw Gist URL). It can be useful if you use many platforms through their clients (web or mobile) and would like to be able to search those conversations in one place. Play with it and let me know what you think! Repository here

Readability index

tom@tomrochette.com (Tom Rochette) — Sun, 21 Dec 2025 00:00:00 +0000

The readability index is a metadata field added to articles on this blog to help readers quickly assess whether an article is appropriate for their level of expertise and available attention.

The scale
#

Articles are rated on a 0-5 scale based on their readability:

0 - Personal notes: Content that is only meaningful to me. These are often shorthand notes, context-dependent references, or incomplete thoughts that lack the necessary background for others to understand.
1 - Cryptic: Readable but highly condensed or assumes significant context. These articles may use jargon without explanation, reference obscure concepts, or present ideas in a very terse manner. You might be able to extract value, but it requires effort and potentially external research.
3 - Specialized/Expert audience: Articles written for readers with domain expertise. These assume familiarity with technical terminology, concepts, and background knowledge in a specific field (e.g., machine learning, software architecture, AGI research). The writing is clear if you have the prerequisite knowledge.
5 - General audience: Articles written to be accessible to anyone with general reading ability. These explain concepts from first principles, define technical terms when used, and don’t assume specialized background knowledge. They’re structured for easy consumption.

Purpose
#

The readability index serves several purposes:

Reader efficiency: Helps readers quickly determine if an article matches their current context and expertise level before investing time in reading it.
Content discovery: Makes it easier to filter or search for articles at the appropriate level - whether you want deep technical content or accessible introductions.
Author awareness: Forces me to be conscious about my target audience when writing, which can improve clarity and focus.
Archive navigation: As this blog contains a mix of polished articles and personal research notes, the index helps distinguish between content types.

How it’s used
#

This index is subjective and represents my assessment at the time of writing. Your mileage may vary - what I consider a “3” might be a “5” for experts in that field or a “1” for beginners.

Why not a continuous 0-5 scale?
#

You might notice the scale uses discrete values (0, 1, 3, 5) rather than every integer from 0 to 5. This is intentional:

2 would fall between “cryptic” and “specialized” - a fuzzy middle ground that’s hard to define
4 would be between “specialized” and “general” - again, unclear distinction

The four-point scale provides enough granularity to be useful without creating artificial precision. If an article truly feels intermediate, I’d likely rate it at the lower level (1 or 3) since it’s better to underpromise and overdeliver on accessibility.

Relationship to article status
#

The readability index is independent of the article’s status field:

status: draft - Article is incomplete or actively being written
status: in progress - Article is being updated and refined
status: finished - Article is complete and unlikely to be revised

An article can be status: finished with readability: 0 (polished personal notes) or status: draft with readability: 5 (an in-progress accessible introduction). They measure different dimensions of the content.

Evolution
#

Like any other metadata on this blog, readability ratings may change over time as I revisit articles or as my sense of what constitutes each level evolves. The index is a tool for navigation, not a rigid categorization system.

The merge conflict

tom@tomrochette.com (Tom Rochette) — Sat, 20 Dec 2025 00:00:00 +0000

Dr. Sarah Chen stared at her terminal, the familiar green text glowing in the darkened lab.

$ git log --all --graph --oneline
* a3f9b2c (HEAD -> main) Fix climate models
| * 7c8d1e4 (origin/2157) Prevent asteroid impact
|/
* 2b4a8f3 Initial timeline

“Three timelines,” she muttered. “And they’re diverging.”

The Temporal Version Control System had seemed like humanity’s salvation. Jump to any point in history, create a branch, make changes, then merge back. Fix mistakes. Optimize outcomes. What could go wrong?

Everything, apparently.

Sarah’s colleague Marcus rushed in. “We’ve got a problem. The 2157 branch where we prevented the asteroid? It created a merge conflict with main.”

“Show me.”

$ git merge origin/2157
Auto-merging timeline.dat
CONFLICT (content): Merge conflict in timeline.dat
Automatic merge failed; fix conflicts and then commit the result.

Sarah pulled up the diff:

<<<<<<< HEAD
2089: Global climate stabilized, population 9.2B
2157: Thriving lunar colonies established
=======
2089: Asteroid prevention tech drives new space race
2157: Mars terraforming 40% complete, population 12.7B
>>>>>>> origin/2157

“They’re both real,” Marcus whispered. “Both timelines exist simultaneously until we resolve the conflict.”

Sarah nodded slowly. Quantum superposition at a temporal scale. The universe itself refusing to compile until they chose which future to keep-and which to discard.

Her fingers hovered over the keyboard. One timeline solved climate change through sacrifice and discipline. The other achieved it through desperate innovation sparked by near-extinction.

“What if,” she said, “we don’t choose?”

“You can’t leave a merge conflict unresolved. The timeline will remain in an unstable state-”

“Or we git rebase everything onto a new branch. Cherry-pick the best commits from each timeline.”

Marcus’s eyes widened. “You want to rewrite history itself.”

“We already are. We’ve just been doing it badly.” Sarah started typing:

$ git checkout -b unified
$ git cherry-pick 7c8d1e4  # Asteroid prevention tech
$ git cherry-pick a3f9b2c  # Climate stability

The lab hummed. Reality flickered.

When the command completed, Sarah checked the log:

* e9f2a1b (HEAD -> unified) Climate models + prevention tech
* 2b4a8f3 Initial timeline

Clean. Linear. Optimal.

“Git push –force?” Marcus asked nervously.

Sarah smiled. “Git push –force.”

She hit enter.

The universe accepted the merge.

The repository

tom@tomrochette.com (Tom Rochette) — Sat, 20 Dec 2025 00:00:00 +0000

The lab called it the Repository.

Time was not a river. It was a commit graph.

Mara’s console showed history as hashes and arrows. Every moment a node. Every decision a branch. The past was immutable. The future was a working tree full of untracked files.

She did not travel backward. She checked out.

git checkout -b stop-war a1f3c9e

The world recompiled around her. Same initial state. Same variables. Different branch name. In this timeline Hitler was still a student. Mara changed one small file. A rejected application. She committed and returned.

git checkout main

Nothing changed. Of course not. Main was untouched. The war still existed. The scars still matched their hashes.

People kept asking why she could not fix history. She explained patiently. You never fix history. You fork it.

Each jump created divergence. Entropy grew like unmerged branches. The Repository ballooned. Infinite timelines. Infinite storage. Garbage collection impossible. Nothing was truly unused.

One day she found a branch tagged by someone else.

origin/hope

No author. No timestamp. The diff was small. Fewer deaths. Slower weapons. More pauses between commits.

Mara did not merge it. Merges caused conflicts. Merges caused paradoxes.

She rebased.

She replayed the present onto hope. One commit at a time. Carefully resolving conflicts. Choosing better defaults.

When she finished, the graph looked cleaner. Still complex. Still branching. But survivable.

She pushed.

Somewhere, someone typed their first commit message.

“Initial commit.”

Daily planning

tom@tomrochette.com (Tom Rochette) — Sun, 30 Nov 2025 00:00:00 +0000

Trigger
#

Every daily at the end of the (work) day.

Duration
#

5 minutes.

Steps
#

Determine what are the most important tasks to be done tomorrow (manual)
Determine the next step for each task (manual)
Determine how much work can reasonably be accomplished tomorrow (manual)

Weekly planning

tom@tomrochette.com (Tom Rochette) — Sun, 30 Nov 2025 00:00:00 +0000

Trigger
#

Every week at the beginning of the (work) week.

Duration
#

10 minutes.

Steps
#

Determine what are the most important tasks to be done this week (manual)
Determine the next step for each task (manual)
Determine how much work can reasonably be accomplished this week (manual)

Gitlab SSH post-quantum key exchange

tom@tomrochette.com (Tom Rochette) — Sat, 08 Nov 2025 00:00:00 +0000

A small PSA for Gitlab users who use SSH to connect to their Git repositories. If you get the following warning when trying to connect:

** WARNING: connection is not using a post-quantum key exchange algorithm.
** This session may be vulnerable to "store now, decrypt later" attacks.
** The server may need to be upgraded. See https://openssh.com/pq.html

You should upgrade your Gitlab instance to the latest. If you need to upgrade, you can use Gitlab’s upgrade path tool which is very helpful to identify the correct upgrade steps to take.

You may also have to upgrade your operating system. In my case I was still on Ubuntu 20.04 LTS it did not support post-quantum key exchange.

Note that if you do a release upgrade, you also should update the apt sources to point to the new release (e.g., going from focal to jammy) and upgrade gitlab using the updated source.

The meaning of life

tom@tomrochette.com (Tom Rochette) — Sat, 08 Nov 2025 00:00:00 +0000

The meaning of life isn’t something you discover - it’s something you construct through systematic exploration and iterative refinement.

I think about it like optimizing a machine learning model. You start with some initial parameters (your genetics, environment, early experiences), but the actual trajectory emerges through the training process. The loss function isn’t predetermined - you have to define what you’re optimizing for, which is itself part of the work.

There’s a bootstrapping problem here that’s worth acknowledging: how do you choose meaning without already having meaning to guide that choice? The way out is probably recognizing that you’re already embedded in a process. You don’t start from a blank slate - you have patterns, preferences, curiosities that already exist. The work is surfacing those, examining them, and deciding which ones to amplify.

For me, it clusters around a few things:

Building systems that reduce cognitive overhead. Whether that’s infrastructure automation, better tooling, or frameworks that make complex problems tractable. There’s something deeply satisfying about creating leverage - doing work once that pays dividends repeatedly.

Understanding how things actually work. Not surface-level explanations, but the real mechanisms. Why does Kubernetes behave this way under load? How do transformers actually learn? What’s the evidence base for this claim? Drilling down until you hit bedrock.

Documenting the process. Writing isn’t just communication - it’s thinking made concrete. When I write about my thinking process on AGI or automation, I’m not just sharing conclusions, I’m making my reasoning debuggable. Both for others and for future me.

The meta-level realization is that meaning comes from engagement with hard problems. Not difficulty for its own sake, but the kind of problems where the solution space isn’t obvious and you have to actually think. The satisfaction isn’t in having answers - it’s in the process of going from “I don’t understand this” to “okay, I see how this works now.”

There’s probably no cosmic meaning. But there’s local meaning in building things that matter to you, learning things that genuinely puzzle you, and leaving some kind of documented trail that might be useful to someone else trying to solve similar problems.

The philosophical questions - consciousness, creativity, what happens after death - are interesting, but they don’t need to be answered to have a meaningful life. The work is meaningful even if the ultimate questions remain open.

My client-side only AI web application workflow

tom@tomrochette.com (Tom Rochette) — Mon, 13 Oct 2025 00:00:00 +0000

Over the past month I’ve started building client-side only AI web applications (e.g., ai-text-editor, a private ai-language-assistant to teach myself Chinese Mandarin). I’ve gone with this approach because it lends itself very well to vibe coding with vibe-kanban. I’ve configured the Dev Server Script option to open the index.html file in my browser and it works immediately, no need to build assets or start a backend server. This speeds up iteration cycle considerably. This approach is also great because it produces a tool that can then be used directly in the browser from any device, without needing to install anything. I can run what I built on my phone, on my work computer, one someone else’s computer easily by pointing them out to the project’s GitHub Pages URL which serves the application and is “production” ready.

I haven’t really picked any frontend libraries or frameworks, just vanilla HTML/CSS/JS. That is something I need to explore (e.g., react, svelte, solid, tailwind, vue.js, etc.) but for now I want to keep things simple.

For the past few projects I’ve used Claude Code. I ask Claude to create the common CLAUDE.md using /init. Additionally, I ask Claude to maintain a SPEC.md file that describes the features of the application. In many cases the database relies on the browser’s localStorage API and IndexedDB to store data, which is sufficient for my needs. I ask Claude to maintain a DATABASE_SPEC.md file to describe the database schema. Claude typically goes for a index.html, app.js, and styles.css file structure. While it is ok for the first few iterations of the project, I usually ask Claude to refactor the code to split it into multiple files and modules as the codebase grows. Doing so speeds up some of the iteration process since it doesn’t end up reading large irrelevant chunks of the file when making edits. It also makes it easier to review changes since I use the files modified as an indication of whether it worked on the right part of the codebase.

The main downside of this approach is that generally the app.js file ends up being quite large (e.g., 1000+ lines of code) since it contains all kind of global state and logic.

With this approach I’ve been able to fairly effectively work on small projects (~40 hours of work) and get something functional out the door that would have taken me weeks and where I’d probably have given up mid-project due to all kind of minor problems.

The template
#

The template is available as a GitHub repository.

In index.html I have the following code to load llm.js and my application code:

<script src="https://cdn.jsdelivr.net/gh/tomzxforks/llm.js@main/dist/index.min.js"></script>
<script type="module" src="app.js"></script>

In app.js I have the following code to configure the LLM options:

const applicationId = "my-ai-application";

function getConfigurationValue(key, defaultValue) {
    // Try to get configuration from applicationId key
    try {
        const appConfig = localStorage.getItem(applicationId);
        if (appConfig) {
            const config = JSON.parse(appConfig);
            if (config && config.hasOwnProperty(key)) {
                return config[key];
            }
        }
    } catch (error) {
        console.warn(`Error parsing ${applicationId} configuration:`, error);
    }

    // Fall back to llm-defaults key
    try {
        const defaultConfig = localStorage.getItem('llm-defaults');
        if (defaultConfig) {
            const config = JSON.parse(defaultConfig);
            if (config && config.hasOwnProperty(key)) {
                return config[key];
            }
        }
    } catch (error) {
        console.warn('Error parsing llm-defaults configuration:', error);
    }

    // Use provided default
    return defaultValue;
}

const llmOptions = {
    service: getConfigurationValue("service", "groq"),
    model: getConfigurationValue("model", "openai/gpt-oss-120b"),
    extended: true,
    apiKey: getConfigurationValue("api_key", "LLM_API_KEY_NOT_SET"),
    max_tokens: parseInt(getConfigurationValue("max_tokens", "8192")),
};

I set a key in localStorage called llm-defaults that contains a JSON object with default values for the LLM service, model, and API key. For example:

{
    "service": "groq",
    "model": "openai/gpt-oss-120b",
    "api_key": "sk-xxxxxx",
    "max_tokens": "8192"
}

This way I can easily change the LLM configuration for all my client-side AI applications by updating this single localStorage key. If I need to override the configuration for a specific application, I can set another key in localStorage with the name of the applicationId (e.g., my-ai-application) that contains the specific configuration for that application. In the event that neither key is set, the code falls back to hardcoded default values.

Notes
#

The LLM.js I use is forked from themaximalist/llm.js. The main changes I’ve made was to enable IIFE (Immediately Invoked Function Expression) builds that can be loaded directly in the browser via a <script> tag instead of using modules. I also disabled minification since jsdelivr automatically minifies the code if you have min in the filename.

The debug loop

tom@tomrochette.com (Tom Rochette) — Fri, 05 Sep 2025 00:00:00 +0000

Marcus closed his laptop at exactly 6 PM, just as he had promised himself he would every day this week. The screen went dark, but the code remained illuminated behind his eyelids-persistent, glowing green text against black. Even as he stood from his desk and stretched, he could still see the function he’d been wrestling with, its logic branching through his mind like creeping ivy.

Not now, he told himself. Work is over.

He made dinner-pasta with store-bought sauce, the same meal he’d eaten three nights running. As the water boiled, his mind wandered back to the memory leak in the application. Maybe if he restructured the garbage collection calls? Or perhaps the issue was in the parent component, not the child. He caught himself drumming his fingers on the counter in the rhythm of typing, each tap a phantom keystroke solving problems that could wait until tomorrow.

His girlfriend called while he ate. Sarah’s voice was warm, talking about her day at the veterinary clinic, a difficult surgery on a golden retriever that had gone well. Marcus made appropriate sounds of interest, but part of him was still debugging. Her words became background processes while his main thread analyzed whether implementing a cache would improve the API response time.

“Are you listening?” Sarah asked, not unkindly. She knew the signs.

“Sorry, yes. The dog’s owner was crying?” He guessed, poorly.

“That was five minutes ago, Marc.”

After the call, he tried to read a novel-something about a detective in Victorian London that his mother had recommended. But the detective’s methodology reminded him of debugging: isolating variables, testing hypotheses, following the trail of clues through nested mysteries. Even fiction had become code.

At the gym, counting reps became iterations in a for-loop. One more set translated to one more compile. The rowing machine’s display showed metrics that made him think about performance optimization. His heart rate monitor might as well have been displaying server response times.

He met Tom for drinks, his oldest friend who worked in marketing and didn’t know a compiler from a cucumber. But when Tom complained about a difficult client presentation, Marcus found himself mentally architecting a solution-a simple web app that could dynamically generate presentations based on client data. He was halfway through explaining the tech stack before he noticed Tom’s glazed expression.

“Remember when you used to talk about music?” Tom asked. “You had that whole theory about Radiohead’s album structure.”

Marcus did remember, vaguely, like recalling a program written in a deprecated language.

That night, he lay in bed, Sarah sleeping beside him. The ceiling was a blank canvas where his mind projected code. He tried counting sheep, but they became objects in an array, each one instantiated with properties: fluffiness, jump_height, sequential_number. He tried meditation, focusing on his breath, but his inhales and exhales became binary: 1, 0, 1, 0.

At 2 AM, he gave up and opened his laptop. The blue light washed over him like baptism, like coming home. The bug that had haunted him all day revealed itself within minutes-a missing await keyword, so simple it was almost insulting. He fixed it, pushed the commit, and felt the sweet release of resolution.

But even as he closed the laptop again, he knew this was just one bug fixed in a system full of them. Tomorrow would bring new problems, and the day after that, and the day after that. The code would follow him home, eat dinner with him, sleep in his bed, wake with him in the morning.

He looked at Sarah, sleeping peacefully, her mind presumably full of dreams that had nothing to do with her work. He envied her ability to close the clinic door and leave the sick animals behind. But then again, maybe she dreamed of surgery, of sutures and symptoms. Maybe everyone carried their own infinite loops.

Marcus finally drifted off around 3 AM, his last conscious thought a promise to himself that tomorrow he would try harder to context-switch, to properly close all his mental tabs. But even as sleep took him, somewhere in his subconscious, a background process continued running, optimizing and refactoring, an endless daemon that would not-could not-terminate.

In his dreams, he was debugging reality itself, and the bug was somewhere in his own source code.

Fix Windows 11 account

tom@tomrochette.com (Tom Rochette) — Wed, 03 Sep 2025 00:00:00 +0000

I recently moved to Windows 11. I had created only a local account during creation but at some point I configured OneDrive to use my wife’s account. This resulted in her account being bound as the “primary” account of the computer. This is not what I wanted.

I looked online for a solution but all the instructions I found didn’t have the screen I had. I initially tried a regedit fix but it didn’t work.

Here is how I fixed it:

Go to Settings > Accounts > Your info.
This is the “weird part”, click on “Sign in with a Microsoft account instead”.

Follow the instructions using a different account.
The previous account will be “detached” from the computer and you will now be using a local account.
If you go in Settings > Accounts > Email & accounts, you will see that the previous account is still listed under “Accounts used by other apps” but that you can now remove it (which you couldn’t do previously).

Hope this helps!

Work jail

tom@tomrochette.com (Tom Rochette) — Wed, 03 Sep 2025 00:00:00 +0000

Ethan’s eyes burned as he stared at the ceiling in the dark. It was past midnight, yet his mind churned with lines of code, bug reports, and deadlines. He could hear the faint hum of his laptop from across the room, the machine sleeping-but his brain never did.

He wasn’t in the office. He wasn’t even near his desk. But he might as well have been shackled there. Every time he tried to drift into sleep, a stray thought would pierce through: Did I fix that memory leak? What if the deployment fails tomorrow?

On weekends, when his daughter tugged at his sleeve to play, his body was present, but his mind wandered back to sprint boards and review notes. He’d nod and smile, but she could tell he wasn’t really there. The guilt would come, heavy and sharp, but instead of freeing him, it only chained him tighter.

Work lived in him like a warden. No one forced him to think about it-not his boss, not his colleagues. The prison wasn’t physical. It was a cage built from expectation, ambition, and fear. A cage he carried with him everywhere.

Sometimes, he wondered what silence would feel like. Not the silence of a muted Slack notification, but real silence-the kind that let you hear your own heartbeat without worry pressing against it.

One evening, walking home, he noticed a sparrow land on a fence. It hopped, light and unbothered, and then flew off. He stopped in his tracks, watching it disappear into the sky. For a fleeting second, he envied the bird’s freedom, a freedom he had once believed was his by right.

And in that second, he realized: the keys to his cell weren’t held by his company, or his laptop, or even the endless tasks. They were in his own pocket, hidden beneath the weight of his own unwillingness to set them down.

Effective vs efficient

tom@tomrochette.com (Tom Rochette) — Sun, 31 Aug 2025 00:00:00 +0000

In software development, understanding the difference between being effective and being efficient is crucial for delivering high-quality products.

Effectiveness is about doing the right things - choosing the correct features to implement, solving the right problems, and aligning development efforts with business goals. An effective developer ensures that their work has a meaningful impact and contributes to the project’s success.

Efficiency, on the other hand, is about doing things right - optimizing code, reducing resource usage, and minimizing development time. Efficient developers focus on speed and resource management, ensuring that solutions are implemented with minimal waste.

Balancing effectiveness and efficiency leads to better outcomes. For example, writing highly optimized code for a feature that users don’t need is efficient but not effective. Conversely, delivering valuable features slowly or with unnecessary complexity may be effective but not efficient.

In summary, successful software development requires both: building the right solutions (effectiveness) and building them well (efficiency).

Slow git under WSL

tom@tomrochette.com (Tom Rochette) — Sat, 23 Aug 2025 00:00:00 +0000

I have a git repository with 25k commits in it and 7k+ files.

Under Windows 11 using WSL, I noticed that git operations were significantly slower compared to running them natively on Windows.

I have a script that I use to synchronize many branches that was taking forever to execute, but should have been relatively fast. It also had trouble with line endings which caused issues when merging branches but reminded me of a setting I used to configure in my ~/.gitconfig a very long time ago.

Given that git configuration under Windows and WSL are separate, I had to update the ~/.gitconfig file in my Linux environment with the following.

[core]
    autocrlf = true

This immediately fixed my problem and git was fast again.

Slow network under WSL

tom@tomrochette.com (Tom Rochette) — Sat, 23 Aug 2025 00:00:00 +0000

When I started using WSL on Windows 11 I had slow network performance issues. We’re talking running speedtest-cli and getting ~3 Mbps download speeds while my connection can reach 400 Mbps.

After searching online for a while and trying a variety of things I finally found a solution.

In %USERPROFILE%\.wslconfig add the following:

[wsl2]
networkingMode=mirrored

With this fix applied I’m now getting ~400 Mbps download speeds in WSL, matching my native Windows performance.

Company offboarding

tom@tomrochette.com (Tom Rochette) — Tue, 19 Aug 2025 00:00:00 +0000

Meet with colleagues to discuss ongoing projects and hand off responsibilities
Write down knowledge transfer documents
Download pay stubs and tax documents
Ensure accounts that should still be accessible use a personal email address (e.g., insurance, stocks)
Return company equipment (laptop, phone, etc.)

Feedback

tom@tomrochette.com (Tom Rochette) — Tue, 19 Aug 2025 00:00:00 +0000

Trigger
#

Every week, on Friday.

Duration
#

15 minutes.

Steps
#

Gather feedback from team members.
Review feedback and identify key themes.
Identify action items based on the feedback.
Identify a date at which to revisit the feedback and the action items.

Daily review

tom@tomrochette.com (Tom Rochette) — Sat, 02 Aug 2025 00:00:00 +0000

Trigger
#

Every daily at the end of the (work) day.

Duration
#

15 minutes.

Steps
#

Review what was planned for the day (manual)
- Did you finish each planned task?
- Were any deliverables missed or delayed?
- How many times I was interrupted?
- How much time I spent on unexpected work?
- Was I got blocked and for how long?
- Rate the quality of work delivered.
Provide feedback related to the plan (manual)
Learning & Insights (manual)
- Did you discover a new tool, technique, or process?
- What could be improved next time?
Review weekly plan and align
Plan next day

Weekly review

tom@tomrochette.com (Tom Rochette) — Sat, 02 Aug 2025 00:00:00 +0000

Trigger
#

Every week, either at the beginning or end of the week.

Duration
#

15 minutes.

Steps
#

Review what was planned for the week (manual)
Provide feedback related to the plan (manual)
- Write down what was worked on that wasn’t part of the plan (manual)
Review monthly plan and align
Plan next week

GPU cluster monitoring

tom@tomrochette.com (Tom Rochette) — Sun, 06 Jul 2025 00:00:00 +0000

Overview
#

In this article I list metrics and alerts one should have when monitoring a GPU cluster to ensure efficient utilization of resources.

GPU cluster monitoring is critical for organizations to optimally utilize the limited capacity they have. Without monitoring it is easy for users to leave jobs running that do not use GPU resources, or do not use them efficiently. In some cases GPU clusters use certain technologies that require the users to provide images with specific libraries, and not including those dependencies can result in significantly worse compute performance.

Metrics
#

Allocated GPUs
- Used to determine who (or which project) has GPU allocated (i.e., currently assigned to a running workload)
GPU utilization
- Used to determine whether the GPU is partially or fully used, and if it is partially used, to potentially identify the causes
GPU memory utilization
- Used to determine if the GPU memory is partially or fully used
- Used to identify out of memory issues and potential memory leaks
InfiniBand receive/transmit bytes
- Used to determine if a workload is making use of the technology
Job launch wait duration
- Used to determine when there’s queueing of jobs due to compute being exhausted and how long it takes for jobs to start
Job duration
- Used to gather statistics about the type of workload running on the cluster in order to make informed decisions

Alerts
#

Allocated GPUs are used
- Used to detect jobs that may ask multiple GPUs but end up using 1 or only a few of them
GPU utilization below threshold (<10%)
- Used to detect workloads that do not make full use of the GPU or are allocated to an oversized GPU
GPU utilization above threshold (>90%)
- Used to detect when the GPU is saturated
GPU utilization range above threshold (>25%)
- Used to detect uneven distribution of GPU compute workload
GPU memory utilization below threshold (<10%)
- Used to detect workloads that do not make full use of the GPU or are allocated to an oversized GPU
GPU memory utilization above threshold (>95%)
- Used to detect when a job is about to run out of GPU memory
InfiniBand receive/transmit > 0 when running multi-node workloads
- Used to identify workloads that are not properly configured to use InfiniBand

Quotes

tom@tomrochette.com (Tom Rochette) — Wed, 14 May 2025 00:00:00 +0000

ChatGPT 4o
#

If the behavior is chronic and unproductive, decide how much engagement is worthwhile.

Sometimes planting a seed is better than trying to change their mind in the moment.

Some people are resistant to new perspectives. If they refuse to engage, focus on managing your own reaction rather than changing theirs.

Choose your battles: Not every conversation is worth having. Consider whether it’s worth investing time and energy into trying to change someone’s mind.

ChatGPT OSS 20B
#

Change is a marathon, not a sprint; pace yourself and your words.

Every conversation is a decision.

Learning - 2025

tom@tomrochette.com (Tom Rochette) — Fri, 21 Feb 2025 00:00:00 +0000

Claude code
Cursor
DeepSpeed
dstack
How to use LLM more in my development process
Kueue
Kyverno
Model context protocol (MCP)
Multi-node training and inference
NATS
Nebius
Vibe-Kanban

My python stack

tom@tomrochette.com (Tom Rochette) — Mon, 13 Jan 2025 00:00:00 +0000

Here is the list of python tools and libraries I use regularly.

(Sorted alphabetically)

Reference
#

https://www.stuartellis.name/articles/python-modern-practices/#format-your-code

AI tools I have used

tom@tomrochette.com (Tom Rochette) — Sun, 05 Jan 2025 00:00:00 +0000

In this article I list all the AI tools I’ve used.

I also try to keep this list up to date with regards to whether I’m still using the tool or not.

Legend:

🟢 Regularly using
🟡 Sometimes using
🔴 Not using

Text generation
#

🔴 Cerebas
🟡 Claude
🔴 Cohere
🔴 DeepSeek
🔴 DuckDuckGo AI
🔴 Gemini
🔴 Groq
🔴 Kimi
🔴 Mercury
🔴 Meta.ai
🔴 MiniMax
🔴 Mistral AI
🔴 NotebookLM
🔴 Obsidian companion plugin
🟡 OpenAI ChatGPT
🔴 Perplexity
🔴 Poe
🔴 Qwen
🔴 Reka.ai
🟢 Zhipu GLM

Code generation
#

🔴 Bolt
🔴 Cerebas Coder
🔴 Claude Code
🔴 Cursor
🔴 GitHub Copilot
🔴 Tabnine
🔴 v0
🟢 Zhipu GLM Coding Plan

Image generation
#

🟡 Gemini
🔴 Leonardo
🟡 OpenAI ChatGPT

Audio generation
#

🔴 Suno

Task orchestration
#

🟢 OpenChamber (web UI for OpenCode)
🔴 OpenCode Web UI
🔴 Vibe-Kanban

Speech to text
#

🟢 Handy
🔴 MacWhisper
🔴 Superwhisper

Desktop client
#

🔴 BoltAI
🔴 Claude Desktop

Web client
#

🔴 LibreChat
🔴 OpenWebUI

Models
#

gantt
    title Model usage
    dateFormat YYYY-MM-DD
    axisFormat %b %Y
    section Composer
    Composer 1          :done,   2026-01-01, 2026-03-13
    Composer 1.5        :done,   2026-02-09, 2026-03-19
    Composer 2 Fast     :done,   2026-03-20, 2026-04-30
    Composer 2.5        :done,   2026-05-19, 2026-08-28
    section Claude Opus
    Claude Opus 4.6     :done,   2026-03-05, 2026-04-11
    Claude Opus 4.7     :done,   2026-04-16, 2026-05-29
    Claude Opus 4.8     :done,   2026-05-28, 2026-07-29
    Claude Opus 5       :done,   2026-07-27, 2026-08-06
    section DeepSeek
    DeepSeek v4 Flash   :done,   2026-06-04, 2026-08-12
    DeepSeek v4.1 Flash :active, 2026-09-10, 2026-09-23
    section GLM
    GLM 4.7             :done,   2026-02-08, 2026-04-20
    GLM 5               :done,   2026-02-14, 2026-04-14
    GLM 5.1             :done,   2026-04-15, 2026-06-13
    GLM 5.2             :done,   2026-06-14, 2026-08-17
    GLM 5.3             :done,   2026-08-14, 2026-08-28
    GLM 5.3 Flash       :active, 2026-08-26, 2026-09-23

🔴 Composer-1
🔴 Composer-1.5
🔴 Composer-2
🔴 Composer-2.5
🔴 Claude Fable 5
🔴 Claude Opus 4.1
🔴 Claude Opus 4.5
🔴 Claude Opus 4.6
🔴 Claude Opus 4.7
🔴 Claude Opus 4.8
🔴 Claude Opus 5
🔴 Claude Sonnet 4.5
🔴 Claude Sonnet 5
🔴 DeepSeek r1
🔴 DeepSeek v4 Flash
🟢 DeepSeek v4.1 Flash
🔴 Gemini 2.5 Pro
🔴 Gemini 3 Pro
🔴 GLM 4.6
🔴 GLM 4.7
🔴 GLM 5
🔴 GLM 5.1
🔴 GLM 5.2
🔴 GLM 5.3
🟢 GLM 5.3 Flash
🔴 GPT 3.5
🔴 GPT 4
🔴 GPT 4.1
🔴 GPT 4o
🔴 GPT 5
🔴 GPT 5.1
🔴 GPT 5.2
🔴 GPT 5.2
🔴 GPT 5.3
🔴 GPT 5.4
🔴 GPT 5.6 Sol
🔴 GPT OSS 120B
🔴 GPT OSS 20B

Apache flink rate limiting

tom@tomrochette.com (Tom Rochette) — Sun, 17 Nov 2024 00:00:00 +0000

In this article we’ll cover adding rate limiting to an Apache Flink pipeline. While Apache Flink already contains some APIs that implement some form of rate limiting indirectly, such as AsyncDataStream through a capacity limit which limits the number of concurrent executions, these do not rate limit directly.

Rate limiting is critical in applications where calling 3rd party APIs with rate limits or quotas could result in multiple unnecessary retries or even failures to process an event successfully.

Implementation of rate limiting
- This consist mostly in including a call to a blocking implementation of a rate limiter just before you would execute the code you want rate limited. For example if you are rate limiting calls to an API, you would block just before sending your HTTP request.
Rate limiting in relation to parallelism
- When defining rate limiting we generally think of the overall rate limit per second. With Apache Flink parallelism, this number ends up being used by each instance, which makes the rate limit useless in this situation, unless it is divided by the number of parallel instances running the code that is rate limited.
- One way to implement this local rate limit is given in the open function in Flink GuavaFlinkConnectorRateLimiter by dividing the global rate limit by runtimeContext.getTaskInfo().getNumberOfParallelSubtasks()
- In a scenario where we could increase the parallelism indefinitely, what will determine if we autoscale will be how busy the vertex containing our rate limiting operation is. If we have a rate limit of 100/s, it will be 100% busy as soon as we’re processing that many and are rate limited.
- In most situations however we will want to cap our total rate so we will need to configure a maximum parallelism.
- I’ve always thought that we should be making use of the full rate limit we’re allowed, such that even with a parallelism of 1, if our rate limit is 1000/s, that is our rate limit. If the vertex containing the rate limited operation scales to 2, the rate limit of each operator would now be 500.
  - Earlier we mentioned that busyness was used to determine when to scale. In this scenario, it seems we would only scale once we reached 1000/s. But then scaling would not help us, as we would simply be 100% busy but on more instances.
  - This approach only makes sense if scaling happens for a different reason than rate limiting, such as getting capacity limited or because we cannot reach the rate limit on a single instance. Another reason could be that the rest of the operations in the vertex make it highly busy.
- The downside of specifying a rate limit that is smaller than the total rate limit you have is that you will need to scale possibly unnecessarily because the instance could have handled all the rate limited operations of the global limit.
- What options do we have?
  - Keep the rate limited in the same vertex and divide the global rate limit by the number of parallel subtasks
    - This allows us to benefit from lower overhead communication between operators
  - Isolate the rate limited operation in its own chain
    - This allows the operation to scale independently of what happens before and after.
    - The downside is increased overhead to transfer the data between the chains before and after.
  - Partially isolate the operation in a new chain (either with the operators before or after)
    - It’s a trade-off of the benefits of full isolation with no isolation, namely that overhead is partially reduced, but you may affect the parallelism of other operations within the same vertex.

Learning - 2024

tom@tomrochette.com (Tom Rochette) — Mon, 21 Oct 2024 00:00:00 +0000

(sorted alphabetically)

Apache Beam
Apache Flink
Buildkite
DBT
Scala
Skypilot
Vertex AI (endpoint, feature store, pipeline)

Solving hard software problems

tom@tomrochette.com (Tom Rochette) — Tue, 17 Sep 2024 00:00:00 +0000

For problems related to environment setup, trying to accomplish the same thing on two computers can help identify disparities caused by the environment and not the code itself.
If you are blocked when trying to solve your problem, define timebox how long you will continue attempting to address the problem before changing your approach.
- Every half-hour/hour ask yourself “Have I made progress in the last period?” If the answer is no, define a time limit before reassessing your next steps

Tools

tom@tomrochette.com (Tom Rochette) — Mon, 26 Aug 2024 00:00:00 +0000

Tools I use on a regular basis at work (sorted alphabetically).

Apple calendar
Chrome
Cursor
gh (GitHub CLI)
ghx
git
GitHub
gt (Graphite CLI)
gcloud (Google Cloud CLI)
Google suite (Calendar, Docs, Meet, Sheets, Slides)
LLMs: GLM 5.3 Flash
iTerm2
Jetbrains Toolbox
OpenChamber
opencode (OpenCode)
OpenLens
Pi
podman (Podman)
Postman
PyCharm
Rectangle
Slack
Stats
VS Code

Calendar reminders

tom@tomrochette.com (Tom Rochette) — Fri, 23 Aug 2024 00:00:00 +0000

Daily

15m to document
1h lunch

Weekly

30m 1:1 with coworkers I work with on a daily basis
30m 1:1 with my manager
2 1h for continuous learning

Weekly readings - 2024-06-30

tom@tomrochette.com (Tom Rochette) — Mon, 08 Jul 2024 00:00:00 +0000

Gradually, then Suddenly: Upon the Threshold I’ve recently started playing with Claude 3.5 artifacts for fun to prototype an idea I had and while I struggled to get it to do something “fairly” simple, I was impressed with the ease of prototyping compared to if I had to do it myself. I expect this to continue to improve, reducing the amount of time spent on setting up your development environment and getting more immediate results.

[…] I suggest that people and organizations keep an “impossibility list” - things that their experiments have shown that AI can definitely not do today but which it can almost do.

Innovation through prompting Pretty exciting ideas on how to use LLMs to enable more dynamic teaching, even though it might not be perfect.

Algorithmic progress in language models

[LLM] Models require 2× less compute roughly every eight months

This would be 3 times faster than Moore’s law (every 24 months). Similar to Moore’s law, the big question is when we’ll reach a plateau on those performance improvements.

How to Make Yourself Into a Learning Machine A lot of things I’ve found myself doing over the years, mostly reading many books each year, keeping quotes (highlights) and notes from what I’m reading, using Anki to learn and remember languages and concepts/ideas, the use of Zettelkasten (but really, just the habit of writing down any thoughts into a digital note), etc. Definitely a recommended read it you’re into personal information management.

Writing one sentence per line A good way to make your writing clear and to the point. I also suggest to use easy words instead of fancy ones that people don’t often use.

Weekly readings - 2024-06-23

tom@tomrochette.com (Tom Rochette) — Fri, 28 Jun 2024 00:00:00 +0000

How to… use ChatGPT to boost your writing Tips from the article:

More elaborate and specific prompts work better.
You can ask the AI to use specific styles for writing.

Tips from me:

Use it to review your syntax, grammar, clarity, tone, biases, identify convoluted sentences, sentences that are too long.
Use it to generate alternative sentences when you don’t like how yours reads.
Ask it to give you feedback on what you have written so far, what gaps are there.
Ask it to produce an article with the opposite viewpoint.

Working with AI: Two paths to prompting

Structured Prompting is about turning the AI into a tool that does a single task well in a way that is repeatable and adapts to its user.

Structured prompts are very powerful. Once you start using a LLM regularly you’ll frequently have the same type of requests which will nicely lead you to collect those statements (prompts) so that you can simply copy/paste them and adapt them to your new use case. I think that being able to share, easily edit, and observe how others use your structured prompts can help you improve them. I’ve personally found that reading other people’s prompts enabled me to broaden my capabilities and the breadth of my thinking.

LLM prompting guide Tips:

When choosing the model to work with, the latest and most capable models are likely to perform better.
Start with a simple and short prompt, and iterate from there.
Put the instructions at the beginning of the prompt, or at the very end. When working with large context, models apply various optimizations to prevent Attention complexity from scaling quadratically. This may make a model more attentive to the beginning or end of a prompt than the middle.
Clearly separate instructions from the text they apply to.
Be specific and descriptive about the task and the desired outcome - its format, length, style, language, etc.
Avoid ambiguous descriptions and instructions.
Favor instructions that say “what to do” instead of those that say “what not to do”.
“Lead” the output in the right direction by writing the first word (or even begin the first sentence for the model).
Use advanced techniques like Few-shot prompting and Chain-of-thought
Test your prompts with different models to assess their robustness.
Version and track the performance of your prompts.

Cognitive Load is what matters Interesting way to discuss cognitive load when reading code.

No, you don’t owe me a favor

If I take the time to do something for you, it’s not because I’m a matcher looking for something in return. It’s because I aspire to be a giver—I enjoy being helpful. My effort to support you means that I think highly of you and might even care about you. When you say you owe me, it reduces my investment in you to an accounting transaction.

Something that resonated with me quite a lot. When I do things for others, it’s not because I expect things in return. Maybe the only thing I hope is that you acknowledge and possibly appreciate the help, but I don’t expect reciprocation.

Weekly readings - 2024-06-16

tom@tomrochette.com (Tom Rochette) — Fri, 21 Jun 2024 00:00:00 +0000

I read more articles from https://www.oneusefulthing.org this week.

How to… use AI to teach some of the hardest skills Very insightful article on the topic of using LLMs to teach students… or yourself. Based on this article I started learning about sociology terms, electronics, tried to have it role play a senior software backend engineer I could practice mentoring (and get mentoring feedback from). I also added the prompt “Explain how X works” to my prompt collection. I love articles that expand my thinking and exploration.

Prompt to learn about a domain through question/review cycles: Act as an expert in X. Ask me to explain a concept and then correct me if I’m wrong. Then restart the process, continuing endlessly.

How to… use AI to unstick yourself I’ve been using LLMs a lot to help me get some quick sanity check on thoughts I have and see what I might not have considered. I think LLMs are a rather useful tool to help you stay motivated when you feel a bit stuck or don’t want to particularly work on a piece of code. It’s like having a peer that’s always willing to help.

Thinking companion, companion for thinking Two heads are generally better than one. LLMs can be your second head when you need to think about what might go wrong or to address gaps in your thinking. You should also learn about opportunity cost and sunk cost!

ChatGPT is my co-founder One of LLMs strengths is their ability to always be somewhat helpful. One helpful thing they do is lowering the barrier to doing anything, as long as you know how to ask for help. While I code this mostly means giving me a small push to accomplish a task I would partially complete without its help. When writing, it’s a great tool to stimulate creativity and get feedback on which you can act.

Superhuman: What can AI do in 30 minutes? More and more of how you decide to spend your time will decide how effective (or not) you are. In this article the author spends 30 minutes to accomplish the following with the help of generative AI:

Output: Bing generated 9,200 words or so of text and a couple images, GPT-4 generated a working HTML and CSS file, MidJourney created 12 images, ElevenLabs created a voicefile, and DiD created a movie.

Input: I made less than 20 inputs to all the systems to generate these results.

Assuming that there were only 20 interactions, that would mean ~1 minute between interaction. Over a 30 minutes period, most of the time is likely spent on reviewing the generated content and then deciding our next move/writing prompts. A time breakdown would have been interesting.

Weekly readings - 2024-06-09

tom@tomrochette.com (Tom Rochette) — Fri, 14 Jun 2024 00:00:00 +0000

I discovered https://www.oneusefulthing.org and ended up reading a few articles.

ChatGPT Remembers What I Tell It. It’s Now My Personal Digital Assistant! The addition of implicit memory is an exciting move toward a more useful AI agent that knows more about you and your preferences. It’ll be interesting to see how this evolves.

Experimenting with AI code review The article is a few months old so it’s hard to say if newer models have addressed the concerns of the article. The main value here will be over time to get closer to instant feedback while implementing changes instead of having to push code to get a code review.

Almost an Agent: What GPTs can do I’m looking forward to OpenAI and other GPT providers to allow GPT creators to review their users feedback when interacting with their bot. The idea here is that a GPT is software, so it needs to evolve and adapt to new needs and requirements as well as address bugs in its behavior.

How to… have better meetings A few good tips on having better meetings. See Meetings for my own meeting process.

Captain’s log: the irreducible weirdness of prompting AIs Prompting is weird. Over time we expect LLMs to get smarter and better at inferring our intent such that becoming good at prompting isn’t a skill you shouldn’t invest too much into. Until then, it’s somewhat similar to knowing how to write good search engine queries.

Written by

tom@tomrochette.com (Tom Rochette) — Tue, 11 Jun 2024 00:00:00 +0000

All articles on this blog originate from my mind. Most articles are written by me, but some are partially or entirely AI/LLMs‑generated.

Those articles will be tagged accordingly:

No tag for completely original content.
partially-ai-generated for articles with one or many AI-generated sentences or with some feedback provided by AI. This covers articles where there is 1 word changed by AI to the article being almost entirely written by AI but with some human input.
fully-ai-generated when all the content is AI-generated. This covers articles that are entirely written by AI without any human input (except for possibly removing sentences).

I also use additional tags in relation to AI usage, namely:

ai-feedback for articles that were edited following AI feedback.

I tag the articles with the LLMs that were involved. Look for tags starting with llm=.

I use a variety of LLM providers (in order of frequency of use):

References
#

https://sive.rs/ai

Quotes

tom@tomrochette.com (Tom Rochette) — Fri, 10 Nov 2023 00:00:00 +0000

Marcus Aurelius
#

The happiness of your life depends upon the quality of your thoughts.

Seneca
#

People are frugal in guarding their personal property; but as soon as it comes to squandering time they are most wasteful of the one thing in which it is right to be stingy.
He who spares the wicked injures the good.

Zeno
#

No loss should be more regrettable to us than losing our time, for it’s irretrievable.

Learning - 2023

tom@tomrochette.com (Tom Rochette) — Sat, 31 Dec 2022 00:00:00 +0000

(sorted alphabetically)

ChatGPT
Parenting
Prompt engineering

Incident investigation

tom@tomrochette.com (Tom Rochette) — Thu, 14 Apr 2022 00:00:00 +0000

Define the incident owner
Define the incident secretary/communicator
Create and document
- Summary
- Observations (link to metrics dashboards with absolute timestamps as much as possible)
  - Screenshots
    - Who took the screenshot
    - Link to get the graph/data
    - Associated conclusions
  - Links to logs
- Hypotheses/theories
  - Who made them
  - When
  - If they have been validated/invalidated
- The actions taken
  - By whom
  - If it had the desired effect
- etc.
In the situation where an incident has been caused by the introduction of a code regression, revert the change and deploy as soon as possible
Start by reducing/relieving the impact of the incident before searching for a root cause
Use multiple data sources when data sources do not agree
Diagram all the implicated systems and the relationship to one another in order to identify the potential locations where the problem might be
Test your hypotheses to verify if they hold or not
Develop a procedure over time that can be followed to diagnose similar issues
Write down a list of improvement suggestions in order for the incident not to reproduce itself in the future or to lessen its impact
Once the incident is completed, have a summary of the conclusions at the top of the document with a link to the sections in the document explaining the rationale behind the conclusions

Incident post-mortem

tom@tomrochette.com (Tom Rochette) — Thu, 14 Apr 2022 00:00:00 +0000

Identify the cause of the problem
- 5 whys
List potential solutions
Investigate potential sources of similar problems
Address the additional sources of risk

Goals
#

Reduce incident duration
- Identify the cause of the problem more rapidly
Reduce incident cost
Reduce the number of people involved

Learning - 2022

tom@tomrochette.com (Tom Rochette) — Fri, 14 Jan 2022 00:00:00 +0000

(sorted alphabetically)

Ads mediation
Ads serving
GCP
- Traffic director
Grafana unified alerts
Managing large scale services (500k+ rps)
Imply
Renovate

Monthly review

tom@tomrochette.com (Tom Rochette) — Mon, 03 Jan 2022 00:00:00 +0000

Trigger
#

Every month, either at the beginning or end of the month.

Duration
#

30 minutes.

Steps
#

Fill out the (internal) employee survey (Gallup Q12) to assess my engagement at work
Review what was planned for the month
Provide feedback related to the plan
Review yearly plan and align
Plan next month

Yearly review

tom@tomrochette.com (Tom Rochette) — Mon, 03 Jan 2022 00:00:00 +0000

Trigger
#

Every year, either at the beginning or end of the year.

Duration
#

A few hours spread over the course of a few days.

Steps
#

Review year according to various facets
Plan the next year according to the same facets

Notes
#

I use a mind map software to do my yearly review and plan.

References
#

Learning - 2014