Dead Code Review

Core principle: Unused code is not the same as unwanted code. Code exists for a reason — find the reason before removing it.

The Three Categories

Before touching any dead-looking code, classify it:

When in doubt → Unwired. Create an issue.

Step 1 — Check git history first

# Who wrote it and when — read the commit message for intent
git log --all --follow -p <file> | head -60

# Search commits mentioning this function/class
git log --all --oneline --grep="<function_name>"

# When was it last touched?
git blame <file> | grep -n "<function_name>"

If the commit message says "add X endpoint" or "implement Y for phase 3" — this is unwired or future-phase, not dead.

Step 2 — Search for references

# Is anything calling or importing it?
grep -r "<function_name>" --include="*.py" --include="*.ts" --include="*.vue" .

# Is it referenced in tests, even if test is skipped?
grep -r "<function_name>" --include="test_*.py" --include="*.spec.ts" .

# Is it referenced in any issue or TODO?
grep -r "<function_name>" --include="*.md" docs/
gh issue list --search "<function_name>" --state all

Zero references ≠ safe to delete. A function waiting to be wired up will have zero callers.

Step 3 — Check for wiring signals

Look for these patterns that indicate the code is unwired, not dead:

# Signal: Function exists but no route registered
async def get_analytics_summary(...):  # no @router.get("/analytics/summary")

# Signal: Service method exists but never called from handlers
class ConfigRevisionService:
    async def record_revision(self, ...):  # no caller in api/ layer

# Signal: Event handler registered nowhere
async def on_agent_complete(event):  # never passed to event_bus.subscribe()

# Signal: Feature flag gates it
if feature_flags.get("new_search_ui"):
    # This whole block appears dead until flag is enabled

Any of these → Unwired. Create an issue.

Step 4 — Classify and act

If Truly Dead

Must satisfy ALL of these before deleting:

• No callers found anywhere in codebase
• Git history shows no feature intent (e.g., "cleanup", "remove old code")
• No open GitHub issue referencing the functionality
• No TODO/FIXME comment nearby suggesting wiring intent
• Removing it does not break any tests

Then document the removal:

git commit -m "chore: remove dead <name> — no callers, confirmed via grep + git log (#NNNN)"

If Unwired → Implementation Gap Issue

Unwired code is a feature that was built but never connected. This is an implementation gap — not a cleanup task, not an enhancement, not tech debt. It needs to be wired up to deliver the intended functionality.

# file it, then attach it to its umbrella as a native sub-issue (`issue` skill, Step 4)
gh issue create \
  --title "impl gap: wire up <name> — <what it does>" \
  --body "## Implementation Gap
<function/class/module> in <file:line> is fully implemented but has no callers/routes/subscribers.

## What it does
<brief description from reading the code and git history>

## What is missing to complete it
- [ ] <route registration / event subscription / frontend call / lifecycle hook / etc.>
- [ ] <any other wiring needed>

## Location
\`<file>\` line <N> — \`<function_or_class_name>\`

## Discovered During
Working on #<original-issue>

## Evidence it was intentional
<git commit message / comment / related issue that shows this was planned>" \
  --label "enhancement,backend,priority: medium"

Then report:

Created #<number>: implementation gap for <name>.
This code is complete but unwired — leaving it in place.
Should I: a) Wire it now  b) Finish current issue first  c) Leave for later

If Future Phase

Leave the code. Add a comment if context is unclear:

# TODO(#NNNN): Wire this up in phase X — see issue for details

Red Flags — STOP before deleting

• "This function has no callers" → Check git history first
• "This import is unused" → Check if it's a re-export
• "This class is never instantiated" → Check for dynamic instantiation or factory patterns
• "This file is never imported" → Check for dynamic loading or string-based references
• "autoflake/linter flagged it" → Linters don't understand intent. Investigate manually.

Common Patterns in AutoBot

# Pattern: Service implemented, not yet registered in app lifecycle
class ProcessAdapterService:  # exists but start()/stop() not called in lifespan

# Pattern: API endpoint implemented, not registered on router
async def get_config_revision(...):  # missing @router.get(...)

# Pattern: Agent tool defined, not added to tools list
async def search_knowledge(...):  # defined but not in agent.tools = [...]

# Pattern: WebSocket event emitted but no subscriber
await publish_live_event("agent.complete", ...)  # no subscriber registered

All of these look dead. None of them should be deleted — they need issues to wire them up.