dead-code

GitNexus Dead Code Detector

CLI ONLY — no MCP server exists. Never use readMcpResource with gitnexus:// URIs.

Find orphan functions, dangling imports, isolated files, and unreachable code using the GitNexus knowledge graph.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use

• Periodic codebase cleanup
• Before a major release to reduce surface area
• After a refactor to find newly orphaned code
• "Are there any unused functions?"

For language-specific dead code tools (vulture, knip, clippy): use quality-tools:dead-code-detector instead. This skill uses the GitNexus graph for cross-file structural analysis.

Workflow

Step 0: Pre-flight — Ensure CLI Is Callable

The gitnexus binary is installed via npm/mise. The mise shim may fail if node isn't active in the current project. Run this pre-flight before any gitnexus command:

# Test if gitnexus is actually callable (not just a broken shim)
gitnexus --version 2>/dev/null || mise use [email protected]

All commands below run from the repo root. If multiple repos are indexed in the workspace, add --repo <repo-name> to specify the target. Otherwise --repo is optional.

Step 1: Auto-Reindex If Stale

gitnexus status

If stale (indexed commit ≠ HEAD), automatically reindex before proceeding — do not ask the user:

gitnexus analyze

Then re-check status to confirm index is current.

Step 2: Run Cypher Queries

Run these 4 queries to detect different categories of dead code:

Orphan Functions

Functions with no incoming CALLS edges and not participating in any process:

gitnexus cypher "MATCH (f:Function) WHERE NOT EXISTS { MATCH ()-[:CALLS]->(f) } AND NOT EXISTS { MATCH ()-[:STEP_IN_PROCESS]->(f) } RETURN f.name, f.file, f.line ORDER BY f.file LIMIT 50"

Dangling Imports

Import edges with low confidence (< 0.5), indicating potentially broken references:

gitnexus cypher "MATCH (a)-[r:IMPORTS]->(b) WHERE r.confidence < 0.5 RETURN a.name, b.name, r.confidence, a.file ORDER BY r.confidence LIMIT 30"

Dead Code (Unreachable)

Functions unreachable from any entry point — no callers and no process membership:

gitnexus cypher "MATCH (f:Function) WHERE NOT EXISTS { MATCH ()-[:CALLS]->(f) } AND NOT EXISTS { MATCH ()-[:STEP_IN_PROCESS]->(f) } AND NOT f.name STARTS WITH '_' AND NOT f.name STARTS WITH 'test_' RETURN f.name, f.file, f.line ORDER BY f.file LIMIT 50"

Isolated Files

Files with no imports in or out:

gitnexus cypher "MATCH (f:File) WHERE NOT EXISTS { MATCH (f)-[:IMPORTS]->() } AND NOT EXISTS { MATCH ()-[:IMPORTS]->(f) } RETURN f.path ORDER BY f.path LIMIT 30"

Step 3: Filter Results

Exclude false positives:

• Test files (**/test_*, **/tests/*, **/*_test.*) — test functions are legitimately "uncalled"
• __init__ files — may be legitimately empty or used for re-exports
• Entry points (main, cli, __main__) — called by the runtime, not by other code
• Private helpers prefixed with _ — may be used via dynamic dispatch

Step 4: Structured Report

Present categorized by module/directory:

## Dead Code Report

### Orphan Functions (N found)
| Function | File | Line |
|----------|------|------|
| ...      | ...  | ...  |

### Dangling Imports (N found)
| Source | Target | Confidence |
|--------|--------|------------|
| ...    | ...    | ...        |

### Isolated Files (N found)
- path/to/file.py
- ...

### Summary
- Total orphans: N
- Total dangling: N
- Total isolated: N

Notes

• Results depend on index freshness — reindex if results seem wrong
• The graph captures static relationships only — dynamic dispatch, reflection, and plugin loading may cause false positives
• Use quality-tools:dead-code-detector for language-specific analysis (vulture, knip, clippy) which complements this structural view

Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. Locate yourself. — Find this SKILL.md's canonical path before editing.
1. What failed? — Fix the instruction that caused it.
2. What worked better than expected? — Promote to recommended practice.
3. What drifted? — Fix any script, reference, or dependency that no longer matches reality.
4. Log it. — Evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.