home / skills / falkicon / mechanic / s-clean

s-clean skill

safe

This skill helps you clean WoW addon code by finding dead code and stale docs, guiding safe removal and hygiene improvements.

npx playbooks add skill falkicon/mechanic --skill s-clean

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.9 KB

---
name: s-clean
description: >
  Find and remove dead code and stale documentation. Covers unused functions,
  orphaned files, dead links, and outdated references. Use for maintenance,
  pre-release cleanup, or codebase hygiene.
  Triggers: clean, dead code, unused, orphan, stale, cruft, maintenance.
---

# Cleaning WoW Addons

Expert guidance for finding and removing cruft in addon codebases.

## Related Commands

- [c-clean](../../commands/c-clean.md) - Cleanup workflow
- [c-review](../../commands/c-review.md) - Full review (includes clean step)

## MCP Tools

| Task | MCP Tool |
|------|----------|
| Find Dead Code | `addon.deadcode(addon="MyAddon")` |
| Find Stale Docs | `docs.stale(addon="MyAddon")` |
| Filter by Confidence | `addon.deadcode(addon="MyAddon", include_suspicious=false)` |

## Capabilities

1. **Dead Code Detection** — Find unused functions, orphaned files, dead exports
2. **Stale Docs Detection** — Find broken links, outdated refs, version drift
3. **Confidence Levels** — Definite (100%), Likely (90%+), Suspicious (70%+)

## Detection Categories

### Dead Code (`addon.deadcode`)

| Category | Description |
|----------|-------------|
| `unused_function` | Functions defined but never called |
| `orphaned_file` | Lua files not in TOC |
| `dead_export` | Exported values never used |
| `unused_library` | Libraries in Libs/ never used |
| `stale_event` | Event handlers for unregistered events |
| `commented_code` | Large blocks of commented-out code |

### Stale Docs (`docs.stale`)

| Category | Description |
|----------|-------------|
| `dead_link` | Internal links to non-existent files |
| `dead_reference` | Mentions of functions/files that don't exist |
| `version_drift` | Old version numbers in documentation |
| `relative_staleness` | Docs not updated in many commits |

## Workflow

### Quick Cleanup

1. Run `addon.deadcode` with `include_suspicious=false` for high-confidence issues only
2. Remove identified dead code
3. Run `docs.stale` to find documentation issues
4. Fix broken links and update outdated references

### Deep Cleanup

1. Run `addon.deadcode` with all confidence levels
2. Manually verify suspicious findings before removal
3. Run `docs.stale` with all techniques
4. Update documentation to match current code

## Confidence Interpretation

| Level | Meaning | Action |
|-------|---------|--------|
| **Definite** | 100% certain (e.g., file not in TOC) | Safe to remove |
| **Likely** | 90%+ certain (e.g., function never called) | Review briefly, usually safe |
| **Suspicious** | 70%+ certain (e.g., dynamic code patterns) | Manual verification required |

## Best Practices

1. **Start with definite issues** — These are safe to fix immediately
2. **Check dynamic patterns** — `_G`, `rawget`, `loadstring` may hide usage
3. **Preserve intentional dead code** — Mark with `-- KEEP:` comment if needed
4. **Update docs after code changes** — Run `docs.stale` after refactoring

Overview

This skill helps find and remove dead code and stale documentation in World of Warcraft addon projects. It targets unused functions, orphaned files, broken links, and outdated references to improve codebase hygiene. Use it for routine maintenance, pre-release cleanups, or to shrink and clarify a repository before sharing.

How this skill works

The skill runs static inspections across Lua source files and documentation to detect categories of cruft with confidence scoring. It reports definite, likely, and suspicious findings so you can safely remove obvious trash and manually verify ambiguous cases. It also provides dedicated checks for documentation drift and dead links and supports filtering by confidence level.

When to use it

Before releasing a new addon version to reduce size and regressions
During maintenance sweeps to remove accumulated cruft
After refactors to identify leftover exports, files, or comments
When preparing a public repo or submitting to an addon site
To audit docs and fix broken links and outdated references

Best practices

Start with definite findings (100%) — safe to remove immediately
Run with include_suspicious=false for a fast, high-confidence pass
Manually verify suspicious results, especially around dynamic globals and loadstring
Mark intentional dead code with a clear KEEP: comment to avoid future removal
Always run docs checks after code changes and update version numbers

Example use cases

Quick cleanup: run deadcode with suspicious excluded, delete definite items, then run docs stale
Deep cleanup: run all confidence levels, manually review suspicious findings, reconcile docs
CI step: add a pre-release check that fails on new dead links or orphaned files
Refactor audit: detect dead exports and unused libraries after API changes
Repository trim: remove commented-out blocks and orphaned Lua files not in TOC

FAQ

What does each confidence level mean?

Definite is 100% certain (safe to remove), Likely is 90%+ (review briefly), Suspicious is 70%+ (requires manual verification).

How do I avoid removing intentional dead code?

Annotate intentional keeps with a clear comment like -- KEEP: and run the tool so those patterns are ignored or manually skipped.