agentleFS
Sign inStart free
hidenobunagaihidenobunagai/astack/skills/principle-explain-the-number/SKILL.md

principle-explain-the-number

Skill1 starsChanged 13 days agoMITView on GitHub

Apply before you trust, report, or act on a number you computed: a metric value, a delta between periods or segments, a model score, a row count, a runtime. Find what drives it, and rule out that it measured something other than what you think.

29 other projects use a version of this, 27 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use ketchup-video, ketchup and 5 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.
  • tristanphvnSkill

    ketchup-video

    Catch the user up like /keel:ketchup, with a short silent video of slides for what happened and the waiting calls as text under it. Use for /keel:ketchup-video.

    Also in 11 projects that use this

  • instructureSkill

    ketchup

    Rebuild context after /clear by analyzing uncommitted changes across Canvas LMS and all plugin repositories

    Also in 18 projects that use this

  • ElyzeSolutionsSkill

    control-cli

    Build or adapt a local harness to drive, inspect, and profile an interactive CLI or TUI without external services. Use for CLI UX checks, startup regressions, memory leaks, hangs, prompt flows, or terminal demos.

    Also in 3 projects that use this

  • gandolhSkill

    thermo-nuclear-review

    Comprehensive security and correctness audit of a branch's changes. Use for thermo nuclear, thermonuclear, or deep review requests, or branch/PR diff audits focused on bugs, breaking changes, security issues, devex regressions, and feature-gate leaks.

    Also in 3 projects that use this

  • ElyzeSolutionsSkill

    control-ui

    Build or adapt a local browser/CDP harness to drive and inspect a web, IDE, or Electron UI. Use for local UI verification, screenshots, accessibility snapshots, perf profiles, visual diffs, or reproducing UI bugs.

    Also in 3 projects that use this

  • SentrySkill

    deslop

    Strip AI-generated noise from the diff before pushing — extra comments a human wouldn't write, defensive try/catch in trusted code paths, casts to any, inline imports in Python, and other style inconsistencies with the surrounding file. Use this immediately before commit so the diff stays clean.

    Also in 5 projects that use this

The file

We split this skill into the rules it gives an agent

1 rule. 1 is common, 0 are distinctive, and 0 are very specific to this project.

  • 1

    Common

    Most of the 28 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Common:

    Keep the evidence with the number: Put the query or code, the row counts, the spread, and the main driver in the notes or a linked artifact.

    line 18

“Common” is measured: kept by at least 6 in 10 of the 28 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

Explain the Number

  • Ask "why this value and not double or half?" Name what drives the result: which segment, which period, which rows, which filter. Get it from a breakdown that ran, yours on synthetic data or the human's on real data, not from reading the code. If you cannot say which part of the data produces most of the number, 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 in data work:
    • Join fan-out or dropped rows. Compare row counts and key uniqueness before and after each join (principle-respect-the-grain).
    • Nulls, sentinels (0, -1, "", 1970-01-01), and duplicates silently included or excluded.
    • A filter, date boundary, or timezone that cuts the window differently than you think.
    • Survivorship, a changed definition, or a changed upstream source between the two periods.
    • Small samples and noise. A delta inside the normal spread is not a finding.
    • Mix effect. A shift in segment shares can move the total while every segment rate stays flat. This is not Simpson's paradox.
    • Simpson's paradox. The aggregate trend has the opposite sign from every segment trend. Test for it by comparing the sign of each segment's change with the sign of the total change.
  • Reconcile against an independent source. Tie the total to a number someone else owns (a dashboard, a finance report, a raw count from the source table). Say which one and by how much they differ.
  • Keep the evidence with the number. Put the query or code, the row counts, the spread, and the main driver in the notes or a linked artifact.

For a runtime or performance number, run the full procedure with the benchmark-checklist skill.

You skipped this when a reported number has no row count, no comparison baseline, no named driver, or no reconciliation.

Distinct from principle-prove-it-works, which checks that an output is real.

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.

Check your setup, free