DEV Community: Isamu Arimoto

The Missing Bottom Layer: Why AI Isn't Making Your Company Faster

Isamu Arimoto — Sat, 10 Oct 2026 22:46:51 +0000

A "business harness": minimize human intervention, keep quality constant.

This is an English adaptation of a Japanese article published on the Singularity Society site. It grew out of a talk, "Living at 500 commits a day with MulmoTerminal" (2026-09-06), whose second half was about the three-layer harness that lets AI write software without a human reading every change. The examples here are rewritten for US-style business practice. Everything from section 4 onward is a hypothesis we have not yet validated. Times and counts are illustrative, not measured.

Contents

Drafting takes 30 minutes now. Reading hasn't gotten any faster
The bottleneck moved to "after drafting"
What already happens in software development
What a business harness is
What's missing from the tools you already have
The core idea: make the AI produce fields, not prose
Five scenes: inbound lead, business trip, client dinner, business case, vendor invoice
Turning human judgment into a mechanism
Where to start
Open questions
Build the layer, not the app
Sidebar: the software vocabulary
Appendix: glossary, sources

1. Drafting takes 30 minutes now. Reading hasn't gotten any faster

An account executive drafts a proposal with a generative AI. What used to take half a day takes 30 minutes. So far, this is happening everywhere.

The problem starts after that. The draft goes to the VP of Sales, who reads the whole thing. The pricing section is thin, so it comes back. The AE fixes it and resubmits; the VP reads the whole thing again. It goes to Legal, who reads the whole thing. The assumptions section is missing, so it comes back. Fix, resubmit, and the VP reads it a third time. The customer gets it four to five business days later. Humans have read it end to end five times.

AI sped up one step, "drafting." The "checking" steps have not moved an inch. And because AI can now produce more drafts, the checking side is busier than before.

This is not a model problem. It is not a prompting problem. There is no mechanism in the business workflow that decides, before a human looks at it, whether an AI-made artifact is stopped or passed.

Software development already has that mechanism. This article calls it a harness and asks what it would take to port it to business work.

2. The bottleneck moved to "after drafting"

Replay the proposal story by what humans physically did.

Read — the VP three times, Legal once, the AE once
Fix — the AE twice
Carry — the AE emailed it to the VP, to Legal, to the customer
Search — next month, a different AE gets the same pushback and digs through old email threads to find out why

AI did only "draft." Everything else ran on human hands, at human speed. However fast the AI gets, the whole thing tops out at "how fast a human reads."

Two numbers run through the rest of this article.

Human interventions — how many times a human read, fixed or carried the artifact before it reached its recipient. In the story above: read 5, fix 2, carry 3, so 10
Decision split — of the decisions made about that artifact, what share was made by a machine, by an AI, and by a human. Above: humans made 100%

The harness exists to move those two numbers: interventions down to the entry and the exit, decisions shifted toward the machine. Quality is measured separately, by post-delivery returns, corrections and incidents. If you cut interventions and those go up, you are doing it wrong.

3. What already happens in software development

Software teams hit this problem first, when AI started writing code, and answered it first. In the author's environment, AI-written changes are checked and merged a few hundred times a day. No human reads all of them; nobody even tries.

Broken changes still don't get in, because there are machine checks between the steps, and when a check fails the AI is sent back to redo the work. The flow:

A human writes what they want, one ticket per request. Rough is fine; the AI tidies it
The AI makes the change
Machines check it. Style rules, type consistency, each unit's behavior, the end-to-end path. If anything fails, the AI fixes it and re-runs. No human looks
A different AI reads it and comments. The AI fixes. This loops automatically until the reviewer is satisfied
What reaches a human is "a change that passed everything" plus "the points the AI wants a human to rule on"
A human decides whether to merge. Minutes
When the same comment appears twice, it becomes a machine rule. After that, neither humans nor AIs ever see it again

Humans touch steps 1 and 6. Most decisions are made by machines; the AI's job is to keep reworking until the machines pass it. Requests, changes, check results, comments, decisions and history all live in one place (GitHub).

The important part is the shape, not the tool names. Machines stop. AI drafts and flags. Humans see only exceptions. Everything runs in one place, and the same comment never reaches a human twice. The tools are in the sidebar at the end.

4. What a business harness is

Definition

A business harness is the control system that lets an AI agent produce output of consistent quality while cutting human intervention to the minimum.

AI behavior is probabilistic. The same request produces different output every time; one day the assumptions are missing, another day a number has no source. A harness wraps that variance in deterministic constraints and increases the number of decisions made by machines, so that the output stabilizes even though the AI does not. You don't make the AI smarter. You harden what surrounds it.

Three layers

Control is organized in three layers. The lower the layer, the wider and the stronger.

Layer	Role	Nature of its judgment	Authority	Software counterpart
Machine	Stop	Same input, same answer, every time (deterministic)	Decides pass / fail	lint, type checks, unit tests, end-to-end tests, CI
AI	Draft, flag	Same input, different answer (probabilistic)	Redo, attach concerns. No authority to stop	code generation, AI code review, cross-review
Human	Notice, decide	Understands anything, but slow and headcount-bound	Final call, exceptions, policy	PR merge decision; MulmoTerminal for noticing

Only the deterministic layer, the machine, can hold the authority to stop. AI judgment fluctuates, so it cannot be the gate. Make it the gate and the same proposal passes on Monday and fails on Tuesday. Nobody follows a verdict that cannot be explained.

So what does the AI do? It drafts and it flags. There is a step where an AI "approves," but it is not a gate: two AIs trade comments and fixes to reduce the number of open points that reach a human. Whatever the AI did not sign off on is attached as a "concern," and the human decides.

Ten stages

Where do the controls go? Split the workflow into ten stages; every stage has a control point, "who decides here."

Stage	What happens	Who decides	Software counterpart
① Request	Record who wants what, by when, in what form	Human asks, AI tidies	Issue
② Context	Hand the AI the company standards, procedures, policies, history, budget, related records	Machine keeps one source; AI reads	CLAUDE.md / skills / the repo's code and design docs
③ Draft	Produce the artifact	AI	AI writes code, opens a PR
④ Machine check	Structure, consistency, prohibited content, cross-references	Machine	lint / types / unit / e2e / duplication, run in CI
⑤ AI review	A second AI reads, comments, the first fixes; loops until satisfied	AI (never stops)	AI code review → fix → LGTM loop
⑥ Human decision	Humans see only what passed, plus the AI's concerns	Human	PR merge
⑦ Send / execute	Send to the customer, sign, pay. The irreversible point	Machine runs the final check and executes; the human's "OK to send" was given in ⑥	merge → release / deploy; branch protection blocks unverified merges
⑧ Record	Who decided what, when, on which version	Machine	GitHub: issue, PR, reviews, CI results, history
⑨ Visibility and alerts	Where things are stuck and how many are waiting, across all document types	Machine shows; humans notice	MulmoTerminal / notifications
⑩ Improvement	Count returns and comments; turn repeats into rules	Machine counts; humans decide	same comment twice → lint rule / test (warn → error)

The ten stages need one place where they all live (a hub). If requests, artifacts, check results, decisions and history sit in different systems, humans end up carrying things between stages.

The harness's job is to keep pushing decisions downward: the points humans used to find by reading go to the AI's flags; whatever can be written as a rule goes to the machine. The further down, the fewer the interventions and the smaller the variance.

Not only stopping: surfacing

Checking is only half of the harness. Stage ② is not just "hand over the company standards." It is find every record relevant to this piece of work, including the ones the human has forgotten, and put them in front of the AI.

Before a client visit: when did we last meet this contact, what did we discuss, what did we bring? At the dinner, what did their VP order and what did she avoid? What has their company announced in the last month? If a web inquiry turned into a deal: the original inquiry text, the SDR's qualification notes, the call transcript, past proposals and quotes, their latest 10-K.

Humans forget. When the account owner changes, it all disappears. Machines don't forget. As long as the records are in the hub, the AI reads them and becomes the one proposing the next move: a gift suggestion, the skeleton of a business case, the first draft of a quote, the trip report. The time humans spent remembering, searching and asking around goes away.

Stopping (④) and surfacing (②③) run on the same data in the same hub. One without the other does not connect. The records you structured for checking are the same records that feed the proposals.

5. What's missing from the tools you already have

Businesses are not short of parts. If anything they have too many.

Drafting — ChatGPT, Claude, Gemini, Microsoft 365 Copilot, Gemini for Google Workspace, Notion AI
Saved instructions — custom instructions, GPTs, Claude Projects, Copilot Studio agents, the internal prompt library
AI review — contract lifecycle management with AI playbooks (Ironclad, Evisort and others) that flag missing clauses and off-policy language and suggest fallbacks. Copilot's and Grammarly's document review
Human approval — approval workflows in Salesforce, NetSuite, ServiceNow or Jira; delegation-of-authority matrices that say who can approve how much
Send and sign — e-signature (DocuSign and others), increasingly bundled with contract management and review
Machine checks — field validation in Salesforce and ERPs; three-way matching (PO, receipt, invoice) in accounts payable; expense platforms (Ramp, Concur, Expensify) that flag or, in Ramp's case, block out-of-policy spend at the point of purchase; data loss prevention (Microsoft Purview and others) that detects and blocks sensitive data across email, drives and chat

Each of these works inside its own territory. What's missing is not any one feature. It is four connections.

Gap 1: The stages are not connected and don't live in one place.
The request is in Slack, the context in Google Drive, the draft in a chat window, the approval in Salesforce, the delivery in email, the record in each system's own log. Every stage is in a different place, so humans carry things between them. The carrier's speed becomes the company's speed.

Gap 2: The machine layer is thin for documents.
Field validation works on data typed into a system, not on a proposal written in Word or Google Docs. Three-way match works on invoices, not on quotes. Expense policy engines work on card transactions, not on the SOW. DLP catches credit card numbers, not "the assumptions section is missing" or "a price marked tentative is written as final." And documents are exactly what AI now produces in volume.

Gap 3: There is no path from a return to a rule.
The reason for a pushback ends in an email to the author. Nothing counts, so nobody notices that the same comment has now appeared twice. Without this path, the number of items reaching humans never goes down.

Gap 4: No cross-cutting visibility.
You can see your own approval queue. You cannot see, across proposals, contracts, business cases and invoices, how many items are stuck where and for how many days.

The four are not independent. Without a hub (Gap 1) you cannot build visibility (Gap 4); without a machine layer (Gap 2) a new rule (Gap 3) has nowhere to land. So buying more parts does not connect them. This is not about replacing the products you have. It is about the "bottom layer" that wires them into one flow of control.

The condition for wiring: everything is data, everything runs through an API

That fixes a selection criterion for tools.

A harness is a mechanism where machines and AIs, not humans, carry work between stages. Machines and AIs can only drive tools that expose an API (a connection point for operating the tool from outside, without a human clicking through a screen). A tool that only moves when a human clicks forces a human into the stage. That tool sits outside the harness.

Three rules follow.

Everything becomes data. Requests, artifact fields, check results, decisions and reasons, delivery records. Also policies, budgets and approval records, and agreements made in email or chat. Not prose or screens for humans, but data machines and AIs can read and write
Everything runs through an API. Drafting, checking, approving, sending, recording: all callable by machines and AIs
Tools without an API don't go in the harness. However good the feature, if a human has to operate it, it cannot reduce human interventions

The role of the GUI follows too. A screen is a viewer for the human's final check. The human presses a minimal set of buttons: pass, return, OK to send. A product that piles features into its screen is designed for humans to drive the workflow; it points the opposite way from a harness, and the more convenient it looks, the more firmly it locks human intervention in place.

By this criterion, only tools with data and APIs can sit on the ten stages. Keep the approval system and the e-signature tool if they connect through an API; replace them if they don't.

6. The core idea: make the AI produce fields, not prose

Building a machine layer for documents takes one change of mindset. Stop asking the AI to write a document. Ask it to produce fields.

Make the fields the source of truth

Today: ask the AI to "write the proposal," get prose, a human reads it.
Instead: ask the AI to "produce the proposal's contents as fields." Problem, approach, scope, price, assumptions, and the source for every number come out as fields. Machines check the fields; only what passes is rendered into prose.

quote    = fields (line items, unit price, quantity, terms, valid-until) + rendering
proposal = fields (problem, approach, scope, price, assumptions)        + rendering

The fields are the truth; the prose is their output. Four things follow.

Checks become writable — "at least one price," "every decision has an owner and a due date" are rules over fields. No reading comprehension required
Changes become meaningful — "what changed since the last version" is no longer a text diff but "the price changed," "one assumption was added." That is all a decision-maker needs
Contradictions become impossible — if the proposal and the quote reference the same price field, they cannot disagree
Wording changes don't break checks — the AI phrases things differently every time. Compare fields and a check fails only when the meaning changed

Don't run it backwards. "Write prose → have an AI extract fields → check" means the extraction fluctuates, so you are checking an estimate. "Produce fields → check → render prose" means the thing being checked is the truth. Use the AI to draft, not to judge pass or fail. Drafting may fluctuate; if it fails, send it back until it passes.

What machines can check, and what stays with the AI

Draw the line honestly. What a machine can check deterministically is field-to-field matching.

Machine, deterministic	AI, probabilistic
Are the required fields present (structure)	Is the content sound (is the price right, is a fourth assumption missing)
Do fields agree — proposal price = quote price, cover total = line-item total, start date < end date (consistency)	Does the argument hold together, is it persuasive
Is the source field filled and does the reference resolve (source present)	Is that source a valid basis for that number (source validity)
No prohibited terms; recipient and version match what was approved (prohibitions, identity)	Will it land with this reader; is the tone right
Do outside records agree — is it tied to an approved budget line; do invoice items and amounts match the PO, receipt and contract; does the expense carry amount, time, place, purpose and attendees and sit under policy caps; does it match the terms agreed in the deal record (cross-reference)	Reading an agreement out of free-form email or chat; judging whether an exception is justified in the spirit of a policy

