principle-respect-the-grain
Skill1 starsChanged 14 days agoMITView on GitHub
Apply before you join, filter, group, or aggregate a table, and before you trust a total. Name the grain (what one row means) of every table, and check key uniqueness and row counts before and after each step so fan-out and silent drops do not change the number.
In this repository50 other files it gives its agents.
- analyst-modeSkill
- architectSkill
- arenaSkill
- astack-helpSkill
- benchmark-checklistSkill
- blast-radiusSkill
- catch-upSkill
- correctSkill
- create-formal-verification-skillSkill
- figure-it-outSkill
- howSkill
- interrogateSkill
- in-your-own-wordsSkill
- maintain-formal-verification-skillSkill
- no-commentsSkill
- plain-wordsSkill
- principle-attack-the-premiseSkill
- principle-boundary-disciplineSkill
- principle-build-the-leverSkill
- principle-define-the-questionSkill
- principle-encode-lessons-in-structureSkill
- principle-experience-firstSkill
- principle-explain-the-numberSkill
- principle-fix-root-causesSkill
- principle-foundational-thinkingSkill
- principle-guard-the-context-windowSkill
- principle-laziness-protocolSkill
- principle-make-operations-idempotentSkill
- principle-minimize-reader-loadSkill
- principle-model-the-domainSkill
- principle-name-the-estimandSkill
- principle-never-block-on-the-humanSkill
- principle-prove-it-worksSkill
- principle-reproduce-from-clean-stateSkill
- principle-sequence-verifiable-unitsSkill
- principle-simulate-the-methodSkill
- principle-subtract-before-you-addSkill
- principle-test-behavior-not-implementationSkill
- recallSkill
- reflectSkill
- retail-analyticsSkill
- sharpenSkill
- show-me-your-workSkill
- statechartSkill
- swarmSkill
- tddSkill
- teachSkill
- technical-writingSkill
- unslopSkill
- whySkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
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
- Distinctive: line 8
Every table has a grain: what one row represents, such as one order, one customer per day, or one page view per session.
- Distinctive: line 12
Write the grain next to the load, for example "one row per order_id", and assert it with a uniqueness check on the key.
- Distinctive: line 16
After each filter or aggregation, compare the count with the count the definition predicts.
≈ “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.
Files
Respect the Grain
Every table has a grain: what one row represents, such as one order, one customer per day, or one page view per session. Name the grain before you use the table. Most wrong numbers in analysis come from ignoring it.
A join that fans out duplicates rows and inflates sums. An inner join that silently drops unmatched keys shrinks the base. A group-by at the wrong level averages averages. Each of these still returns a clean-looking table.
- Write the grain next to the load, for example "one row per order_id", and assert it with a uniqueness check on the key.
- Before and after each join, log row counts and key uniqueness on the side that must be unique. A left join from orders to a customer table with duplicate
customer_idrows multiplies every order. Passvalidate="m:1"(or"1:1") tojoinon the lookup side. The default isvalidate="m:m", which checks nothing. The streaming engine does not run the check, so for streaming runs add an explicit assertion on key uniqueness. - Count null keys on each side before every join. A Polars join never matches null keys by default (
nulls_equal=False, renamed fromjoin_nullsin 1.24). An inner join drops them without a trace, and a left join keeps them unmatched. Write the count withpl.col(key).is_null().sum(), and state the handling: kept unmatched, or excluded by design. - Make the join type explicit. Use
how="anti"to list the keys that did not match before you decide to drop them. - After each filter or aggregation, compare the count with the count the definition predicts. A filter that removes 40 percent of rows needs a reason you can state.
- Aggregate at the grain the question asks for. Sum the lowest-level rows, then roll up. Do not average per-segment averages unless the weights are equal.
- Compare the total against an independent figure at the same grain (see principle-explain-the-number).
You skipped this when a join changes the row count with no stated reason, or when a total is reported without row counts before and after.
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
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.

