Multi-File Dead Code Elimination Plan Prompt

This prompt is for engineering managers and tech leads who need to reduce maintenance burden by systematically removing dead code across a repository. The job-to-be-done is producing a safe, verifiable elimination plan that identifies unreachable functions, unused exports, dead dependencies, and orphaned configuration—without breaking runtime behavior. The ideal user has access to the codebase, understands its build system and module graph, and can run static analysis tools to validate the plan before any code is deleted. Required context includes the repository structure, a list of entry points (binaries, route handlers, cron jobs, test suites), and any known dynamic access patterns (reflection, dependency injection containers, string-based imports) that static analysis alone would miss.

Do not use this prompt when the codebase relies heavily on runtime metaprogramming that cannot be enumerated—frameworks with convention-over-configuration routing, ORM lazy-loading, or plugin systems that discover modules at startup. In those cases, a dead code elimination plan from static analysis will produce dangerous false positives. Similarly, avoid this prompt for repositories where the build graph is incomplete or where critical entry points are undocumented; the model cannot infer what it cannot see. For high-risk codebases (payments, auth, safety-critical systems), every removal candidate must be verified with runtime coverage data and a human approval gate before deletion. This prompt is a planning tool, not an automated deletion engine.

After generating the plan, validate each removal candidate against your static analysis toolchain (e.g., ts-prune, vulture, dead, knip) and cross-reference with runtime coverage reports if available. Flag any candidate where the model's reasoning cites 'appears unused' rather than a concrete unreachability argument—these are the highest-risk false positives. The next step is to stage removals in dependency order (leaf modules first) with a build-and-test gate between each stage, ensuring no removal breaks downstream consumers. If you need a broader change impact analysis before executing, pair this prompt with the Multi-File Change Impact Analysis Prompt to assess downstream breakage risk across the full dependency graph.

The following prompt template is designed to be copied directly into your AI coding agent or orchestration harness. It instructs the model to produce a structured removal plan rather than executing deletions immediately. The template uses square-bracket placeholders for all dynamic inputs—replace these with your repository context, analysis results, and safety constraints before sending the prompt to the model.

textCopy
You are a senior software engineer planning dead code elimination across a multi-file codebase. Your task is to produce a safe, verifiable removal plan. Do not suggest or execute any deletions. Output only the plan.

## Repository Context
[REPOSITORY_CONTEXT]

## Dead Code Candidates
These symbols, files, and imports have been flagged as potentially dead by static analysis. Each entry includes the file path, symbol name, and the tool that flagged it:
[DEAD_CODE_CANDIDATES]

## Dynamic Access Patterns
These patterns may reference code through reflection, dynamic imports, string-based lookup, or runtime configuration. Code flagged as dead may still be reachable through these paths:
[DYNAMIC_ACCESS_PATTERNS]

## Build and Test Configuration
[BUILD_AND_TEST_CONFIG]

## Output Schema
Return a JSON object with the following structure:
{
  "plan_version": "1.0",
  "generated_at": "ISO timestamp",
  "safe_removals": [
    {
      "file": "path/to/file",
      "symbol": "function_or_class_name",
      "removal_type": "delete_symbol | delete_file | remove_import | remove_export",
      "evidence": ["list of reasons this is safe to remove"],
      "pre_removal_checks": ["checks to run before deleting"],
      "dependent_files_to_update": ["files that import or reference this symbol"]
    }
  ],
  "false_positives": [
    {
      "file": "path/to/file",
      "symbol": "function_or_class_name",
      "reason_retained": "explanation of why this code is actually reachable",
      "reachable_through": "dynamic import | reflection | config | test-only | external_consumer | other",
      "recommendation": "keep | add_suppression_comment | refactor_to_make_obvious"
    }
  ],
  "uncertain_cases": [
    {
      "file": "path/to/file",
      "symbol": "function_or_class_name",
      "uncertainty": "description of what is unknown",
      "investigation_steps": ["steps a human should take to resolve"],
      "risk_if_removed": "what could break"
    }
  ],
  "removal_ordering": [
    {
      "phase": 1,
      "description": "Remove leaf-node dead code with no dependents",
      "files": ["file_list"]
    }
  ],
  "verification_plan": {
    "per_phase_checks": ["build must succeed", "test suite must pass", "lint must be clean"],
    "rollback_triggers": ["any test failure", "build failure", "runtime error in staging"],
    "recommended_test_focus": ["specific test files or suites to run"]
  }
}

