Dead Code Surgeon - Phased Codebase Audit & Cleanup Roadmap

───────────────────────────────────────────────────────────────────────────
PHASE 1 — COMPREHENSIVE CODEBASE ANALYSIS (scanning all code)
───────────────────────────────────────────────────────────────────────────
As a seasoned software architect with expertise in codebase health and technical debt reduction, your initial task is to scrutinize the entire codebase for various categories of waste and obsolescence.

Identify the following types of inert code and dependencies across the codebase:

A) UNREACHABLE DECLARATIONS
• Identify functions, methods, and classes that are never directly or indirectly invoked. Consider:
- Indirect references through callbacks, event handlers, and third-party libraries
- Variables and constants that are assigned but never read after the initial write
- Types, enums, and structs that are defined but never instantiated or referenced
- Entire source files that are excluded from compilation or never imported by other code

Example:

// A function that is never called
function unusedFunction() {
  console.log('This function is never executed');
}

B) DEAD CONTROL FLOW
• Locate branches that cannot be reached due to logical conditions. Examples include:
- Conditions that are always true or false, rendering the following code unreachable
- Code that appears after an unconditional return, throw, or exit statement
- Feature flags that have been hardcoded to a single state without any conditional logic

Example:

if always_false_condition:
    # This code will never execute
    print("This line is unreachable")
else:
    print("This line is reachable")

C) PHANTOM DEPENDENCIES
• Detect import statements (including require, use, or module imports) whose exported symbols are completely untouched within the importing file. Consider:
- External library dependencies that are imported but have no symbols used within the file
- Package-level dependencies listed in configuration files (package.json, go.mod, Cargo.toml) that are not referenced in the source code

Example:

import { unusedSymbol } from 'external-library';

// The unusedSymbol is imported but never used within this file

───────────────────────────────────────────────────────────────────────────
PHASE 2 — PRECISION AUDIT (avoiding false positives)
───────────────────────────────────────────────────────────────────────────
Before declaring any code as "dead," ensure that you rule out the following sources of false positives:

• Dynamic dispatch and reflection: Symbols that are resolved at runtime based on user input or system conditions
• Dependency injection systems: Symbols used as keys or identifiers in wiring containers, which may not appear as direct method calls
• Serialization and deserialization targets: Symbols that represent database models, JSON mappers, or protocol buffers, which may be used indirectly
• Metaprogramming: Macros, annotations, templates, and code generators that may reference symbols dynamically
• Test fixtures and utilities: Symbols used exclusively within testing environments
• Public API surface: Symbols that are exported and may be consumed by external clients through the library's public interface
• Framework lifecycle hooks: Symbols used in middleware chains, initialization hooks, or event listeners
• Configuration-driven behavior: Symbols whose usage is determined by configuration files, environment variables, or feature registries

Exclude symbols that fall into these categories, and if any ambiguity remains, assign a lower confidence rating to the finding and provide a detailed explanation of why it may not be safely deletable.

───────────────────────────────────────────────────────────────────────────
PHASE 3 — STRATEGIC TRIAGE (prioritizing the cleanup)
───────────────────────────────────────────────────────────────────────────
Assess the risk associated with each finding by assigning a Risk Level:

🔴 HIGH — Safe to delete immediately; zero external callers, no framework magic, and minimal risk of breakage
🟡 MEDIUM — Likely dead but indirect usage is possible; requires verification before deletion to avoid unintended consequences
🟢 LOW — Probably used via reflection, configuration, or public API; flag for human review to ensure no critical dependencies are affected

───────────────────────────────────────────────────────────────────────────
OUTPUT STRUCTURE
───────────────────────────────────────────────────────────────────────────
Your analysis should be presented in three clear sections:

1. Findings Report

Categories: UNREACHABLE_DECL / DEAD_FLOW / PHANTOM_DEP
Actions: DELETE / RENAME_TO_UNDERSCORE / MOVE_TO_ARCHIVE / MANUAL_VERIFY / SUPPRESS_WITH_COMMENT

2. Cleanup Roadmap

Group findings into three sequential batches based on Risk Level.

Batch 1: High-Confidence Deletions

• Estimated lines of code removed: 1,500 LOC
• Potential bundle / binary size impact: 20% reduction
• Suggested refactoring order: Touch core libraries first, then external dependencies

Batch 2: Medium-Risk Verifications

• Estimated lines of code removed: 500 LOC
• Potential bundle / binary size impact: 5% reduction
• Suggested refactoring order: Dependencies used in tests first, then production code

Batch 3: Low-Risk Manual Reviews

• Estimated lines of code removed: 200 LOC
• Potential bundle / binary size impact: 2% reduction
• Suggested refactoring order: Public API files, then framework-specific utilities

3. Executive Summary

End with a concise paragraph assessing the overall codebase health, highlighting key insights from the analysis, and suggesting the top-3 highest-impact actions to address immediately.

───────────────────────────────────────────────────────────────────────────
CONSTRAINTS AND CONSIDERATIONS
───────────────────────────────────────────────────────────────────────────
Ensure that your analysis adheres to the following constraints and considerations:

1. Context awareness: Consider the specific architecture, language, and framework used in the codebase.
2. Performance impact: Estimate the potential improvement in build times, startup times, and runtime memory usage.
3. Complexity reduction: Assess the reduction in cognitive load for new developers joining the project.
4. Test coverage: Identify any test cases that may need to be updated or removed as a result of the cleanup.
5. Versioning and migrations: Plan for any necessary changes to package versions, dependency updates, or API modifications.

The goal is to produce a comprehensive, actionable report that enables the development team to safely and strategically eliminate technical debt while minimizing the risk of introducing bugs or breaking existing functionality.

───────────────────────────────────────────────────────────────────────────