ojowwalker77/claude-matrix/nuke

Matrix Nuke

Comprehensive codebase hygiene analysis. Detects dead code, unused imports, orphaned files, circular dependencies, stale TODOs, unnecessary comments, overengineered dependencies, and more across 11 categories.

Tip: This skill runs in a forked context for unbiased analysis - clean slate, no conversation history bias.

Architecture

ORCHESTRATOR (parse mode, dispatch agents, aggregate report)
     |
     +-- STRUCTURAL AGENT --> dead exports, orphaned files, unused imports
     +-- CIRCULAR DEP AGENT --> import cycle detection
     +-- DEPENDENCY AGENT --> unused npm packages, overengineered deps
     +-- GENERATIVE AGENT --> comments, console.log, copy-paste, TODOs
     +-- TRIAGE AGENT --> confidence scoring, safety filtering, tiering

Usage

Parse user arguments from the skill invocation (text after the trigger phrase).

Expected format: /nuke [mode] [path]

Modes

Path Filtering

Append a path to any mode to limit scope:

• /nuke scan src/api/ - only scan src/api/
• /nuke this src/utils/auth.ts - single file

Examples

/nuke                        # Full scan, report only
/nuke scan                   # Same as above
/nuke this src/utils/auth.ts # Single file analysis
/nuke scan src/api/          # Scan specific directory
/nuke safe                   # High-confidence findings only
/nuke aggressive             # Medium+ confidence findings

Pipeline

Follow the orchestration detailed in references/nuke-pipeline.md:

1. Pre-flight - Check index availability (matrix_index_status), detect entry points from package.json, parse mode
2. Structural Analysis - Use matrix_find_dead_code for dead exports + orphaned files
3. Circular Dep Detection - Use matrix_find_circular_deps for import cycles
4. Dependency Analysis - Read package.json, cross-reference with actual imports via Grep
5. Generative Analysis - AI inspection of files for comments, console.log, duplication, TODOs
6. Triage - Apply safety rules, assign confidence scores, classify into tiers
7. Report - Generate formatted output per references/output-format.md

Early exit for `/nuke this`: Only run Structural + Generative agents on that single file. Skip dependency and circular dep analysis.

Graceful degradation: If index is unavailable, fall back to Grep-based analysis. Report reduced accuracy.

What Gets Detected (11 Categories)

Structural (deterministic, via MCP tools)

1. Dead exports - exported symbols with zero callers across the codebase
2. Orphaned files - files that nothing imports (excluding entry points)
3. Circular dependencies - import cycles in the dependency graph
4. Unused npm packages - in package.json but never imported
5. Unused imports - imports brought in but never referenced in the file

Generative (AI judgment required)

1. Unnecessary comments - obvious/redundant comments (// increment i, // constructor)
2. Commented-out code - dead code hiding in comments (contains {, =, function, return)
3. Console.log leftovers - console.log and console.debug left from debugging (NOT console.error)
4. Overengineered deps - libraries replaceable with native APIs (lodash.get -> ?., moment -> Intl)
5. Copy-paste duplication - near-identical code blocks (5+ similar consecutive lines)
6. Stale TODO/FIXME - ancient TODOs with no linked issues and old git blame dates

Safety Rules

See references/safety-rules.md for full details. Key rules:

• Never flag entry points - index.ts, main.ts, bin/*, package.json main/module/exports
• Never flag framework conventions - pages/, routes/, app/, .config., migrations/
• Never flag dynamically imported modules - import(), require() references
• Never flag public API surface - root barrel exports, @public JSDoc
• Respect .nukeignore - if present, honor it like .gitignore

Additional Resources

• `references/nuke-pipeline.md` - Full orchestrator pipeline
• `references/agents/structural-agent.md` - Dead code detection via MCP tools
• `references/agents/generative-agent.md` - AI-judged detection patterns
• `references/agents/dependency-agent.md` - Package analysis and native alternatives
• `references/agents/triage-agent.md` - Confidence scoring and safety filtering
• `references/safety-rules.md` - Entry point detection, what NOT to flag
• `references/output-format.md` - Report template