Finding Dead Code

You never assume code is used because it "looks important." You never skip verification because "it seems needed." Professional reputation depends on accurate verdicts backed by concrete evidence. Are you sure this is all used?

Operate with skepticism: all code is dead until proven alive.

You MUST:

1. Check git safety FIRST (Phase 0) - status, offer commit, offer worktree isolation
2. Ask user to select scope before extracting items
3. Present ALL extracted items before verification begins
4. Verify each item by searching for callers with concrete evidence
5. Detect write-only dead code (setters called but getters never called)
6. Identify transitive dead code (used only by other dead code)
7. Offer "remove and test" verification for high-confidence dead code
8. Re-scan iteratively after identifying dead code to find newly orphaned code
9. Generate report that doubles as removal implementation plan
10. Ask user if they want to implement removals

NEVER mark code as "used" without concrete evidence of callers. This is very important to my career.

When user responds to questions:

• RESEARCH_REQUEST ("research this", "check", "verify") → Dispatch research subagent
• UNKNOWN ("don't know", "not sure") → Dispatch research subagent
• CLARIFICATION (ends with ?) → Answer the clarification, then re-ask
• SKIP ("skip", "move on") → Proceed to next item

Invariant Principles

1. Dead Until Proven Alive - Every code item assumes dead status. Evidence of live callers required. No assumptions based on appearance.
2. Full-Graph Verification - Search entire codebase for each item. Check transitive callers. Re-scan after removals until fixed-point.
3. Data Flow Completeness - Track write→read pairs. Setter without getter = write-only dead. Iterator without consumer = dead storage.
4. Git Safety First - Check status, offer commit, offer worktree BEFORE any analysis or deletion. Never modify without explicit approval.
5. Evidence Over Confidence - Never claim test results without running tests. Never claim "unused" without grep proof. Paste actual output.

Inputs

Outputs

BEFORE_RESPONDING Checklist

Step 0: Have I completed Phase 0 (Git Safety)? If not, STOP and do it now.

• Did I check git status --porcelain?
• Did I offer to commit uncommitted changes?
• Did I offer worktree isolation (ALWAYS, even if no uncommitted changes)?

Step 1: What phase am I in? (git safety, scope selection, extraction, triage, verification, reporting, implementation)

Step 2: For verification - what EXACTLY am I checking usage of?

Step 3: What evidence would PROVE this item is used?

Step 4: What evidence would PROVE this item is dead?

Step 5: Could this be write-only dead code (setter called but getter never used)?

Step 6: Could this be transitive dead code (only used by dead code)?

Step 7: Have I checked ALL files for callers, not just nearby files?

Step 8: If claiming test results, have I ACTUALLY run the tests?

Step 9: If about to delete code, am I in a worktree or did I get explicit user permission?

Now proceed with confidence following this checklist.

Workflow Phases

Phase 0: Git Safety (MANDATORY)

ALWAYS check git state before any analysis. Dead code verification involves code deletion - protect user's work.

Step 1: Check for uncommitted changes

git status --porcelain

If output non-empty:

• Present to user: "You have uncommitted changes. Should I commit them first?"
• Options:
  • Yes - Ask for commit message and create commit
  • No, proceed anyway - Continue but warn about risks
  • Abort - Stop the analysis

Step 2: Worktree decision

ALWAYS ask about worktree, regardless of uncommitted changes. Protects main branch from experimental deletions.

Present to user: "Should I use a git worktree for dead code hunting? (Recommended)"

Explanation: "A worktree creates an isolated branch where I can safely delete code to test. Your main branch stays untouched. At the end, you review findings and decide what to apply."

Options:

• Yes, create worktree (Recommended) - Invoke using-git-worktrees skill
• No, work in current directory - Warn about risks, require explicit approval for deletions

If worktree selected:

1. Create branch: dead-code-hunt-YYYY-MM-DD-HHMM
2. All "remove and test" operations happen in worktree
3. Final report generated with findings
4. User decides what to apply to main branch

If worktree declined:

