s-debug

Systematic debugging and error recovery for WoW addons.

Related Commands

• c-debug - Reload loop workflow for finding and fixing issues
• c-review - 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

1. Evidence-Based Debugging — Hypothesis-driven investigation with runtime instrumentation and log proof
2. Error Analysis — Parse Lua errors, identify root cause in stack traces
3. Taint Investigation — Track secure/insecure code interaction and "Action blocked" issues
4. Combat Issues — Debug lockdown-related failures and protected frame issues
5. 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 | | Lua errors, nil values | references/error-patterns.md | | Debug workflow, isolation | references/debugging-strategies.md | | Error tracking (BugGrabber) | ../../docs/integration/errors.md | | Troubleshooting guide | ../../docs/integration/troubleshooting.md | | Structured logging | ../../docs/integration/console.md | | Frame inspection | ../../docs/integration/inspect.md |

Debug Output Best Practice

CRITICAL: Use MechanicLib:Log() instead of print() 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

1. Gather Evidence: Ask user to /reload, wait for confirmation, then addon.output(agent_mode=true)
2. Isolate: Can you reproduce with minimal code?
3. Hypothesis: "If X then Y because Z"
4. Fix & Validate: Apply minimal fix, ask user to /reload and confirm, then verify with addon.output.