---

name: s-debug description: > Diagnose and fix bugs using evidence-based investigation. Requires runtime evidence before fixes—never guess based on code alone. Covers hypothesis-driven debugging, instrumentation logging, Lua errors, taint issues, combat lockdown, and API failures. Triggers: error, bug, debug, fix, crash, taint, nil value, diagnose, hypothesis, runtime, evidence, instrumentation.

Debugging WoW Addons

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.

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

Debug Output Best Practice

CRITICAL: Use MechanicLib:Log() instead of print() for all debug output.

Copy-- ✅ 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:

Copyaddon.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.