primitives-sweep
Skill24 starsChanged yesterdayMITView on GitHub
Move what a package's comments and prose claim into the registry (primitives/**/primitive.yml), then delete the comments. Load it when asked to sweep, strip or cut comments, to add a primitive, invariant or decision to the registry, to record why something was built a certain way, or to shrink AGENTS.md or an ARCHITECTURE.md into registry entries. Also load it before writing a comment longer than two lines in framework code, because the comment probably belongs in the registry instead.
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- framework/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- adversarial-testsSkill
- app-introspectSkill
- chaos-testSkill
- component-buildSkill
- eval-reportSkill
- gofastr-docsSkill
- gofastr-hostSkill
- gofastr-mcp-debugSkill
- gofastr-uiSkill
- log-debugSkill
- plain-wordsSkill
- review-gateSkill
- twin-sweepSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 34
Find the owner: Run go run ./cmd/primitives for <files>.
- Very specific: line 64
Reach for
judgelast: Use it alone only when no test or analyzer can state the rule, and write it as a yes/no question where yes means a … - Very specific: line 74
Two ways to do one job: When the sweep finds two internal paths for the same job, merge them (see the twin-sweep skill).
≈ “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
Primitives sweep
A comment that states a rule is not enforced and gets copied. The sweep
turns each such comment into a registry entry that names what fails when
the rule is broken, and only then deletes the comment. The format is
primitives/README.md. Read it first.
One sweep covers one package or one primitive. Keep it to one PR.
The evals behind this skill (evals/primitives/results/) found that
deleting a comment costs nothing where a test already enforces what it
says: agents found the rule in the test. So the sweep is fast for most
comments and slow only for the few that state a rule nothing enforces.
The order of work across packages is in primitives/PLAN.md.
What a sweep never deletes
- Directives:
//go:,//gofastr:allow(...)with its reason,//gofastr:test-reads,//gofastr:generated, build tags,// Output:in examples, licence headers. Leave these exactly as they are. - Doc comments on exported identifiers. These are kept but may be trimmed: cut one down to the contract (what it does, what it returns, when it errors) and move the history out.
- Comments in
_test.gofiles. A test says what it pins. Leave them. - Generated files. Leave them.
Steps
- Find the owner. Run
go run ./cmd/primitives for <files>. If a file has no owner, add a primitive first. Split by job, not by package, and nest it under the parent it is a part of. Sort every remaining comment into one of five kinds.
Kind Example What happens Rule "must match nothing, never everything" invariant Choice "position was the first attempt" decision Workaround "until X is fixed, do Y here" fix X, or open an issue and record a decision with revisit_ifNarration "loop over the rows" delete History "caught 2026-06 in PR #198" delete; the commit log has it - Write the invariant as a sentence that can be false. "Handles scope carefully" cannot be false. "A read-scope operator the renderer does not know matches no row" can.
Name the enforcer and prove it. Find the test, analyzer or contract rule that pins the invariant. Then break the code and run it. If nothing fails, the mapping is wrong or the rule is unenforced: write the test, watch it fail, fix the code back. A test name that merely sounds right is not an enforcer. Record each proof in the PR description as
mutation -> failing test.Spend this effort where it pays. A rule that already had a test, one you have now watched fail, can lose its comment without a registry entry. A rule that had no test gets the test and an entry. So does a rule a contributor could break while every nearby test still passes.
- Reach for
judgelast. Use it alone only when no test or analyzer can state the rule, and write it as a yes/no question where yes means a violation. Pair it with a test when the rule is "these two sites must change together". - Record a decision only where something lost. One sentence for
what was chosen, one
rejectedentry per alternative with the reason it lost, and arevisit_ifwhen the comment implies one. Link it to its invariant withupholds. - Two ways to do one job. When the sweep finds two internal paths
for the same job, merge them (see the
twin-sweepskill). If the merge is too large for this sweep, record atwinsentry whosewhysays what keeps them apart, and pin them with a parity test. The entry is a debt:primitives lintcounts the ones left, and the goal is none. - Delete the comments the entries replace. Where a symbol is named
in a registry entry, no pointer back is needed:
primitives for <file>finds it. - Check.
go run ./cmd/primitives lint,go run ./cmd/primitives gen,make test,make analyze.
Reporting
End with a table: comments removed by kind, invariants added, decisions added, mutations proven, and every rule left unenforced with the reason. An unenforced rule is a finding, not a footnote.
Moving prose out of AGENTS.md and the architecture documents
Same steps, with the paragraph as the comment. A hard rule becomes an
invariant on the primitive it governs, enforced by the analyzer or
contract rule that already checks it. A rule that governs files of
several primitives lives on one of them and lists the rest under
applies; never copy it. Delete the paragraph once
primitives for prints the rule on a file in every tree the rule
governs, each applies entry included; a tree it does not reach yet
keeps the paragraph. What stays in AGENTS.md
is how to find the registry and what no primitive can own.
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.

