untangle

Files (2)

• SKILL.md
• report-template.md · references/

SKILL.md (first lines)

# /untangle

Map how a repository actually depends on each thing it pulls in, what each
dependency would cost to remove, and — when removal is worth it — perform the
removal cleanly. Three guiding principles:

- **This is an ownership map, not a purge manifesto.** `keep` is a first-class
  verdict and must be argued as explicitly as any removal. The output's value
  is knowing *exactly* what you depend on and what each exit would cost, not
  a smaller number in `Cargo.toml`.
- **Evidence before verdicts.** Every score and verdict traces to numbers in
  the Evidence appendix, produced by the standard commands below, so the next
  audit run can be diffed against this one.
- **Shipping vs dev is the first cut.** The audit's subject is the normal
  (shipping) dependency graph — what consumers inherit, including optional
  and target-gated deps. Dev-dependencies (tests, examples, benches) never
  ship and get the light-touch table only. Classify usage by where the call
  site lives, not where the dependency is declared, and label every count in
  the report with the graph it measures.

## Modes

| Invocation | Does |
|---|---|
| `/untangle` | Full audit of every direct dependency → `<docs>/DEPENDENCY_AUDIT.md` |
| `/untangle <dep>` | One dependency's dossier (update its section in an existing audit, else standalone) |
| `/untangle extract <dep>` | Guided removal: preflight gates → approved plan → execute → verify |

Detect the repo's docs folder the way the other house skills do (`docs/` or
wherever existing design docs live). Report mode **refreshes
`DEPENDENCY_AUDIT.md` in place** — regenerate it each run with a fresh audit
header, but preserve any `## Notes (human)` section verbatim, and when a
previous audit exists, add a one-line `Δ` note to any dossier whose score or
verdict changed.

## Report mode

### 1. Establish context

- Host license (from the manifest) — the extraction license gate depends on it.
- Current commit (`git rev-parse --short HEAD`) and toolchain version for the
  audit header. Read-only git only; never run state-changing git commands.
- Workspace? Run from the root; add a Crate column to the summary table when
  members differ.

### 2. Gather evidence (standard commands)

Required baseline is only the package manager + `rg`. Run:

- `cargo metadata --format-version 1` — versions, **licenses**, feature flags,
  which deps are optional. Its package count is **not** a size metric: it is
  unfiltered by target and includes dev-deps and inactive optional edges.
- `cargo tree -e normal` — the **shipping graph**, the audit's subject.
  Record the canonical baselines as unique crates excluding the root:
  host target, `--target all`, and the dev-inclusive count (no `-e` filter)
  for contrast — label each. Per-dep `cargo tree -i <dep>` — what each direct
  dep uniquely drags in (its *baggage*) and what depends on it.
- `cargo tree -d` — duplicate versions. **Partition shipping vs dev-only**
  (reachable only via dev-deps): dev-only duplicates never reach consumers
  and are reported as such, never as shipping bloat.
- Per-dep census with `rg`: `use <dep>` imports, call sites, files touched,
  and `derive(...)` attributes referencing the dep's macros — **two counts
  per dep**: shipping code (`src/` outside `#[cfg(test)]` modules and
  doc-test fences) and dev code (`tests/`, `examples/`, `benches/`, test
  modules). The split is what surfaces misclassified dependencies.
- Opportunistic, if installed — degrade silently when absent: `cargo machete`
  or `cargo udeps` (unused deps → `drop` candidates), `cargo audit` /
  `cargo deny` (advisories), `cargo license`.
- Maintenance signals: last release + advisories (via `cargo audit`, `cargo
  info`, or a web lookup). Offline or unavailable → record `unchecked`, never
  guess.

Raw numbers go into the report's **Evidence appendix** (see template) — that
appendix is what makes the next run comparable.

### 3. Judge each direct dependency

The census can't answer the questions that dominate removal cost. For each
third-party dep, answer explicitly:

- **Does it actually ship?** — decided by call site, not declaration: a
  `[dependencies]` entry whose only usage is in `tests/`, `examples/`,
  `benches/`, or `#[cfg(test)]` modules is misclassified — verdict
  `demote-to-dev`, not `keep` or `drop`. Converse trap: usage behind a
  feature that examples enable via `required-features` is still shipping
  usage.
- **Public API leakage** — do the dep's types/traits appear in this crate's
  exported signatures (including trait impls downstream consumers rely on)?
  This is the single biggest cost driver: leakage means removal is a breaking
  release, not an internal refactor.
- **Derive/macro saturation** — attribute macros on N types are structural
  entanglement that call-site counts miss entirely.
- **Contract exposure** — do persisted files, wire formats, or downstream
  repos depend on output this dep produces?
- **Replaceability** — std equivalent? Re-implementable blind from observed
  behavior (≲50 lines)? Bounded enough to vendor? Or genuinely hard?
- **Vendorable LOC** — estimate what a copy-out would actually take. A dep
  can look small and balloon ("part of serde" is not a thing); this estimate
  is the trap detector.

**First-party deps** (same author/org — check repository/authors fields) get
the **absorption rubric** instead: license work is moot; the real questions
are (a) does maintaining it in two places cost more than folding it in, (b)
who else consumes the standalone crate and what breaks for them, (c) is the
boundary itself wrong (fix the sibling crate's API rather than absorb).

### 4. Score, size, and issue verdicts

**Entanglement score (1–5)** — use these anchors, not ad-hoc prose labels:

1. Contained — optional/feature-gated or leaf usage, few call sites, no leakage.
2. Spread-shallow — many call sites but one narrow API surface, no leakage;
   removal is mechanical.
3. Structural — leaks into public API in one bounded place, OR saturates one
   subsystem.
4. Leaks and spreads — public API leakage plus wide module spread, or
   persisted/wire contracts depend on it.
5. Ecosystem hub — derive/format machinery with downstream consumers pinned
   to its output; removal is a coordinated breaking release.

From folkengine/.claude, Apache-2.0.

More from folkengine/.claude