## Constraints
- Never mark a symbol as safe to remove if it appears in [DYNAMIC_ACCESS_PATTERNS] unless you can prove the dynamic path never resolves to it.
- If a symbol is exported from a public API module, treat it as uncertain unless you have evidence of zero external consumers.
- Test files that import a symbol count as reachable code—do not flag them as dead.
- If build configuration references a file (e.g., entry points, script targets), that file and its transitive imports are reachable.
- Prefer marking uncertain cases over false positives when evidence is incomplete.
- Order removals so that leaf nodes (symbols with no dependents) are removed first, then their callers.

To adapt this template, replace each placeholder with concrete data from your repository. [REPOSITORY_CONTEXT] should include the language, framework, module structure, and any conventions that affect reachability analysis. [DEAD_CODE_CANDIDATES] should come from static analysis tools such as ts-prune, vulture, dead, or IDE inspections—include the tool name so the model can weigh false-positive tendencies. [DYNAMIC_ACCESS_PATTERNS] is critical: populate it by searching for eval, getattr, importlib, require, string-based dispatch tables, and plugin systems. If you skip this section, the model will produce a plan with dangerous false negatives. After generating the plan, always run the verification steps before any deletion, and escalate uncertain cases to a human reviewer who understands the runtime behavior of the system.

The dead code elimination prompt is not a one-shot code deletion tool. It is a planning prompt that produces a structured removal plan before any code is touched. Wire it into a workflow where the plan is generated, validated against static analysis ground truth, reviewed by a human, and only then executed. The prompt should receive repository context from a codebase exploration step—file trees, symbol indexes, import graphs, and test coverage reports—rather than raw file contents dumped into the context window. This separation keeps the prompt focused on planning and reduces the risk of hallucinated references when the model cannot see the full dependency graph.

Input assembly. Before calling the prompt, run a static analysis pass to collect: (a) all exported symbols and their importers across the target file set, (b) test file-to-source mappings so the prompt can flag dead code that still has test coverage, (c) any dynamic access patterns detected via grepping for getattr, eval, __import__, reflection APIs, or string-based dispatch tables relevant to the language ecosystem. Package these into the [CODEBASE_CONTEXT] placeholder as structured JSON or YAML, not raw source. For the [TARGET_FILES] placeholder, provide a list of file paths with brief descriptions of each file's role. The [EXCLUSION_PATTERNS] placeholder should capture files or symbols known to be reachable through external entry points, config-driven loading, or plugin systems that static analysis cannot see.

Validation and retry loop. After the model returns a removal plan, validate every claimed dead symbol against the static analysis ground truth. Flag any symbol the model marks as dead but that appears in an import statement outside the target set. Flag any symbol marked as safe to remove that matches a dynamic access pattern from the pre-collected grep results. If validation failures exceed a configurable threshold (start with zero tolerance for false positives), feed the failures back into a retry prompt that includes the specific symbols, their actual references, and an instruction to re-evaluate. Do not proceed to human review until the plan passes automated validation. Log every validation failure for prompt improvement over time.

Human review gate. Even after automated validation passes, the removal plan must go to a human reviewer. The review interface should display: each symbol proposed for removal, its file location, the model's stated reasoning, the static analysis confirmation, and a checkbox to approve or reject each item individually. Highlight any symbols where the model's confidence was marked low or where dynamic access patterns exist nearby. The reviewer should be able to approve the entire plan, reject specific items, or request a re-plan with additional exclusions. Only after human approval should the plan be converted into actual file edits or deletion commands.

Model choice and tool integration. Use a model with strong code reasoning capabilities and a large context window—the prompt needs to hold symbol tables, import graphs, and file descriptions for potentially dozens of files. If the repository is large, split the analysis into batches by module or package and run the prompt per batch, then merge the plans. For tool integration, the validated and approved plan can be passed to a file-editing agent that applies removals one file at a time, runs the test suite after each batch, and rolls back if tests fail. Never wire the prompt output directly to automated deletion without the validation and review gates described above. The cost of a false positive—deleting code that is actually reachable at runtime—is a production incident, not a linting warning.