agentleFS
YomudoglyYomudogly/oh-my-agy/skills/performance-goal/SKILL.md

performance-goal

Skill4 starsChanged todayMITView on GitHub

[oh-my-agy] Evaluator-gated performance optimization loop with durable artifacts: define an evaluator command and pass/fail contract first, then optimize in small reversible patches with recorded checkpoints until the evaluator passes. Use when the user wants measurable speed, latency, throughput, memory, or benchmark improvement as a goal-oriented loop.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill when the user asks to optimize performance and wants a goal-oriented loop rather than a one-off review.

    line 8
  2. Distinctive:

    No optimization work starts until an evaluator command and a pass/fail contract exist.

    line 13
  3. Very specific:

    If no workflow exists, establish (asking with ask_question only for values the repo cannot answer):

    line 19
  4. Distinctive:

    Evaluate: run the evaluator and related regression tests after each patch.

    line 36
  5. Very specific:

    Checkpoint: every result by appending to checkpoints.jsonl (using newline-isolated appends via sh <plugin>/hooks/run.sh append-jsonl …

    line 37
  6. Very specific:

    Complete: only when lastValidation.status == "pass" and the audit confirms no required work remains.

    line 40
  7. Distinctive:

    Before declaring a benchmark or evaluator result trustworthy, audit the evaluation setup across:

    line 45
  8. Very specific:

    8 Independence Failure Probes: check for Contamination (benchmark leakage), Invalid controls (unfair baseline flags/warmup), Circular …

    line 47

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “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

Performance Goal Workflow

Use this skill when the user asks to optimize performance and wants a goal-oriented loop rather than a one-off review.

Contract

  • Durable workflow state lives under .omagy/goals/performance/<slug>/ (state.json, checkpoints.jsonl).
  • No optimization work starts until an evaluator command and a pass/fail contract exist.
  • Completion requires a passing evaluator checkpoint plus a completion audit. Passing ordinary tests alone is not enough unless they are the declared evaluator.
  • Codex's hidden goal tools do not exist in Antigravity. The artifacts are the source of truth.

Create

If no workflow exists, establish (asking with ask_question only for values the repo cannot answer):

  • objective (e.g. "Reduce CLI startup latency by 20%")
  • evaluator command (e.g. npm run perf:startup)
  • evaluator contract (e.g. "PASS when p95 latency improves by >= 20% vs baseline and regression tests pass")
  • slug

Write .omagy/goals/performance/<slug>/state.json:

{"slug":"startup-latency","objective":"...","evaluator_command":"...","evaluator_contract":"...",
 "baseline":null,"lastValidation":null,"status":"active","created_at":"<ISO>","updated_at":"<ISO>"}

Also write .omagy/state/performance-goal-state.json (mode:"performance-goal", active:true, current_phase:"baseline", state.slug). The Stop hook uses it to keep the loop going.

Agent loop

  1. Baseline, Coverage Guard & 5-Step Number-Vetting Checklist (benchmark-checklist): before optimizing, check sh <plugin>/hooks/run.sh coverage-map <workspace> --json so any unmapped hot-path module is locked by a correctness test first; before trusting any baseline or post-patch number, verify all 5 checks: (1) Name the limiter (CPU, memory bandwidth, disk/network I/O, lock contention, or startup parse), (2) Measure warm vs. cold separately, (3) Repeat >= 5x and report median + spread (min/max or IQR) rather than a single run, (4) Rule out observer overhead (profiler/logger distortion), and (5) Label every number explicitly as measured | inferred | guess. Optionally dispatch runtime-qa to stress timeout/concurrency behavior under load.
  2. Optimize (hillclimb): iterate in small, reversible patches — strictly 1 hypothesis per commit/patch so wins and regressions are attributable. Load domain-playbooks.md when targeting web CWV, SQL queries, connection pools, or caching. Use the debugger or architect subagent for profiling analysis when useful.
  3. Evaluate: run the evaluator and related regression tests after each patch.
  4. Checkpoint every result by appending to checkpoints.jsonl (using newline-isolated appends via sh <plugin>/hooks/run.sh append-jsonl .omagy/goals/performance/<slug>/checkpoints.jsonl '<json>' or ensuring a leading newline if the file tail was torn): {"at":"<ISO>","status":"pass|fail|blocked","evidence":"<numbers, command, exit code>","patch":"<summary>"} Then update lastValidation in state.json and updated_at/iteration in the mode state. Apply "Neutral is a revert" (domain-playbooks.md): revert patches that regress or stay within run-to-run noise rather than accumulating complexity.
  5. Complete only when lastValidation.status == "pass" and the audit confirms no required work remains. Set state.json status:"complete" and write the mode state terminal (active:false, current_phase:"complete", completed_at).
  6. Blocked (e.g. a missing fixture or benchmark infra): checkpoint blocked, set the mode state to current_phase:"blocked", active:false, and ask the user.

Evaluation Integrity Audit (eval-integrity)

Before declaring a benchmark or evaluator result trustworthy, audit the evaluation setup across:

  1. 7 Evaluation Roles: map Claim, System under test, Dataset and split, Designer, Evaluator or judge, Scorer, and Subjects, and confirm an independent ground-truth signal exists.
  2. 8 Independence Failure Probes: check for Contamination (benchmark leakage), Invalid controls (unfair baseline flags/warmup), Circular judging (system judging its own output), Scorer-label coupling, Evaluator-designer coupling (tuning the evaluator to make the patch pass), Split/annotator dependence, Hypothesis priming, and Observer/demand effects.
  3. Verdict Line: record a single **Verdict: PASS | FAIL | INCONCLUSIVE** line in .omagy/goals/performance/<slug>/summary.md (and evalIntegrityVerdict in state.json if needed), which the HUD Overview tab surfaces on the benchmark card.

Domain Playbooks (Lazy-Loaded)

Consult domain-playbooks.md only for the subsystem under optimization:

  • Web / Frontend CWV: Core Web Vitals Field (CrUX p75) vs Lab (Lighthouse) Metric-Honesty Rule
  • SQL / Database Queries: EXPLAIN (ANALYZE, BUFFERS) 3-signal table and connection pool sizing math (instances * pool_max < max_connections - reserved)
  • Caching & Concurrency: viewer-keyed cache isolation + singleflight stampede coalescing and "Neutral is a revert"

Completion gate

A performance goal is incomplete unless state.json holds lastValidation.status: "pass" produced by the declared evaluator command, with the evidence recorded in checkpoints.jsonl and an eval-integrity **Verdict: PASS** in summary.md. Report baseline vs final numbers, the patches kept, the patches reverted, and the residual risks, and surface [oh-my-agy HUD](sidecar://oh-my-agy/hud/) once so the user can inspect the benchmark card in the Auxiliary Pane.

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.