legacy-code-disposition — Legacy Code Disposition Decisions

When to use

Encounter a stretch of "seemingly unused" code and need to decide what to do with it:

• Functions / methods that are never called
• Commented-out logic blocks
• Empty implementations / interfaces returning placeholder values
• Half-finished work that was computed but never wired into the main flow (typical: val x = compute() followed by code that uses the raw value instead)
• Code marked TODO / FIXME for a long time, no longer clear whether it is still wanted

When NOT to use

• Clearly temporary debug code — just delete it.
• Newly written code still in active use.
• Active feature work — use workspace-consistency for end-of-work cleanup instead.

How this differs from related tools

• code-review / general review — review finds problems (what bug is in this code). This skill is for code that is already known to be unused; the decision is delete / keep / wire up.
• dev-recap-docs — produces understanding docs. This skill produces a disposition action.
• Sequence: use this skill first to decide "delete / keep / wire up", then use dev-recap-docs to record the rationale.

Output

A reasoned disposition decision + execution (delete / wire up / preserve with annotation), with traceable rationale.

Methodology (6 steps)

1. Confirm it is truly unused

Search the whole repo for references (definition + all call sites). Distinguish two kinds of "unused":

• Computed but never used (half-finished): result is calculated / defined but never wired in → possibly a missing feature.
• Call removed after evaluation (falsified): was called, then removed when the approach changed → possibly genuinely unneeded.

Commit history can tell them apart: was the call "never added" or "added then deleted"?

2. Recover the original design intent

From comments / commit history / design docs, recover where it was supposed to plug in, what it was supposed to do, and why it was written. Notes like "for X / to prevent Y / to trigger Z" in comments are design motivations.

3. Build the current-state evidence chain

List every exit point where it should have been wired in, and confirm one by one that it is in fact not wired:

• Watch out for "looks unused but takes effect indirectly elsewhere" (reflection / config / callback invocation).
• For each exit point, give "confirmed not wired" evidence (grep shows no references / the flow skips it / a substitute value is used).

4. Verify the motivation is empirically grounded

The design intent from step 2 often says "may / might / could cause X" — ask:

• Is there empirical evidence in logs / docs / measured records? Or is it only a preventive speculation?
• Does the system currently (without this code wired in) actually run correctly? If it does, the motivation may already be falsified by reality.

Key insight: comments like "may be incompatible / may cause X" are usually preventive speculation written at the time, not empirically grounded. If the system runs fine in practice, the preventive concern may no longer hold.

5. Make the decision (three options)

6. Record the rationale

Write the delete / preserve rationale into docs (design doc / commit message / code comment) so it is traceable.

• Delete: record "X was once implemented, judged unneeded by Y (measured Z), deleted".
• Preserve with contingency: record "unused; enable when condition X triggers".

Red lines (reasoned, not absolute)

• Do not delete based on "looks unused" alone — walk the full evidence chain (step 3) first; otherwise you may delete code that takes effect indirectly.
• Do not treat "preventive speculation" as "confirmed problem" — step 4 must distinguish them.
• Do not delete without leaving a record — step 6 is mandatory; otherwise the same question will be re-litigated in the future.

Worked example: one full disposition (sanitized)

1. Confirm unused: grep the whole repo; found the definition and one "computed but unused" call site (constructed a result variable, but subsequent send / cache code uses the raw value).
2. Design intent: comment said "cleans a string to prevent the peer's parsing library from rejecting an extension field → dropping it → stalling".
3. Evidence chain: each exit point where it should have been wired (send, cache refresh) confirmed to use the raw value; the result is never referenced.
4. Empirical motivation: searched all joint-debug docs, no recorded "stall" evidence (motivation was speculation at writing time); after adding fallback config, the system actually connects fine.
5. Decision: delete (motivation not empirically grounded + measured as unneeded).
6. Record: rationale written into the relevant section of the design doc + commit message.

This is one instance, not the methodology itself.