santosomar/general-secure-coding-agent-skills/dead-code-eliminator

Dead Code Eliminator

Dead code is code that cannot execute under any input. It's not "rarely used" — it's never reachable. The distinction matters: deleting rarely-used code is a product decision; deleting dead code is housekeeping.

Deadness classes — from certain to uncertain

The public-symbol problem

Static analysis says doThing() has zero callers. Before deleting, check:

• Reflection / dynamic dispatch: getattr(obj, name)(), Class.forName(...), Spring @Component scanning. The call is in a string.
• Entry points: CLI scripts, web handlers, cron jobs — registered in config, not called from code.
• External callers: It's a library. Someone downstream imports this. Check __all__, check the public API docs.
• Serialization hooks: __getstate__, toJSON(), ORM hooks — called by the framework, not by you.
• Tests only: The only caller is a test. The test exists to test the function — circular. Delete both.

If you can't rule all of these out, it's probably dead but you can't prove dead. Deprecate before delete.

Safe deletion workflow

1. Identify → 2. Verify → 3. Deprecate (if public/uncertain) → 4. Delete → 5. Test

Worked example

Candidate: utils/legacy_format.py — 3 functions, 0% test coverage, no callers found by grep.

Verify:

• Private? No — top-level module functions.
• Reflection? rg 'legacy_format' --type py → one hit: import utils.legacy_format in utils/__init__.py. Nobody uses the import. Re-exported but unused.
• Entry point? Check setup.py / pyproject.toml [project.scripts] — not there.
• External? This is an app, not a library. No downstream.
• Serialization? Function names are parse_v1, parse_v2, detect_version — not hook-shaped.

Verdict: Dead. But the __init__.py re-export means someone thought it was public. Check git log: last non-formatting commit to legacy_format.py was 3 years ago, message says "migrate to v3 format." The v3 migration finished; v1/v2 parsers are orphaned.

Delete:

1. Remove the __init__.py re-export. Test. Green.
2. Delete utils/legacy_format.py. Test. Green.
3. rg 'legacy_format' one more time — clean.

Commit message: Remove dead v1/v2 format parsers — v3 migration completed 2023, no remaining callers.

Dead feature flags

A flag that's been at one value in every environment for 3+ months is a dead conditional:

if settings.USE_NEW_CHECKOUT:
    new_path()
else:
    old_path()     # ← dead if flag has been True everywhere since Q3

Delete the flag check, inline the winning branch, delete the losing branch. Then delete the flag from config. This is the #1 source of dead code in feature-flag-heavy codebases.

Do not

• Do not delete based on zero coverage alone. Tests are not exhaustive. Production logs are closer — if you have them, check for the function's log lines.
• Do not delete a public symbol without a deprecation cycle unless you can prove no external callers.
• Do not delete the function but leave the test. Now you have a test for nothing — and it'll fail, and someone will "fix" it by re-adding the function.
• Do not delete an else branch just because the if is always true today. If the condition reads external config, "always true" is a current fact, not an invariant.
• Do not batch-delete 50 functions in one commit. One commit per logical dead-code cluster — if you're wrong about one, the revert is surgical.

Output format

## Dead (certain — delete now)
- <file>:<symbol>  — <proof: private+no-callers | after-return | const-false>
  Also delete: <tests, imports>
 
## Probably dead (deprecate first)
- <file>:<symbol>  — <why uncertain: might-be-reflected | public-api>
  Deprecation: <log line / warning to add>
  Revisit after: <one release cycle>
 
## Not dead (looked dead, isn't)
- <file>:<symbol>  — <actual caller you found>