2buildDocumentationGitHub
2build / DocumentationRead Markdown (.md) View source

Performance & architecture

Two skills answer "is the system fast enough, and what should it become?" before anyone buys capacity:

SkillAnswersWrites
/bbs:perf-auditWhat do users feel, which proven cause is behind it, what to fix first?a report in .babysit/perf-audit/<date>-<scope>/ (or the ticket's evidence/), and docs/PERFORMANCE.md
/bbs:architectWhat does the system really look like today, and what is the next generation, in which order?the current architecture docs with diagrams, and docs/architecture-next.md

Neither skill edits product code, configuration, infrastructure or data. Fixes ship through /bbs:autopilot with the audit's numbers as acceptance; staged architecture work goes to /bbs:autopilot or /bbs:team.

Run a performance audit

text
/bbs:perf-audit                          # the whole system: every hot path and shared resource
/bbs:perf-audit audit "<journey|page|route|job>"
/bbs:perf-audit verify <report path>     # re-measure after a fix

The audit maps the path from the user's entry through edge, web, API, caches, database, queues and external calls, ranks paths by weight × total time, gives each a budget, then diagnoses the red and yellow ones. A cause counts only when it is proven: a local toggle that removes it and re-measures, a plan at production volume, or a counted fact. An unproven cause stays a suspect and is never ranked as a fix.

What it needs

EvidenceSourceWithout it
liveproduction logs, database statistics, host metrics, CDN headers, field page datathe report is a measurement plan, health not-measured
laba local or reserved environment at production shapecauses stay suspects
staticcode and query plansalways available; never a status or a gain

Production access must be a route that a repo doc or the owner names as read-only. A credential that can write (an app database URL, an admin role, an SSH user that can restart services) is not read-only: the skill asks once for access, naming what it reads and for how long, and finishes with lab and static evidence when nobody can answer. Record the route in the project's docs/PERFORMANCE.md Signals table so later audits find it.

On production it never load-tests, restarts, redeploys, changes config or flags, purges caches, writes or enables extensions. Database reads go through the bundled pg_snapshot.sql, and EXPLAIN runs inside BEGIN READ ONLY … ROLLBACK. Logs are aggregated by route with the bundled log_paths.py, which replaces ids, emails and token-like strings; raw log lines, ids, emails, IPs and SQL parameters never reach the report.

Budgets

The project's docs/PERFORMANCE.md wins; otherwise these defaults apply.

ClassBudget
Page, real mobile users at p75LCP ≤ 2.5 s · INP ≤ 200 ms · CLS ≤ 0.1 · TTFB ≤ 0.8 s
Interactive API read / write, server p95≤ 300 ms / ≤ 1 s
Errors per path5xx and timeouts ≤ 0.1 %
Host at peakCPU pressure some avg60 ≤ 20 % · memory ≤ 80 % · disk ≤ 80 %
Databasebuffer cache hit ≥ 99 % · connections ≤ 80 % of max

A path is green within budget, yellow up to 1.5× or 20 % worse than the last audit, red beyond 1.5×, over its error budget or on a saturated shared resource, and unmeasured without a live or lab number.

Reading the report

The report is two parts. Part 1, "for the owner", opens the file and is all an owner needs to read: the short answer, a "What people feel today" table in seconds, why in plain words, numbered recommendations each with cost, risk and the command to paste, what is not worth doing, decisions only you can make, what the audit assumed and what it could not measure. It has no routes, percentiles, ids or jargon. A divider follows, and below it Part 2 holds the technical detail: every number with its date and source, the paths, causes and evidence. Business facts the skill could not read are written as assumed (<source>, <date>) in Part 2 and as a plain sentence under "I assumed" in Part 1, instead of being asked mid-run. The chat reply opens with the same short answer and the first recommendation before the status block.

Each recommendation states money per month, downtime, risk and whether it can be undone; one that needs your yes is also listed under the decisions.

Fixes are ordered on a ladder, lowest rung first: code, query and index, data, flow, cache on what already exists, then infrastructure and architecture. Each proven cause goes on the lowest rung that removes it. Data changes (purges, retention) are always owner-approved proposals marked irreversible. Caching what an index fixes, adding capacity for unattributed cost and splitting a service for performance alone are never proposed.

Each fix theme ends with a ready command:

text
/bbs:autopilot "<fix theme> — acceptance in .babysit/perf-audit/<date>-<scope>/report.md#f1"

After the fix ships, verify re-measures the same paths with the same method and comparable traffic and marks each finding fixed, still or regressed. A change counts when the after median lies outside the before range and differs by at least 10 %. A lab verify of undeployed code says so; production confirmation is a later verify.

A verify judges each finding by its own acceptance criteria, not by whether the patch merged. On 2novel (2026-11-09) the audit found that a bulk cancel refunded every job at once on the request pool and froze the API for about four minutes. Two hours after the fix shipped, verify returned VERIFIED(fixed=1 still=2 regressed=0):

FindingBefore → afterVerdict
F1 bulk cancel drains the request poolfreeze ~4 min → ~15 s; cancel errors 2/25 → 3/5still: the root cause is gone (lab tests pass), but live acceptance failed
F2 logs lack route, workspace and SQLSTATEall three present, no SQL paramsfixed
F3 library aggregates every chapter per pollcustomers ~20 ms, internal workspace 0.89 sstill, deferred by design

The F2 logs also exposed what the freeze had hidden: each failed cancel was a 40P01 deadlock between two updates fired by the cancel itself. That became a new rung-1 finding with its own acceptance. A one-window verify says that its numbers are provisional until a second comparable window is measured.

The performance profile

docs/PERFORMANCE.md carries what one audit learns to the next: the read-only signal sources and commands, budgets, hot paths with their last status, known traps and the audit log. AGENTS.md links it so every agent reads it before performance work.

Design the next generation

text
/bbs:architect            # current, then next
/bbs:architect current    # verify the as-is architecture and its diagrams
/bbs:architect next       # horizon, next-gen design and roadmap
/bbs:architect new        # smallest system for a product with no code yet

current reads code, deploy config and read-only running state, corrects the project's architecture docs where a fact is verified wrong, renders the diagrams and audits safety gaps, headroom, single points of failure, coupling, scaling cliffs and cost. Where docs and code disagree, the code wins and the drift becomes a finding.

new is for a product with no code yet, and autopilot runs it when it starts a project from an idea. Nothing runs or is measured, so the as-is steps and headroom do not apply: it designs the fewest deployable services the requirement's first release needs (one web app until a requirement needs a separate API), takes each stack from a starter where one fits, names one production target with a monthly price and the date it was read, and writes docs/architecture.md with one diagram. It creates and buys nothing. Its reply is an owner summary: what the product is made of, the monthly cost once live, what was left out and when it would be added, and the decisions that are yours with their defaults.

next takes a horizon from the PRD, roadmap or tickets (else ×2 and ×5 the current peak, labelled), projects the headroom table onto it and designs the smallest change set that clears the first limits. The roadmap orders stages (edge, right-size, database, shared cache, jobs, instances, replicas, partitions, services), and each stage waits for a measured trigger:

text
<signal> <op> <threshold> in <n> of <m> windows
host CPU PSI some avg60 > 20 % in 2 of 3 weekly peak windows

A trigger whose signal is not collected is added to docs/PERFORMANCE.md as TODO(2build):. Seams (database location from the environment, idempotent side effects, no shared state in process memory) are kept now; the component they enable is added when its trigger fires. A "Not yet" list records what was considered and the trigger that would change the answer.

A load-driven stage needs a perf-audit report, or equal evidence, that the waste is already removed. Run /bbs:perf-audit first when load is unmeasured.

Verdicts

text
VERDICT: AUDITED(<good|attention|problem|not-measured>, red=<n> yellow=<n> green=<n> unmeasured=<n>)
VERDICT: VERIFIED(fixed=<n> still=<n> regressed=<n>)
VERDICT: ARCHITECTED(<current|next|both|new>, findings=<n>, stages=<n>)

not-measured, or a critical path left unmeasured, ends DONE_WITH_CONCERNS. Both skills run unattended; the only question either may raise is missing read-only production access.