nexus-slop-killer

name	nexus-slop-killer
description	Dead code detection and removal skill for NEXUS. Finds and eliminates unused imports, orphan exports, ghost components, dead types, console.logs, commented code, unused dependencies, and stale TODO/FIXME comments. Three modes: audit (report only), clean (safe removals), deep (aggressive with confirmation). Always load nexus-core first.

NEXUS Slop Killer — Dead Code Elimination (Layer 1)

Prerequisite: Load nexus-core kernel before running this skill.

---

Modes of Operation

Mode: audit (safe, read-only)

Scans and reports slop without touching any files. Produces a categorized report with file paths, line numbers, and confidence scores.

Mode: clean (safe removals)

Removes items that are definitively dead code:

• Unused imports
• Unused local variables
• console.log / console.warn / console.error in production code
• Commented-out code blocks (>3 lines)
• Empty catch blocks

Mode: deep (aggressive, with confirmation)

Everything in clean plus:

• Orphan exports (exported but never imported anywhere)
• Ghost components (.tsx files never referenced by any route or component)
• Dead types/interfaces (defined but never used)
• Unused dependencies in package.json
• Stale TODO/FIXME/HACK comments
• Redundant files (.bak, .old, Copy of...)

ALWAYS ask for confirmation before executing deep mode.

---

Detection Categories

1. Dead Imports

# Detection: find imports not referenced in the rest of the file
# Tool: TypeScript compiler (tsc --noUnusedLocals) or manual grep
# Confidence: HIGH — safe to remove

Search pattern: For each .ts/.tsx file, check if every named import is referenced at least once below the import line.

2. Orphan Exports

# Detection: exported symbol not imported by ANY other file
# Method: grep -r "from.*/{filename}" across entire src/
# Confidence: MEDIUM — verify it's not dynamically imported or used in tests

Exceptions — do NOT flag:

• Exports from index.ts barrel files
• Types exported for external consumers (API contracts)
• Components in src/ui/components/common/ (may be used in future)
• Store actions (used via useStore.getState())

3. Ghost Components

# Detection: .tsx file in src/ui/ not imported by any other file
# Method: grep -r "from.*/{ComponentName}" across src/ — 0 results = ghost
# Confidence: MEDIUM — check App.tsx lazy imports and dynamic imports

Verification: Before flagging, also check:

• React.lazy(() => import('./...')) patterns in App.tsx
• Dynamic imports anywhere in the codebase
• Storybook or test files that reference it

4. Dead Types/Interfaces

# Detection: type or interface defined in src/types/ but never imported
# Method: grep -r "from.*types.*{TypeName}" across src/
# Confidence: MEDIUM — some types used only via type inference

5. Console Statements

# Detection: console.log/warn/error in src/ (excluding tests and setup)
# Method: grep -rn "console\.(log|warn|error)" src/ --include="*.ts" --include="*.tsx"
# Exclude: src/tests/, src/setupTests.ts, files with "debug" in name
# Confidence: HIGH — should not be in production

CRITICAL EXCEPTION: Never remove console.error inside catch blocks that re-throw — these are intentional error logging.

6. Commented Code

# Detection: blocks of 3+ consecutive lines starting with //
# Also: blocks wrapped in /* ... */ containing code-like patterns
# Confidence: HIGH if contains code syntax (function, const, return, import)
# Confidence: LOW if looks like documentation

7. Stale TODO/FIXME/HACK

# Detection: comments containing TODO, FIXME, HACK, XXX, TEMP
# Method: grep -rn "TODO\|FIXME\|HACK\|XXX\|TEMP" src/ --include="*.ts" --include="*.tsx"
# Confidence: MEDIUM — some may be intentional reminders

8. Unused Dependencies

# Detection: package in package.json not imported by any source file
# Method: for each dep, grep -r "from.*{dep}" src/ + grep -r "require.*{dep}" src/
# Exclude: vite plugins, tailwind plugins, postcss, types-only packages (@types/*)
# Confidence: MEDIUM — some deps used in config files (vite.config, tailwind.config)

9. Duplicate/Stale Files

# Detection: .bak, .old, .backup, Copy of, .tmp files
# Also: files with same name in different locations (potential duplicates)
# Confidence: HIGH for backup extensions

---

Safety Rules

NEVER remove:

1. Anything in RED ZONE files (see nexus-core File Zones) without running protocol-integrity
2. Exports from service files — may be used by Cloud Functions or tests
3. Types from PatientTypes.ts — single source of truth, used across entire codebase
4. Barrel exports (index.ts re-exports) — breaking these breaks downstream
5. Store actions — may be called via getState() which grep won't find
6. Firestore collection names — hardcoded strings, not import references
7. CSS classes — Tailwind purges unused classes at build time already
8. Test files or test utilities — even if they seem unused
9. console.error in catch blocks that re-throw
10. Data files in src/data/ — static catalogs referenced by variable name

ALWAYS verify after removal:

# Step 1: TypeScript still compiles
npx tsc --noEmit

# Step 2: Build still works
npx vite build

# Step 3: Tests still pass (if clean/deep mode)
npx vitest run

# Step 4: No new errors introduced
# Compare test count before and after — must be equal or higher

---

Report Format

After running in any mode, produce this report:

## Slop Killer Report — [DATE]
**Mode:** audit | clean | deep
**Scope:** [file | module | all]

### Summary
| Category | Found | Removed | Skipped |
|----------|-------|---------|---------|
| Dead imports | X | X | X |
| Orphan exports | X | — | X |
| Ghost components | X | — | X |
| Dead types | X | — | X |
| Console statements | X | X | X |
| Commented code | X | X | X |
| TODO/FIXME | X | — | X |
| Unused deps | X | — | X |
| Stale files | X | — | X |

### Top Offenders (files with most slop)
1. `path/to/file.ts` — X issues
2. ...

### Details per Category
[itemized list with file:line for each finding]

### Verification
- tsc --noEmit: PASS/FAIL
- vite build: PASS/FAIL
- vitest run: PASS/FAIL (X/Y tests)

---

Integration with Quality Gates

After clean or deep mode:

1. Run regression-shield (Layer 2) to verify no tests broke
2. If protocols were touched, run protocol-integrity (Layer 2)
3. Compare build size before/after (slop removal should reduce bundle)