agentleFS
lohi-ailohi-ai/babysit/.claude/skills/perf-audit/SKILL.md

perf-audit

Skill0 starsChanged 2 days agoMITView on GitHub

Audit one feature's or the whole system's performance for an owner who is not an engineer: what users feel, proven causes from production signals, fixes ranked easiest and safest first. Use when something feels slow, before buying capacity, or to verify a fix.

15 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use a11y-audit, security-audit and 1 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • renfei-designSkill

    a11y-audit

    Audit Figma designs for WCAG accessibility issues — color contrast, minimum font size, touch target sizing, and missing text alternatives. Use when asked to check accessibility, audit contrast ratios, find a11y issues, verify WCAG compliance, or review designs for accessibility problems. Scans nodes, analyzes offline, and annotates issues in Figma.

    Also in 4 projects that use this

  • CloudflareSkill

    security-audit

    Security guidance and vulnerability review for codebases, APIs, services, CLI tools, libraries, and daemons. Use for security questions, focused reviews, vulnerability research, security audits, or pen tests. Run the complete workflow only for explicit codebase audit or pen-test requests, full/comprehensive/end-to-end reviews, or requested report artifacts.

    Also in 4 projects that use this

  • GoogleSkill

    code-review

    Adversarial systems, concurrency, memory-model, and architecture code review protocol. Use this skill whenever asked to review code, PRs, diffs, or branches in Filament.

    Also in 4 projects that use this

The file

We split this skill into the rules it gives an agent

6 rules. 0 are common, 5 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 11 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Follow preamble and the Auto-Decision Framework.

    line 14
  2. Distinctive:

    Never block on a question.

    line 35
  3. Distinctive:

    Every recommendation states money per month, downtime, risk and whether it can be undone.

    line 40
  4. Distinctive:

    Write part 1 last, then re-read it alone: a word, number or name that only part 2 explains is replaced or moved down.

    line 43
  5. Distinctive:

    Map: Read AGENTS.md, the architecture, caching and deployment docs it links, the profile and the previous report (carry its known-findings …

    line 66
  6. Distinctive:

    When a person reads the result, the reply opens with the report's short answer, the first recommendation with its cost and risk, and the …

    line 120

“Common” is measured: kept by at least 6 in 10 of the 11 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

perf-audit

Measure, attribute, then propose. Most "we need bigger servers" is avoidable work in code or queries; capacity is justified only for measured real work. This skill evaluates and reports. It never edits product code, config, infrastructure or data; fixes ship through autopilot with this audit's numbers as their acceptance, and verify re-measures them. A cause that is a bug rather than a cost (wrong results, crashes, a broken deploy) goes to investigate.

Follow preamble and the Auto-Decision Framework. Shared refs are filesystem paths beside this skill's directory, so read them by path, not as skill://. Detail: measure (access, sources, where time goes, budgets, noise) · ladder (fix order, safety per rung) · profile (the project's performance profile) · report (template).

Modes

  • audit <feature> — one journey, page, route or job, end to end.
  • audit with no target, or system — every hot path and shared resource.
  • verify <report> — re-measure an earlier audit's paths after a fix.

Writing for the owner

The reader decides with money and risk, not stack traces, and reads only the report's first part. That part follows owner language and the template's part 1: journeys and seconds a person feels, causes a non-engineer could repeat, numbered recommendations each with money, risk and the command that starts it. Routes, percentiles, ids and sources live in part 2.

  • Never block on a question. Infer business facts (which journeys earn money or keep users, complaints, budget, acceptable downtime) from product docs, analytics and code; record each as assumed (<source>, <date>) in part 2 and as a plain sentence under "I assumed" in part 1. Budgets come from the profile or the defaults, never from a question.
  • Every recommendation states money per month, downtime, risk and whether it can be undone; one that needs the owner's yes is under "Decisions only you can make".
  • Write part 1 last, then re-read it alone: a word, number or name that only part 2 explains is replaced or moved down.

Production is read-only

