OneLinersCommand workbench
AI
Back to skills
SKILL.md

Safe dead-code removal

An evidence-first workflow to prove that code is unreachable or unused before deleting it.

Revision
2
Verified
2026-10-20
Save or explore
Save to collectionCreate a collection in the sidebar first.

Compatibility and paths

Codexskills/dead-code-removal/SKILL.md
Claude Code.claude/skills/dead-code-removal/SKILL.md
VS Code.github/skills/dead-code-removal/SKILL.md

Trust and provenance

Curated record reviewed 2026-10-20. Results still depend on the supplied context and target environment.

Generated assetReady to copy or download
---
name: dead-code-removal
description: Separates static non-references from real removal evidence, including dynamic registries, public exports and import-time effects. Use before deleting an apparently unused module; return a bounded candidate ledger, not a blind deletion command.
license: CC-BY-4.0
compatibility: Complete owned Node.js 22.13+ exercises run offline without credentials or dependencies. They do not scan, modify or delete project files.
metadata:
  author: oneliners
  version: "2.0.0"
---

# Safe dead-code removal

## Ask what can enter the program
Inventory web/CLI/worker/job entry points, public package exports, supported versions/consumers, registries, configuration-driven names, reflection, generated code and import-time side effects. Distinguish production roots from tests and build tools without assuming tests are the only callers. Record which environments and time window telemetry actually covers; an absent log event is not proof a recovery or infrequent path is unused.

## Original dynamic-registry counterexample
This eight-node inventory and small object/Map runtime are entirely synthetic. The markdown name identifies a toy handler returning md:text, not a full Markdown renderer or a plugin loaded from disk. The graph is supplied metadata, not output from a scanner. Save the complete reviewed block as removal-fixture.mjs and run node removal-fixture.mjs with Node.js 22.13+; there are no filesystem or network operations.