The left column gives the same answer whoever looks, so it can be delegated to a machine, and the moment it is, that angle disappears from human review. The right column fluctuates, so the AI flags but never stops. The final word stays with a human.

Checking against facts outside the document

Checking a document on its own does not make it a correct document. An invoice is correct only when it matches the PO, the receipt and the contract. A business case can be approved only when it is tied to an approved budget line. A proposal's price must match what was agreed with the customer in email or on the call. An expense passes only when who, with whom, for what purpose and how much are explicit and within policy.

So the check runs not only inside the document but against four kinds of facts outside it.

History — prices, dates and scope agreed with the customer or internally in email, chat, calls and meetings. For a business case, the meeting where it was decided
Policy — the T&E policy, the delegation-of-authority matrix, pricing and discount rules, the gift policy, the conditions that trigger Legal review
Related records — quote, PO, receipt, contract (MSA/SOW), previous meeting notes, past business cases
Plan and budget — the approved annual operating plan and its remaining balance, the OKRs or targets it serves, the approval records

That is why section 5 said "everything becomes data." While the policy lives in a PDF, the agreement lives in an email and the budget lives in a spreadsheet, cross-referencing is a human job. Once they are data in one place, it is a machine job.

The evidence chain: no document stands alone

From here to the end of section 6 is about the internals. If you only need to decide whether to try this, read the scenes in section 7 and the steps in section 9 first, and come back to these tables when you implement.

Company documents are built on earlier documents. A typical chain:

meeting decision → business case → spending approval → PO → receipt → invoice → payment → expense report
       ↑               ↑                 ↑                                              ↑
   OKRs / AOP     approved budget   quote / contract                       pre-approval / budget
   (strategy)     (line + balance)  (MSA / SOW)

The horizontal arrows are document order; the vertical arrows are the evidence that supports each document from below. The annual budget is not on the main line. It was approved at the start of the year, and it supports the business case, the spending approval and the PO as an existing frame. Every arrow is a reference. The business case carries the meeting-decision ID and the budget line; the spending approval carries the business case ID and the budget ID; the invoice carries the PO number and the receipt number. When references are IDs, a machine can verify the same five things for every one:

Existence — the referenced record exists
Status — it is approved and in force. Not a rejected case, an expired quote, or last year's closed budget
Values — amounts, quantities and periods match; for a budget, the balance covers it
Period — the fiscal year matches. This year's case is not pointing at last year's line
Authority — the requester and approvers are allowed, per the delegation-of-authority matrix, to raise and approve this; the body that made the decision had the power to make it

Per document, the evidence to reference and what the machine verifies:

Document	Evidence to reference	What the machine verifies
Business case	The meeting decision that spawned it. The AOP line and its balance. The OKR it serves. Related past initiatives. Sign-off from affected teams	The decision includes "build a case," owner matches the author. The budget line exists, is approved for this fiscal year, and the balance covers the ask. The OKR link is a field. If a similar initiative ran before, its outcome is referenced
Spending approval	The approved business case. The budget ID. The attached quote. The DoA matrix	Case is approved. Budget is current-year and sufficient. Amount matches the quote. Routed to the approver the DoA requires for this amount
Proposal / SOW	The opportunity record. Agreed price, timeline and scope. The price book version. Discount approval	Matches the agreed terms. Price book is current. Discount within policy, or deal-desk approval is attached
Quote	The proposal or opportunity. Price book. Discount approval. Previous quote	Price matches the proposal. The delta from the previous quote is tied to a recorded agreement
Contract (MSA / SOW)	Proposal and quote. The standard clause library version. The Legal review record	Price and scope match. Clauses are from the current library. Deviations carry an approval. If Legal-review triggers apply, review is recorded
Purchase order	The approved spending request. The quote. The budget	Approval is in force. Amount matches the quote. Budget balance covers it
Vendor invoice	The PO. The goods or service receipt. The contract's payment terms. The vendor master	Items and amounts match the PO. Receipt is complete. Due date matches the contract. Bank details match the vendor master, and any change has a verified callback on file
Expense report	Pre-trip approval or spending approval. Budget. T&E policy. The vendor/contact record. The opportunity or initiative it served	Amount, time, place, business purpose and attendees are all present. Matches the pre-approval. Within budget. Within per-diem and policy caps. Attendees exist in the CRM and the purpose links to an opportunity or initiative ID
Meeting notes	Previous notes. The body's authority. Attendee records	Previous decisions carry a status. Decisions above the DoA threshold link to a spending approval. The body that decided had the authority to

Everything in the right column is matching of IDs, statuses, values, periods, authority and field values, which a machine can do deterministically. "Where's the evidence?" "Is there budget for this?" "Which meeting decided that?" — the questions people ask out loud today — all land here.

How references get created

If humans wrote the references by hand, this would last as long as any paperwork reform. Split it: the AI creates, the human confirms, the machine verifies.

The AI finds the evidence and links it — when drafting a business case, the AI searches the hub for the relevant meeting decision, budget line and OKR, and links them by ID
The human confirms once — "is this meeting, this decision, the right basis?" Reading free-form text fluctuates, so a human looks here, once
The machine verifies from then on — existence, status, values, period and authority of the linked IDs, at every later step: when the case goes for approval, when the PO is cut, when the invoice arrives

History needs the same care. Pulling "the agreed price" out of an email thread or a call transcript is AI work and fluctuates. So the extracted agreement is attached to the request as a field and a human confirms it once; after that, matching is field-to-field, by the machine. Same direction as the start of this section: don't re-read free text every time; turn it into a field once and make the field the truth.

Expenses are where this bites hardest. Who, with whom, for what purpose, how much, as fields; tied to a budget ID and an approval record; under the policy cap — all verified by the machine before a human sees it. If anything is missing, it goes back. Spend against a budget that was never approved stops right there. The same holds for initiatives: a business case not tied to a decision and a current-year budget line does not go to approval.

Check the machinery, not just the output

Checking each finished artifact is not enough. You also check that when a template, an AI instruction or a procedure changes, the artifacts coming out keep their properties. This is the unit test and the end-to-end test of section 3.

The failures are silent. Someone tidied the proposal template's layout and the assumptions section vanished. Someone shortened the AI's instructions and quotes stopped carrying a valid-until date. A field was renamed in the ERP and forecast revenue came out as zero.

The fix: keep a fixed set of inputs (a handful of past deals), regenerate automatically every time the machinery changes, and run the checks above. If anything fails, the change is blocked. Nobody waits for a human to notice; it goes red the moment it changes. Software teams call this a test, and since the AI now writes the tests, the cost of adding them has fallen a long way.

The last step

If the AI also renders the fields into prose, you need one more check after rendering, because rendering is where a number not in the fields gets added, or "tentative" gets rewritten as final.

Draw the line here too. Whether every number, date and proper noun in the fields appears in the prose can be matched by a machine. Whether the prose contains a claim that is not in the fields requires reading meaning, so it stays with the AI review. If you want that second half on the machine, render with templates: the check disappears, at the cost of stiffer prose. How much to let the AI write is that trade-off.

7. Five scenes: inbound lead, business trip, client dinner, business case, vendor invoice

Now the whole thing against real workflows. The flows follow common US practice. Times and counts are illustrative. The "human interventions" below extend the section 2 count to a whole workflow: every confirmation, approval, choice and execute instruction in the scene.

Scene 1: From a web inquiry to a proposal in the customer's inbox

Today

An IT manager at a prospect fills in the website form: "Must integrate with our existing order-management system. Looking at next fiscal year's budget." The form lands in a shared inbox; marketing routes it to an SDR. Industry data says inbound leads convert far better when contacted within five minutes, so the SDR calls, qualifies on BANT (budget, authority, need, timeline), and notes the economic buyer, the integration requirement and a competitor in evaluation. The notes live in the SDR's own doc. "Warm lead, booked for Thursday," goes in Slack. The AE runs discovery, then digs old proposals out of Google Drive and drafts with an AI. The form's "must integrate" and the SDR's "economic buyer is the CIO" never reach the AE. Then the section 1 story: VP reads three times, Legal once, deal desk reviews the discount, four to five business days to send.

With a harness

The form becomes the request record (①): company, contact, inquiry text, source
The SDR's call is turned into fields by the AI after the call: budget, timeline, economic buyer, existing systems, competitors. The SDR confirms once; it attaches to the request (①⑥)
The discovery call is also turned into fields and confirmed by the AE: agreed scope, concerns raised, open items (①⑥⑧)
The AI produces the proposal fields, reading the inquiry text, the qualification notes, the call fields, the prospect's latest 10-K and similar past deals on its own. "Integrate with order management" lands in scope, "next fiscal year's budget" in assumptions, "CIO" as the addressee, without anyone saying so (②③)
Machines check: price = quote, assumptions present, source field on the adoption-rate figure, no price marked tentative rendered as final, discount within policy or deal-desk approval attached. Failures go back to the AI (④)
A second AI reads: "the integration section doesn't answer the question they asked." The first fixes. One remaining point becomes a concern (⑤)
The VP's queue shows the fields and the concern. The VP reads the fields, not the prose, and approves through to "OK to send." The machine has already confirmed none of the Legal-review triggers apply (⑥)
Render, run the post-render match, verify recipient and version, send (⑦). Everything is on the request record (⑧)

Humans touched it three times: the SDR's confirmation, the AE's confirmation, the VP's approval. What the prospect typed into the form reached the proposal without passing through anyone's memory.

Scene 2: A business trip, from pre-approval to gift to expense report

Today

On the call: "We'll come to your HQ in Austin next week." Back at the desk, the AE files a pre-trip request in the T&E tool (about two-thirds of companies require one): dates, destination, purpose, estimate. The manager approves. Flights and hotel get booked by the AE. The day before: "should I bring something?" Nobody remembers what was brought last time, or whether the prospect's company even allows gifts; something gets picked up at the airport. Afterwards, a trip report, and an expense report: flights, hotel, meals against per diem, receipts for anything over $75 (policy says $25), all within 30 days. Finance checks it against policy. The hotel is over the city cap: returned. The AE writes a justification and resubmits.

With a harness

The moment "on-site visit, date" becomes a field in the deal record, the AI drafts the pre-trip request: dates, destination, purpose, estimate, the opportunity ID. The AE confirms and presses "submit" (①②③⑥)
Machines check: hotel within the city cap, meals within the GSA per-diem for the destination, the opportunity's travel budget has balance (④). It lands in the manager's queue; the manager presses "approved" (⑥)
Flights and hotel are booked through the travel tool's API on approval (⑦)
The day before, the AI surfaces: the three attendees, names and titles. Last visit was in April; we brought a box of local pastries. The dinner record notes their VP avoids sugar. Their press release from last week. Our open items from last time (②)
On the gift: the AI first checks the prospect's published gift policy on the account record. If their policy forbids gifts, or the contact is a public official where FCPA applies, it says so and proposes no gift. Otherwise it suggests two options under our gift cap, mindful that the IRS deduction limit is $25 per recipient per year, individually wrapped for the headcount, not a repeat of April, and not from a store next to their office (③). The AE picks one (⑥)
On the way home, the AI drafts the trip report from the meeting fields and the expense report from the corporate-card feed and the booking records, applying per diem from policy (②③)
Machines check: dates within the trip window, amounts match the card feed, receipts attached for anything at or above the policy threshold, hotel under the cap, per diem for the right city, no duplicate of a card line (④)
The AE reviews the fields and presses "submit" (⑥). What reaches Finance is only the exception that needs a human reason, such as a late-night rideshare outside policy

Humans: the AE three times (submit the request, pick the gift, submit the report), the manager once. Finance: zero, or one on an exception.

Scene 3: A client dinner on the expense report

Today

Dinner with the prospect's VP and two of her team. The AE keeps the receipt. The following week, the expense tool: date, restaurant, amount, attendees. US tax rules require five things for a business meal: amount, time, place, business purpose, and the business relationship of everyone at the table; meals are 50% deductible, and if the evening had included a game or a show, that part would not be deductible at all. The AE reconstructs titles and company names from memory. The manager approves; Finance reviews. "Business relationship missing for one attendee": returned.

With a harness

The dinner was scheduled from the deal record, so attendees are already fields: three from the prospect, two from us, the opportunity ID (⑧)
The corporate-card transaction arrives through the API. The AI drafts the expense fields: date, restaurant and city, amount, each attendee's name, company and relationship, headcount, business purpose (the opportunity ID), per-person amount (②③)
Machines check: attendees match the meeting record, all five substantiation elements present, receipt attached (over $75), per-person amount within the policy cap, no entertainment line mixed in, matches the pre-approval, no duplicate receipt, budget balance (④)
If it passes, the AE presses "submit" (⑥). Finance sees only what fell outside policy

Humans: the AE, once. "Who, with whom, for what purpose, how much" is assembled by the AI from the meeting record and the card feed and verified by the machine, not reconstructed from memory.

Scene 4: From a business case to spending approval and the annual budget

Today

In the quarterly planning meeting: "Let's run a partner training program next year." The owner writes a business case from scratch. Which budget line has room? Ask FP&A. Which company OKR does it serve? Write it in the first paragraph, from memory. The spending request goes up the delegation-of-authority chain: manager, director, VP. The VP sends it back: "That line is already committed for the year." "Didn't we try a partner program two years ago? What happened?"

With a harness

The planning meeting's notes carry the decision as a field: "Build a case for partner training. Owner: A. Due: March 15" (⑧)
The AI drafts the business case fields and, as it does, surfaces the decision ID, the matching AOP line and its remaining balance, the OKR ID, and past similar initiatives with outcomes. "Partner training, two years ago, cancelled: attendance was half of plan" goes into "prior history" even though nobody remembered it (②③)
The owner confirms once: "this meeting, this budget line, this OKR are the right basis" (⑥)
Machines check: the decision exists and the owner matches; the budget line exists, is approved for this fiscal year, and the balance covers the ask; the OKR link is a field; the prior initiative's outcome is referenced (④)
A second AI reads: "the benefit estimate doesn't state an attendance assumption." The first fixes. What remains becomes a concern (⑤)
The director's queue shows the fields and the concern. The director checks the evidence links and the concern, and approves (⑥)
The spending request inherits the case's fields. The machine confirms the amount matches the attached quote and, per the DoA matrix, routes it to the VP (③④)
The VP decides on two things only: that decision, case, budget line and quote are linked by ID, and the concern (⑥)

