diagnose

name	diagnose
description	Guided runtime debugging — add Debug.Log diagnostics, test in play mode via MCP, read console, identify root cause and fix

Runtime Bug Diagnosis

Structured workflow for diagnosing runtime bugs in Unity play mode.

Arguments

• bug (required): Description of the bug or unexpected behavior
• scene (optional): Scene to test in (default: currently loaded scene)

Workflow

Phase 1: Gather Context

1. Read the console for existing errors: mcp__UnityMCP__read_console(types=["error","warning"])
2. Identify the suspect code paths based on the bug description
3. Read the relevant source files to understand the flow

Phase 2: Add Diagnostics

CRITICAL: Use Debug.Log, NEVER Diag.Log — Diag.Log writes to an internal event log that does NOT appear in the Unity console.

For each suspect location, add a Debug.Log with:

• A unique [ClassName] prefix for filtering
• Key variable state: $"[Foo] MethodName: ref={ref != null} value={value}"
• Place logs BEFORE null checks and branching to see which path executes

Commit each modified file immediately (project rule).

Phase 3: Test

1. Ensure the correct scene is loaded: mcp__UnityMCP__manage_scene(action="get_active")
2. Clear console: mcp__UnityMCP__read_console(action="clear")
3. Enter play mode: mcp__UnityMCP__manage_editor(action="play")
4. Wait 4-5 seconds for initialization
5. If the bug requires user interaction, ask the user to perform the action
6. Read console: mcp__UnityMCP__read_console(count=30)
7. Read errors specifically: mcp__UnityMCP__read_console(types=["error","warning"])
8. Stop play mode: mcp__UnityMCP__manage_editor(action="stop")

Phase 4: Analyze

From the console output, determine:

• Which diagnostic logs fired (and which did NOT — gaps reveal the break point)
• Whether references were null at specific checkpoints
• Whether methods were called in the expected order
• Any Unity errors/warnings that appeared

Phase 5: Fix

1. Implement the targeted fix based on diagnosis
2. Remove diagnostic Debug.Log calls (or leave them if they add value)
3. Commit each file immediately
4. Re-test using Phase 3 to verify the fix
5. Check for zero errors/warnings in the console

Tips

• If a file is at the 450-line limit, REPLACE an existing Diag.Log with Debug.Log instead of adding lines
• Check mcp__UnityMCP__read_console(types=["error"]) after script edits to catch compile errors before testing
• For intermittent bugs, add more diagnostics rather than fewer — you can always remove them
• Filter console output with filter_text parameter if output is noisy