The rules in measure § Access and safety apply to every command. In short: only an access route a repo doc or the owner names as read-only; nothing that writes, restarts, purges or loads production; logs aggregated, never quoted. The only files this skill writes are its output dir, the profile, and one link line in AGENTS.md when the profile is new.

The one NEEDS_CONTEXT this skill may raise is missing read-only production access. Raise it once, through the preamble's channel, naming exactly what access is needed, for how long and that it only reads; when the channel cannot wait, finish with lab and static evidence and put the request in NEXT.

Flow

Output dir: evidence/perf-audit/<date>-<scope>/ in the ticket when one resolves, else .babysit/perf-audit/<date>-<scope>/. Mirror the steps into the task list.

  1. Map. Read AGENTS.md, the architecture, caching and deployment docs it links, the profile and the previous report (carry its known-findings ledger). Feature: trace the path from the user's entry through edge, web, API, caches, database, queues and external calls, including requests the browser fires after load (polling, prefetch, retries); name the files, routes, queries and each cache layer with its owner; write the feature's route templates to <out>/routes.txt (input to log_paths.py --routes); draw the path as a sequence diagram. System: components, what runs where, sizes, managed services. Where a doc and the code disagree, the code wins: map what runs, and record the drift as a finding citing both. No architecture doc → map from code and deploy config and recommend architect. Compare the running revision with the default branch: an undeployed fix is a finding, not a bottleneck.
  2. What matters. Rank paths by weight × total time (calls × mean), from production signals first (measure § Sources), weight from product docs and the profile. Collect pain: over-budget latency, errors and timeouts, saturation, retry loops, regressions around a deploy, complaints.
  3. Budget. Each hot path gets the profile's budget, else the default. green within budget · yellow up to 1.5×, or ≥ 20 % worse than the last audit · red beyond 1.5×, errors over budget, or a saturated shared resource · unmeasured without a live or lab number.
  4. Diagnose red and yellow paths, heaviest first: split the time (measure § Where time goes), name the cause in one sentence, classify it waste or real work, and prove it (a local toggle that removes the suspect and re-measures, a plan at production volume, or a counted fact such as queries per request). Check earlier fixes in the same area first (git archaeology). An unproven cause is a suspect, never a ranked fix.
  5. Rank each proven cause on the lowest ladder rung that removes it, with estimated gain (ms × calls, CPU share, money), confidence, rollout risk and undo. Drop fixes within noise or under 5 % of their path. Infra and architecture rungs go to architect with the headroom evidence.
  6. Report (template) and update the profile. Each fix theme is a ready autopilot requirement with its acceptance command.

With no live or lab number, the deliverable is a measurement plan: the static findings as suspects, and for each hot path the exact signal to read, the access it needs and how long it takes. Health is not-measured.

Verify mode

Re-measure the report's paths with the same method, level, window type and comparable traffic; before → after per path, judged by measure § Noise. Each finding becomes fixed, still or regressed, and the rest of the inventory is re-checked for collateral regressions. A lab verify of undeployed code says so; production confirmation is a later verify after release.

Output

Health: good every measured hot path green · attention any yellow · problem any red · not-measured no live or lab number (owner words: Good, Needs attention, Problem, Not measured).

When a person reads the result, the reply opens with the report's short answer, the first recommendation with its cost and risk, and the command that starts it, in the owner's language; the status block follows for callers.

STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
VERDICT: AUDITED(<good|attention|problem|not-measured>, red=<n> yellow=<n> green=<n> unmeasured=<n>) | VERIFIED(fixed=<n> still=<n> regressed=<n>)
REPORT: <report path; profile path>
SUMMARY: <scope, evidence level live|lab|static, worst path vs budget, its cause>
NEXT: <copy-paste /bbs:autopilot "<fix theme>" in ladder order; /bbs:architect; the first measurement or the access request; owner decisions>

not-measured, or unmeasured critical paths, is DONE_WITH_CONCERNS. Not being able to map the target at all is BLOCKED.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.