Humans: the owner once (confirming the evidence), the director once, the VP once. "Is there budget?" and "didn't this fail before?" are verified by the machine when the case is drafted, not discovered by a human halfway up the approval chain.

Scene 5: From a vendor invoice to payment

Today

An invoice arrives as a PDF by email. AP matches it against the PO and the receipt: is the bill-to right, is the vendor the one we expected, do items and amounts match the PO, is the tax right, are the bank details and due date there. The PO can't be found. Has the work been accepted? Email the requester. The amount differs from the quote. Email the requester. Payment waits for replies. Meanwhile, the email thread also contains, from last month, a "we've changed our bank account" message from the vendor's domain. The FBI logged about 25,000 business email compromise complaints in 2025, with reported losses above $3 billion, and most of that money moved by wire or ACH, which is close to unrecoverable once it lands.

With a harness

The AI turns the PDF into fields: vendor, invoice number, line items, amounts, tax, bank details, due date (③)
Machines check: the PO number exists and is approved; the receipt or acceptance record is complete; items and amounts match the PO; the due date matches the contract's terms; the bank details match the vendor master, and any change to them carries a callback verification to the phone number on file, never a number from the email; the amount is under the threshold for single approval, otherwise dual approval is required; no duplicate invoice number; budget balance (④)
What passes lands in AP's queue; AP presses "pay" (⑥). Payment executes through the bank API and the journal entry posts (⑦⑧)
What fails goes back with a reason. "Acceptance not recorded" appears in the requester's queue as "record acceptance"; the moment they do, the match re-runs (④⑨)

Humans: AP once; the requester once, on an exception. "Email the requester" becomes a status change on a queue, and the bank-change message never reaches a human who might believe it.

What the five scenes share

Humans touch the entry, the exit, and the exceptions neither machine nor AI could decide
"Remember," "search" and "ask around" become references inside the hub. What humans forgot, the machine surfaces
Stopping and surfacing run on the same data. The dinner's attendee list feeds both the gift suggestion and the expense check
Return reasons are counted as queue states, not buried in email

8. Turning human judgment into a mechanism

Some judgments stay with the AI's flags, so human evaluation never disappears. If it won't disappear, make how it happens a mechanism. Three parts.

Visibility — how many items are waiting on a human, where they are stuck, in whose queue, across every document type, on one screen
A place to decide — pass, return, or pick a reason, right there. Not in a meeting or an email. Reasons are a pick-list because they need to be counted
A path from decision to rule — the same reason twice is a candidate for a rule. If it can be written as structure, consistency or prohibition, it becomes a machine check; if not, it goes into the AI's instructions

Without the third, this is just the AI review products of section 5: "it told you." The mechanism counts; nobody has to notice. New rules enter as warnings, existing violations are cleared, then the rule becomes an error.

Accumulated human decisions also solve two problems. If the AI scores risk and "below 80 goes to a human," the 80 has no basis, but the distribution of passed-versus-returned items will tell you where to draw the line. And when the AI model is updated, re-run past human decisions as a regression test and detect every verdict that changed.

The accumulation is not a UX nicety. It is the mechanism that keeps shrinking the number of items reaching humans.

9. Where to start

You don't build all of it at once. The first 90 days can look like this.

Measure — take ten proposals, meeting notes and contracts; count human interventions from request to send, and the decision split (machine / AI / human). Count what share of past comments the section 6 tables would have caught
Put structure, consistency and budget/approval cross-references on the machine — presence of fields, matching numbers, a link to an approved budget line. Leave source validity and prose quality alone
Add the pre-send match — recipient and version equal what was approved. One deterministic check just before the irreversible point
Pick one surfacing target — past visits, dinners and open items before a trip; or the inquiry, qualification notes and past proposals before a draft. Hand the data you check with to the AI before it drafts
Make return reasons a pick-list and count them — line up every reason that appeared twice as a rule candidate
Connect the approval system and the e-signature tool if they have an API; replace them if they don't — wherever a human carries work between stages, make a machine carry it

Three objections, answered in advance.

"Our existing SaaS already does this." The individual features exist. What doesn't is one flow of control across document types from request to improvement. The four gaps in section 5 are connections, not features, and a product without an API cannot be on the connecting side. An API alone isn't enough either: you can surface last quarter's dinner notes before a trip only if they were recorded at that granularity.

"Will Legal, Finance and the auditors accept AI automation?" In this design, the AI never has authority to stop. Stopping is done by deterministic machine checks, and every pass and fail is on the request record. The human final decision remains. The conditions that trigger Legal review are themselves machine-checked rules. Compared with decisions passed around in email, this is more recorded and more reproducible, which is what a SOX-style control framework asks for in the first place.

"Won't quality drop?" Measure it by post-delivery returns, corrections and incidents. If interventions fall and those rise, move one step back up. That is why measurement goes first.

10. Open questions

Who pays for evaluation. If humans still evaluate every artifact, the bottleneck has moved, not shrunk. Visibility's job is not to be readable but to keep reducing what reaches humans; if that doesn't work, none of this holds. Reviewing fields instead of prose makes each item lighter; it does not make them fewer.

Documents whose shape can't be fixed. A proposal whose structure changes with every customer. How far can fields be enforced before quality suffers?

Evaluators disagree. Accumulating human decisions as ground truth assumes they agree. They don't. Whose verdict is the truth is unsettled.

Connecting existing systems. Wiring the approval system, e-signature and CRM into a hub is more an operations problem than a technical one. The migration order is not decided.

11. Build the layer, not the app

In software, nobody builds the section 3 machinery per project. There is shared infrastructure (GitHub, CI) and each project puts its own rules and tests on top. Business work has almost none of that shared layer, so every company writes its own prompts, wires its own approval chains and decides its own delivery steps, per workflow, from zero.

Build the layer first and every workflow on top of it moves much faster. And the layer accumulates: every workflow adds check rules, every decision adds to the human ground truth, the machine catches more, and fewer items reach humans. The more workflows it carries, the stronger it gets. That is the difference from an ordinary tool.

Requests, checks, approvals, delivery and records are needed by every business and differentiate none. That is exactly why they belong in a shared layer rather than in each product.

Author's note: this "shared layer" is one concrete piece of the Compound Startup idea presented at SS Connect: each venture keeps only its core and pushes everything else into shared infrastructure.

Sidebar: the software vocabulary

The tools from section 3, in business terms.

Term	What it does	In business terms
Instructions file (CLAUDE.md)	Standing instructions the AI reads on every task. Kept short; long files stop being followed	Custom instructions, the internal prompt library
Skill	A procedure the AI can invoke by name, so nobody re-explains it	A saved "how we write a proposal" the AI runs on request
lint	Machine checks on style rules, hundreds of them; fails block progress	"Does the proposal have a pricing section," checked by a machine
Type checking	Verifies "this value is money," "this value is a date"	Quantity can't be "about 10"; delivery date can't be "TBD"
Unit test	Pins "this input gives this output" per component; goes red when a change breaks it	After editing the quote template, the same deal still totals the same
End-to-end test	Replays a user's path from start to finish automatically	Run "opportunity → quote → approval → send" on a dummy deal
CI	Runs all the checks above on every change; nothing merges unless all pass	Every machine check sits before "send to next approver"
AI code review	A second AI reads the change and comments; loops to approval, but cannot block	CLM playbook review, run to approval automatically
Issue / merge	One ticket per request / taking a verified change into the main line	The request record / send and sign

Appendix A: Glossary

Term	Meaning
Harness	The control system that lets an AI agent deliver consistent quality with minimal human intervention: wrap probabilistic behavior in deterministic constraints and increase machine-made decisions
Deterministic / probabilistic	Same input, same answer, always / the answer varies
Machine / AI / human layer	The three layers: stop / draft and flag / notice and decide
Ten stages	Request, context, draft, machine check, AI review, human decision, send, record, visibility, improvement
Hub	The one place the ten stages live. In software, GitHub
Human interventions / decision split	The two numbers that measure whether the harness works (section 2)
Fields	The set of elements a document is made of: problem, price, assumptions. Prose is their output
Cross-reference	Checking a document against history, policy, related records and the plan/budget, not only against itself
DoA matrix	Delegation of authority: who may approve how much
Three-way match	Verifying PO, receipt and invoice agree before paying
BEC	Business email compromise: fraudulent payment or bank-change instructions sent while impersonating a vendor or executive
API	A connection point for operating a tool from outside, without a human at a screen. The precondition for machines carrying work between stages
GUI	The screen a human operates. In a harness, a viewer for final checks plus a minimal set of buttons

Appendix B: Sources

Original Japanese article: https://singularitysociety.org/articles/blog/2026-10-11-business-harness/
What a harness is on the software side, with six implementations (Japanese): https://zenn.dev/singularity/articles/agent-harness-anatomy
The talk this grew out of (Japanese slides): https://github.com/isamu/presentation/tree/main/2026-09-06-ai-event
Prior art for checking documents as structured data: Schematron (ISO/IEC 19757), remark-lint, textlint

The workflows in section 7 draw on:

Business meal substantiation, the $75 receipt rule, 50% deductibility and nondeductible entertainment (IRS Publication 463): https://www.brex.com/spend-trends/expense-management/irs-receipt-requirements, https://ramp.com/blog/irs-receipt-requirements
Procure-to-pay and three-way match: https://www.doss.com/glossary/three-way-match, https://lapasar.com/procurement/procure-to-pay
Inbound qualification, BANT / MEDDIC, five-minute response: https://leadfeeder.com/blog/marketing-strategy/b2b-sales-process, https://blog.hubspot.com/sales/a-step-by-step-guide-to-the-meddic-sales-qualification-process
Travel policy, pre-trip approval, GSA per diem, expense platforms: https://www.ramp.com/blog/corporate-travel-policy, https://ramp.com/blog/expensify-vs-concur-vs-ramp
Business gifts, the $25 deduction limit, FCPA: https://blog.giftpack.ai/article/en-corporate-gifts-united-states-tax-fcpa-privacy-import-controls, https://nolo.com/legal-encyclopedia/are-gifts-business-clients-deductible.html
Annual operating plan and budget approval: https://corporatefinanceinstitute.com/resources/fpa/budgeting-process-guide-fpa
Business email compromise, 2025 FBI IC3 figures, callback and dual-approval controls: https://www.eftsure.com/statistics/payment-fraud-index/, https://beancount.io/blog/2026/08/13/business-email-compromise-3-billion-fbi-payment-verification-controls-guide
AI contract review playbooks: https://ironcladapp.com/product/review-contracts, https://doc.workday.com/evisort/en-us/contract-management-and-document-intelligence/workflow/workflow-tickets/review-documents-with-ai-playbooks.html

ever-better: 13 commands that make a codebase only able to get better

Isamu Arimoto — Sat, 15 Aug 2026 09:43:57 +0000

Adding a strict linter to an existing repository produces four thousand errors and gets reverted. The usual workaround — set everything to warn — enforces nothing, and the count grows quietly.

ever-better is the way around that. It records every violation that exists today as a ceiling: old code is grandfathered, new code is held to the whole rule set, and the ceiling can fall but never rise.

Below is every command, what it does, and the problem it exists for.

npx ever-better <command>

MIT, zero runtime dependencies, Node 20.11+.

`diagnose` — what is missing, and what each gap costs

ever-better diagnose            # read-only
ever-better diagnose --write    # also writes QUALITY.md

What it does. Surveys the repository — package manager, language, framework, runtime, ESLint setup, formatter, test runner, dead-code and duplication scans, agent instructions, CI, file sizes — and lists the gaps with the phase each belongs to.

Why. "Add linting" is not a task; it is six of them in an order that matters. Formatting has to land before linting or the first cleanup PR is a diff nobody can read. Type-aware rules cannot run without TypeScript. This prints that order instead of leaving you to discover it.

`bootstrap` — install the tooling, generate the configs

ever-better bootstrap
ever-better bootstrap --dry-run

What it does. Adds the dependencies, writes eslint.config.mjs, Prettier config, .gitattributes, knip.json, the package scripts CI needs, workflows for three platforms, dependabot.yml, and a secret-scan workflow. Prices each TypeScript strictness flag by enabling it in a temporary config and counting the errors — turning on the free ones, reporting what the rest would cost.

Why. Every rule it writes is an error, not a warning. That is only survivable because of the next command.

`freeze` — pin today's violations as the ceiling

ever-better freeze

What it does. Runs eslint --suppress-all, which records how many violations each rule has in each file, then stores the totals in .ever-better/state.json.

Baseline pinned: 4,942 violations across 72 rules are now grandfathered.

Why. From this commit on, the 4,942 are silent and violation 4,943 fails the build. You do not have to fix anything today to start enforcing everything tomorrow.

The ratchet itself is ESLint's own bulk-suppressions feature. ever-better is the part around it: knowing which rules to add, keeping the ledger, and failing CI when a number goes up.

It refuses to run twice. A second freeze would grandfather everything added since — which is the one thing the baseline exists to prevent.

`check` — the gate

ever-better check

What it does. Compares current counts against the ceiling and exits non-zero if anything rose.

8 unsuppressed error(s) — these are new since the baseline:
  2  id-length
  1  prettier/prettier

Why. A baseline is only a ratchet if something rejects a regression. Without CI it is a note.

Do not pipe it. ever-better check | tail exits with tail's status and reports a failing gate as success.

`prune` — lower the ceiling after a fix

ever-better prune

What it does. Removes suppressions for violations that no longer exist, so the recorded ceiling matches reality.

Why. Without it, fixing 100 violations changes nothing: the ceiling still permits them, and they can come back. This is what makes the number monotonic.

`next` — what to drain first

ever-better next
ever-better next --fan-in

What it does. Ranks the backlog by which edit enforces the most, not by which rule is biggest.

