remove-deadcode

name	remove-deadcode
description	Remove unused code from this project with LSP-verified safety and parallel task subagents for atomic removal batches. Triggers: 'remove dead code', 'dead code', 'cleanup', 'remove unused'.

Dead code removal via massively parallel task subagents. You are the ORCHESTRATOR — you scan, verify, batch, then delegate ALL removals to parallel agents.

- **LSP is law.** Verify with `lsp(action: "references")` before ANY removal decision. - **Never remove entry points.** `src/index.ts`, `src/cli/index.ts`, test files, config files, `packages/` — off-limits. - **You do NOT remove code yourself.** You scan, verify, batch, then fire `task` subagents. They do the work.

Hard Preconditions

1. You are in the main session, not a background subagent. Phase 4 fans out 5–10 parallel task subagents; a parent task agent MUST NOT load this skill (it would recurse and trip OMP's 16-concurrent-subagent cap).
2. Before dispatching a batch, check live peer count with irc (op:"list") and keep total concurrent subagents ≤ 10 to leave headroom.

NEVER mark as dead: - Symbols in `src/index.ts` or barrel `index.ts` re-exports - Symbols referenced in test files (tests are valid consumers) - Symbols with `@public` / `@api` JSDoc tags - Hook factories (`createXXXHook`), tool factories (`createXXXTool`), agent definitions in `agentSources` - Command templates, skill definitions, config files - Symbols in `package.json` exports

---

PHASE 1: SCAN — Find Dead Code Candidates

Run ALL of these in parallel:

Static unused-symbol scan (run this FIRST): detect the project toolchain and run its unused-symbol checker, e.g.:

# TypeScript (tsconfig.json / package.json): bunx tsc --noEmit --noUnusedLocals --noUnusedParameters
# Python (pyproject.toml):                   ruff check --select F401,F811,F841 .
# Go (go.mod):                               go vet ./... ; staticcheck ./...
# Rust (Cargo.toml):                         cargo check 2>&1 (dead_code warnings)

Pick the command matching the project's manifest. This yields the definitive list of unused locals, imports, parameters, and types with exact file:line locations. If the toolchain is unknown, fall back to search/ast_grep + lsp(action: "references") per symbol.

Explore agents (fire ALL simultaneously via one task() call):

task(
  agent: "explore",
  context: "Dead code scan. Return file paths and symbol names for candidates.",
  tasks: [
    {
      id: "OrphanFiles",
      role: "Orphaned file finder",
      description: "Find orphaned files",
      assignment: "Find files in src/ NOT imported by any other file. Check all import statements using search and find. EXCLUDE: index.ts, *.test.ts, entry points, .md, packages/. Return: file paths."
    },
    {
      id: "UnusedExports",
      role: "Unused export symbol finder",
      description: "Find unused exported symbols",
      assignment: "Find exported functions/types/constants in src/ that are never imported by other files. Cross-reference: for each export, use search to find the symbol name across src/ — if it only appears in its own file, it's a candidate. EXCLUDE: src/index.ts exports, test files. Return: file path, line, symbol name, export type."
    }
  ]
)

Collect all results into a master candidate list.

---

PHASE 2: VERIFY — LSP Confirmation (Zero False Positives)

For EACH candidate from Phase 1:

lsp(action: "references", file: "<filePath>", line: <line>, character: <character>)
// 0 references → CONFIRMED dead
// 1+ references → NOT dead, drop from list

Also apply the false-positive-guards above. Produce a confirmed list:

| # | File | Symbol | Type | Action |
|---|------|--------|------|--------|
| 1 | src/foo.ts:42 | unusedFunc | function | REMOVE |
| 2 | src/bar.ts:10 | OldType | type | REMOVE |
| 3 | src/baz.ts:7 | ctx | parameter | PREFIX _ |

Action types:

• REMOVE — delete the symbol/import/file entirely
• PREFIX _ — unused function parameter required by signature → rename to _paramName

If ZERO confirmed: report "No dead code found" and STOP.

---

PHASE 3: BATCH — Group by File for Conflict-Free Parallelism

Goal: maximize parallel agents with ZERO git conflicts.

1. Group confirmed dead code items by FILE PATH
2. All items in the SAME file go to the SAME batch (prevents two agents editing the same file)
3. If a dead FILE (entire file deletion) exists, it's its own batch
4. Target 5-10 batches (stay within OMP's 16-subagent cap with headroom). If fewer than 5 items total, use 1 batch per item.

Example batching:

Batch A: [src/hooks/foo/hook.ts — 3 unused imports]
Batch B: [src/features/bar/manager.ts — 2 unused constants, 1 dead function]
Batch C: [src/tools/baz/tool.ts — 1 unused param, src/tools/baz/types.ts — 1 unused type]
Batch D: [src/dead-file.ts — entire file deletion]

Files in the same directory CAN be batched together (they won't conflict as long as no two agents edit the same file). Maximize batch count for parallelism.

---

PHASE 4: EXECUTE — Fire Parallel Task Subagents

Fire ALL batches simultaneously in a single task() call:

Use the project's typecheck command in the agent context and verification below. The example uses bunx tsc --noEmit (TS/Bun); for other toolchains substitute the command detected in the scan phase.

task(
  agent: "task",
  context: "Dead code removal. Load and follow the git-master skill for commit discipline. Each agent handles one batch of files. Read the file, re-verify with lsp(action: 'references') that symbols are still dead, apply the removal, then run the project's typecheck via bash (e.g. 'bunx tsc --noEmit' for TS; substitute the toolchain command detected in the scan phase — ruff/pytest, go vet, cargo check) to verify. If it fails, revert with bash('git checkout -- [files]') and report failure. Stage ONLY your batch's files — NEVER git add -A.",
  tasks: [
    {
      id: "DeadcodeBatchA",
      role: "Dead code remover — batch A specialist",
      description: "Remove dead code batch A: [brief description]",
      assignment: "## TASK: Remove dead code from [file list]\n\n## DEAD CODE TO REMOVE\n\n### [file path] line [N]\n- Symbol: `[name]` — [type: unused import / unused constant / unused function / unused parameter / dead file]\n- Action: [REMOVE entirely / REMOVE from import list / PREFIX with _]\n\n## PROTOCOL\n\n1. Read each file to understand exact syntax at the target lines\n2. For each symbol, run lsp(action: 'references') to RE-VERIFY it's still dead (another agent may have changed things)\n3. Apply the change:\n   - Unused import (only symbol in line): remove entire import line\n   - Unused import (one of many): remove only that symbol from the import list\n   - Unused constant/function/type: remove the declaration. Clean up trailing blank lines.\n   - Unused parameter: prefix with `_` (do NOT remove — required by signature)\n   - Dead file: delete with bash('rm <file>')\n4. After ALL edits in this batch, run: bash('bunx tsc --noEmit')\n5. If typecheck fails: bash('git checkout -- [files]') and report failure\n6. If typecheck passes: report what you removed\n\n## CRITICAL\n- Stage ONLY your batch's files. NEVER git add -A — other agents are working in parallel.\n- If typecheck fails after your edits, REVERT all changes and report. Do not attempt to fix.\n- Pre-existing test failures in other files are expected. Only typecheck matters for your batch."
    },
    {
      id: "DeadcodeBatchB",
      role: "Dead code remover — batch B specialist",
      description: "Remove dead code batch B: [brief description]",
      assignment: "[same structure, different files]"
    }
    // ... one task per batch
  ]
)

Wait for all batch agents to complete.

---

PHASE 5: FINAL VERIFICATION

After ALL agents complete:

# Run the project's own typecheck / test / build (detected in the scan phase). Examples:
#   TS:   bunx tsc --noEmit && bun test && bun run build
#   Py:   ruff check . && pytest -q
#   Go:   go vet ./... && go test ./... && go build ./...
#   Rust: cargo check && cargo test && cargo build

Produce summary:

## Dead Code Removal Complete

### Removed
| # | Symbol | File | Type | Agent |
|---|--------|------|------|-------|
| 1 | unusedFunc | src/foo.ts | function | Batch A |

### Skipped (agent reported failure)
| # | Symbol | File | Reason |
|---|--------|------|--------|

### Verification
- Typecheck: PASS/FAIL
- Tests: X passing, Y failing (Z pre-existing)
- Build: PASS/FAIL
- Total removed: N symbols across M files
- Parallel agents used: P

---

SCOPE CONTROL

If $ARGUMENTS is provided, narrow the scan:

• File path → only that file
• Directory → only that directory
• Symbol name → only that symbol
• all or empty → full project scan (default)

ABORT CONDITIONS

STOP and report if:

• More than 50 candidates found (ask user to narrow scope or confirm proceeding)
• Build breaks and cannot be fixed by reverting