Skip to content

mrlightspeed/untangle

v0.1.0

Map code wiring and refactor material knots with recoverable checkpoints and verified before/after evidence.

Untangle

License: MIT Python: 3.13 or newer CI: Bun only Latest GitHub release GitHub stars Skills.sh install count Sponsor Untangle

Untangle helps coding agents untangle spaghetti code while preserving the program's behavior. It maps the files behind a feature and records each accepted knot with source evidence, its concrete impact, and a proposed correction.

Install

With Node.js and npm installed, run this in your project's terminal.

npx skills@latest add MrLightspeed/untangle

Choose your agent if prompted. The installer uses that agent's project skills directory. Untangle uses Git and needs Python 3.13 or newer to render maps. See the installation guide for Bun, native installers, and ways to pin a release.

Try Untangle

Open your agent in the same project and ask for a read-only audit.

Use Untangle to map this repository in read-only mode.

Expect an HTML wiring map (untangle.html) and a ranked list of knots with source locations.

Before and after

Checkout wiring before and after. Price lookup and pending orders each go from three handoffs through helper files to one direct connection. Storage now sends order records to reconciliation.

As an example, Untangle traced two checkout paths through the bundled source. Quotes now call the catalog directly. Storage decodes rows before passing order records to reconciliation. The same behavior tests pass in both snapshots. See the worked checkout example for the source and tests or open the full wiring map.

Refactor with checkpoints

When you're ready to change code, ask your agent to refactor with checks and recoverable checkpoints.

Use Untangle to map and untangle this repository. Rank the knots by their
impact, preserve behavior, and verify each fix with the project's tests and
build, or documented equivalents. Save a recoverable checkpoint before each
change. Show the actual before/after wiring and explain which paths and
responsibilities changed. Keep all work on a local branch.

Patterns Untangle addresses

Every accepted knot needs source locations, an observed consequence, a proposed correction, and checks that can distinguish preserved behavior from a regression. The table covers all six knot categories and the diagnostic clues, techniques, and working method described in the skill's refactoring reference.

PatternRoleWhat to investigate or applySupporting source
Harmful dependency cyclesKnot categoryA directed module dependency loop prevents useful independent testing, initialization, or change. Confirm the actual chain and consequence; a cycle alone is insufficient.Fowler, Reducing Coupling.
Mixed or scattered responsibilitiesKnot categoryDistinguish one module changing for unrelated reasons from one coherent change requiring edits across several owners. Preserve intentional orchestration.Fowler and Beck, Divergent Change and Shotgun Surgery.
Leaky abstractionsKnot categoryCallers depend on another owner's representation, state or policy. Move that knowledge behind its actual contract while preserving observable behavior.Parnas, module decomposition criteria, and Fowler, Module Dependencies.
Drifted duplicationKnot categoryCopies of one domain rule disagree or require manual synchronization. Confirm shared meaning before consolidating; similar syntax alone is insufficient.Google Testing Blog, Do not DRY prematurely.
Stale workaroundsKnot categoryVerify the original compatibility condition no longer applies before removing a fallback. Age or absence from a static search does not prove obsolescence.Untangle evidence rules and Fowler, Remove Dead Code.
Empty wrappersKnot categoryRemove indirection only after checking APIs, test seams, extension points, permissions, retry policy, resource ownership and telemetry. A short function can still own a useful contract.Untangle evidence rules and Fowler, Inline Function.
Hidden state and call-order requirementsDiagnostic clueIdentify undocumented initialization, shared mutable state and required sequences. Make ownership and lifecycle explicit; verify order, repeated use, failure and cleanup.Seemann, Temporal Coupling, and Parnas, module decomposition criteria.
Tangled branches and mode flagsDiagnostic clueRepeated switches obscure distinct operations or business decisions. Consider named operations, decomposed conditions or guard clauses while preserving evaluation and effect order.Fowler, Flag Argument and Guard Clauses.
Business decisions mixed with I/ODiagnostic clueA rule is difficult to test without a UI, database, filesystem or network boundary. Separate testable decisions from the code that performs effects when there is a demonstrated benefit.Feathers, The Humble Dialog Box, and Bernhardt, Functional Core, Imperative Shell.
Split PhaseRefactoring techniqueSeparate stages with a clear intermediate value so each stage can be understood and tested independently.Fowler, Split Phase.
Maintenance hotspotsPrioritization techniqueUse relevant change frequency and repeated changes across files to choose investigation targets. History supplements consequence and reach; it does not prove a defect.Tornhill, prioritizing technical debt.
Parallel ChangeMigration techniqueFor an authorized contract migration, support both interfaces, migrate all supported consumers, then remove the old path after verification.Sato, Parallel Change.
Branch by AbstractionMigration techniqueReplace a supplier behind a small interface in verified steps, then retire the temporary adapter after its consumers have moved.Fowler, Branch by Abstraction.
Test seamsVerification techniqueIntroduce the smallest boundary needed to redirect an external effect or observe behavior. Preserve the normal execution owner.Fowler, Legacy Seam.
Characterization testsVerification techniqueRecord what the affected code actually does, including errors and side effects. Investigate surprising behavior before endorsing it as the intended contract.Feathers, Characterization Testing.
Incremental refactoringWorking methodMake one cohesive structural change, verify it and preserve a rollback point before continuing. Keep deliberate feature or behavior changes separately scoped.Fowler, Refactoring, and Google, Small CLs.

