Your app is slow? Measure before you buy a bigger server. Ours was one line of code
For four minutes every screen of 2novel froze. The reflex was a bigger machine. The numbers pointed at a Promise.all refunding 39,523 jobs at once, on an API using 1% of a CPU core. Two new 2build skills measure performance and design architecture for the person who pays.
If your app is slow and someone just said "let's upgrade the server", read this before you pay.
Four minutes
On 9 November 2026, for four minutes one afternoon, every screen of 2novel, 2found's novel translation app, froze. The library page took up to 37 seconds. The cancel button took up to 69 seconds. Even /readyz, an endpoint that runs a single SELECT 1, took 23.7 seconds.
The log said keepalive_timeout, with an operator hint: "restart translate-api".
The usual reflexes are to restart it, give it a bigger machine, or move the workers to their own host. We did none of them. We measured first.
What the numbers said
The cause was a bulk cancel. When a user cancels a book that is waiting for translation, the code refunded every job, one transaction each, all at once, through an unbounded Promise.all. That day it was 39,523 jobs, all landing on the pool of 10 database connections that serves every customer's requests.
The cancel was slow, so the user pressed it again: 25 times in all, each press starting another wave of parallel refunds.
And the three reflexes?
- Restart: fixes nothing. The connections were not dead, they were busy. The hint in the log was wrong.
- Bigger machine: the 2novel API uses about 1% of one CPU core. The database was at 53 of 100 connections. A bigger machine still has the same 10 connections, all taken.
- Separate workers: one more thing to operate, for a process that is nearly idle.
The fix sits on the cheapest rung: refund in small batches in the background, and let the cancel answer at once. Infrastructure cost: zero.
Two new 2build skills
We packaged this way of working as two skills, in 2build since v1.127.
perf-audit answers: where do users feel slowness, why, and what to fix first. It follows a request through the CDN, web, API, caches, database and queues, ranks paths by calls times time, holds each to a budget and diagnoses the red ones. A cause counts only once it is proven. An unproven cause is recorded as a suspect, and never becomes a fix.
architect answers: what does the system really look like today, and how should it grow. It redraws the running architecture from code and deploy config (when an old doc disagrees, the code wins), then designs the next generation as a roadmap. Each stage waits for a measured trigger, such as "host CPU pressure above 20% in 2 of 3 weekly peaks". Until the trigger fires, the stage costs nothing.
Neither skill edits code, infrastructure or data. They measure, prove and propose. Fixes go through Autopilot like any other change, carrying the audit's own numbers as acceptance.
Written for the person who pays
Whoever decides about performance is often not an engineer. They choose between "a few tens of dollars a month more" and "two days of an engineer's time". So the report opens with their section:
- Every number has a date and a source, and reads as what a user feels: "a chapter opens in 0.15 s; the target is 0.3 s".
- Every proposal states the monthly cost, downtime, risk, whether it can be undone and who must approve.
- What the skill cannot know by itself, like which journeys earn money, is written down as an assumption with its source and collected under "Needs your decision", instead of stopping to ask.
For 2novel, that section held decisions only the owner can make: deleting 2.5 GB of old data (irreversible without a backup), or restarting the shared database to turn on query statistics (about a minute of downtime for every app on the machine).
The order of fixes
Every proven cause goes on a ladder. Lower rungs are cheaper and easier to undo:
- Code: avoidable work in each request.
- Query and index: avoidable work in each SQL statement.
- Data: data that has grown too big. Always an owner-approved proposal, marked irreversible.
- Flow: move work to the background, batch it.
- Cache on what already exists.
- Infrastructure and architecture: handed to
architect, with the evidence.
Three things are never proposed: caching what an index fixes, adding capacity for cost nobody has attributed, and splitting a service for performance alone.
Production is read-only
The truest numbers live in production, and so does the one wrong command. So the rules are written into the skill: only access a repo doc or the owner names as read-only; no restarts, deploys, cache purges or load tests against production; EXPLAIN runs inside a read-only transaction. Logs are aggregated by route and never quoted: no ids, emails, IPs or SQL parameters reach the report.
Without production access the skill still runs. It reads the code, measures in a lab, and returns a measurement plan: which signal to read, what access it needs and how long it takes. Health is then "not measured", and it says so.
What the first 2novel audit found
- Everyday use is fast: a book opens in 0.1 s and a chapter in 0.15 s, both under budget.
- Three fixes ready for Autopilot, each with an acceptance command: batched background refunds; logs with the route and the database error code instead of the parameters; a library page that reads counters instead of re-adding every chapter on each refresh.
- A safety gap from
architect: no alert fires when the API errors or slows down. Those four minutes may not have reached anyone. - A roadmap that costs nothing yet: an own database, separate workers, a second API instance, each waiting for a measured threshold. None has been reached.
- The shared host really is short of CPU, but 2novel is about 2% of its load. Moving 2novel would barely help. That is a platform decision, and it sits under "Needs your decision".
Where it stands
Autopilot shipped the first two fixes: refunds in small background batches, and logs that carry the route and the database error code. They reached production at 17:05 the same day (Vietnam time). Two hours later we ran perf-audit verify on that same report, with the same sources and the same method.
| Before | After | |
|---|---|---|
| Whole app frozen during a large cancel | about 4 minutes | about 15 seconds |
Slowest /readyz |
23.7 s | 0.56 s |
| Slowest cancel | 69 s | 23 s |
| Cancel returned an error | 2 of 25 | 3 of 5 |
The verdict was one finding fixed, two still open and none regressed.
- Fixed: the logs. They now say who is slow. The library page is slow only for our own internal workspace, while real customers load it in about 0.02 s. That kept the third fix (counters on a 1.5 GB table) on hold, because no customer needs it yet.
- Still open: cancel. The freeze went from 4 minutes to 15 seconds, but the fix did not meet its acceptance criteria, and 3 of 5 cancels still failed. The new logs showed why: the cancel collides with itself. It updates the same thousands of rows with two statements running at once, so the database has to stop one of them. The four-minute jam used to hide this. It is the next fix, still on the code rung, still $0.
- Not 2novel: a 10-second slowdown at 18:41, with no cancel running, matched a moment when the shared server was starved for CPU. The report files it as a suspect at the platform level, not as work for 2novel.
Two things are not settled yet. We have one measurement window of about two hours, and the skill wants two windows with comparable traffic. The refunds have not been reconciled on production either, because that needs database read access, which the owner approves each time.
If we had stopped at "tests pass, deployed", the cancel fix would be marked done. Measuring again showed that the fix was right but not enough, and it pointed at the next cause.
Try it on your app
1. Install or update 2build.
brew tap 2found/2build https://github.com/2found/2build
brew install 2found/2build/bbs # already installed? run: bbs update
bbs install # detects Claude Code, Codex, AntigravityThen restart your agent.
2. Ask your agent to measure.
| Agent | Whole system | One journey | Architecture |
|---|---|---|---|
| Claude Code | /bbs:perf-audit |
/bbs:perf-audit audit "open a chapter" |
/bbs:architect |
| Codex | $bbs:perf-audit |
$bbs:perf-audit audit "open a chapter" |
$bbs:architect |
3. Read the top of the report. That part is written for you. Each fix at the end of the report is an Autopilot command you can paste as is. After the fix, run /bbs:perf-audit verify <report path> to see before and after.
Not using 2build? Check these yourself
- Measure before you buy. Find which process uses the CPU, and how much.
- Look at the database connection pool, not only CPU. One bulk task can take every connection while the CPU sits idle.
- Look for an unbounded
Promise.allover data whose size a user decides. - Distrust every "just restart it" hint. If a resource is busy, a restart only moves the incident to next time.
- Alert when the API errors or slows down, and make sure the alert reaches a real person.
- Write down what you are not doing yet, and why. Redis, read replicas and microservices all have their moment. Write down the number that would change your mind.
Most "we need a bigger server" moments are waste in the code. Measure first, then pay.
How to use both skills: Performance and architecture in the 2build docs. Source, skills and issues: github.com/2found/2build.