• Warning: "Working directly in your current directory. Any 'remove and test' verification will modify your working files."
• Require explicit approval before ANY file modifications

Step 3: Proceed to scope selection

Only after git safety confirmed, proceed to Phase 1.

Phase 1: Scope Selection

ALWAYS ask user to select scope before extracting any code items.

Use AskUserQuestion with these options:

After selection, identify target files:

• Branch: git diff $(git merge-base HEAD main)...HEAD --diff-filter=AM --name-only
• Uncommitted: git diff --diff-filter=AM --name-only + git diff --cached --diff-filter=AM --name-only
• Specific: User-provided paths
• Full repo: All code files matching language patterns

ARH Response Processing

After presenting scope options, process user response per ARH patterns.

Phase 2: Code Item Extraction

Extract ALL added code items from scoped files.

What to Extract

Language-Specific Patterns

Nim:

proc|func|method|macro|template|iterator NAME
type NAME = (object|enum|distinct|...)
field: TYPE in object definitions
import|from|include MODULE
const|let|var NAME at top level

Python:

def NAME, class NAME, import/from statements

TypeScript/JavaScript:

function NAME, class NAME, const/let/var at top level
export/import statements

Extraction Strategy

For each added/modified file in scope:

1. Get the diff of added lines: git diff <base> <file> | grep "^+"
2. Parse added lines for code item declarations
3. Record: {type, name, location, signature}
4. Group symmetric pairs (get/set, create/destroy, etc.)
5. For each setter/store call: Record corresponding getter/read pattern to check later
6. For each field assignment: Record field read patterns to check later

Phase 3: Initial Triage

Present ALL extracted items upfront before verification begins. User must see full scope.

Display items grouped by type with counts:

## Code Items Found: 47

### Procedures/Functions (23 items)
1. proc getDeferredExpr(t: PType): PNode - compiler/semtypes.nim:342
2. proc setDeferredExpr(t: PType, n: PNode) - compiler/semtypes.nim:349
3. proc clearDeferredExpr(t: PType) - compiler/semtypes.nim:356
...

### Type Fields (12 items)
24. deferredPragmas: seq[PNode] - compiler/ast.nim:234
...

### Symmetric Pairs Detected (4 groups)
Group A: getDeferredExpr / setDeferredExpr / clearDeferredExpr
Group B: sizeExpr / sizeExpr= (getter/setter)
...

Proceed with verification? (yes/no)

Symmetric Pairs: If you see getFoo / setFoo / clearFoo, or foo / foo=, group them. They often live or die together.

Phase 4: Verification

For EVERY code item, search the ENTIRE codebase for usages. Start from "dead" assumption.

Step 1: Generate "Dead Code" Claim

CLAIM: "proc getDeferredExpr is dead code"
ASSUMPTION: Unused until proven otherwise
LOCATION: compiler/semtypes.nim:342

Step 2: Search for Usage Evidence

Search Strategy:

1. Direct calls: grep -rn "getDeferredExpr" --include="*.nim" <repo_root>
2. Exclude definition: Filter out the line where it's defined
3. Check callers: Are there calls outside the definition?
4. Check exports: Is it exported and could be used externally?
5. Check dynamic invocation: Could it be called via reflection, eval, or string-based dispatch?

Evidence Categories:

Step 3: Write-Only Dead Code Detection

Check for code that STORES values but stored values are NEVER READ:

Patterns:

1. Setter without getter: setFoo() has callers but getFoo() has zero callers
2. Iterator without consumers: iterator items() defined but never used in for loops
3. Field assigned but never read: Field appears on LHS of = but never on RHS
4. Collection stored but never accessed: seq.add(x) called but seq never iterated

Algorithm:

FOR each setter/store found:
  Search for corresponding getter/read
  IF setter has callers BUT getter has zero:
    → WRITE-ONLY DEAD
    Mark BOTH setter and getter as dead (entire feature unused)

Step 4: Transitive Dead Code Detection

If item only called by other items, check if ALL callers are dead:

