| name | roblox-debugging-bugfix |
| description | Debug and fix Roblox bugs through Studio MCP. Use for repro steps, console errors, script search/read/edit flow, broken UI, failed gameplay systems, data issues, remotes, regressions, root-cause reports, and post-fix verification. |
Roblox Debugging Bugfix
Goal
Move from symptom to verified fix without guessing. For hard or intermittent bugs, follow the discipline below; skip phases only when you can justify it.
Phase 1 — Build a repro loop first (this is the skill)
Everything else is mechanical once you have a fast, repeatable pass/fail signal for the bug. Spend disproportionate effort here. Be aggressive and creative before you touch a fix.
Ways to construct one, roughly in order:
- Studio playtest repro — the exact steps in Play mode that surface the bug; watch
get_console_output.
execute_luau harness — call the suspect server/module function directly with a fixture input and assert the result, instead of clicking through the whole game.- Targeted scenario — spawn the minimal instances/state that trigger the code path (one part, one remote, one player state).
- Replay a captured payload — save the real remote payload / data profile that misbehaves and push it back through the code path in isolation.
Make the loop fast, sharp, and deterministic: narrow to the specific symptom, pin any randomness/timing, and cut unrelated setup. A 2-second deterministic check beats a 30-second flaky one.
Intermittent bugs: the goal is a higher reproduction rate, not a clean one-shot. Loop the trigger many times, add stress, narrow timing windows. A 50%-flake bug is debuggable; keep raising the rate until it is.
If you genuinely cannot build a loop, stop and say so — list what you tried and ask the user for the environment, a captured artifact (log dump, screen recording with timestamps, the offending data), or permission to add temporary instrumentation. Do not hypothesize without a loop.
Phase 2 — Reproduce
Run the loop. Confirm it produces the failure the user described (not a nearby lookalike), that it repeats, and that you've captured the exact symptom for later verification.
Phase 3 — Hypothesize
Generate 3–5 ranked, falsifiable hypotheses before testing any — single-hypothesis debugging anchors on the first guess. Each states a prediction: "If X is the cause, then changing Y makes it disappear." Show the ranked list to the user before probing; they often re-rank instantly ("we just changed #3"). Proceed on your ranking if they're AFK.
Phase 4 — Instrument
Each probe maps to one hypothesis; change one variable at a time. Prefer inspecting real values (inspect_instance, execute_luau) over log spam. Tag every temporary log with a unique prefix like [DEBUG-a4f2] so cleanup is a single script_grep. For performance regressions, measure first (timing/os.clock, MicroProfiler, instance counts) and bisect — logs are usually the wrong tool.
Phase 5 — Fix + regression check
Make the smallest safe fix with multi_edit. Before declaring done, turn the repro into a durable check where a correct seam exists (an execute_luau assertion or a documented playtest step). If no good seam exists, that itself is a finding — note that the architecture is preventing the bug from being locked down.
Debug Loop (mechanics)
- Capture the user-visible symptom and expected behavior.
- Reproduce in Play mode when possible.
- Read
get_console_output.
- Search with
script_grep and script_search.
- Read relevant scripts with
script_read.
- Inspect relevant instances with
search_game_tree and inspect_instance.
- Make the smallest safe fix with
multi_edit.
- Re-run the repro and check console output again.
- Remove all
[DEBUG-...] instrumentation (script_grep the prefix).
Common Bug Classes
- Client/server state mismatch.
- Remote payload trust issue.
- UI not updating after server state changes.
- Event connections duplicated or never disconnected.
- DataStore load/save race.
- Object path renamed or missing.
- Play mode DataModel mismatch.
- Race between character spawn, UI creation, and server initialization.
Fix Rules
- Prefer root-cause fixes over defensive silence.
- Do not swallow errors without logging context.
- Add validation near trust boundaries.
- Keep unrelated refactors out of bug fixes.
- Verify no new console errors.
Output
Return:
- Repro.
- Root cause (state which hypothesis proved correct).
- Files/scripts changed.
- Verification performed.
- Residual risks.
- Post-mortem: what would have prevented this bug? If the answer is architectural (no good test seam, tangled client/server boundary, hidden coupling), recommend
roblox-code-maintenance-refactor or roblox-luau-architecture — after the fix is in, not before.
Next
Verify the fix holds with roblox-playtest-qa (and roblox-mobile-playtest if it touched UI/mobile). If the post-mortem surfaced architectural debt, hand off to roblox-luau-architecture or roblox-code-maintenance-refactor. Return to roblox-game-development-lifecycle to resume the roadmap.
