untangle
Skill11 starsChanged 5 days agoMITView on GitHub
This repo's method for untangling code so a change lands in one place and agents break less without noticing. Use when splitting a busy file, surveying an area for hidden links or special cases, turning flags, refs and timers that encode a mode into one named state, or planning an untangle PR. Small Lane A PRs, bugs first, Brad's yes on clinical and workflow items. Adapted from caldoai's untangle-codebase skill (MIT).
9 other projects use a version of this.
Adopted by
Most recently taken up by
- ryanportfolio/HarnessFirmware.comtheir own version, first seen Nov 16, 2026
- ryanportfolio/Corewise.Academytheir own version, first seen Nov 16, 2026
- ryanportfolio/STKtheir own version, first seen Nov 16, 2026
- ryanportfolio/savetokenstheir own version, first seen Nov 16, 2026
- ryanportfolio/winuse-mcptheir own version, first seen Nov 16, 2026
- Come-In-Labs/agent-skillstheir own version, first seen Nov 15, 2026
Other versions9 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 9
- Come-In-Labs/agent-skills★ 2same name
- ryanportfolio/winuse-mcp★ 2same name
- ryanportfolio/Corewise.Academy★ 1same name
- ryanportfolio/Harness-Firmware★ 1same name
- ryanportfolio/savetokens★ 1same name
- ryanportfolio/STK★ 1same name
- luisgui1757/sentinel★ 0same name
- Pesty-Marketing/agent-skills★ 0same name
- ryanportfolio/HarnessFirmware.com★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository4 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ios/CLAUDE.mdCLAUDE.md
- codex-reviewSkill
- design-reviewSkill
The file
We split this skill into the rules it gives an agent
6 rules. 0 are common, 6 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 9 edited versions we read keep these.
6
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
- Distinctive: line 14
Should these pieces change together?
- Distinctive: line 37
No bulk comment deletion.
- Distinctive: line 48
Redesign (required): Before any per-lead PR, ask: what one fix sits behind several of these leads?
- Distinctive: line 54
Pin before a move: Before moving code, add tests that pin what the caller sees today.
- Distinctive: line 62
Before you move a literal, find who reads the source as text.
- Distinctive: line 81
Test it with a table: each state x event row names the state that follows.
“Common” is measured: kept by at least 6 in 10 of the 9 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.
Files
Untangle
Adapted from the untangle-codebase skill in github.com/caldoai/skills (MIT, copyright 2026 Maze). We kept its one question and its three kinds of error. We replaced its one-pass, whole-codebase refactor with Brad's terms: small PRs, one area at a time.
The one question
Should these pieces change together? Every tangle answers it wrongly in one of three ways.
- Hidden links. Pieces must change together, and nothing shows it: copied logic or values, a module that reads state another module sets, a feature scattered across folders, a call order callers must just know.
- Needless links. Pieces are tied, yet change for different reasons: callers that reach into internals, stable code importing volatile code, a general function with a parameter only one caller understands, a shallow module whose interface moves with its insides.
- Surplus. Pieces with no reason of their own to change: pass-through wrappers, config for things that never vary, dead code.
Special cases are the best clue. An if for one value, a parameter for one
caller, a swallowed error, a retry or sleep, a skipped test: each is a
requirement the design never planned for. Read them to learn what the system
needs, then fix the design so most of them go.
Brad's terms (these override the source skill)
- Small Lane A PRs, one per fix. Each cites a US-xx AC and lands a test that failed first (CLAUDE.md, Development Pathway).
- Order: bugs first, then scripted moves of the busy files, then quiet sections.
- No bulk comment deletion.
- A test is removed only from a list Brad approved.
- Brad's yes first on clinical items and on workflow changes.
- Announce a section lock in the agent channel (docs/agent-channel.md) before work starts there. No repo-wide freeze.
- Low-risk PRs merge in batches of 8-10. High-risk ones merge one at a time.
Per area: the steps
- Survey (read-only). Change nothing. List the implicit states (below), the special cases, and every hidden or needless link, each with file:line.
- Redesign (required). Before any per-lead PR, ask: what one fix sits behind several of these leads? It often looks nothing like them. Design as if today's requirements were known from the start. Check each fix: what changes together ends up together, nothing else is tied, and everything depends on what changes less.
- Bugs first. Each bug lead is its own Lane A PR: AC, failing test, fix.
- Pin before a move. Before moving code, add tests that pin what the caller sees today. They must fail if the moved code is broken or dropped. A converted check must also pin where the value must not apply. When a test moves to a better route (CSS read through the cascade, say), it is easy to keep the positive case and drop the negative. Reviewers caught this twice (PRs 1170, 1179). Assert at a width, state or element where the value must be absent too.
- Move. One move per PR, with its pins kept and green.
Before you move a literal, find who reads the source as text. A build
step, a guard test or a script may match a string where it is spelled,
not where it is used, so naming it once can silently unhook that reader.
In PR 1201 the dev build rewrote the server URL in source; the new
constant no longer matched, so localhost would have called production.
CI caught it, two reviews did not. Grep
tools/,scripts/, the vite configs and the tests for the literal first.
Implicit state machines
A flow with modes (saving, reading, sending, reviewing) often holds its mode in
scattered pieces: an isX boolean, a ref, a timer. They drift apart, and the
drift is the bug. Make them one discriminated union that carries its own data:
type Glow = { phase: 'still' } | { phase: 'glowing'; ids: Set<string> } | { phase: 'fading'; ids: Set<string> };- Change it only through a pure
transition(state, event). - Test it with a table: each state x event row names the state that follows.
- A transition table that needs events in a set order has a hidden link. If
A reaches C only when event x comes before y, the order is an unwritten
rule. Carry the fact on one event (
saved{attempt}, notsaveWrittenthensaved), so any order is safe (PR 1181). - Warranted where async work races: upload, chat send, saves, erase.
- Not warranted for plain view state: a tab, a toggle.
- Synchronous claim refs stay. A ref set in the same turn as a click, so a second press sees the claim before React re-renders, is not a mode.
- Convert one machine per PR, with its pins kept.
Examples in this repo:
widget-src/src/hooks/useHighlights.ts: theGlowunion (settling, still, held, glowing, fading), data and baseline inside each phase, changed only by its exportedtransition; the hook sends events and runs the timers the phase asks for.useHighlights.test.tsxhas the table (US-07 AC3).widget-src/src/lib/remote-replay.ts: one named state (loading | loading-held | idle | held), each event a method;remote-replay.test.tsdrives it through its states and events (US-34 AC4).widget-src/src/hooks/useErase.ts: runs on the erase machine (widget-src/src/lib/erase-machine.ts, fix 4): oneEraseStateunion (loading | idle | erasing, with the erase shown and heard), a puretransitionwith a table test, and effects run through doors. Theerasingboolean anderasingNowref are gone.
None of these yet has a separate pure transition function. The first PR that
writes one sets the pattern; keep it small.
Composition
Hooks talk to each other: one hook's event drives another's transition. Survey that protocol too. Write it as a table of events x machines (who sends, who reacts, in what order) and test the pairs that can race.
Split by what changes together
Split a file by what changes together, never by line count alone. A feature's files belong together by domain. A folder move is one pure-move PR per domain, with Brad's yes first; this skill prescribes no layout.
Empty slots: a slot that may be empty returns null, never an element that
renders nothing. An element is truthy even when its component renders null, so
a parent that draws a section for any truthy slot draws an empty one
(docs/gotchas.md, 2026-11-09).
When an area is done
- Few special cases left. The count is the best gauge of progress.
- A typical change lands in one place.
- Imports point from volatile to stable code, never the reverse.
- Git co-change agrees: files that change together in
git logsit together. - Behaviour is unchanged apart from the bugs fixed, checked by the pins.
Line counts are a vital sign, not the goal (CLAUDE.md, Code entropy).
node tools/untangle-measures.mjs <files or folders> counts what a regex
can: size, mode flags (refs, boolean state, timers), special cases,
co-change and fan-in/out. It cannot see a mode kept as a string, and the
rest (a typical change lands in one place, import direction, unchanged
behaviour) are still judged by reading and by the tests. Run it on the area before the
first PR and after the last, with the same --since both times, or the date
the area's work started. Add --json to compare runs. Put both sets of
numbers in the PR body. They are trend numbers from regexes, not verdicts.
Decision log
The log lives in docs/untangle/, the ledger every untangle PR updates, one file per lead
(its README says how). Write each fix above the
problems it solves, so a reader sees why it exists. The shape (names made up):
- One send state carries the message it sends, so the flag and the timer go.
- `Composer.tsx:40` sets `isSending` and a ref; they disagree after a retry.
- `Thread.tsx:88` waits 200 ms for the flag to clear.The repo is public. No unfixed security lead goes in the log; report it to the orchestrator instead.
Tips
- Survey with a skeleton: function signatures only, so an area fits in context.
- Script an import graph and rerun it after each move.
git log --name-onlyshows how often files change and what changes with them.
Licence of the adapted source
The untangle-codebase skill (github.com/caldoai/skills) is used under this licence:
MIT License
Copyright (c) 2026 Maze
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.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.