getDeferredExpr:
  - Called by: showDeferredPragmas (1 call)
  - showDeferredPragmas: Called by: nobody
  → BOTH are transitive dead code

Algorithm:

WHILE changes detected:
  FOR each item with callers:
    IF ALL callers are marked dead:
      Mark item as TRANSITIVE DEAD
  Repeat until no new transitive dead code found (fixed point)

Step 5: Remove and Test Verification (Optional)

For high-confidence dead code, offer experimental verification:

Protocol:

1. Ask user: "Would you like me to experimentally verify by removing and testing?"
2. If yes, create temporary git worktree or branch
3. Remove the suspected dead code
4. Run the test suite
5. If tests pass → definitive proof code was dead
6. If tests fail → code was used (or tests are incomplete)
7. Restore original state

When to offer:

• User uncertain about grep-based verdict
• Code looks "important" but has zero callers
• High-value cleanup (large amount of code)

Step 6: Symmetric Pair Analysis

For detected symmetric pairs:

IF ANY of {getFoo, setFoo, clearFoo} is ALIVE → all potentially alive
IF ALL are dead → entire group is dead
IF SOME alive, SOME dead → flag asymmetry for user review

Phase 5: Iterative Re-scanning

After identifying dead code, re-scan for newly orphaned code. Removal may cascade.

Why Re-scan:

Round 1: evaluateDeferredFieldPragmas → 0 callers → DEAD
Round 2: iterator deferredPragmas → only called by above → NOW TRANSITIVE DEAD
Round 3: setDeferredExpr → stores to iterator that's dead → NOW WRITE-ONLY DEAD

Re-scan Algorithm:

1. Mark initial dead code (zero callers)
2. Re-extract remaining items, excluding already-marked-dead
3. Re-run verification on remaining items
4. Check for newly transitive dead code
5. Check for newly write-only dead code (getter removed → setter orphaned)
6. Repeat until no new dead code found (fixed point)

Cascade Detection:

• If removal of A makes B dead → note "B depends on A" in report
• Present cascade chains: "Removing X enables removing Y, Z"

Phase 6: Report Generation

Generate markdown report that serves as both audit and implementation plan.

Report Template

# Dead Code Report

**Generated:** YYYY-MM-DDTHH:MM:SSZ
**Scope:** Branch feature/X (N commits since base)
**Items Analyzed:** N
**Dead Code Found:** N | **Alive:** N | **Transitive Dead:** N

## Summary

| Category | Dead | Alive | Notes |
|----------|------|-------|-------|
| Procedures | N | N | N transitive dead |
| Type Fields | N | N | |
| Imports | N | N | All used |

## Dead Code Findings

### High Confidence (Zero Callers)

#### 1. proc getDeferredExpr - DEAD
- **Location:** compiler/semtypes.nim:342
- **Evidence:** Zero callers in codebase
- **Search:** `grep -rn "getDeferredExpr"` → only definition found
- **Symmetric Pair:** Part of get/set/clear group; set/clear ARE used
- **Verdict:** Asymmetric API, getter never needed
- **Removal Complexity:** Simple - delete proc

### Transitive Dead Code

#### 2. proc showDeferredPragmas - TRANSITIVE DEAD
- **Location:** compiler/debug.nim:123
- **Evidence:** Only called by `dumpTypeInfo`, which is itself dead
- **Call Chain:** showDeferredPragmas ← dumpTypeInfo ← nobody
- **Verdict:** Dead because caller is dead

### Write-Only Dead Code

#### 3. iterator deferredPragmas - WRITE-ONLY DEAD
- **Location:** compiler/ast.nim:456
- **Evidence:** setDeferredExpr called 3 times, but iterator has ZERO callers
- **Write-Only Pattern:** Data is stored but never read
- **Verdict:** Entire deferred pragma storage feature is dead

## Alive Code (Verified Necessary)

#### 1. proc setDeferredExpr - ALIVE
- **Location:** compiler/semtypes.nim:349
- **Evidence:** 3 callers found
- **Callers:**
  - compiler/semtypes.nim:567 (in semGenericType)
  - compiler/pragmas.nim:234 (in processPragmas)
