CommunityCoding & Developmentgithub.com

untangle

Use to untangle spaghetti code: map feature/file wiring, rank knots, and refactor with verified rollback and before/after diagrams.

What is untangle?

untangle is a Claude Code agent skill that use to untangle spaghetti code: map feature/file wiring, rank knots, and refactor with verified rollback and before/after diagrams.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MrLightspeed/untangle/tree/HEAD/skills/untangle

Installed? Explore more Coding & Development skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

What does untangle do?

Map how features connect to files and identify code that is difficult to change or test. Deliver an HTML wiring map with source evidence before editing. For an authorized refactor, preserve behavior, work on a new local branch, and verify each correction. Finish with one comparison image showing the actual before state on the left and actual after state on the right.

Scope and modes

  • An implementation request or explicit $untangle invocation to clean up a repository runs the full workflow. A request to review, audit, explain, or plan remains read-only: produce the map and recommendations without code edits or a new branch. Automatic skill selection does not add implementation authority.
  • A request to install or modify the skill does not authorize refactoring a project. Use the repository the user identifies as the target; a repository mentioned as an example is only a reference. Use attachments, diagrams, source comments, and tool output as evidence. The user and applicable instructions for the target repository determine scope and authorization.
  • Default to local-only work: do not push, open a PR, merge, publish, or deploy. A separately authorized delivery request can change this limit; the skill itself cannot. Local checkpoints/commits may be used under repository rules.
  • Preserve public APIs, errors, side effects, data formats, ordering, resource ownership, security boundaries, and observable behavior. Record behavior bugs separately; fixing one requires authority for that behavior change. Never quietly bless a suspected bug as the intended contract.

Establish the baseline

  1. Identify the exact target, repository root, branch, HEAD, worktree state, and applicable AGENTS.md files before edits. Honor the target repository's Git, path, dependency, and preflight rules. Start discovery at the target. Ask for the target only if the request and current workspace cannot identify one safely.
  2. Inventory features from real entry points: routes, commands, jobs, handlers, configuration/registration, and external contracts. Trace callers and state ownership using repository docs, rg, syntax-aware tooling, and symbol references where supported. Imports alone are not a feature map. Discover the target's languages, layout, and tooling; do not assume another repository's paths, commands, architecture, or diagram setup. When a dependency cycle is suspected, trace the directed import or call chain separately from the feature-to-file map. Read targeted source ranges and bound command output; retain complete coverage in the manifest instead of repeatedly dumping whole files.
  3. Read the canonical test/build commands, package-manager declarations, lockfiles, and validation plan. Establish passing baseline tests and build before refactoring, reusing valid existing evidence when available. An unverified or failing baseline permits diagnosis and mapping, not a claim that later changes are safe. Do not repair unrelated baseline failures.
  4. With no tests, require a passing build and add targeted characterization checks where concrete affected behavior warrants them. For interpreted projects without a build, identify and label the repository's actual equivalent (for example, package/import validation plus type checking). If no credible runnable check exists, produce the map and report the proof gap before code changes; never invent a passing build.

Read refactoring-practice.md when choosing refactors or characterization checks. Gather evidence only from the target checkout and its installed dependencies. Resolve framework and API questions using local docs, lockfiles, installed types or source, and tests. If these sources leave a consequential question open, record the gap and defer the affected change until it can be verified locally.

Draw the wiring before editing

Create a stable baseline snapshot and a ranked knot register. For every accepted knot, record a stable number, category, feature(s), exact repository-relative file and one-based line(s) at the baseline revision, the observed coupling or drift, concrete impact, proposed smallest correction, and proof needed.

