protect

Arguments. [<counter or claim>]. e.g. /performance:protect the 4-to-1 spawn reduction

Purpose

Answers "what keeps this win from eroding?"

Performance wins decay in a codebase that keeps moving: nothing asserts the new cost, so the next change that adds it back passes every test. A checked-in counter ceiling, checked in CI, turns the win into a build failure the next regression has to answer.

Run it once, after /performance:verify reports MET on a counter. It proposes files; a human approves them. It never merges, and no model runs in CI: the check is a script and a number.

Read ${CLAUDE_PLUGIN_ROOT}/reference/techniques.md#g-protect-the-win for the technique entries this skill applies.

1. Choose the counter

• Counters only, never durations. A duration ceiling moves with runner load, fails at random, and teaches people to raise it. Ratchet the headline counter from the verify report.
• Measure it in the state CI will see. A counter behind a cache has a cold value and a warm value; a guard with a per-user cache can count 6 spawns cold and 1 warm. CI runners start cold, so a ceiling measured warm fails there. Pin the state in the command (unset or empty the cache location), and measure that.
• It must be deterministic. ratchet.py add measures twice and refuses a counter whose two runs disagree (${CLAUDE_PLUGIN_ROOT}/reference/harness-integrity.md rule 1). Fix what varies before ratcheting.

2. The ceilings file

Propose .performance/ratchets.json, created by python3 ${CLAUDE_PLUGIN_ROOT}/scripts/ratchet.py add --name <n> --field <f> --goal <g> --command <cmd> from the repository root:

{"counters": [{"name": "guard-spawns", "command": "<shell command>", "field": "spawns",
               "ceiling": 6, "goal": "<the verified goal this protects>"}]}

• command runs through the shell from the repository root and prints a <field>=<number> token.
• The command must exit non-zero when the subject fails. A subject that errors out early spends fewer spawns and passes any ceiling. spawn-census.sh exits 0 whatever the subject did and prints rc=<n>, so append | grep -F ' rc=0 '.
• The ceiling is the measured value, never a round number above it. Headroom is room for a regression.
• CI has no plugin installed, so the proposal vendors ratchet.py (one stdlib file) into the repository, for example .performance/ratchet.py, unless the repository already carries it.