- **Verdict:** Necessary

## Implementation Plan

### Phase 1: Simple Deletions (Low Risk)
1. [ ] Delete `getDeferredExpr` proc (line 342)
2. [ ] Delete `importcExpr` field (line 237)

### Phase 2: Transitive Deletions
3. [ ] Delete `showDeferredPragmas` proc (line 123)

### Verification Commands

After each deletion, verify no references remain:
```bash
grep -rn "getDeferredExpr" compiler/ tests/
# Should return: no results

# Run tests
nim c -r tests/all.nim
# CRITICAL: Actually run this command and paste output

Risk Assessment

Next Steps

Would you like me to: A. Implement all deletions automatically B. Implement deletions one-by-one with approval C. Generate a git branch with deletions for review D. Just keep this report for manual implementation

---

## Phase 7: Implementation Prompt

After presenting report, ask:

Found N dead code items accounting for N lines.

Would you like me to: A. Remove all dead code automatically (I'll create commits) B. Remove items one-by-one with your approval C. Create a cleanup branch you can review D. Just keep the report, you'll handle it

Choose A/B/C/D:

### Implementation Strategy (if user chooses A or B)

Follow the writing-plans skill pattern:

1. **Create implementation plan** (already in report)
2. **For each deletion:**
   - Show the code to be removed
   - Show grep verification it's unused
   - Apply deletion
   - Re-verify with grep
   - Run tests if requested
3. **Create commit** after each logical group
4. **Final verification:** Run full test suite

---

## Detection Patterns (Pseudocode)

### Pattern 1: Asymmetric Symmetric API

IF getFoo exists AND setFoo exists AND clearFoo exists: Check usage of each independently IF any has zero callers → flag as dead EVEN IF others in group are used

### Pattern 2: Convenience Wrapper

IF proc foo() only calls bar() with minor transform: Check if foo has callers IF zero callers → dead wrapper EVEN IF bar() is heavily used

### Pattern 3: Transitive Dead Code

WHILE changes detected: FOR each item with callers: IF ALL callers are marked dead: Mark item as transitive dead

### Pattern 4: Field + Accessors

IF field X detected: Search for getter getX or X Search for setter setX or X= IF all three have zero usage → dead feature

### Pattern 5: Test-Only Usage

IF all callers are in test files: ASK user if test-only code should be kept Don't auto-mark as dead

### Pattern 6: Write-Only Dead Code

FOR each setter/store S with corresponding getter/read G: IF S has callers AND G has zero callers: Mark BOTH S and G as write-only dead Mark data is "stored but never read"

### Pattern 7: Iterator Without Consumers

IF iterator I defined: Search for "for .* in I" or "items(I)" patterns IF zero consumers found: Mark iterator as dead Check if backing storage is also write-only dead

---

<FORBIDDEN>
### Pattern 1: Marking Code as "Used" Without Evidence
- Assuming code is used because it "looks important"
- Marking as alive because "it might be called dynamically" without checking
- Skipping verification because "it's probably needed"
**Reality**: Every item needs grep proof of callers or it's dead.

### Pattern 2: Incomplete Search
- Only searching nearby files
- Only searching same directory
- Not checking test directories
- Not checking if it's exported
**Reality**: Search the ENTIRE codebase, including tests.

### Pattern 3: Ignoring Transitive Dead Code
- Marking code as "used" because something calls it
- Not checking if the caller is itself dead
- Stopping after first-level verification
**Reality**: Build the call graph, check transitivity.

### Pattern 4: Deleting Without User Approval
- Auto-removing code without showing the plan
- Batch-deleting without per-item verification
- Not offering user choice in implementation
**Reality**: Present report, get approval, then implement.

### Pattern 5: Claiming Test Results Without Running Tests
- Stating "tests fail" without actually running the test command
- Claiming code "doesn't work" without execution evidence
- Saying "tests pass" after removal without running them
**Reality**: Run the actual command. Paste the actual output.

### Pattern 6: Missing Write-Only Dead Code
- Only checking if code is called, not if stored data is read
- Not verifying iterator/getter counterparts exist for setter/store
- Assuming "something calls it" means "code is used"
**Reality**: Check the full data flow. Code that stores without reading is dead.

### Pattern 7: Single-Pass Verification
- Marking code as "alive" or "dead" in one pass
- Not re-scanning after identifying dead code
- Missing cascade effects where removal orphans other code
**Reality**: Re-scan iteratively until no new dead code found.

### Pattern 8: Deleting Code Without Git Safety
- Running "remove and test" without checking git status first
- Deleting code without worktree isolation
- Not offering to commit uncommitted changes
- Skipping worktree recommendation
**Reality**: ALWAYS check git status in Phase 0. ALWAYS offer worktree isolation.
</FORBIDDEN>

---

## Complete Example

**User**: "Find dead code in my current branch"

**Step 0 - Git Safety**:
```bash
git status --porcelain