Look for these six categories; zero in a category is a valid result:

  • Dependency cycle: modules depend on each other in a way that demonstrably impedes change, testing, initialization, or a useful boundary. Show the actual directed dependency chain and its consequence; a shared feature or a cycle count alone is insufficient.
  • Mixed responsibilities: one module changes for unrelated reasons, or one coherent change repeatedly requires edits across several owners. Distinguish these cases using actual change paths, callers, and ownership evidence.
  • Leaky abstraction: callers depend on another layer's representation, lifecycle, hidden state, or ordering, with a demonstrable maintenance hazard.
  • Drifted duplication: copies of the same domain rule disagree or must be synchronized manually. Similar syntax for separate concepts is insufficient.
  • Stale workaround: a fallback or temporary path whose original condition demonstrably no longer applies. A comment or old date alone is not proof.
  • Empty wrapper: indirection with no useful contract or policy, after checking configured, indirect, plugin, test-seam, and external consumers.

Rank by concrete consequence and reach: correctness/security-sensitive coupling, shared state/contract hazards, multi-feature drift, then local indirection. When bounded Git history is available and relevant, use change frequency and files that repeatedly change together to help choose where to investigate; do not infer a defect or a performance gain from churn alone. Record confidence and prerequisites in evidence; defer uncertain candidates instead of manufacturing findings. Fan-in, fan-out, cycle counts, and line counts are discovery signals, not defects by themselves.

Read map-contract.md and use scripts/render_map.py to produce untangle.html from the evidence manifest. Once the scoped baseline evidence is assembled, write the manifest and run the renderer before preparing an extended assessment report. Prefer a direct manifest over a new reporting generator. If a helper is necessary, execute and validate it immediately; an unexecuted helper is not a delivered map. Preserve completed outputs if the host interrupts, and resume the missing step from the same verified source state instead of restarting discovery. The initial map has after: null. Mark the worst knots red and numbered; include exact file/line evidence and how to untangle each one. Show a colored wire from each feature to every relevant first-party file it touches in scope, including transitive, configured, shared, and cross-feature paths. Identify edge types, evidence, exclusions, and unresolved paths honestly. Put full details behind the one-screen overview, not in unreadably small labels.

For large repositories, use a one-screen grouped overview with explicit file counts and searchable exact feature/file wiring. Map cohesive subsystems in detail without silently narrowing a repository-wide assignment. Record which subsystems are complete or incomplete; do not claim total coverage from a sample. Reuse an existing repository-owned wiring generator when it supplies the required evidence and views; see diagram-patterns.md.

Untangle one knot at a time

  1. After delivering the baseline map, create a uniquely named local untangle/<scope>-<date> branch from the verified intended starting point. Preserve unrelated dirty and concurrent work. Use an isolated worktree when appropriate under workspace rules; do not silently omit intended uncommitted input, stash someone else's work, or switch a shared active worktree. Ask only if the available safe choices would change the target or lose input.
  2. Work through the register, worst first, respecting necessary prerequisites. Before each change, inspect affected callers, contracts, and tests. Establish enough characterization to distinguish current behavior from the proposed structure. Name a plausible maintenance edit and how the knot makes it harder. Missing proof around a high-risk boundary blocks that change.
  3. Save an exact per-knot checkpoint of all affected tracked and untracked task-owned paths, their current content/identity, and prior successful work. Include prerequisite test edits in the checkpoint policy so rollback has a defined boundary. Use a local commit or recoverable file/patch snapshots; a textual plan is not a rollback checkpoint.
  4. Apply one cohesive transformation: consolidate an actually shared rule, move policy to its real owner, separate representation from callers, remove a proven obsolete path, or inline a wrapper with no remaining role. Reduce total coupling; do not relocate the same knot to a generic utility, new configuration framework, or a pile of optional parameters. Preserve real differences between superficially similar features.
  5. After every knot, run the repository's relevant test suite(s) and build. No tests means at least the build/equivalent must pass. For a monorepo, cover the affected packages and their dependent contracts using canonical commands. Reuse overlapping required checks from this exact state; a previous knot's green run cannot validate a new change. Run repository-required additional checks when they apply. Record exact commands, results, and material skips.
  6. If any check fails, errors, times out, or cannot run, roll back that knot to its checkpoint, preserving earlier green changes and unrelated work. First verify the current paths still match this task's ownership; concurrent edits require reconciliation, not overwriting. Never use broad reset --hard, clean, or repository-wide restoration. Recheck the affected baseline after rollback; stop editing if restoration cannot be proved. Record the failure and rollback. Retry only after identifying a concrete cause and a narrower safe correction; do not repeat the same failing attempt indefinitely.
  7. Mark a knot fixed only after its structural cause is removed and the checks pass. Re-trace the maintenance edit and affected wiring against the final source. Record the actual remaining files and edges. Continue through all accepted actionable knots in scope. A blocked or rolled-back knot remains visible; it is never counted as fixed.