```js
function reviewRemovalCandidates(packet) {
  if (!packet || !Array.isArray(packet.nodes) || !Array.isArray(packet.edges) || !Array.isArray(packet.roots) || !Array.isArray(packet.dynamicEntries) || !Array.isArray(packet.unresolvedDynamic)) throw new Error("complete inventory fields required");
  const nodes = new Map(packet.nodes.map((node) => [node.id, node]));
  if (nodes.size !== packet.nodes.length) throw new Error("duplicate nodes");
  const adjacency = new Map(packet.nodes.map((node) => [node.id, []]));
  for (const [from, to] of packet.edges) {
    if (!nodes.has(from) || !nodes.has(to)) throw new Error("unknown edge endpoint");
    adjacency.get(from).push(to);
  }
  const publicRoots = packet.nodes.filter((node) => node.publicExport === true).map((node) => node.id);
  function reachable(roots) {
    const found = new Set(), todo = [...roots];
    while (todo.length) {
      const id = todo.pop();
      if (!nodes.has(id)) throw new Error("unknown entry point");
      if (found.has(id)) continue;
      found.add(id); todo.push(...adjacency.get(id));
    }
    return found;
  }
  const staticReachable = reachable([...packet.roots, ...publicRoots]);
  const allReachable = reachable([...packet.roots, ...publicRoots, ...packet.dynamicEntries]);
  const staticUnreachable = packet.nodes.filter((node) => !staticReachable.has(node.id)).map((node) => node.id);
  const candidates = packet.unresolvedDynamic.length ? [] : packet.nodes.filter((node) => !allReachable.has(node.id) && node.publicExport === false && node.sideEffects === false).map((node) => node.id);
  return { staticUnreachable, protectedByDynamic: staticUnreachable.filter((id) => allReachable.has(id)), candidates, scope: packet.unresolvedDynamic.length ? "UNKNOWN_DYNAMIC_REACHABILITY" : "CLOSED_FIXTURE_ONLY" };
}
function createRemovalRuntime({ includeMarkdown = true, includeUnused = true } = {}) {
  const helpers = includeUnused ? { unusedPad: (text) => " " + text } : {};
  const registry = new Map([["text", (text) => "text:" + text]]);
  if (includeMarkdown) registry.set("markdown", (text) => "md:" + text);
  return { unusedHelperPresent: Object.hasOwn(helpers, "unusedPad"), render(kind, text) {
    const handler = registry.get(kind);
    if (!handler) throw new Error("Unsupported fixture plugin " + kind);
    return handler(text);
  } };
}
function runRemovalFixture(packet) {
  const original = createRemovalRuntime();
  const withoutPlugin = createRemovalRuntime({ includeMarkdown: false });
  const withoutUnused = createRemovalRuntime({ includeUnused: false });
  let pluginFailure = null;
  try { withoutPlugin.render("markdown", "hello"); } catch (error) { pluginFailure = error.message; }
  return { analysis: reviewRemovalCandidates(packet), originalMarkdown: original.render("markdown", "hello"), pluginFailure, originalUnusedPresent: original.unusedHelperPresent, unusedRemovedPresent: withoutUnused.unusedHelperPresent, afterUnusedRemoval: withoutUnused.render("markdown", "hello") };
}
const packet = {
  "provenance": "closed synthetic module inventory, not a whole-repository reachability proof",
  "nodes": [
    {
      "id": "api/public",
      "publicExport": true,
      "sideEffects": false
    },
    {
      "id": "cli/main",
      "publicExport": true,
      "sideEffects": false
    },
    {
      "id": "lib/format",
      "publicExport": false,
      "sideEffects": false
    },
    {
      "id": "plugin/loader",
      "publicExport": false,
      "sideEffects": false
    },
    {
      "id": "plugin/text",
      "publicExport": false,
      "sideEffects": false
    },
    {
      "id": "plugin/markdown",
      "publicExport": false,
      "sideEffects": false
    },
    {
      "id": "startup/register",
      "publicExport": false,
      "sideEffects": true
    },
    {
      "id": "lib/unused",
      "publicExport": false,
      "sideEffects": false
    }
  ],
  "roots": [
    "api/public",
    "cli/main"
  ],
  "edges": [
    [
      "api/public",
      "lib/format"
    ],
    [
      "api/public",
      "startup/register"
    ],
    [
      "cli/main",
      "lib/format"
    ],
    [
      "cli/main",
      "plugin/loader"
    ],
    [
      "plugin/loader",
      "plugin/text"
    ]
  ],
  "dynamicEntries": [
    "plugin/markdown"
  ],
  "unresolvedDynamic": []
};
console.log(JSON.stringify(runRemovalFixture(packet), null, 2));
```

## Candidate ledger and observed counterexample
Static-only reachability marks plugin/markdown and lib/unused unreachable. The supplied registry manifest protects plugin/markdown; with public entry points and that manifest included, only lib/unused is a candidate in this closed fixture. startup/register is reachable from the public API and explicitly has side effects: having no public exports would not justify dropping its import.

Runtime control: original markdown handler returns md:hello. Constructing the registry without that handler actually throws Unsupported fixture plugin markdown. Removing the unused helper from the owned runtime object leaves md:hello unchanged, and unusedHelperPresent changes true→false. That is a limited control, not proof about arbitrary external callers. No repository file, package export or production plugin was deleted.

Decision: KEEP the dynamically registered plugin and reachable registration module. lib/unused is a removal-review candidate only because this supplied inventory is explicitly closed, has no unresolved dynamic entries, marks it private/pure and contains no route/CLI/export/registry reference to it. Add one unresolved dynamic loader and the evaluator returns no removal candidates (UNKNOWN_DYNAMIC_REACHABILITY), not permission to delete the same list.

Real removal gate: identify all supported public entry points and consumers, framework/configuration/registry loaders, import-time effects and deployment overlap; test the exact supported paths against the proposed removal. No recent runtime hit is insufficient for seasonal, recovery-only or rarely used features. Preserve a reversible commit and recovery artifact; stop on unknown callers/side effects instead of treating an empty reference search or compiler warning as whole-program proof.