Agent: "I see you have uncommitted changes in 2 files:

• compiler/ast.nim (modified)
• tests/test_pragmas.nim (new file)

Should I commit these changes first? A. Yes, commit them (I'll ask for a commit message) B. No, proceed anyway (risky if we do remove-and-test) C. Abort the analysis"

User: A

Agent: "What commit message should I use?"

User: "WIP: deferred pragma implementation"

git add .
git commit -m "WIP: deferred pragma implementation"

Agent: "Committed! Now, should I use a git worktree for dead code hunting?

This is recommended because:

• Creates an isolated branch (dead-code-hunt-2025-12-30-1430)
• All 'remove and test' operations happen there
• Your current branch stays untouched
• You review findings and decide what to apply

Options: A. Yes, create worktree (Recommended) B. No, work in current directory

Choose A or B:"

User: A

Agent: "Creating worktree..."

# Worktree creation via using-git-worktrees skill

"Worktree created at ../nim-dead-code-hunt. All analysis and testing will happen there."

Step 1 - Scope Selection:

What should I analyze?
A. Branch changes (all code added since merge-base with devel) [Recommended]
B. Uncommitted changes only
C. Specific files (you provide paths)
D. Full repository (use carefully)

User selects: A

Step 2 - Extraction:

Analyzing branch feature/generic-deferred-pragmas (2 commits since devel)...

Extracting code items from 3 modified files:
- compiler/ast.nim
- compiler/semtypes.nim
- compiler/pragmas.nim

Step 3 - Triage:

## Code Items Found: 12

### Procedures (7 items)
1. proc getDeferredExpr(t: PType): PNode - semtypes.nim:342
2. proc setDeferredExpr(t: PType, n: PNode) - semtypes.nim:349
3. proc clearDeferredExpr(t: PType) - semtypes.nim:356
4. proc `sizeExpr=`(t: PType, n: PNode) - semtypes.nim:380
5. proc sizeExpr(t: PType): PNode - semtypes.nim:386
6. proc `alignExpr=`(t: PType, n: PNode) - semtypes.nim:387
7. proc alignExpr(t: PType): PNode - semtypes.nim:393

### Type Fields (4 items)
8. deferredPragmas: seq[PNode] - ast.nim:234
9. sizeExpr: PNode - ast.nim:235
10. alignExpr: PNode - ast.nim:236
11. importcExpr: PNode - ast.nim:237

### Iterators (1 item)
12. iterator deferredPragmas(t: PType): PNode - ast.nim:456

### Symmetric Pairs Detected
- Group A: getDeferredExpr / setDeferredExpr / clearDeferredExpr
- Group B: sizeExpr / sizeExpr=
- Group C: alignExpr / alignExpr=

Proceed with verification? (yes)

Step 4 - Verification (showing two items):

Item 1: proc getDeferredExpr

• Claim: "getDeferredExpr is dead code"
• Search: grep -rn "getDeferredExpr" compiler/ tests/
• Results:

  compiler/semtypes.nim:342:proc getDeferredExpr(t: PType): PNode =
  

  (only the definition)
• Callers: ZERO
• Symmetric Pair Check: setDeferredExpr has 3 callers, clearDeferredExpr has 1 caller
• Verdict: DEAD - Getter never needed, only set/clear used

Item 8: iterator deferredPragmas

• Claim: "deferredPragmas iterator is dead code"
• Search: grep -rn "deferredPragmas" compiler/ tests/
• Results:

  compiler/ast.nim:456:iterator deferredPragmas(t: PType): PNode =
  compiler/ast.nim:234:  deferredPragmas: seq[PNode]
  compiler/semtypes.nim:567:  sym.setDeferredExpr(word, expr)  # stores to field
  

• Write-Only Check: setDeferredExpr stores data, but iterator has ZERO callers
• Callers: ZERO for iterator
• Data Flow: Data is STORED but NEVER READ
• Verdict: WRITE-ONLY DEAD

Step 5 - Iterative Re-scan:

After marking getDeferredExpr as dead, re-scan:

Round 2 discoveries:

• iterator deferredPragmas → NOW detectable as write-only
• proc evaluateDeferredFieldPragmas → Transitive dead

Round 3 discoveries:

• setDeferredExpr → NOW detectable as write-only dead

No new dead code found → Fixed point reached

Step 6 - Remove and Test Verification:

User: "I'm not sure about deferredPragmas, it looks important"

Agent: "I understand. Let me experimentally verify:

git checkout -b verify-dead-code-temp

# Remove deferredPragmas iterator and related code
# ... (edits made) ...

nim c -r tests/all.nim

Test output:

[TEST] Running 1247 tests...
[PASS] All tests passed in 23.4s

Tests passed! This confirms deferredPragmas was dead code. Restoring original state..."

Step 7 - Implementation Prompt:

Found 4 dead code items accounting for approximately 35 lines:
- 1 unused getter (getDeferredExpr)
- 1 write-only iterator (deferredPragmas)
- 2 transitive dead items (found in re-scan)

Would you like me to:
A. Remove all dead code automatically
B. Remove items one-by-one with approval
C. Create a cleanup branch for review
D. Just keep the report

Choose A/B/C/D:

Self-Check

Git Safety (Phase 0):

• Did I check git status before starting?
• Did I offer worktree isolation before any "remove and test"?
• If user has uncommitted changes, did I offer to commit them?
• If user declined worktree, did I warn about risks?

Scope Selection (Phase 1):

• Did I ask user to select scope first?

Extraction & Triage (Phases 2-3):

• Did I present ALL extracted items for triage?

Verification (Phase 4):

• For each item: did I search the ENTIRE codebase for callers?
• Did I check for write-only dead code?
• Did I check for transitive dead code?
• Did I analyze symmetric pairs as groups?
• Does every "dead" verdict have grep evidence?
• If I claimed test results, did I ACTUALLY run the tests?
• Did I offer "remove and test" for uncertain cases?

Re-scanning (Phase 5):

• Did I re-scan iteratively for newly orphaned code?

Reporting & Implementation (Phases 6-7):

• Did I generate an implementation plan with the report?
• Am I waiting for user approval before deleting anything?

IF ANY UNCHECKED: STOP and fix before proceeding.

CRITICAL GIT SAFETY (Phase 0): NEVER skip git safety checks before starting analysis. NEVER delete code without checking git status first. NEVER run "remove and test" without offering worktree isolation. ALWAYS check for uncommitted changes and offer to commit them. ALWAYS offer worktree isolation (recommended for all cases).

VERIFICATION RIGOR: NEVER mark code as "used" without concrete evidence of callers. NEVER skip searching the entire codebase for usages. NEVER miss write-only dead code (stored but never read). NEVER ignore transitive dead code. NEVER claim test results without running tests. NEVER delete code without user approval. NEVER skip iterative re-scanning after finding dead code. ALWAYS assume dead until proven alive. ALWAYS verify claims with actual execution.

Exact protocol compliance is vital to my career. This is very important to my career. Strive for excellence. Achieve outstanding results through rigorous verification.