Dead-code cleanup

Remove code only when evidence supports that it is unused and removal preserves behavior. Treat absence of obvious references as a lead, not proof. Keep the investigation and proposed change small and reviewable.

Triggers

• A user asks to find or remove dead, unreachable, obsolete, or unused code.
• A maintenance task identifies a specific symbol, module, branch, or asset as a cleanup candidate.

Non-triggers

• A feature is merely unpopular, old, or unfamiliar; age and low visibility do not establish deadness.
• The request is to redesign, optimize, or change behavior without an unused-code hypothesis. Use the appropriate workflow instead.
• A candidate may be controlled by production configuration or operational procedures that cannot be inspected safely; do not infer permission to change those systems.

Process

1. Bound the candidate. Identify the exact symbols/files and the requested scope. Read surrounding implementation, callers, tests, and local project instructions before proposing changes. Prefer the smallest candidate set.
2. Gather evidence. Search references across the repository, including imports, string-based names, registrations, dependency injection, generated code, build manifests, scripts, documentation, and tests. Inspect available history (for example, blame or recent changes) for intent and compatibility constraints. Use telemetry or profiling only when already available, relevant, and authorized; absence of telemetry is not evidence of non-use. Do not require proprietary tools, production access, or new instrumentation.
3. Review indirect and dynamic use. Check reflection, plugin/entry-point discovery, decorators or registries, callbacks, serialization/deserialization names, template or configuration references, command routing, runtime imports, conditional/platform-specific paths, and external consumers of public APIs. Search beyond the immediate directory when scope permits. If a usage mechanism cannot be ruled out, record that uncertainty rather than treating a static search as conclusive.
4. Separate facts from hypotheses. For each candidate, record concrete evidence for and against use, uncertainty, expected impact, and affected callers or consumers. A zero-result search, unreachable-looking branch, or lack of recent history is insufficient by itself. If evidence is incomplete or conflicting, do not delete; request human review or propose a further read-only check.
5. Apply safety gates. Preserve production behavior and safety mechanisms, including kill switches, SDK fallbacks, compatibility paths, and local overrides. Do not remove code merely because a default configuration does not use it. Treat live systems and configuration as read-only: never change them to test a hypothesis. Any exception affecting safety-sensitive or production behavior requires explicit approval from an authorized human.
6. Propose a minimal change. When evidence is adequate, prepare a small, reviewable diff limited to the confirmed dead code and necessary references/tests. Avoid unrelated cleanup, broad rewrites, or opportunistic behavior changes. If the change could affect external consumers or rollback is not straightforward, present it for human review before applying it.

Evidence and Reporting

Provide a structured report with:

• Candidate: Exact symbol, module, file, and line ranges scoped for cleanup.
• Evidence: Documented search findings across direct references, dynamic lookups, repository history, and available runtime telemetry. Clearly separate verified facts from hypotheses.
• Uncertainty & Impact: Document unresolved dynamic paths, external consumer risks, or uninspectable environments.
• Proposed Diff: Present the minimal change as a reviewable diff or draft PR. Keep uncertain or safety-sensitive removals as proposals for human review.

Verification

• Run focused test suites and relevant static analysis, lint, or build checks available in the project.
• Inspect the diff to confirm no unintended behavior changes, test coverage reductions, or broken platform matrix paths.
• Document exact checks executed and their outcomes; do not claim validation that was not performed.
• Provide clear rollback considerations or revert steps in case unexpected downstream impact occurs.

Example

Trigger: A maintenance scan flags src/plugins/formatters/xml_formatter.py (XmlFormatter) as having zero static references in src/ and tests/, proposing immediate deletion.

Investigation & Evidence:

• Direct static reference search across the codebase returns 0 imports or references for XmlFormatter.
• Inspection of src/plugins/registry.py shows dynamic entry-point discovery via importlib and string-based class lookup: plugin names defined in external configuration or environment variables are dynamically imported at runtime.
• Repository history shows XmlFormatter was added to support dynamic plugin extensions; runtime invocation telemetry is unavailable in the repository.

Finding & Safety Gate:

• Zero static references alone is insufficient proof of dead code because the dynamic plugin discovery path remains unresolved.
• Deletion is deferred. The class and fallback paths are preserved.

Report & Next Step:

• Submit an evidence report documenting the zero static imports alongside the unresolved dynamic plugin lookup mechanism. Request plugin owner review and runtime invocation evidence before scheduling any deletion diff.