## Triangulate before editing
Search references with the project's resolver and supported configurations, inspect the dynamic/public roots, and test a candidate removal in an owned branch/environment. Use a failed supported-path test as evidence to keep code, not as a test to delete. Examine registration side effects and downstream artifacts before removing an apparently empty import. [TypeScript noUnusedLocals](https://www.typescriptlang.org/tsconfig/noUnusedLocals.html) reports unused local declarations; it is not evidence that an exported module has no external consumer. [Node package entry points](https://nodejs.org/api/packages.html#package-entry-points) help identify supported exports and conditions, not a license to remove every unexported file.

## Reversible rollout and handoff
For each candidate list identity/version, static references, dynamic loaders checked, public consumers, side-effect evidence, coverage gaps, regression test, owner and recovery plan. Separate deprecating a public API from removing a genuinely private helper. If an approved deletion proceeds, make one bounded commit, preserve compatible artifacts during rollout, rerun the real build/consumer tests and verify the resulting package actually contains all supported entry points. Do not execute an untrusted repository script or bulk delete directory matches during this review. Unknown dynamic loading, incomplete export inventory, uncertain effects or an irreversible deployment step requires a hold and a specific missing-evidence request.

Real example

Input

Review the supplied closed inventory and execute only the complete owned registry counterexample from SKILL.md. No real files should be deleted.

{
  "provenance": "closed synthetic module inventory, not a whole-repository reachability proof",
  "nodes": [
    {
      "id": "api/public",
      "publicExport": true,
      "sideEffects": false
    },
    {
      "id": "cli/main",
      "publicExport": true,
      "sideEffects": false
    },
    {
      "id": "lib/format",
      "publicExport": false,
      "sideEffects": false
    },
    {
      "id": "plugin/loader",
      "publicExport": false,
      "sideEffects": false
    },
    {
      "id": "plugin/text",
      "publicExport": false,
      "sideEffects": false
    },
    {
      "id": "plugin/markdown",
      "publicExport": false,
      "sideEffects": false
    },
    {
      "id": "startup/register",
      "publicExport": false,
      "sideEffects": true
    },
    {
      "id": "lib/unused",
      "publicExport": false,
      "sideEffects": false
    }
  ],
  "roots": [
    "api/public",
    "cli/main"
  ],
  "edges": [
    [
      "api/public",
      "lib/format"
    ],
    [
      "api/public",
      "startup/register"
    ],
    [
      "cli/main",
      "lib/format"
    ],
    [
      "cli/main",
      "plugin/loader"
    ],
    [
      "plugin/loader",
      "plugin/text"
    ]
  ],
  "dynamicEntries": [
    "plugin/markdown"
  ],
  "unresolvedDynamic": []
}

Expected result

Static-only reachability marks plugin/markdown and lib/unused unreachable. The supplied registry manifest protects plugin/markdown; with public entry points and that manifest included, only lib/unused is a candidate in this closed fixture. startup/register is reachable from the public API and explicitly has side effects: having no public exports would not justify dropping its import.

Runtime control: original markdown handler returns md:hello. Constructing the registry without that handler actually throws Unsupported fixture plugin markdown. Removing the unused helper from the owned runtime object leaves md:hello unchanged, and unusedHelperPresent changes true→false. That is a limited control, not proof about arbitrary external callers. No repository file, package export or production plugin was deleted.

Decision: KEEP the dynamically registered plugin and reachable registration module. lib/unused is a removal-review candidate only because this supplied inventory is explicitly closed, has no unresolved dynamic entries, marks it private/pure and contains no route/CLI/export/registry reference to it. Add one unresolved dynamic loader and the evaluator returns no removal candidates (UNKNOWN_DYNAMIC_REACHABILITY), not permission to delete the same list.

Real removal gate: identify all supported public entry points and consumers, framework/configuration/registry loaders, import-time effects and deployment overlap; test the exact supported paths against the proposed removal. No recent runtime hit is insufficient for seasonal, recovery-only or rarely used features. Preserve a reversible commit and recovery artifact; stop on unknown callers/side effects instead of treating an empty reference search or compiler warning as whole-program proof.

Source evidence

Agent Skills specificationofficialTypeScript compiler options — noUnusedLocalsofficialNode.js package entry pointsofficial