agentleFS
DonaldMurilloDonaldMurillo/gofastr/.claude/skills/primitives-sweep/SKILL.md

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.

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
  1. Very specific:

    Find the owner: Run go run ./cmd/primitives for <files>.

    line 34
  2. Very specific:

    Reach for judge last: 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 …

    line 64
  3. Very specific:

    Two ways to do one job: When the sweep finds two internal paths for the same job, merge them (see the twin-sweep skill).

    line 74

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.go files. A test says what it pins. Leave them.
  • Generated files. Leave them.

Steps

  1. 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.
  2. Sort every remaining comment into one of five kinds.

    KindExampleWhat 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_if
    Narration"loop over the rows"delete
    History"caught 2026-06 in PR #198"delete; the commit log has it
  3. 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.
  4. 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.

  5. Reach for judge last. 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".
  6. Record a decision only where something lost. One sentence for what was chosen, one rejected entry per alternative with the reason it lost, and a revisit_if when the comment implies one. Link it to its invariant with upholds.
  7. Two ways to do one job. When the sweep finds two internal paths for the same job, merge them (see the twin-sweep skill). If the merge is too large for this sweep, record a twins entry whose why says what keeps them apart, and pin them with a parity test. The entry is a debt: primitives lint counts the ones left, and the goal is none.
  8. 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.
  9. 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.

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.