| name | roblox-debug |
| description | Use when diagnosing Roblox or Luau errors, crashes, or unexpected behavior with an iterative reproduce, inspect, fix, and verify loop. |
| last_reviewed | "2026-07-12T00:00:00.000Z" |
| sources | ["original"] |
When to Load
Load when diagnosing errors, crashes, or unexpected behavior in Roblox/Luau code. Provides a structured 7-step iterative debug loop with a max of 5 iterations before escalating. Works in both file-sync and MCP modes.
Quick Reference
7-Step Debug Loop (max 5 iterations)
1. Error Gathering — Get exact error message, stack trace (script + line), trigger condition (join/action/timer). Use MCP for console output if available.
2. Code Discovery — Read relevant script(s). Search for error text, function names, or script from stack trace.
3. Root Cause Analysis — Categorize: Syntax (missing end) · Runtime (nil, destroyed Instance) · Logic (wrong calc/condition) · Security (client-side logic) · Performance (timeout, memory). Load roblox-sharp-edges for known gotchas. Find the exact line + true root cause.
4. Generate Fix — Produce corrected Luau. Explain what was wrong, why fix works, related code to check. Flag architectural changes.
5. Apply & Test — Write fix to file. MCP verify if available. In offline mode: before/after diff + manual test instructions.
MCP evidence: discover/select Studio, inspect before editing, read back the fix, run playtest when relevant, and report console/screenshot limitations explicitly.
6. Verify — Resolved → Step 7. New errors → back to Step 1. Same error → new hypothesis, back to Step 3. Iteration 5 → escalate with full diagnosis.
7. Summary — Document: bug description · root cause · fix applied · verification · related risks · prevention pattern. If systemic, recommend /code-review.
Escalation (at iteration 5)
Output: all attempted fixes + why rejected, remaining hypotheses, recommended next steps (manual investigation, DevForum search, etc.).
📖 Full reference: references/full.md
