principle-explain-the-number — Claude Code skill: what it does
A skill for the moment before you trust a measured number: name what caps it, then rule out that the test measured something other than your work.
npx skills add backnotprop/pstack --skill principle-explain-the-number -a claude-codeWhat principle-explain-the-number does
Reach for this before a speedup, a regression, a throughput figure, a latency or an eval result goes anywhere near a report. The skill asks why the result is not twice as good. The answer has to be a specific resource or code path — a core, a lock, the disk, the network, the load generator itself — pulled from a profile or from system counters taken during the run and mapped back to source. A guess from reading the code is not a limiter.
Then it makes you list what else the number could be measuring and knock each item out with evidence: errors, skipped or cached work, code that never ran, one side left on default settings, noise, a piece too small to matter end to end. Evidence travels with the number. Run count, spread and the named limiter go in the notes or a linked artifact.
The SKILL.md itself is short and points at neighbouring skills: benchmark-checklist for performance runs, principle-prove-it-works for whether an output is real. Its frontmatter carries disable-model-invocation: true, so the agent will not pick it up on its own — you have to ask for it by name. Worth deciding up front when you want it in the loop.
What it helps with
- explain what caps a speedup before quoting it
- rule out a benchmark that measured cache hits instead of work
- separate a real regression from run-to-run noise
- attach run count, spread and limiter to the number
- catch a run where the changed code never executed
Example prompts for the agent
- Apply
principle-explain-the-numberto yesterday's benchmark: what caps it, and what else could that test have measured? - Before I write the speedup into the report, run the
principle-explain-the-numberskill and show the spread with the profile. - Is that regression noise or a real drop? Work it through
principle-explain-the-number.
How to install principle-explain-the-number
1Skills CLI (Vercel)
npx skills add backnotprop/pstack --skill principle-explain-the-number -a claude-code2Manually: put the files in place
~/.claude/skills/principle-explain-the-number/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/principle-explain-the-number/
1Skills CLI (Vercel)
npx skills add backnotprop/pstack --skill principle-explain-the-number -a codex2Manually: put the files in place
.agents/skills/principle-explain-the-number/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add backnotprop/pstack --skill principle-explain-the-number -a cursor2Manually: put the files in place
.cursor/skills/principle-explain-the-number/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install backnotprop/pstack principle-explain-the-number2Manually: put the files in place
.github/skills/principle-explain-the-number/SKILL.md1Skills CLI (Vercel)
npx skills add backnotprop/pstack --skill principle-explain-the-number -a gemini-cli2Platform CLI
gemini skills install https://github.com/backnotprop/pstack --path skills/principle-explain-the-numberManually: put the files in place
.devin/skills/principle-explain-the-number/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add backnotprop/pstack --skill principle-explain-the-number -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about principle-explain-the-number
How to install principle-explain-the-number in Claude Code?
Run npx skills add backnotprop/pstack --skill principle-explain-the-number -a claude-code, then confirm the file landed at ~/.claude/skills/principle-explain-the-number/SKILL.md.
What does principle-explain-the-number do?
It forces an explanation of a measured number: the resource that bounds it, plus the other things it might have measured, each ruled out with evidence. Run count, spread and limiter stay with the number.
Why doesn't the skill trigger on its own?
Its frontmatter sets disable-model-invocation: true, so the agent leaves it alone until you name it in a request.
Source text
SKILL.md · MIT
--- name: principle-explain-the-number description: "Apply before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result. Find what limits it, and rule out that it measured something other than the work you think." disable-model-invocation: true --- # Explain the Number - **Ask "why not double?"** Name the resource or code path that bounds the result, such as a core, a lock, the disk, the network, or the load generator itself. Get it from a profile or from system counters taken during a run, then map it to source. A guess from reading the code is not a limiter. If you cannot say why the number is not twice as good, you do not know what you measured. - **List what else the number could be measuring, and rule out each one with evidence.** The usual suspects are errors, skipped or cached work, code that never ran, an untuned side (one left on default settings), noise, and a piece too small to matter end to end. - **Keep the evidence with the number.** Put the run count, the spread, and the limiter in the notes or a linked artifact. For a performance number, run the full procedure with the [benchmark-checklist](../benchmark-checklist/SKILL.md) skill. For an eval result, ask the same of the trials: did every run do the task, does the gap hold across trials and models, and does the scenario matter. You skipped this when the evidence behind a number has no run count, no spread, or no named limiter, or when the time saved is larger than the time the changed piece took. Distinct from [Prove It Works](../principle-prove-it-works/SKILL.md), which checks that an output is real.
© backnotprop · MIT · backnotprop/pstack
