twin-sweep
Skill24 starsChanged 2 days agoMITView on GitHub
TEMPORARY (2026-11). Changes how GoFastr bug hunts are run. (1) Twins: find places where one rule is written twice (Postgres vs SQLite, HTTP vs MCP vs Go API, SSR vs runtime JS, list vs get, JSON vs form vs multipart, memory vs DB store), then merge each pair into one implementation or pin it with a parity test. (2) Density: every hunt round records which packages it read and what it found, and the next round reads unread and changed packages first, while retired packages are skipped. Load it when planning, briefing, validating or fixing a bug hunt or bug bash, when writing a hunt LEDGER.md, or when asked about twins, parity drift, hunt coverage or bug density.
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
- primitives-sweepSkill
- review-gateSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 81
Only full reads count toward retiring a package.
- Distinctive: line 83
Write a row for a read that found nothing, too.
- Very specific: line 120
Plan from the table: Run density.sh on the hunt's base commit.
- Very specific: line 139
Close the round: Run density.sh shapes and put the round's line in the hunt's memory note: count, Majors, share of twin findings, packages …
- Very specific: line 160
Parity test: Use it only when the sites cannot share code (Go vs runtime.js, Postgres vs SQLite SQL).
- Very specific: line 214
Every package over 2,000 lines is RETIRED, or was read after its last churn.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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
Twin sweep and hunt density
Temporary skill. Delete it (and fold density.sh into scripts/ if it
earned its keep) once the exit criteria at the bottom are met.
Why it exists
Round 11 (PR #718) found 28 bugs. About 14 of them had the same shape: a rule held on one path and was missing on its twin. Examples:
- crud Get vs List query parsing (F2-02)
entity_formvsentity_listchecks (F1-02)- SSR stamp vs runtime paint (U2-02)
html.TextAreavsheadless.Textarea(U2-03)- the access observer vs the hook/event recover (U4-02)
The November bashes found the same thing ("about half of that corpus was parity drift", AGENTS.md). 16 of the 28 came from packages no recent round had read. So the count measures where a round looked more than how buggy the code is. This skill goes after both causes: twins become single implementations, and every hunt records what it read, so the next round can be planned from that record.
Where an open twin is recorded
In the repository, in the primitives registry: a twins entry on the
primitive that owns the code (primitives/**/primitive.yml, format in
primitives/README.md). An entry is a debt. It lists every site, says
in why what keeps them apart today, and is deleted when they become
one implementation. go run ./cmd/primitives lint prints how many are
left. The target is none whose why is work not yet done; an entry
whose sites cannot share code stays, pinned by a parity test.
Recording a twin there is what makes the next agent see it: the hook in
.claude/settings.json shows the entry to any session that changes one
of its sites, and the stop check asks every session about sibling paths
before it finishes. twins.md, below, stays as the hunt's own history
of families and what was decided; the registry holds what is still open.
Where the history lives
- State for this skill, outside git:
~/programming/gofastr-hunt-state/($HUNT_STATEoverrides it). It lives on the maintainer's machine on purpose: hunts run there, and the ledgers it is built from are not in the repo. Without it,density.shhas nothing to read.coverage.tsv: one row per package per round that read it.findings.tsv: one row per accepted or rejected finding.twins.md: the twin registry (families, sites, decision, PR).
- Past ledgers, in varying formats:
~/programming/gofastr-bug-bash-2026-10-27.md(619 findings, by slice)~/programming/gofastr-bug-hunt-2026-10-31-r4.md(rounds 4–6)~/programming/gofastr-bug-hunt-2026-11-01-r7.md~/programming/gofastr-bug-hunt-2026-11-02-r8.md(201 findings, 95 slices)~/programming/gofastr-bug-hunt-2026-11-{10-r9,12-r10,12-r11}/LEDGER.mdplusslice-*.txtpackage lists andreport-*.mdhunter text.
- Hunt threads on this Mac, through T3: search with
t3_thread_search "Bug hunt"and read them witht3_thread_read. The linked Windows machine has no GoFastr hunt threads (checked 2026-11-13). Claude Code cloud/web sessions are not reachable from here. - Memory notes
project_bug_hunt_r*andproject_bug_bash_2026_10_27hold the decisions and rejections. Don't re-raise a rejected item.
File formats
Tab-separated with a header row. Rows go in round order, oldest first.
coverage.tsv
round base pkg depth majors minors
r11 23fd7aac1 core-ui/store full 0 2pkgis a repo-relative directory,.for the root.depthtakes one of three values:full: the package and its callers were read end to end.partial: some files were read.fix-review: only a previous round's fix commits were read.
- Only
fullreads count toward retiring a package. baseis the commit the hunters read. Churn is measured from it.- Write a row for a read that found nothing, too. A clean read is the signal that retires a package.
findings.tsv
round id sev pkg shape family status
r11 F2-02 Minor framework/crud twin crud-query-parse fixedshapetakes one of four values:twin: the rule holds on one path and is missing on its twin.fix-sibling: an earlier fix missed a sibling input or path.docs: a doc describes behaviour that no longer holds.other
familynames the twin family intwins.md(-if none).statusis one offixed,rejectedorheld.
The density table
.claude/skills/twin-sweep/density.sh # every package, worst first
.claude/skills/twin-sweep/density.sh shapes # findings by round × shape
.claude/skills/twin-sweep/density.sh families # twin families by finding countStatus per package:
UNREAD: no read on record. Sorted by size, largest first.REREAD: read before, but the lines changed since that read's base exceedCHURN_LINES(default 300) or 20% of the package. Sorted by churn.OPEN: read, and not yet clean enough to retire.RETIRED: the last twofullreads found no Major, and the most recent one found at mostMINOR_MAX(default 2) Minors.
Hunts skip RETIRED packages, except in fix-review slices that read a
fix landing there.
Running a hunt round with this skill
- Plan from the table. Run
density.shon the hunt's base commit. Build slices fromUNREADandREREADfirst, in table order. Add one fix-review slice over the previous round's fix commits. Put the table excerpt in the brief, so hunters know why they got the package. - Brief the twin families. Paste
twins.md's open families into the hunter brief. When a hunter finds a gap on one path, it names the twin and checks that path too. - Validate into the files, not only the ledger. For every slice,
append one
coverage.tsvrow per package read, even when the read was clean. For every finding, append afindings.tsvrow with shape and family. Atwinfinding with no family starts a new family intwins.mdand atwinsentry in the registry, on the primitive that owns the sites. If the path has no primitive yet, add one (go run ./cmd/primitives for <path>says whether it does). - Fix with the registry open. A fixer touching a family's rule reads
that family's sites first:
go run ./cmd/primitives for <file>lists them, and the hook shows them unasked on the first edit. Then it merges the pair (see below) or fixes every site in the same commit and adds the site to the family's parity test. - Close the round. Run
density.sh shapesand put the round's line in the hunt's memory note: count, Majors, share of twin findings, packages retired.
The twin work (separate from hunts)
Work the families in twins.md by finding count, highest first
(density.sh families). For each family:
- List every site that enforces the rule. The ledger's "A vs B"
validator notes name the first two. Then grep for the others: the
same refusal message, the same
i18n.Phrase, the same helper name across dialect/transport files. Sweep by the invariant, not by a name ([[feedback_sweep_by_invariant_not_name]]). - Pick one, and record it in
twins.mdand in the registry:- Merge (preferred). One function, which every site calls. Delete
the copies in the same change, with no shim
([[feedback_no_legacy_no_deprecation]]). Delete the
twinsentry, add an invariant saying there is one implementation, and a decision naming the copy that was removed. The model isprimitives/crud/scope/primitive.yml(one-scope-gate). - Parity test. Use it only when the sites cannot share code (Go vs
runtime.js, Postgres vs SQLite SQL). One table of inputs runs through every site and the outcomes are compared. The model isframework/crud/readhook_parity_security_test.go(TestReadHookParityCrud). A new site joins by adding a case. Thetwinsentry stays, itswhynames the reason code cannot be shared, and an invariant names the parity test as its enforcer. - Intentional difference. The sites are not twins. Delete the entry and record a decision with the reason. Do not leave a comment at each site: the registry is where a reader finds it.
- Merge (preferred). One function, which every site calls. Delete
the copies in the same change, with no shim
([[feedback_no_legacy_no_deprecation]]). Delete the
- Prove the parity test. Break one site, watch the test fail, then put the site back (Hard rule 11). A parity test nobody has seen fail is unproven.
- Batch. 4–5 families per PR, one PR per round, never one PR per family ([[feedback_batch_prs_hard_rule]]).
Families to seed twins.md with (from rounds 10–11). Each one still
open also needs its twins entry; check first, since several were
merged in #719 and the two crud scope families were merged with the
registry itself:
- crud query parse: List, Get, include, fields, where, q, trashed (strict decode and repeated-key refusal)
- query-pair undecodable warning: entityui lists vs admin Audit and Jobs
- appspec block checks:
entity_formvsentity_listvsentity_detail, node vs catalog kinds - SSR vs runtime paint:
storevalueString vs signals.js,noderendervshtmlbuilders,html.TextAreavsheadless.Textarea - callback recover: hook, event, access observer, and any other
SetObserver/On*registry - scaffold name checks:
new handlervsnew route - i18n of generated packages: siteheader vs docpage
Who does what
- Hunters: GLM read-only, briefs as in rounds 9–11.
- Validation,
coverage.tsv/findings.tsvwrites, andtwins.md: the main loop. - The one-time backfill of rounds 8–11 into the TSVs, and twin-family fixes: Opus subagents, at most 2 at once ([[feedback_never_sonnet_agents]], [[feedback_claude_subagent_cap_two]]).
- Backfill depth: rounds 9–11 at finding level, since their ledgers are
tables. Round 8, rounds 4–7 and the 10-27 bash at slice level, with
depthset topartialunless the slice heading says the whole package was read.
Exit criteria (delete the skill when all hold)
twins.mdhas no family left open: each one is merged, pinned by a proven parity test, or recorded as intentional.- No
twinsentry is left whosewhyis work not yet done. Lint counts the entries and cannot judge awhy, so read each one thatgo run ./cmd/primitives lintstill counts: it must name a real reason code cannot be shared and a parity test that enforces it. - Every package over 2,000 lines is
RETIRED, or was read after its last churn. - Two consecutive rounds found no Major and fewer than 5 twin findings.
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.

