Pitfall: Dead Code False Positives¶

Severity: HIGH — Has caused loss of working code in past sessions Discovered: 2026-04-08 (codebase audit session) Root cause: LLM context rotation + static analysis bias

The Problem¶

When Claude audits the codebase and finds files with zero runtime imports, it classifies them as "dead code" and proposes archival or deletion. This is wrong in approximately 50% of cases because the codebase contains two categories of "unused" files that look identical to static analysis:

Category	What it looks like	What it actually is	Correct action
Truly dead	Zero imports, zero callers	Built for a retired system (e.g., Dolly), explicitly superseded by a new implementation	Archive
Scaffolded/unwired	Zero imports, zero callers	Built as part of a development plan, fully implemented, just not yet connected to the production loop	KEEP — wire it up when the roadmap reaches it

Static analysis (grep, vulture, import chain tracing) cannot distinguish between these two categories. Both show the same signal: no callers, no imports, no runtime references.

Why This Keeps Happening¶

Claude builds scaffolding in Session N — writes a complete module as part of a multi-phase plan
Context rotates — Session N ends, the plan context is lost
Session N+1 Claude audits the codebase, sees the file has no callers
Proposes deletion/archival — because from a fresh context, it looks like dead code
Human may approve — especially during a large cleanup with many files
Working code is lost — a perfectly implemented module gets archived, and when the roadmap reaches that phase, it has to be rewritten from scratch

Real example (2026-04-08): sla_tracker.py (366 lines, fully implemented SLA compliance with daily reports, per-agent tracking, violation alerts) was flagged as "dead code — zero importers, safe to archive." Cross-referencing against the development plans revealed it was scaffolded as part of the monitoring/compliance story and just hadn't been wired to a cronjob yet. Five other modules (ge_engine/quality/, ge_engine/reviews/, ge_engine/human_queue/, ge_engine/billing/, ge_orchestrator/completion_scanner/) were similarly saved from incorrect archival.

Mandatory Protocol: Before Classifying Code as Dead¶

NEVER classify a file as dead code based solely on import/caller analysis. Always complete ALL of these checks:

1. Check the development plans¶

ls /home/claude/.claude/plans/
cat /home/claude/.claude/plans/*.md | grep -i "<module_name>"

Is this file part of an active or future plan phase?

2. Check the session memories¶

cat /home/claude/.claude/projects/-home-claude/memory/MEMORY.md

Was this file created in a documented session? What was the intent?

3. Check git log for creation context¶

git log --diff-filter=A --format="%h %s %ai" -- <file_path>

What commit message accompanied this file? Was it part of a feature branch or plan?

4. Check the roadmap¶

cat /home/claude/.claude/projects/-home-claude/memory/roadmap-to-operational.md
cat /home/claude/.claude/projects/-home-claude/memory/session-2026-04-03-roadmap.md

Is the functionality this file provides on the roadmap (even if far out)?

5. Read the file itself¶

Does it look like a stub/placeholder, or is it a complete implementation? A 366-line module with error handling, edge cases, and Redis integration is not something that was accidentally left behind.

6. Check if it was built for a RETIRED system¶

The only safe "dead code" classification is when the file was built for a system that is explicitly and permanently retired. In GE's case: - Dolly is retired (scaled to 0, 8509 crashloop restarts). Files built exclusively for Dolly are dead. - Filesystem-based communication is retired (replaced by Redis Streams). Files that ONLY do filesystem inbox/outbox are dead. - Everything else needs the full protocol above.

7. When in doubt: KEEP¶

If you cannot confirm the file is built for a retired system, keep it. The cost of keeping an unused file is near zero. The cost of deleting a scaffolded module is a full rewrite.

Classification Template¶

When auditing files, use this template for each file:

File: <path>
Lines: <count>
Last modified: <date>
Created in commit: <hash> — <message>
Import count: <N> (live: <N>, test: <N>, dead: <N>)
References in plans: <yes/no — which plan?>
References in roadmap: <yes/no — which phase?>
Built for retired system: <yes/no — which system?>
Classification: DEAD / SCAFFOLDED / LIVE
Confidence: HIGH / LOW
Action: ARCHIVE / KEEP / WIRE UP

For the Human (Dirk-Jan)¶

If Claude proposes archiving files during an audit, ask: - "Did you check this against the development plans?" - "When was this file created and in what context?" - "Is this file part of a roadmap item we haven't reached yet?" - "Are you sure this wasn't scaffolded by a previous Claude session?"

If Claude says "zero imports, safe to archive" without answering these questions, reject the proposal and request the full protocol.

CODEBASE-STANDARDS.md section 9 — deletion safety protocol
ge-ops/wiki/docs/development/standards/file-structure.md — file allocation rules
/home/claude/.claude/plans/ — active development plans
/home/claude/.claude/projects/-home-claude/memory/ — session memories and roadmaps