take these first — one or two edits, and the rule is enforced in that file for good:
    1  src/browser.js  @typescript-eslint/no-require-imports
    1  src/common.js   no-param-reassign

Why. The ratchet is per file per rule. A file with no suppression left for a rule fails on its next violation, whatever that rule's total is elsewhere — so two violations in one file buy more enforcement than twenty spread across twenty files.

--fan-in adds how many files import each one, because a fix in a widely imported module lands errors in files the diff never opened.

`report` — what the debt actually looks like

ever-better report
ever-better report --json

What it does. Prints the backlog as a rule × area table, and appends it to $GITHUB_STEP_SUMMARY when that is set.

Why. next answers "which edit enforces the most". This answers "what shape is this repository's debt". And because the generated workflow runs it after check with if: always(), the run where the gate just failed is the run where the backlog is visible — no one has to edit a workflow to get a report.

`secrets` — scan the history for committed credentials

ever-better secrets

What it does. Runs gitleaks over both the history and the working tree, failing on any finding.

Why both. Either alone passes a repository that is holding a secret. A history scan misses the key you pasted an hour ago and have not committed. A working-tree scan misses the key that was committed and then deleted — which is still in every clone.

This is the one check with no baseline. A leaked key is not debt you ratchet down.

`migrate` — JavaScript to TypeScript

ever-better migrate            # show the plan
ever-better migrate --all      # rename everything in one pass
ever-better migrate --file src/foo.js

What it does. Renames with git mv so history follows, and lets the lint fallout land in the ratchet instead of blocking the migration.

Why. Types are the cheapest rule set there is, and the tier that finds the most real bugs cannot run without them. On a 13-year-old JavaScript project, renaming 49 files and changing no logic produced 2,641 type errors — every one of them a question nobody had answered.

`emit-diff` — prove a refactor changed nothing

ever-better emit-diff --against main

What it does. Compiles the working tree and a git ref, then compares the emitted JavaScript.

Why. Types erase at compile time, so a change that only moves types must produce byte-identical output. That is a proof, in seconds. No amount of test coverage states it as strongly, because tests only cover the paths someone thought of.

`catalog` — the helpers that already exist

ever-better catalog

What it does. Writes docs/shared-helpers.md: every exported function, grouped by directory, with the first sentence of its doc comment. Point your CLAUDE.md at it.

Why. A linter sees inside one file. Duplication detection only notices copies once they are textually similar, and two independent implementations of the same idea rarely are. Nothing else reports the same function written a sixth time under a sixth name.

`status` — where you are

ever-better status

What it does. Prints the phase, the frozen date, the current backlog, which rules improved or regressed, and the smallest remaining backlogs.

STALE      100 commits since the diagnosis; re-run diagnose before trusting it
phase      drain
backlog    3532

Why. That STALE line matters more than it looks. A diagnosis from a hundred commits ago is a description of a repository that no longer exists.

`log` — why, not how many

ever-better log --kind drained  --rule max-depth "6 violations, 1 real bug"
ever-better log --kind deferred --rule max-lines "router.ts is 1400 lines; its own project"
ever-better log --kind issue    --rule no-floating-promises "opened #42 — product decision"

What it does. Records what happened against the current commit — the only command that writes the Work log in QUALITY.md. Everything else records counts.

Why. deferred is the one that earns its keep. It renders as a Carried over checklist stamped with the commit it was seen at, because "router.ts needs splitting" is useless four hundred commits later unless a reader can tell when it was true.

The whole loop, in five commands

The other eight are for when you need them. This is the shape:

npx ever-better diagnose     # what is missing
npx ever-better bootstrap    # install it
npx ever-better freeze       # pin today's count
npx ever-better check        # gate CI on it
npx ever-better prune        # lower the ceiling as you fix

Or hand the repository to an agent

The commands are the deterministic half — count, record, gate, refuse. The judgement half is eight Claude Code skills that ship with it: which violation is a real bug, when to stop and ask, what deserves an issue rather than a fix.

/plugin marketplace add isamu/ever-better
/plugin install ever-better

Then say clean this repo up. It formats, installs, freezes, and works the backlog down one rule per pull request — fixing violations, extracting the pure functions that make the fixes testable, writing the tests, and lowering the ceiling as it goes.

It is not unattended. Anything it can decide from the code, it decides. Anything it cannot — ambiguous behaviour, a public API change, a refactor that is its own project — becomes an issue with the options written out, and it moves on.

Try it on something you did not write

That is the honest test. Pick a repository you have never read:

git clone --depth 1 https://github.com/debug-js/debug.git
cd debug
npx ever-better diagnose
npx ever-better bootstrap
npx prettier --write .
npx ever-better freeze

Then add a file with a violation and run npx ever-better check. The 72 existing violations stay silent; the new ones fail.

On this particular repository you will also see five (parse error) entries — /* eslint-env */
comments and stale eslint-disable directives that flat config rejects. Those are real, they have
no rule id, and --suppress-all cannot record them, so freeze names the file and line for each.
It is a fair first impression of what the tool does: it tells you where, and it does not pretend the
number is smaller than it is.

Results welcome — docs/RESULTS.md collects what people froze and how much of it turned out to be real defects. It has two rows and both are mine, which is enough to notice a pattern and nowhere near enough to claim one. A run that found zero real bugs is the most useful row that table could get.

→ github.com/isamu/ever-better (MIT)

Handing an AI a big spec and letting it build the whole thing is like buying a lottery ticket

Isamu Arimoto — Fri, 07 Aug 2026 07:27:28 +0000

Ever since I wrote I stopped reviewing my own code, I keep getting the same question.

I ended up with a huge pile of code and I can't review it. What should I do?

The comments say the same thing in different words. The volume the AI writes went up. The reading side did not keep up. So what now?

Here is the blunt answer first.

Don't get into that state.

Taking something that already exists and rescuing it with review alone is, I think, very hard. You can split it, scope it down, throw parts away — but none of those is a substitute for actually reading it. And "just have the AI review it" probably isn't the answer either.

And this is not only a team problem. It happens exactly the same way when you work alone. The cause isn't headcount. It's writing a big spec up front and having the whole thing built in one go.

That is like buying a single lottery ticket where you don't find out whether you won until the very end. This post is about why, with arithmetic and with measurements.

The second half spills over into a related question: how many people should be on a product.

Note: the numbers here are measured from my own repository. But treat commit and PR counts as observational data about how I work, not as evidence of productivity.

Why you end up with "too big to review"

Most of the time, I think it's because the whole spec was decided first and built in one shot.

You write the spec. You hand it to the AI. A large amount of code comes out. And now, to judge whether any of it is right, you have to read all of it.

But there's a prior question.

You can't write a spec for something when you don't know if it's possible or if you even want it

The starting point for MulmoTerminal, which I build, was an experiment: can a terminal run inside a browser? It worked, so I widened it into a grid. After that I just used it and added what I wanted. That's all.

There was no room for a spec at that moment.

I didn't know if it was possible — nine real terminals side by side in a browser tab, usable in practice?
I didn't know if I wanted it — would putting them side by side actually be nice? I couldn't tell.

With those two unknown, what exactly is there to write? Anything you write is a wish, not a spec.

There are, clearly, cases where a spec works well. Building an Amazon clone. Building an internal system where the UI doesn't matter much. The reason a spec is writable there is that the thing already exists in the world.

A spec is a compression of knowledge that already exists. It is not a way to discover what doesn't exist yet.

You cannot compress something that isn't there to compress.

It's like buying a single lottery ticket

Deciding everything before you know anything is, to me, betting the outcome on one ticket.

And it's worse than a lottery in one specific way.

A lottery tells you whether you won on the spot.
A big spec doesn't tell you until you've finished building and started using it.

Let's compute the odds that "all of it works"

Hand over a big spec and let it build. Some of it comes out good, some of it doesn't. You can specify the UI in detail and sometimes get exactly that, sometimes not.

So what are the odds that all of it comes out the way you wanted?

Say each individual decision has a 90% chance of landing the way you intended. That's a generous assumption.