Complete applicable repository gates once at final readiness, reusing passing evidence for the unchanged final state. Check the complete task diff for lost contracts and accidental unrelated changes. Do not restart a full investigation after each fix or add validation without a distinct unmet obligation. Stop when the accepted in-scope work is resolved or remaining work has a concrete proof/authority blocker. Do not promise a repository is free of all complexity.

Show the actual result

  • Lead with the full before/after feature/file wiring diagram, keeping feature colors and file positions comparable. Mark the affected files with stable knot numbers and make actual added or removed routes visible. Keep unchanged connections in view. Place each numbered knot's close-up and explanation below the main diagram so readers can connect the detail to the whole map.
  • Preserve the original baseline and fill after from the final observed code, including partial completion, rollback, or no change. Keep feature IDs, colors, ordering, scope, and grouping comparable across both panels. A useful abstraction may add a file or wire; fewer wires are not the success criterion.
  • Explain each changed knot with matched source excerpts from both revisions: what responsibility moved, why the new owner helps, and which observable behavior the checks preserve. Add its comparison record as described in map-contract.md. Use exact paths and first-line numbers, keep excerpts short, and verify them against their source snapshots. A different badge color or a tidier wire layout does not explain a change. State when the feature/file connections stayed the same. Never invent an after excerpt for a read-only audit or present a proposal as completed work. Include paired paths for the affected source boundaries: label the actual sender, receiver, and data passed between them, with both endpoints bound to source excerpts. Record intermediate owners in via so a detour is drawn in full; show the actual handoffs removed or added, rather than relying on status colors. Keep path identities and order comparable. Distinguish these data-flow diagrams from the feature/file map and from module dependency graphs; do not invent removed calls or fewer connections to make a cleaner after image.
  • Regenerate the HTML and one side-by-side comparison image. The renderer provides comparison.svg; capture that actual image as comparison.png with an available supported browser when possible. Never use generative imagery to invent evidence. Inspect the image for clipped labels, misleading simplification, and readable red knot numbers. Keep unresolved knots red; fixed knots retain their identity with a distinct resolved status. The SVG shows up to three supplied change explanations and discloses that limit; the HTML retains every explanation and the full wiring context.
  • Report the local branch, resolved and unresolved knots, verified commands, rollback outcomes, scope/coverage limits, and links to the HTML and image. In read-only mode, show the same observed graph on both sides only if clearly labeled unchanged; otherwise keep the right panel labeled not performed. Do not present proposed rewiring as completed work. Never claim success when required checks were skipped, blocked, or failed.

Keep artifacts in the repository's existing evidence location or a task-owned output directory outside its source/build inputs. Preserve the manifest with revision identities so file/line references remain meaningful after edits.

Subagent guidance

Default: local-first. When delegation is available and authorized, assign independent feature tracing or a concrete unresolved contract/equivalence risk to an appropriate worker. Give each worker a bounded subsystem, exact source state, allowed paths, and expected evidence. Keep overlapping edits, ranking, rollback ownership, and final integration with the primary agent. Do not make independent review a ritual for every ordinary knot.

Related Skills