The six category names and their proof requirements are Untangle's synthesis. Diagnostic clues do not create extra category IDs, and a technique is not itself a finding. The sources explain the underlying practices; they do not prescribe Untangle's map format or Git workflow. See refactoring decisions for corrections, proof, and reasons to leave code alone.

Public API or persistent-data changes need their own authority and proof. The rendered map shows which files each feature touches; a dependency-cycle finding needs an actual directed import or call chain. Crossed feature wires and a simpler diagram cannot establish a defect or preserved behavior.

What you get

ArtifactPurpose
untangle.htmlFull interactive wiring map, numbered knots, and matched source explanations.
comparison.svgA source route that became direct, when present, plus full before/after wiring and numbered knots.
map.jsonValidated source locations, coverage limits, knots, and verification notes used by the renderer.
comparison.pngOptional browser capture of the SVG comparison.

The renderer checks the manifest's structure and references. It does not inspect a repository or prove the agent's findings. Coverage limits and unresolved paths stay visible in the map.

From a checkout of this repository, generate the full example map.

python skills/untangle/scripts/render_map.py examples/evidence.json --output-dir work/example

Validate evidence or preview the output paths without writing files:

python skills/untangle/scripts/render_map.py examples/evidence.json --check --json
python skills/untangle/scripts/render_map.py examples/evidence.json --output-dir work/example-preview --dry-run --json

Use --help for examples and exit codes, or --schema for the machine-readable result contract. See the map contract for overwrite safeguards and error categories.

Compatibility

The workflow can be used with TypeScript, Python, and other languages your agent can inspect and your project can verify. The renderer reads an evidence manifest; it does not parse source code or refactor files itself.

Package and renderer checks run on Windows and Linux in CI. Local Skills CLI installation checks covered Codex, Claude Code, Cursor, and GitHub Copilot. Codex completed a read-only audit, and a separate agent verified a refactor and rollback on a scoped Python project. Copilot produced an audit manifest. See installation and compatibility for the scope of these checks.

Contribute

Use issues for bug reports, help, and focused proposals. Start with an issue before opening a pull request. Share a fork or commit link there if you already have a patch. The maintainer invites pull requests for agreed changes and may import a patch with attribution. See contributing for the review process.

For installation and usage questions, use support. Report vulnerabilities through the security policy. Follow the code of conduct.

Support the project

Sponsor Untangle on GitHub. The page offers one-time and monthly contributions.

Develop

To change this repository, use the tool versions declared in package.json and install from the committed lockfile:

bun install --frozen-lockfile --ignore-scripts
bun run check

npm contributors can use:

npm ci --ignore-scripts
npm run check

Both workflows use the same project-local Bun binary for formatting and JavaScript linting. CI uses Bun only. See contributing for formatting, tests, and the review process, and the writing standard for documentation conventions. These tools are not part of the installed skill.

License

Untangle is available under the MIT License. The installable skill includes its own copy of the license.