mcpField
R
roblox-debug

roblox-debug

github.com/tabooharmonyDevelopment138257 installsUpdated 2w ago
Repository

About roblox-debug

roblox-debug is a structured debugging skill for diagnosing errors, crashes, and unexpected behavior in Roblox/Luau code. It guides Roblox developers through a seven-step loop, with up to five iterations, in file-sync or MCP mode.

Key features

  1. 01Follow a seven-step iterative debug loop
  2. 02Classify and analyze root causes
  3. 03Generate and apply Luau fixes
  4. 04Verify fixes through MCP when available
  5. 05Escalate after up to five iterations

Use cases

  1. 01Trace Roblox script errors and stack issues
  2. 02Investigate runtime, logic, or performance problems
  3. 03Inspect and test fixes in Studio
  4. 04Document attempts and escalate difficult bugs

MCP support

In MCP mode, it can discover and select Studio, inspect code, read back fixes, and run playtests when relevant.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/tabooharmony/roblox-brain --skill roblox-debug

After installing, type/roblox-debugin Claude Code to confirm it loaded.

Bundled filesreferences/full.md

Details

From the project README

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

Comments

Markdown supported