| name | unity-debug |
| description | Diagnose Unity bugs from compile errors to stack traces, runtime failures, and tricky logic issues; gather reproduction details, trace the code path, prove the root cause with evidence, and report options without changing code unless asked. |
| metadata | {"author":"kuozg","version":"3.0"} |
unity-debug
Use this skill for Unity debugging, diagnosis, and root-cause analysis.
Keep it compact and structured. Focus on evidence and actionable solutions. Avoid unnecessary prose.
*** MANDATORY: Use references/output-template.md for debug reports. Follow the structure and icon guidelines strictly. ***
Workflow
1. Capture the issue.
- Issue title or symptom
- Current behavior vs expected behavior
- Key signal: compile error, stack trace, log, visual symptom, or failing state
- Affected scene, prefab, system, build target, or user path
- Scope — single script, system interaction, or timing?
- Check git log -5 for recent changes.
- Reproduction steps and frequency
2. If required debug inputs are missing, ask only for the missing evidence. Do not assume.
3. Understand the codebase.
- Spawn an explorer subagent to read related code when tracing needs more than 3 searches
- Spawn another explorer only if docs, references, or package behavior are needed
4. Investigate the flow.
- Trace input/trigger, data/state path, logic path, and failure point
- Read only the code needed to prove the cause
- Cite file paths and line numbers for every key claim
5. Prove the root cause.
- Identify the cause, proof, and why-now trigger when known
- Assign severity using
references/output-template.md
- Report uncertainty explicitly if proof is incomplete
6. Propose 2 to 3 solutions.
- Each solution must include approach, where to fix, scope, verify, and trade-off
- Prefer minimal fix first, then structural alternatives only when useful
- Recommend one option with a short reason
7. Report the result using references/output-template.md.
- Include Severity, Explain, Impact, Root Cause, Flow, Reproduce, Solutions, Verify, and Prevent sections
- Use tree format for Flow, Reproduce, and Solutions
- Keep each section compact: 1 to 3 bullets unless evidence requires more
- Do not report a final root cause until it is proven with cited evidence
Investigation Rules
- Never apply a fix unless the user asks for it.
- Never guess the root cause.
- If the root cause is not proven after 2 to 3 tries, stop and report what you found.
- Keep evidence concrete: file paths, lines, logs, stack traces, or repro steps.
- Prefer minimal, targeted reads over broad exploration.
