| name | legacy-audit |
| description | Run a deep, manual, project-wide audit for dead code, duplicated logic, stale wrappers, and legacy residue before major refactors or during periodic maintenance. Use this skill whenever a repository needs a human-reviewable cleanup plan across the whole codebase, especially when old architectural layers, abandoned adapters, or oversized legacy files may still be present. |
Legacy Audit
Use this skill for a repository-wide cleanup audit.
This skill reports and proposes. It does not perform broad automatic deletion by default.
Trigger
Run this skill when:
- a maintainer invokes it manually;
- a major refactor is being prepared;
- the codebase has accumulated several implementation cycles without cleanup;
- the team wants a periodic entropy review, for example every N sprints or milestone cycles.
Scope
The scope is the entire repository.
This includes:
- application code;
- shared libraries;
- scripts and tooling;
- configuration surfaces;
- legacy adapters, wrappers, and compatibility branches;
- tests that may preserve outdated integration paths.
Inputs
Review as much of the following as is available:
- repository structure;
- current code paths;
- task plans and architecture notes;
- git history;
- changelog or release notes;
- migration or deprecation documents.
If historical context is missing, say so explicitly in the audit report.
Audit Algorithm
1. Build a codebase-wide dead-code picture
Inspect modules for:
- apparently unused functions;
- apparently unused classes;
- obsolete helper layers;
- dead compatibility wrappers;
- old fallback paths;
- stale config surfaces;
- unreachable or superseded branches.
2. Look for duplicated logic
Identify logic that appears in multiple files or modules with only minor variation, especially when one version looks like a newer replacement for another.
3. Cross-check with historical decisions
Compare suspicious files and code paths against:
- git log;
- changelog entries;
- migration notes;
- architectural decision records where available.
The goal is to distinguish:
- intentionally retained compatibility layers;
- accidental leftovers from replaced designs.
4. Identify oversized legacy concentration
Flag files where more than 30% of lines appear to be:
- dead code;
- obsolete transitional code;
- commented-out legacy implementation;
- duplicate compatibility residue.
Treat this as an audit signal, not automatic proof that deletion is safe.
5. Separate safe and uncertain candidates
Classify findings into:
- likely safe deletion candidates;
- likely consolidation candidates;
- uncertain candidates needing human review;
- historical residue that should stay but needs documentation.
Safety Rules
Do not treat naive search absence as sufficient proof that code is dead.
Before declaring something removable, consider:
- exports and re-exports;
- runtime registration;
- plugin discovery;
- DI containers;
- route wiring;
- CLI commands;
- config switches;
- framework conventions;
- test-only execution paths;
- reflection or dynamic loading.
If evidence is incomplete, lower confidence and mark the item for review.
Output
Produce a structured audit report for human review before deletion.
Use this structure:
# Legacy Audit Report
## Summary
- repository:
- audit_date:
- high_risk_areas:
## Findings
- file:
category:
estimated_dead_lines:
confidence:
rationale:
recommended_action:
## Duplicate Logic
- file_pair_or_group:
shared_behavior:
likely_source_of_truth:
recommendation:
## High Legacy Density Files
- file:
estimated_legacy_ratio:
notes:
## Uncertain Candidates
- file:
reason_uncertain:
required_followup:
Use confidence labels such as:
Non-Goals
This skill does not:
- perform broad automatic deletions;
- rewrite the repository during the audit itself;
- replace task-scoped
post-implementation-cleanup;
- treat historical suspicion as proof.