(This is a simple calculation that assumes the items don't affect each other. In reality they interact, so don't take it literally — it's for the order of magnitude.)

Number of decisions	Chance all of them land
3	73%
5	59%
10	35%
20	12%
50	0.5%

It's a product, so it falls much faster than people expect. Even at a near-ideal 95% per item, twenty items gives you 36%.

And a big spec holds twenty or fifty decisions without trying.

Here's the part that matters. At twenty items, the chance that at least one of them does not land is about 88%. So what happened to that "at least one"?

Usually it gets accepted with "well, it runs, good enough." Because nobody checked which parts didn't land. Checking would mean reading all of it, and the amount that came out is exactly the amount you can't read.

Are you actually satisfied with that?

"Just write a more detailed spec" ends at implementation

Some of you are thinking:

Then write the spec in enough detail that it can't miss?

Correct. The only way to raise the per-item odds is to remove ambiguity.

But writing it out in full means enumerating, in advance, every decision you would otherwise make while implementing.

Where the button goes, what happens when you press it, what shows up when it fails, what to do when the value is empty. Write all of that and yes, you get closer to what you wanted — but the volume you write, and the volume you think, moves toward implementation.

And there is one decisive difference.

A spec doesn't run.
No matter how detailed it is, it will not tell you whether it's right.

Detailing a spec looks like raising your odds. In practice it tends to be "postponing the answer while increasing the bet."

And AI flipped this trade-off

"Settle it on paper first" used to be the correct call.

Before   rewriting is expensive  → building big and then fixing costs a lot
                                 → cheaper to be wrong on paper

Now      rewriting is cheap      → rebuilding doesn't cost much
                                 → cheaper to be wrong in working code

Being wrong on paper was rational because rewriting was expensive. That premise moved.

That said, not everything got cheap. What got cheap is transcribing something whose shape you can already see. Migrations, public APIs, anything wired to another company — rewriting those is still expensive. Settle those up front.

So: once you've reached the point of "let me spec this out in detail," you may as well build it there.

Give the AI instructions in small increments and you get something running in about the time it takes to write the detailed spec. And the running version has a decisive advantage.

A spec stays silent when it's wrong.
Something that runs tells you immediately.

If you're spending the time either way, spend it on the one that tells you. That's the whole argument.

So how do you build? Tighten the implementation, not the spec

First, look at what happens when you build big in one go and it turns out to be wrong.

Everything produced up to that point sits on top of that spec. You aren't fixing a part; you're restacking. And you usually notice "restacking would have been faster" only after you've finished stacking.

So keep it small enough to throw away. There's one thing to do.

Cut down to the smallest unit that needs a judgement, implement them one at a time, and judge each time.
What you tighten is the implementation, not the spec.

On odds, it's just the table read backwards: decide five at a time and you're at 59%; three and you're at 73%.

But odds aren't the only thing that improves. Cutting small changes three other things.

1. The judgement itself gets more accurate

Looking at twenty things at once and asking "is this fine?" versus looking at them one at a time — the second is more accurate. Detail drops out when you look at everything together. And as above, you end up waving it through with "well, it runs."

2. You can change direction partway

If you realise at the third one that the whole direction is wrong, you can turn there. Realise it after finishing all twenty and the cost of turning is everything you already stacked.

3. You can put it in front of people early

This might be the biggest one. Getting something running early also means getting it used early.

Later in this post I describe how the purpose I built the thing for turned out to be wrong. The only reason I found that out is that people could actually touch something running. Had I shown nobody until it was all finished, it would have been completed against the wrong purpose.

"Isn't one at a time slow?"

Yes. Done serially, of course it is.

So do it in parallel.

Run about ten independent things at the same time. Then evaluate them as they land and feed corrections back.

cut small, serially     →  slow. which makes you want to batch it up
cut small, in parallel  →  not slow. it can stay small

Cutting small only becomes practical once you can run things in parallel. Conversely, in an environment where you can't run in parallel, betting big is all that's left. That, I suspect, is why "write the whole spec first" still looks rational.

And what happens when you do run in parallel? You end up evaluating finished work, one after another. When that clogs, everything stops. If there's one person evaluating, their spare attention is the ceiling.

That's why the second half of this post ends up being about headcount and parallelism.

That said, cutting small isn't automatically safe

It isn't as simple as "cut it smaller and per-item accuracy is preserved." Cut in the wrong place and new mistakes appear at the seams.

What is decisively different is this: you find out you were wrong sooner, and you can throw away only what you built so far.

Every number in the second half of this post exists to serve that.

This isn't AI's fault. It was always like this

Something worth remembering.

Back when only humans wrote code, specs were wrong too.

You write the spec, hand it to engineering, and it comes back: "this doesn't work as written." You touch something running and only then realize "no, not this." Those round trips did not happen because implementation was slow.

They happened because the spec was wrong and nobody could tell until they touched it.

What AI made fast is mostly implementation, and the planning around it.

what was slow       implementation  → got fast
what was wrong      the spec        → barely changed

The cause of failure is largely unaddressed. If anything, wrong specs now become real faster and in larger volume.

The same thing happens under Agile

"That's why we do Agile" is a fair objection. Short cycles, build, check, correct. The distance really does shrink.

But it stops when the product owner and the team are separated. The person deciding is in a meeting, not at a keyboard. Decisions lag, and in the worst case the kind of judgement you only discover while writing code never reaches anyone.

I don't think the real variable is waterfall vs. Agile.

The distance between the person deciding and the code.

spec everything first   the decider is farthest from the code, and decides once, from there
Agile (separated)       the decider is in a meeting; decisions come at sprint granularity
working alongside       the decider is at the keyboard

Agile shortened the distance. It didn't take it to zero. And there are decisions that only reach you at zero. The examples below are what I mean.

The tool got smarter. You didn't

Some of you are thinking:

But AI helps write the spec now. Isn't that different from before?

I think this is the biggest misunderstanding around.

AI did get smarter. Throw it requirements and a plausible-looking spec comes back. And that makes it feel like your own ability went up.

It didn't. The tool got smarter. You are still the bottleneck.

Leverage is a multiplier, not the number being multiplied

AI is powerful leverage. People with a clear vision of what they want to build use it astonishingly well. That part is real.

But leverage is multiplication, and the thing being multiplied hasn't changed.

A plausible spec appears instantly. But reading it and deciding "this is sound" or "this is wrong" is still you. And the ability to produce a good spec is still yours to have or not have.

Writing makes this easy to see.

Plausible prose is easy to get out of an AI.
Getting genuinely excellent prose out of one is still extremely hard.

Anyone who writes knows this in their gut. Specs and design are exactly the same.

Former CTOs joining AI labs as individual contributors is probably the same story

This is actually happening.

Peter Bailis — CTO of Workday (from May 2025). Left in March 2026 and joined Anthropic as a Member of Technical Staff, working on reinforcement learning engineering (The Next Web, 2026-04-09)
Bryan McCann — co-founder and CTO of You.com. Also moved to Anthropic as a Member of Technical Staff (The Information)

CTOs of public companies and fast-growing startups, dropping the title for an IC seat. At minimum, several moves in the same direction have been reported recently.

The Next Web characterises it this way:

executives at the top of established technology companies choosing proximity to cutting-edge research over the authority that comes with managing large organisations

That is where the reporting ends. Both moves are documented. Why they did it is not in those articles.

From here on, this is my speculation.

If the goal were a bigger title or better terms, being CTO somewhere else was available. Not taking that reads, to me, like a statement about priorities.

Until now, building something large required a large team. For a CTO-level person to realise an idea, they needed capable people and an organisation. AI is filling that part.

If so, taking an IC seat where the smartest model and unlimited access to it live, instead of leading an organisation, is an entirely reasonable choice.

This is also a story about people with a clear vision being able to move with fewer people — the same direction as this post's conclusion.

But again. What changed is leverage.

AI increases the material for a decision. It lists options, it catches omissions. But the criteria for picking among those options exist only inside you. More material without criteria means you feel like you can choose, and you can't.

Without something to multiply, a multiplier means nothing.

Some decisions don't exist until you build

Abstractions don't land, so here are two real ones.

Example 1: the purpose I built it for was wrong

MulmoTerminal, which I build, is a tool for running many AI agents side by side. The screen is a grid of cells, each running its own work.

My assumption while building was clear.

This raises the ceiling on how many you can run in parallel.

If I were writing a spec, I would have written exactly that. It's why I built it.

Once people were actually using it, I asked four of them. How many do you actually run? What's good about it?

Here's what came back.

agents actually run in parallel                1 to 6
people who said "I can run more now"           0

Not one. What all of them said was something else entirely.

I can handle the same number more easily.

One person runs one to three and dropped VS Code entirely. The count didn't go up. They switched anyway.

So the value of this tool was not "raising the ceiling." It was "not losing track." The person who built it had it wrong.

And then it got worse

From the same conversations:

I got up to eight, but the notifications became a storm and I got tired and stopped

Notifications exist to let you run more. So you can walk away and still be called back.

Those notifications were creating a new ceiling. One part of the tool was lowering the ceiling another part had raised.

The cause was concrete: "finished" and "waiting on you" played the same sound. Indistinguishable, so you end up caring about all of them.

There is no way to know this before building. At the moment you add notifications, you assume they only push in one direction. Nobody finds out until someone actually runs eight and gets tired.

Example 2: the AI said "don't do it" — and it was wrong

There are tools that find duplicated code automatically. At one point ours reported a lot of "the same shape appears in many places."

The shape was something like this:

read A → error if missing → catch the failure and log it
read B → error if missing → catch the failure and log it
read C → error if missing → catch the failure and log it

When I went to consolidate it, the AI told me not to. From the dev log:

The checker reports many duplicates, but this is a structural repetition — read, error if not found, catch the exception — and each site is readable precisely because it is self-contained. Consolidating would mean rewriting large parts of a 2,700-line file, and readability would get worse, not better.

The reasoning holds together. "A wrong abstraction is worse than duplication" is in fact a principle we've written down. I read it and thought, fair enough.

But when I opened the code myself later, it was wrong.

What had been flagged was not a coincidental resemblance. It was genuinely the same thing written over and over. Consolidating it made things noticeably cleaner. We ended up doing it as a separate task.

Laid out, what happened was:

the tool said "duplicate"              →  correct
the AI said "don't consolidate"        →  plausible, and wrong
I opened the file and checked          →  consolidating read better

AI can justify not doing something with a plausible reason. And the principle it cites is generally correct, which is why you nod along.

Whether an argument is convincing and whether it's right for this code are different questions. And the second one can't be settled until you open the file.

Which brings us back to distance.

If I had turned this into a ticket that said "reduce duplication" and handed it to someone, the AI's explanation would probably have won. It's well written; there's nothing to argue against. Only the person who opened the file can overturn it.

What these two share is that the right answer wasn't knowable until something actually ran.

Example 1 — the purpose it was built for turned out to be wrong, and only usage revealed it
Example 2 — a plausible explanation from an AI was, in fact, wrong

Neither fits in a spec or a ticket. By the time it fits, you've already checked.

What you can decide before building is only what you already know.

AI doesn't shorten the distance

This is where the original question comes back.

What AI made fast is mostly implementation and planning — and the benefit lands on whoever is at the keyboard. If the authority to decide sits far from the keyboard, that speedup doesn't reach it as-is.

authority at the keyboard   →  fast, and corrected as you go
authority still far away    →  fast, and still far away

"Fast while still far away" is the worst state. When the person judging stays distant, the speed at which mistakes are noticed barely changes, while the speed at which they accumulate goes up.

The result of that is "too big to review."

Why "just have the AI review it" doesn't fix it

AI reads far more text far faster than a human. That's true. So I won't claim "the AI can't read it."

Two things matter, though.

First, there's a ceiling on how much it can hold at once (the context — how much text the model can look at simultaneously). Depending on the model and your tooling, a large diff may not fit in one pass. Split it up and it fits, but splitting makes it much harder to surface "A and B don't line up." It only ever sees one side. And bugs usually live at exactly that seam.

Second, passing review doesn't mean the design is good. I have a concrete example of what survives after every machine check is green.

At one point I eliminated every "function that is too long" in my repo. Machines had nothing to complain about. Three months later:

CollectionView.vue   2,945 lines   187 functions   longest 61 lines
server/index.ts      3,020 lines   212 functions   longest 82 (most under 10)

There are no long functions. Nobody is being warned. And the files are 3,000 lines.

Because the machine only looks at "how long is this one function," never "how many different jobs live in this one file." CollectionView.vue had eleven separate jobs in it — list rendering, filtering, editing, chat, and more.

187 small functions added up to 3,000 lines, and the machine never once complained.

"The machine passed it, so it's fine" doesn't hold for review or for design. And a setup that puts AI review as the last line of defence collapses right here.

So what do I actually do

Numbers from my own way of working. Again: this is not proof of correctness, it's observational data about how I work.

MulmoTerminal (2026-06-14 → 2026-08-06, 53 days)

  commits        3,235
  merged PRs     1,170
  releases          64      about 1.2 per day
  written by     effectively 2 people (2,990 / 221, plus one at 24)

Time from opening to closing, last 400 closed issues
  median          1.6 hours
  within 6h       77%
  within 24h      92%
  over a week      2%

Diff size, last 400 merged PRs
  median          286 lines
  under 300       51%
  files changed   median 7

How I measured

Closed issues: gh issue list --state closed --limit 400, taking the difference between created and closed timestamps. PRs: the last 400, additions plus deletions. Both are cut as "the most recent 400," so if the way I work changed partway through, that shows up in the number. Commits and releases are git rev-list --count and git tag.

Issues shaped like this are not specs written before building. They're notes of something I noticed while using the thing, fixed the same day. That's why they're short-lived. If everything had been decided up front, the distribution wouldn't look like this.

Also: all these numbers can show is that things were built fast. Whether what got built is good is a separate question. Please read them separately.

On that basis, I keep the state from ever producing a giant diff. Not "what do I do with unreviewable code" — don't get there.

I do write plans. 351 of them. But the AI writes them.

To be clear, I'm not building with nothing written down.

351 files in plans/
  features 166 / fixes 132 / cleanups 37 / other 16

  278 of them (79%) carry an issue number

But these are not specs. They're the steps for clearing one issue. And the AI writes them — I read and judge.

The order looks like this:

1  I notice "this is wrong" while using it
2  I open an issue          ← me. deciding what to do
3  the AI writes the steps   ← automatic
4  I read it, correct it     ← me again
5  it gets implemented       ← automatic

The AI can only write step 3 after step 2 is settled. For something where what-to-do isn't decided, having it write is pointless. As above: plausible output appears, and whether to take it is still my call.

Which is to say —

You can only write it once the shape is already known.

Our own process turned out to be the inverse statement of the argument. I'm not rejecting writing things down. I'm keeping to the conditions under which it can be written.

Adding one person doesn't add just one channel

From here on, this is about having more than one person. If you work alone, feel free to skip.

Judgement and alignment grow with the number of channels, not the number of people. It's pairs, so for n people it's n(n-1)/2.

People	Channels	vs. 2 people
2	1	—
3	3	3×
4	6	6×
5	10	10×
8	28	28×
10	45	45×

Go from two to four and you double the hands — and multiply channels by six. At eight, four times the hands and twenty-eight times the channels.

This is a simplified model; not everyone talks to everyone. But it does show that what grows when you add someone isn't only hands. Brooks' The Mythical Man-Month — "adding people to a late project makes it later" — is rooted in the same place.

The question is what AI changed and what it didn't.

Before
  what you gain   implementation   grows with headcount (n×)
  what you pay    channels         grows as n(n-1)/2
  → there's a point where it stops paying, but below it the gain won

Now
  what you gain   implementation   the AI produces it; barely tied to headcount
  what you pay    channels         still n(n-1)/2. unchanged
  → the gain side shrank; the cost side stayed

At least the reason "we need more hands to write it" got weaker, while the price of adding people stayed put.

This connects back to the former CTOs

Earlier I mentioned CTOs from Workday and You.com joining Anthropic as individual contributors. I think that's this formula too.

Lead a large organisation and you get implementation capacity proportional to headcount. At the same time, you carry n(n-1)/2 channels. A decision only becomes real after it has been through all of them.

What happens if you step off that?

take it from an organisation   capacity × headcount  +  carry n(n-1)/2 channels
take it from AI                capacity              +  one person's worth of channels

Sit somewhere you can focus purely on judgement and use AI without limits. Get the implementation capacity from the AI rather than from an organisation.

None of them said this, of course, so this is my reading. But looking at what the people closest to the frontier just gave up and what they went to get, it points this way.

What they gave up was the organisation. What they went for was distance — between judgement and the AI.

That said, the formula doesn't give you a number

This formula does not produce "so the optimal number is N." Channel count is neither productivity nor decision speed. All the formula says is that one side of the scale got lighter; the specific number comes from my own experience below.

There's a ceiling on how much you can run in parallel

The same thing happens inside one person. Honestly, here's mine:

Within one project
  just skimming and judging        about 10 is reachable
  thinking about design            5 is the limit

Across projects
  work that takes no thought       3 to 4 projects
  dependencies / design work /
  chasing a repro                  can't parallelise (1)

The tool can show nine. The one that can't is me.

And adding "one more, I can probably take it" slows everything down. The closer your own utilisation gets to 100%, the more sharply the agents' waiting time grows (picture a convenience store with one register and a clerk who is essentially never idle — a small bump and the queue stretches).

So the way to raise parallelism isn't "add agents," it's reduce the part that can't move without you. Decide design up front, write the repro steps first, cut dependencies early. Though that carving-out is also your work, so it never reaches zero.

Which leads to: teams should be small too

Everything up to here holds for one person. What follows is the multi-person case.

The variable that should set headcount is not implementation volume. It's the amount of judgement. By judgement I mean setting priorities, settling design, deciding how exceptions are handled — the kind of decision that loses accuracy when handed to someone else.

The premise of sizing by implementation volume has broken down, at least around me, because implementation volume no longer tracks headcount. What's left is judgement, and splitting judgement is where the formula above bites.

So here's where I land.

If you're building something whose shape isn't settled yet, and the owner can touch the code:
one to three people per product.
The owner, or someone who can back them, does the implementing.

This is not a universal optimum. It's a conditional rule of thumb. It roughly holds when these are true:

What to build isn't fully decided — you're still exploring the shape
The product's owner can touch the code — the decider is at the keyboard
One person can hold the whole thing in their head — when they can't, that's your split line
You can ship on your own judgement — no approval queue

If any of those is missing, you can't cut headcount. Work that needs deep specialist knowledge, anything running 24/7, industries where the author legally can't review their own work. Those aren't headcount problems.

The two-pizza rule isn't about meetings any more

Amazon's two-pizza team idea was, originally, a design principle for small autonomous teams — meetings being part of it. When implementation needed people, capping communication on top of that was the rational move.

Implementation no longer scales with headcount. What's left is judgement, and judgement is what eats alignment cost.

then   "we need the people. at least keep meetings and teams small."
now    "we don't need the people. the unit of building can be small."

There are things you genuinely want more people for

Read this far and it may sound like "cut headcount, always." It isn't.

The only thing that should be small is the unit of building.

The number of ideas — more is better
The number of people giving you feedback — more is better
The number of people using it — more is better

As in Example 1, I did not find out that the purpose was wrong until I asked four people. That doesn't happen without people around you.

So it splits like this:

the unit of building     smaller is better    because judgement can't be divided
the people around it     more is better       because it grows the material for judgement

That "around" is your community, and your company.

Separate the place you build from the place opinions gather. Two people inside is fine; outside, more is better. If anything, the smaller you make the unit of building, the more you need material from outside — with fewer people inside, your perspective narrows.

Cut people per product, not people

Easy to misread, so: this is not "turn eight people into two."

✗  make eight people into two
✓  stop putting eight people on one product
   → 2 people × 4 products

Reduce the headcount per product, not the headcount.

Though, as above, three or four projects at once only works for the low-thought work. If all of them are in design mode, one is the limit — so "two people, therefore six to eight products" doesn't follow. In practice it's one you're thinking hard about, plus a few you're coasting.

In the end, this is what I think it comes down to

I've written a lot above, but the essence is one line.

The product's owner, in a small group, building it while using it themselves in detail.

That's the shape I think fits building products in the AI era.

If you aren't the heaviest user, it won't get good

In Example 1, the purpose I built it for turned out to be wrong. The only reason I caught that is that I use it every day too.

If I didn't, someone saying "I can handle the same number more easily" would mean nothing to me. I wouldn't know the weight of the answer.

The material for judgement only accumulates through use. A tool its owner doesn't use can't be fixed by anyone's judgement.

You probably don't need to be a strong programmer

This is the hopeful part, I think.

What's required is being clear about what you want to build, and being able to look at the output and say "no, not this." Not writing code quickly.

If you have those two, an era where non-engineers build good products is coming into view. If anything, the clearer you are about what you want, the more the leverage pays.

But you can't just hand it off

You give the AI the spec and the implementation, and what comes out is "somehow not right."

Of course it is.

Without settling the details yourself, you don't get a product with substance. Micromanagement is not usually a compliment when the subject is a person. With an AI, though, I think it's simply the correct approach.

It doesn't complain. It'll redo it as many times as you like. So you may as well push until you're satisfied.

What this post said

Rescuing "too big to review" with review alone is very hard. The answer is to not get there
The cause is writing a big spec up front. This happens when you work alone too
You can't write a spec for something when you don't know if it's possible or whether you want it
This isn't AI's fault. Specs were wrong in the human-only era too, and nobody could tell until they touched it
Even when AI helps write the spec, deciding whether to take it is still you. The tool got smarter, not you
Leverage is a multiplier, not the number being multiplied. Without something to multiply, it means nothing
Adding people grows channels as n(n-1)/2. Hence one to three per product (a conditional rule of thumb)

Handing over a big spec and letting it build in one go is buying a single lottery ticket where you don't learn the result until the end. And if you try to fix that by writing the spec in more detail, where you arrive is implementation. Same effort — write the one that runs.

Rough out the base, then work alongside it, using it yourself in detail. That isn't "being sloppy." It means increasing the number of judgements.

And the only person who can increase that number is the one sitting at the keyboard, using the thing themselves.

One small plug at the end

Every number above came out of building MulmoTerminal. And I'll admit it: it's also the tool for working the way this post describes.

Cut small and draw often, and this always happens:

Wait — which one is waiting on me right now?

Run three or four agents and you'll leave one waiting for tens of minutes without noticing. Since your own attention is what caps parallelism, everything stalls when that clogs.

I built it to solve that with cell colour, sound, and a push to your phone.

This tool is specialised for how far one person can run in parallel. There is nothing in it for splitting work across a team. If you're comfortable in a terminal and don't mind working in parallel, it probably suits you best.

In practice, ten is reachable

Earlier I wrote "measured, it's one to six." That was the result of asking four people.

I myself run about ten when I'm purely skimming and judging. Someone at a US startup I spoke to said twelve.

That may look like a contradiction. It isn't.

thinking about design       5 is the limit
just skimming and judging   about 10 is reachable

Mix them and you get dragged down to the lower number. Which also means: reduce the things that can't move without you, and the number goes up.

Ten to twenty for one person. If you're comfortable in a terminal and don't mind parallelism, I think that's reachable.

Getting there doesn't take more agents. It takes exactly what this post has been about: cut to the smallest unit that needs a judgement, cut dependencies early, write the repro steps first. Shave down the part that can't move without you, as far as it will go.

What raises the ceiling isn't the tool. It's how tightly you work. Give it a go.

But the tool alone won't get you to ten

If you go and read every one of them thinking "is this okay?", you'll cap out at five. To grow the number you have to reduce the attention each one costs.

What I do for that is written up in the other posts in this series (Japanese):

I stopped reviewing my own code — the whole picture of not breaking without reading
Green is not evidence — whether the checks you have are actually checking anything

Without that machinery in place, ten in parallel doesn't hold. With it, your attention goes to judgement only.

It's all connected. "Cut small and run in parallel" here, and "don't break without reading" over there, are the same one thing written from two sides.

It runs on your own machine and you look at it in a browser. It starts with npx, so there's nothing to install first.

npx mulmoterminal@latest
# → http://localhost:34567

→ receptron/mulmoterminal (MIT)

If you're running things in parallel on your own, or with a small group, it may well help.

When your GUI isn't the whole input language

Isamu Arimoto — Mon, 03 Aug 2026 20:59:42 +0000

I spent a week of my life on where a button should go. I don't think I'll do that again, and it took porting a benchmark tool to work out why.

Let me concede the obvious thing first, because otherwise it's the only thing anyone will want to talk about: GUIs are still input devices. Direct manipulation, menus, palettes, keyboard shortcuts, drag targets, accessibility affordances — all input, all irreplaceable. I'm not arguing for chat-instead-of-UI. Command palettes, scripting and macro systems have absorbed open-ended commands inside GUIs for decades, and they work.

The argument is narrower, and it's about a specific failure: designing controls first, for a system whose set of valid operations won't hold still.

Where I noticed

I'd built a benchmark tool. It evaluates combinations of LLM/SLM models × skills, and scores each combination on four things: accuracy, runtime, turn count, and total cost.

It also tracks the moving parts. New models arrive constantly. Prices change constantly. Both are part of the tool's state.

It ran inside Claude Code. I decided to port it to a proper web tool, sat down to design the interface, and got about as far as two dropdowns before it fell apart.

The two dropdowns were fine. Pick a model. Pick a skill set. Both are finite, both need to be shown to you — you can't ask for a model if you don't know it exists — and both are cheap to render.

Everything else was the problem.

What the work actually is

The tool isn't really "run a benchmark." It's maintenance. Every time a model or a skill is added or updated, work appears:

A model was added. Re-run it against which skills? All of them, or the ones where the previous best is close? Compare against which baseline?
A price changed. Recompute historical cost, or only from here? Are last month's cost comparisons still meaningful?
A skill was updated. Which stored results are now invalid? Re-run the whole matrix, or the affected column?

I kept trying to design controls for these and kept discovering the same thing: each one is a slightly different task. Not a variant of a task — a different task, shaped by what changed and what I already knew.

To put that in a UI I'd have to enumerate them. Every one, in advance, before knowing what the next model release would make me want. And each new axis creates more cross-combinations with all the others.

In chat it's a sentence. "gpt-5-mini is in — run it against every skill and put it next to haiku." The agent works out which runs are actually needed. Nothing was designed for that request specifically, and nothing had to be.

That's the whole of it. Not "chat is better." Just: when the set of valid operations keeps changing, a control surface has to keep growing, and it's always one release behind.

Where the line fell

Not "finite versus infinite." I had it wrong at first. The line is:


UI keeps it	Things that must be enumerated and shown — available models, available skills, the price table, the four scores
Chat takes it	Things where the task is different every time — what to re-run, against which baseline, which results to invalidate

The model list has to be a UI, and not because it's short. It's because you cannot ask for something you don't know exists. Enumeration is the whole value.

The four scores are the same. Accuracy, runtime, turns, cost — you read them. They update when a price moves. There is nothing to click, and clicking would not help.

The part I didn't expect

When a user gets stuck in a GUI, you often get nothing usable. They can't find the control, conclude the thing can't be done, and leave. You may see that they dropped off; you rarely learn what they were trying to do.

When a user gets stuck in chat, they type what they were trying to do. Now you have a sentence describing a task your product doesn't support, in their words.

I want to be careful here, because there's an obvious objection and it's correct: chat users also leave silently. Plenty do. And GUIs have telemetry, funnels, session recordings — this isn't a categorical difference, and I'd be overselling it if I said it was.

What it is, I think, is a difference in recovery. A failed GUI interaction usually leaves you an event, not an intention. A failed chat interaction leaves a sentence, which means someone — you, a support person, or the agent itself — has something to answer while the user is still there. Not always. But it's the difference between a signal you have to interpret and one that states itself.

For a tool whose task list changes every week, that mattered more than I expected. The unsupported requests are the roadmap.

A second data point, honestly labelled

I also maintain a browser terminal grid for supervising several coding agents at once. Different product, different problem, built for different reasons.

Counting one cell's header: roughly 11 buttons and 9 status chips. The chips are directory, git branch and change count, model and context percentage, token counts, which PR or issue the cell is on, a diff badge, usage, and a one-line summary of what the agent is currently doing. None of them is clickable in that configuration. They are read.

And every button that survived does the same kind of thing: expand, close, show files, open the canvas, open the timeline. They change where you look. Not one of them makes the agent do anything — that gets typed.

The same boundary appeared in another product, one I wasn't thinking about the benchmark tool while building.

But I should not call that convergence. Same author, same period, same tools, same assumptions. It's a personal design pattern showing up twice, not independent validation. Take it as evidence that the boundary isn't specific to one benchmark workflow, and no more.

Where this stops being true

Precisely, because a claim that never fails isn't saying much:

Precision and spatial feedback. You do not describe a crop, a curve, or a fillet. Photo editors and CAD tools aren't going to move that to a prompt, and shouldn't.
Repetition and muscle memory. An action you take fifty times a day should be one keystroke. Typing it is a downgrade every single time.
Discovery. A new user doesn't know what to ask for. This is the strongest argument for keeping the control surface, and it's why the model list stayed a list.
Safety. "Delete the failed runs" should require pointing at something, not a sentence that could be parsed generously.

Spreadsheets, IDEs and design tools stay hybrids. They should. Chat is an orchestration layer over stable primitives, not a replacement for them.

The thesis, as narrowly as I can put it

A visual interface is excellent at exposing stable objects, state, constraints, and high-frequency actions. It becomes expensive and brittle when the valid operations are numerous, compositional, state-dependent, and continuously changing.

In those systems: let the UI enumerate what has to be chosen and inspected, and let a conversational layer absorb the requests that would otherwise need a new control every week.

The gain isn't that chat replaces the interface. It's that changing intent becomes observable, recoverable and extensible without shipping a button for every new combination.

So: stop agonising over button placement — in the parts of your product where the verbs won't hold still. Everywhere else, the button is still the right answer — as it has been the whole time.

If you've shipped a control surface for a workflow that kept changing underneath it, I'd like to hear how that went. My honest position is that I found the boundary in two of my own products and I don't yet know how far it generalises.

Green is not evidence. Two of my checks were covering less than I thought.

Isamu Arimoto — Mon, 03 Aug 2026 08:25:55 +0000

Someone left this on a post of mine about how I stopped reviewing my own code:

Most teams test the output of a rule (e.g., does this code pass linting?) but rarely test the rule itself.

I'd been writing about pulling decisions into pure functions so they can be tested. They took it one level up: fine, but who tests the thing doing the checking?

I had two answers to that lying around. I just hadn't connected them to each other.

The first one: a typecheck that checked half the repo

We run yarn typecheck in CI on every PR. It had been green for months.

It had also never looked at our server code, or any of our tests.

The root tsconfig.json referenced two of five projects. vue-tsc -b walks the references it's given, so everything else was simply out of scope. Not skipped with a warning — never enumerated in the first place.

Here's the part I want to underline. I fixed the references — and the check stayed green, exactly as green as before. Of course it did; the code was fine. Green looks identical whether you're checking five projects or two, which means it could not tell me whether my fix had worked. So I did this:

const x: number = "nope";

One of those in each of the four areas I cared about, then run the check and confirm it fails.

Where I planted it	Before	After
`server/config/workspace.ts`	passed	✗ caught
`src/utils/focusTrap.ts`	✗ caught	✗ caught
`test/common/readString.spec.ts`	passed	✗ caught
`test/server/git/prs.spec.ts`	passed	✗ caught

Three of four had been silently passing. The one that already worked is why nobody noticed — you get some type errors, so the check is obviously running, so you stop wondering. (Fixed now: the root config references all five.)

There's a footnote to this. Our contributing guide had a line saying "yarn typecheck alone passes while CI fails — run all three commands." Somebody had hit this, worked around it in prose, and moved on. A rule in your docs that tells people to be careful is often a bug you can fix in config.

The second one: a rule set to `error` that reports zero

This one is better, because there is nothing to fix in the config. The config is correct.

We ban type assertions. Not "discourage" — banned, at error severity:

$ npx eslint --print-config src/components/SettingsField.vue \
    | jq '.rules["@typescript-eslint/consistent-type-assertions"]'

[2, {"assertionStyle": "never"}]

Severity 2. Error. For that exact file.

That exact file, line 14:

@input="$emit('update:modelValue', ($event.target as HTMLInputElement).value)"

And:

$ npx eslint src/components/SettingsField.vue
$

Nothing. yarn lint reported 0 errors across the repo.

Both facts are true and neither is a bug. vue-eslint-parser exposes the <template> as a separate AST, and typescript-eslint rules don't walk it. They see <script>. A cast in a template was never in scope for the rule — it just looks like it is, because --print-config will happily tell you the rule is on.

I measured the other frameworks, expecting this to be a template-language problem generally. It isn't:

	script side	template / JSX side
React, Solid, Preact (`.tsx`)	✅	✅
Svelte	✅	✅
Astro	✅	✅
Vue	✅	❌

JSX is part of TypeScript's own grammar, so it lands in the same tree. The Svelte and Astro parsers expose their template expressions in a way these rules can visit. Vue keeps them separate. It's an implementation choice, not something inherent to having a template language — which is what I'd assumed before measuring.

And it's fixable. typescript-eslint can't reach that AST, but eslint-plugin-vue can — vue/no-restricted-syntax is the one rule that walks it:

{
  files: ["**/*.vue"],
  rules: {
    "vue/no-restricted-syntax": [
      "error",
      { selector: "TSAsExpression", message: "Narrow in <script>, pass the result to the template." },
      { selector: "TSNonNullExpression", message: "Same." },
    ],
  },
}

One subtlety worth copying: exclude as const.

selector: 'TSAsExpression:not([typeAnnotation.typeName.name="const"])',

consistent-type-assertions already exempts it, and the two halves of one SFC must not disagree about what's banned. It's also not what the ban is for — a const assertion narrows a literal the compiler can already see, rather than claiming a type it couldn't prove.

We ran this on a sibling project first and it found 16 casts that had been outside the gate the entire time the ban was at error. Six were already unnecessary: a v-if above them had started narrowing the type at some point, and nobody re-checked, because nothing was looking.

The rest moved into <script>, which is where a DOM type check belongs anyway:

<input @input="onInput" />

function onInput(e: Event) {
  if (!(e.target instanceof HTMLInputElement)) return;   // bail if it isn't
  emit("update:modelValue", e.target.value);
}

The cast wasn't protecting anything. It was hiding that the check had been written in the wrong place.

Same file, same line, after the rule went in:

$ npx eslint src/components/SettingsField.vue

  18:41  error  Do not use type assertions — narrow in <script> and pass
                the result to the template   vue/no-restricted-syntax

✖ 1 problem (1 error, 0 warnings)

That is the whole point of this post, in one command. The config didn't get stricter — consistent-type-assertions was already at error. What changed is that something is now looking at the place where the violation lives.

Why this keeps happening: the config composes

Neither failure was carelessness, and I don't think either was avoidable by being more careful. Lint and compiler config compose, and composition is where simple pieces stop behaving simply.

Two examples I only found by measuring.

strict doesn't include what you'd guess. It's eight flags. These six are not among them:

noUncheckedIndexedAccess        exactOptionalPropertyTypes
noImplicitReturns               noPropertyAccessFromIndexSignature
noImplicitOverride              noFallthroughCasesInSwitch

The rule that bans as is not in strict. I loaded each typescript-eslint preset and read back what was enabled:

rule	`recommended`	`strict`	`stylistic`	`recommendedTypeChecked`	`strictTypeChecked`
`no-explicit-any`	✅	✅	—	✅	✅
`no-non-null-assertion`	—	✅	—	—	✅
`consistent-type-assertions`	—	—	✅	—	—
`no-floating-promises`	—	—	—	✅	✅
`no-unsafe-assignment`	—	—	—	✅	✅

It lives in stylistic only. Not in strict, not even in strictTypeChecked. If you reached for strict because casts worried you — which is exactly what I did — you got the opposite of what you wanted, and nothing told you.

Then there's a second-order version, which is the one that actually unsettled me.

sonarjs/different-types-comparison flagged nine comparisons as always-false. All nine were false positives, and they looked like this:

const command = process.argv[2];
if (command === undefined) { /* the rule says this can't happen */ }

Without noUncheckedIndexedAccess, TypeScript types process.argv[2] as string. The rule believed it and concluded the guard was dead. Following the advice would have deleted a real check.

Turning that flag on took it from nine to four — and the remaining four turned out to be genuinely redundant. The rule was never wrong. It was reasoning correctly from a type that was lying to it.

So: when a rule produces false positives, suspect a missing setting upstream before you suspect the rule.

The method, such as it is

Three commands. None of them take more than a few seconds.

# what is ACTUALLY enabled for this file, after all inheritance
npx eslint --print-config src/index.ts

# effective tsconfig, after all extends
./node_modules/.bin/tsc -p tsconfig.app.json --showConfig

# how many errors would this flag produce, before I commit to it
./node_modules/.bin/tsc -p tsconfig.app.json --noEmit --pretty false \
  --noUncheckedIndexedAccess 2>&1 | grep -c "error TS"

Three notes, each from getting it wrong.

Use the project's own tsc. A global one installed by a package manager can be a completely different program wearing the same name, and it will tell you so in a way you won't expect.

Pass --pretty false. With pretty output, tsc writes colour escapes between the two words you're grepping for:

- \x1b[91merror\x1b[0m\x1b[90m TS2322: \x1b[0mType 'string' is not …

The literal string error TS isn't in there any more, so grep -c "error TS" returns 0 — which reads exactly like "no errors." Mine didn't drop colour when piped, either. (And grep -c counts matching lines, so treat it as a gauge, not a census.)

Point -p at a real project, not a solution file. This one is the same bug as the whole post, and I walked into it while writing this section. Our root tsconfig.json is files: [] plus five references — a solution file. -p doesn't follow references, so it compiles nothing and exits clean. I planted one error in server/ and measured:

command	errors reported
`tsc -p tsconfig.json --noEmit` (the root)	0
`tsc -b tsconfig.json`	72
`tsc -p tsconfig.server.json --noEmit`	1

Zero, from a repo with a deliberate type error in it. If your root is a solution file, -p on it is a green light that means nothing — use -b, or name the leaf project.

Then the part no command does for you:

Break it on purpose. --print-config tells you what the config says. It cannot tell you whether the rule can reach your code, and -p can't tell you whether it compiled any. The only thing that answers either question is planting a violation and watching the check fail.

What turned up once the checks were actually running

The point of all this is that the checks then find things. A sample of what came out:

A type claimed a field the API never sent. /api/session/:id doesn't return id. Adding a runtime guard broke four tests, which is how we found out. The type had said id was there since the beginning.
fetchJson<T> returned whatever the caller named it. No validation. If you wrote fetchJson<Config>(...), you got Config — as a claim, not a fact.
Config was validated on save and not on load. Broken entries came straight back in at startup.
String(x ?? ""), seventeen times. When x is an object you get "[object Object]", no exception. That string was used as a lookup key and rendered as a session title. The real damage isn't the display — it's that missing and corrupted stop being distinguishable.
An await on a synchronous function. It waited for nothing and told every future reader "this line is I/O."
A sort whose answer depended on who ran it. A rule suggested localeCompare for filenames — which are zero-padded dates and ISO timestamps. Locale order would have made the result machine-dependent. Following that advice would have introduced the bug.
A guard that could never fire. matchAll always populates index, per spec.

And on the server side, where I cleared 145 of the 407 no-unsafe-* findings, they came from just three entry points:

entry point	why it's `any`
`await import(name)`	a dynamic import with a computed specifier returns `any`, and everything reached through it stays outside the type checker
`JSON.parse(...)`	returns `any`
`req.body`	Express types it `any`

All three are "a value from outside." One validating function at each boundary cleared all 145. The client side had a wider spread — socket frames, Response.json() — but the shape was the same every time: a boundary where an untyped value walked in and nothing stopped to look at it.

If you only do one thing from this post, grep for those three.

One trap in there: typeof x === "function" doesn't narrow enough. You get Function, and calling a Function returns any, so the result escapes again.

Not everything is worth turning on

Two flags I measured and deliberately left off.

noImplicitReturns — 58 findings, and nearly all of them are this:

if (bad) return res.status(400).json({ error });
res.json(result);   // no explicit return

That's correct Express. Nobody reads a handler's return value. Satisfying the flag means adding 58 meaningless returns and closing zero holes.

noPropertyAccessFromIndexSignature — 1,785 findings, all of them obj.key → obj["key"]. Access safety is unchanged.

Compare with noUncheckedIndexedAccess: 118 findings in shipped code, every one of them "write down what the code already assumed." All 118 were worth it.

The count isn't the signal. The question is whether the work closes a hole, and 118 real fixes beat 1,785 renames.

(Tests got their own answer: noUncheckedIndexedAccess is off there. A test indexing its own fixture with rows[0] doesn't need T | undefined — the test is the thing guaranteeing that value. That's 233 findings that were pure noise. exactOptionalPropertyTypes stays on in tests, because that one is about meaning, not fixture ergonomics.)

The thing I'd tell myself six months ago

Both failures had the same shape, and so did the sibling project's — where yarn lint turned out never to reach scripts/, batch/ or config/. That's 21 files, 92 errors, nine of them the very casts we'd banned. The code that decides whether a PR can merge had no gate on it.

Gates don't fail loudly. A gate that isn't running produces the same output as a gate that's running and finding nothing. There is no error message for "this never executed," because from the inside those two states look identical.

So the commenter had it right, and their framing is better than what I'd written. Testing that your code passes the check is not the same as testing the check.

You can't fix that by reading configs more carefully. You fix it by making the check fail on purpose, once, and watching.

Anything you've found this way, I'd like to hear it — particularly if your green was hiding something dumber than mine.

Two things broke when I shipped my Claude Code plugin — and one of my fixes was cargo cult

Isamu Arimoto — Mon, 03 Aug 2026 06:26:37 +0000

My skills worked. I'd been using them locally for weeks. Then I packaged them as a plugin, installed it the way a stranger would, and hit things that don't exist locally — and that don't produce an error message pointing at the cause.

Two of them were real. The third was a rule I'd been repeating for months, which turned out to be about something else entirely. Writing this post is what made me check it.

1. Your skill's name changes, and skill-to-skill calls break silently

A skill in ~/.claude/skills/story/SKILL.md is invoked as:

/story

The same file, shipped inside a plugin named mulmocast, is invoked as:

/mulmocast:story

The plugin name becomes a prefix. Which is fine, until you remember that skills can call other skills.

My mulmocast skill is a router: it reads what you asked for and hands off to story, narrate, illustrate and so on. Written the obvious way, that hand-off says story. So:

locally — mulmocast → story → works
installed from a marketplace — mulmocast → story → no such skill

I never saw an error that named the cause. The hand-off simply didn't happen, and the skill carried on as though that step had been optional.

The fix is to write both names, qualified one first:

1. Try `mulmocast:story` → if not found, try `story`
2. Try `mulmocast:narrate` → if not found, try `narrate`

One note on notation: a user types /story to invoke a skill. Inside a SKILL.md you are naming a skill for the model to dispatch to, not typing a slash command — so write it without the slash, as above.

2. Your CLI's name changes too

Same shape of problem, different layer.

My skills drive a CLI that ships as its own npm package. The plugin repo carries the skills, references and example scripts — not the CLI. While developing the CLI, I ran it from inside its repo:

yarn run cli images script.json

That line is fine in a terminal I own and wrong in a SKILL.md, because the person reading it installed a plugin. They don't have that checkout, so yarn run cli resolves to nothing.

The obvious fix is to write the published bin name instead:

{
  "name": "mulmocast",
  "bin": {
    "mulmo": "lib/cli/bin.js",
    "mulmocast": "lib/cli/bin.js"
  }
}

That works — if they installed the package globally. Which they may not have, and which you have no way to check from inside a skill.

So what my skills actually say is this:

npx mulmocast@latest movie script.json

npx resolves the package and downloads a temporary copy when what's installed doesn't satisfy the spec. No install step to document, and no version to keep in sync with your prose. If you keep a yarn run cli line at all, mark it as the one for people working in the repo — it is not a fallback for your users, it's a note to yourself.

Both of these have the same root cause: you are writing instructions from inside an environment your reader is not in. Every name you put in a SKILL.md — a skill, a command, a path — gets resolved somewhere else.

3. The one I was wrong about

Here is advice I had been giving, including in writing:

Never give your marketplace and your plugin the same name. If you do, installation fails on Linux with an EXDEV error.

I believed it. I set my repo up that way. I couldn't tell you where I first picked it up.

I don't use Linux. I never hit this, never reproduced it, never checked it. Writing this post is what finally sent me looking for the source — anthropics/claude-code#14799.

It has nothing to do with names.

Error: Failed to install: EXDEV: cross-device link not permitted,
rename '/home/user/.claude/plugins/cache/…' -> '/tmp/claude-plugin-temp-…'

On most current Linux distributions /tmp is tmpfs, while ~/.claude sits on your real disk. Two filesystems. fs.rename() can't move a file across that boundary, and the installer was renaming between them.

So it fired for any plugin, whatever anything was called. The workaround was to put the temp directory on the same filesystem:

export TMPDIR="$HOME/.claude/tmp"

And it's fixed — the issue closed in February. On a current Claude Code there's nothing here for you to do.

Why a wrong rule survived that long

This is the part I want to keep.

The rule was harmless. Giving the marketplace and the plugin different names costs nothing, breaks nothing, and looks tidy. So I followed it, everything worked, and nothing ever contradicted me.

A rule that's expensive gets challenged — sooner or later someone asks whether it's worth it. A rule that's free just accumulates. I'd been passing on a diagnosis I had never once tested, and the only reason I found out is that I sat down to write it as fact.

For the record, here are the names in a working setup — and note that two of them are supposed to match:

// .claude-plugin/marketplace.json
{
  "name": "mulmocast-plugins",          // the marketplace
  "plugins": [
    { "name": "mulmocast", ... }        // ← must MATCH plugin.json
  ]
}

// .claude-plugin/plugin.json
{ "name": "mulmocast" }

While we're here: there are three names, not one

The reason the above is confusing at all is that a plugin involves three separate names, and the docs use them in different places:

receptron/mulmocast-claude-plugin        ← GitHub repo
        ↓
marketplace.json  "name": "mulmocast-plugins"     ← marketplace name
marketplace.json  plugins[0].name: "mulmocast"    ← plugin name
        ↓
install:  mulmocast@mulmocast-plugins
          ^^^^^^^^^ ^^^^^^^^^^^^^^^^
          plugin    marketplace

Name	Defined in	Used by
GitHub repo	GitHub	`marketplace add`
Marketplace name	`marketplace.json` → `name`	after the `@` in `install`
Plugin name	`marketplace.json` → `plugins[].name`, and the plugin's own `plugin.json` → `name`	before the `@` in `install`

The repo name is used once in this sequence, when registering the marketplace. After that you work from the names inside the JSON:

claude plugin marketplace add receptron/mulmocast-claude-plugin   # repo name
claude plugin install mulmocast@mulmocast-plugins                 # plugin@marketplace

Minimum layout. These can be two repos or one — mine is one:

my-plugin-repo/
  .claude-plugin/
    marketplace.json     # the catalogue
    plugin.json          # this plugin's metadata
  skills/
    my-skill/
      SKILL.md           # the actual skill

Which distribution method to pick

There are three, and they're not competing for the same job.

	Reach	Ships MCP servers	Ships hooks	Install
Your own marketplace	Claude Code	✅	✅	`/plugin install name@market`
Official store (claude-plugins-official)	Claude Code, no setup step	✅	✅	`/plugin install name@claude-plugins-official`
Skills CLI	Cursor, Codex, OpenCode and dozens more	❌	❌	`npx skills add owner/repo`

Roughly:

Claude Code only, and you use MCP servers or hooks → plugin. Start with your own marketplace, apply to the official store once it's proven.
You want it to work in Cursor, Codex and the rest too → Skills CLI. It symlinks SKILL.md into each agent's directory, so one repo covers all of them. You give up MCP and hooks.

The columns say ships deliberately. Skills CLI distributes SKILL.md files; it does not install plugin manifests, so MCP servers and plugin hooks don't come with them. The target agent may well support hooks on its own.

And the thing I'd actually weigh about the official store isn't discovery — it's that users skip marketplace add entirely. One less step where someone gives up.

What the three have in common

The first two live in the same place: I had only ever run this where the names happen to be right. Locally the skill is story and the CLI is yarn run cli. Published, it's mulmocast:story and mulmocast. Both failures sit in that gap.

The third is the same gap from the other side. I'm on macOS, so a Linux-only failure was never going to reach me — and because my workaround for it was free, no evidence was ever going to reach me either. I'd built a belief that couldn't be falsified from where I was standing.

So the useful habit isn't "test the plugin" — it's install it the way a stranger would, on a machine that isn't yours, before you tell anyone it exists.

And if you're carrying a rule you've never seen fail: that isn't evidence it works. It might just be cheap.

Docs: Claude Code plugins · Marketplaces · Agent Skills spec

I stopped reviewing my own code. Here's what had to be true first.

Isamu Arimoto — Sat, 01 Aug 2026 06:38:10 +0000

Most days now, I merge pull requests without reading the diff.

That sentence used to describe someone I would not have hired. So let me be precise about what changed, because it isn't confidence and it isn't recklessness. It's that I moved the things review was catching to somewhere that catches them earlier.

Here's the honest version of how that happened.

The problem was arithmetic, not philosophy

I run several coding agents in parallel. That produces more diff per day than I can read. Not "more than I feel like reading" — genuinely more than fits in a working day.

When that happens you have exactly two options:

Generate less, so it fits what you can read.
Make it safe to not read.

I picked the second one. Not because I'm brave, but because option 1 means throwing away the reason I set this up.

The uncomfortable part: option 2 is not a mindset. It's a list of specific things that have to be true. Here's mine.

1. The rules live in a file, not in review comments

Every code review I've ever done, the majority of my comments were mechanical. This function is too long. This nesting is too deep. Why is this any?

Machines can say all of that. So I made them say it, as errors:

"max-lines-per-function": ["error", { max: 60, skipBlankLines: true }],
complexity: ["error", 20],
"max-depth": ["error", 4],
"max-nested-callbacks": ["error", 4],

Plus eslint-plugin-sonarjs with cognitive-complexity as an error, and @typescript-eslint's strict preset — any banned, non-null assertions banned.

Nothing here is novel. What's different is the next part.

2. The rules are stricter than a human team would tolerate

This is the part I find genuinely interesting.

If you put those thresholds on a human team, you get a PR relaxing them within a week. Not because engineers are lazy — because "this function is 63 lines and splitting it makes it worse" is sometimes true, and arguing about it every time is exhausting.

Lint strictness has always been a trade-off between machine correctness and human patience. And loosening the rules was never really a technical decision. It was a social one.

An agent doesn't get annoyed. It reads the rule, splits the function, moves on. It has no opinion about being told to do it again tomorrow.

So the social cost went to zero, and once that happens the trade-off only tips one way. I turned everything up until it hurt, and nobody complained, because nobody was there to complain.

3. Exceptions live in the config with a reason, never inline

The moment rules get strict, real exceptions appear. If you allow // eslint-disable-next-line, the rules are dead within a month — that comment is invisible in review and permanent in practice.

So exceptions go in the config file, one line per reason:

files: [
  "src/components/Sidebar.vue",       // @keyframes — the "thinking" spinner ring
  "src/components/GuiPanel.vue",      // `.frame + .frame` sibling-combinator spacing
  "src/components/FilesOverlay.vue",  // :deep into CodeMirror's injected root
],
rules: { "vue/no-restricted-block": "off" },

Every entry says why. And the comment above the block says: delete the entry when the reason goes away.

The difference is visibility. An inline disable is invisible. A growing allowlist in a config file is a thing you can look at and be embarrassed by.

4. The rules themselves are pure functions, and they're tested

This is the part most setups skip.

If a rule decides something — which file extension goes where, how a path is normalised, what counts as a valid session id — that decision is code, and code that is only exercised through a UI is code nobody tests.

So decisions get pulled out into pure functions in a shared module, and those functions get tested against the awkward cases: empty, null, boundary, wrong-cased, wrong-platform. That project currently has a few thousand test cases, and the vast majority are testing small pure functions rather than flows.

The point is not the count. The point is: when the rule is a pure function, the rule can be tested. When it's embedded in a component, it can only be reviewed. And I stopped reviewing.

5. CI runs on the OS your users have, not the one you have

Our whole team is on macOS. Our users are not.

So CI runs Linux and macOS on every PR, and Windows on a nightly schedule (it's slow, and daily is enough to catch drift).

This one paid for itself immediately, and not in the way I expected. It's the only environment where I can reproduce a Windows bug report at all. Before, a Windows issue meant asking the reporter to test my guesses. Now I push a branch.

We also write Windows-specific test cases deliberately — path separators, realpathSync behaviour, fs.watch differences — so that fixing one doesn't quietly break the others.

6. Something else reads the code — and it isn't the thing that wrote it

Claude Code writes. Then Codex reviews, and CodeRabbit reviews, and the loop runs until they stop objecting.

The mechanism that matters here isn't "AI review is good." It's that the writer and the reader are different models. A model reviewing its own output shares its own blind spots. Two different ones don't, mostly.

This is the closest thing to a replacement for what I stopped doing. It isn't as good as a careful human reviewer. It is much better than a tired human reviewer at 11pm on the fortieth PR of the day, which was the realistic alternative.

What I still look at

I want to be honest about the boundary, because "I don't review anything" would be a lie:

UI changes. Nothing in the list above can tell me a layout is ugly or a flow is confusing.
Anything I couldn't verify by running it. If the change is about behaviour under conditions CI doesn't reproduce, I go look.
Anything touching auth, permissions, or data loss. The blast radius is wrong for automation.

Everything else, I let through on green.

The honest cost

Three things I'd want to know if I were reading this skeptically:

It front-loads a lot of work. None of the six items above is free. If you set up two of them and stop, you have strictness without a safety net, which is worse than neither.

It only works if the stack is uniform. The reason my per-repo config files are nearly empty is that every project uses the same language, the same test runner, the same CI shape. If your repos disagree with each other, you'll be writing the same rules over and over. Fix that first; it's cheaper.

Speed is not correctness. Things do get shipped fast and fixed fast. What this setup buys is not "no bugs" — it's that the bugs that survive are the ones review wouldn't have caught either.

The thing I actually took away

I set all this up to save time, and it did. But that isn't the interesting part.

The interesting part is that lint strictness, test coverage, CI breadth — the whole category of "engineering discipline we know we should do but don't" — was never really blocked on knowing better. It was blocked on how much friction a human team will absorb before it starts negotiating.

That constraint just got removed. Not gradually. It's gone.

I don't think most of us have updated for that yet.

Everything above runs in the open: my global config
and the project it runs on, both MIT.
Copy whatever's useful.

AI Changed the Bottleneck of Software Development

Isamu Arimoto — Thu, 23 Jul 2026 08:27:52 +0000

For decades, software engineering was constrained by one thing: writing code.

Today, that bottleneck is disappearing.

With tools like Claude Code, Codex, and other coding agents, generating thousands of lines of code is almost free. The new constraint is no longer how fast we can write code—it's how fast we can keep a codebase healthy.

That is a fundamentally different problem.

AI Doesn't Create Bad Code. It Creates Code Too Easily.

Modern coding agents are remarkably good at producing working code.

But they also tend to:

create another helper function instead of reusing an existing one
leave dead utilities after refactoring
grow functions to hundreds of lines
fall back to any when type inference becomes difficult
introduce subtle architectural violations that are hard to notice in code review

None of these are catastrophic individually.

Together, they slowly increase technical debt.

The challenge isn't intelligence—it's scale.

When an AI can generate code 10× faster than a human, it can also generate technical debt 10× faster.

Human Code Review Doesn't Scale Either

Even experienced reviewers can't remember a 300,000-line codebase.

Suppose a pull request adds another truncate() function.

Is there already one somewhere else?

Maybe.

Maybe there are six.

No reviewer can reliably answer that from memory.

The same applies to unused exports, circular dependencies, or architectural boundaries.

These aren't problems humans should spend their time searching for.

They're mechanical problems.

Let Machines Enforce Code Hygiene

The obvious solution is to automate the boring parts.

Our development workflow combines several layers of static analysis:

ESLint for complexity and coding standards
SonarJS for maintainability and type safety
jscpd for duplicated code
Knip for dead code detection

Each tool catches a different class of problems.

No single tool is sufficient.

Together, they continuously protect the codebase while developers—and AI agents—focus on solving actual problems.

DRY Matters Even More in the AI Era

Many people think DRY ("Don't Repeat Yourself") is mainly about maintainability.

Today, it has another benefit.

AI agents consume context.

Six duplicated implementations don't just increase maintenance cost—they also increase token consumption.

Large functions require more context.

Duplicate utilities require more searching.

Dead code increases noise.

A cleaner codebase is also a cheaper codebase for AI.

Good architecture now directly improves AI efficiency.

CI Should Prevent Regression, Not Punish History

One lesson we've learned is that not every static analysis tool should block a pull request.

Some checks can accurately identify new problems.

Those belong in CI.

Others can only report the current state of the repository.

Those should provide visibility rather than block development.

The goal isn't to eliminate all technical debt overnight.

The goal is simple:

Never create new debt faster than you remove the old one.

The New Engineering Skill

As AI continues to improve, writing code becomes less valuable as a competitive advantage.

The differentiator shifts toward something else:

Designing systems that remain understandable, modular, and maintainable—even when most of the code is written by machines.

Software engineering is becoming less about typing code and more about managing the quality of an ever-growing codebase.

The bottleneck has moved.

The teams that recognize this early will build software faster—not because their AI writes more code, but because their systems stay clean enough for AI to keep writing it.

DEV Community: Isamu Arimoto

The Missing Bottom Layer: Why AI Isn't Making Your Company Faster

1. Drafting takes 30 minutes now. Reading hasn't gotten any faster

2. The bottleneck moved to "after drafting"

3. What already happens in software development

4. What a business harness is

Definition

Three layers

Ten stages

Not only stopping: surfacing

5. What's missing from the tools you already have

The condition for wiring: everything is data, everything runs through an API

6. The core idea: make the AI produce fields, not prose

Make the fields the source of truth

What machines can check, and what stays with the AI

Checking against facts outside the document

The evidence chain: no document stands alone

How references get created

Check the machinery, not just the output

The last step

7. Five scenes: inbound lead, business trip, client dinner, business case, vendor invoice

Scene 1: From a web inquiry to a proposal in the customer's inbox

Scene 2: A business trip, from pre-approval to gift to expense report

Scene 3: A client dinner on the expense report

Scene 4: From a business case to spending approval and the annual budget

Scene 5: From a vendor invoice to payment

What the five scenes share

8. Turning human judgment into a mechanism

9. Where to start

10. Open questions

11. Build the layer, not the app

Sidebar: the software vocabulary

Appendix A: Glossary

Appendix B: Sources

ever-better: 13 commands that make a codebase only able to get better

diagnose — what is missing, and what each gap costs

bootstrap — install the tooling, generate the configs

freeze — pin today's violations as the ceiling

check — the gate

prune — lower the ceiling after a fix

next — what to drain first

report — what the debt actually looks like

secrets — scan the history for committed credentials

migrate — JavaScript to TypeScript

emit-diff — prove a refactor changed nothing

catalog — the helpers that already exist

status — where you are

log — why, not how many

The whole loop, in five commands

Or hand the repository to an agent

Try it on something you did not write

Handing an AI a big spec and letting it build the whole thing is like buying a lottery ticket

Why you end up with "too big to review"

You can't write a spec for something when you don't know if it's possible or if you even want it

It's like buying a single lottery ticket

Let's compute the odds that "all of it works"

"Just write a more detailed spec" ends at implementation

And AI flipped this trade-off

So how do you build? Tighten the implementation, not the spec

"Isn't one at a time slow?"

That said, cutting small isn't automatically safe

This isn't AI's fault. It was always like this

The same thing happens under Agile

The tool got smarter. You didn't

Leverage is a multiplier, not the number being multiplied

Former CTOs joining AI labs as individual contributors is probably the same story

Some decisions don't exist until you build

Example 1: the purpose I built it for was wrong

And then it got worse

Example 2: the AI said "don't do it" — and it was wrong

AI doesn't shorten the distance

Why "just have the AI review it" doesn't fix it

So what do I actually do

I do write plans. 351 of them. But the AI writes them.

Adding one person doesn't add just one channel

This connects back to the former CTOs

That said, the formula doesn't give you a number

There's a ceiling on how much you can run in parallel

Which leads to: teams should be small too

The two-pizza rule isn't about meetings any more

`diagnose` — what is missing, and what each gap costs

`bootstrap` — install the tooling, generate the configs

`freeze` — pin today's violations as the ceiling

`check` — the gate

`prune` — lower the ceiling after a fix

`next` — what to drain first

`report` — what the debt actually looks like

`secrets` — scan the history for committed credentials

`migrate` — JavaScript to TypeScript

`emit-diff` — prove a refactor changed nothing

`catalog` — the helpers that already exist

`status` — where you are

`log` — why, not how many

The second one: a rule set to `error` that reports zero