SKILL.md
Debugging WoW Addons
Systematic debugging and error recovery for WoW addons.
Related Commands
- [c-debug](../../commands/c-debug.md) - Reload loop workflow for finding and fixing issues
- [c-review](../../commands/c-review.md) - Full code review (includes debug step)
MCP Tools (Use These First)
MANDATORY: ALWAYS use MCP tools directly instead of the shell.
| Task | MCP Tool |
|---|---|
| Get All Output | addon.output(agent_mode=true) |
| Lint Addon | addon.lint(addon="MyAddon") |
| Scan Deprecations | addon.deprecations(addon="MyAddon") |
| Queue Lua Eval | lua.queue(code=["GetMoney()"]) |
| Get Eval Results | lua.results() |
Capabilities
- Evidence-Based Debugging — Hypothesis-driven investigation with runtime instrumentation and log proof
- Error Analysis — Parse Lua errors, identify root cause in stack traces
- Taint Investigation — Track secure/insecure code interaction and "Action blocked" issues
- Combat Issues — Debug lockdown-related failures and protected frame issues
- API Failures — Handle deprecated or changed APIs (Midnight 12.0 prep)
Routing Logic
| Request type | Load reference |
|---|---|
| Evidence-based debugging, hypothesis-driven | [references/evidence-based-debugging.md](references/evidence-based-debugging.md) |
| Lua errors, nil values | [references/error-patterns.md](references/error-patterns.md) |
| Debug workflow, isolation | [references/debugging-strategies.md](references/debugging-strategies.md) |
| Error tracking (BugGrabber) | [../../docs/integration/errors.md](../../docs/integration/errors.md) |
| Troubleshooting guide | [../../docs/integration/troubleshooting.md](../../docs/integration/troubleshooting.md) |
| Structured logging | [../../docs/integration/console.md](../../docs/integration/console.md) |
| Frame inspection | [../../docs/integration/inspect.md](../../docs/integration/inspect.md) |
Debug Output Best Practice
CRITICAL: Use
MechanicLib:Log()instead ofprint()for all debug output.
| Feature | print() |
MechanicLib:Log() |
|---|---|---|
| Agent access | ❌ Requires screenshot | ✅ addon.output retrieves directly |
| Filtering | ❌ None | ✅ Source + category filters |
| Copyable | ❌ No | ✅ Yes, via Console export |
-- ✅ Correct: Agent can see this in addon.output
local MechanicLib = LibStub("MechanicLib-1.0", true)
if MechanicLib then
MechanicLib:Log("MyAddon", "Debug: value=" .. tostring(val), MechanicLib.Categories.CORE)
end
-- ❌ Avoid: Spams chat, requires screenshot
print("[MyAddon] Debug: value=" .. tostring(val))Quick Reference
Get Addon Data (Compressed for AI)
Ask user to /reload and confirm, then:
addon.output(agent_mode=true)Common Error Patterns
attempt to index nil value: API returned nil, check if unit exists or data is loaded.Action blocked by Blizzard: You tried to call a protected function in combat.Interface action failed: Taint has spread to a secure UI component.
Systematic Workflow
- Gather Evidence: Ask user to
/reload, wait for confirmation, thenaddon.output(agent_mode=true) - Isolate: Can you reproduce with minimal code?
- Hypothesis: "If X then Y because Z"
- Fix & Validate: Apply minimal fix, ask user to
/reloadand confirm, then verify withaddon.output.