cuozg/unity-investigate

unity-investigate

Investigate Unity codebases. Auto-triage into Quick (inline answer) or Deep (report with diagrams).

Triage

Classify the request before starting work:

| Signal | Mode | |--------|------| | Single symbol, method, or class question | Quick | | "How does X work?" / "What calls Y?" | Quick | | Tracing one call chain or data flow | Quick | | User says "quick" / "briefly" / "explain" | Quick | | User says "investigate" / "analyze" / "report" / "audit" | Deep | | System spans 3+ classes or multiple assemblies | Deep | | Pre-refactor audit or onboarding documentation needed | Deep | | User wants a saved document or team-facing output | Deep |

When ambiguous, start Quick — escalate to Deep if the answer requires 3+ files or cross-system tracing.

---

Quick Mode

Answer the question in the fewest tool calls possible.

Workflow

1. Parse — Extract the exact symbol, file, or concept from the question.
2. Find — lsp_goto_definition on the target symbol to locate its declaration.
3. Trace — lsp_find_references or grep to follow call chains one level deep.
4. Stop — Halt the moment the question can be answered; skip unused steps.
5. Reply — Format as summary + 1-3 typed detail blocks.

---

Deep Mode

Produce a comprehensive investigation report. Follow this workflow:

1. Scope & Discovery

Define boundaries and map the system systematically:

• Entry Points: Public APIs, Unity callbacks (Awake/Start), event handlers.
• Exit Points: Data outputs, event triggers, state mutations.
• Map Files:

  glob(pattern="**/{SystemName}*.cs")
  grep(pattern="ClassName|InterfaceName", include="*.cs")
  lsp_goto_definition -> follow type hierarchy
  

2. Detailed Tracing

Follow execution paths and side effects:

• Call Chains: lsp_find_references from entry points 2-3 levels deep.
• Side Effects:

  grep(pattern="\\.On[A-Z]|event\s+|Action<|UnityEvent", include="*.cs")
  grep(pattern="AddListener|RemoveListener", include="*.cs")
  

• Dependencies: Note using directives (compile-time) and GetComponent (runtime).

3. Test & Safety Analysis

Check for coverage and data implications:

• Coverage: glob(pattern="**/*Tests.cs") to match source to test files.
• Risk Assessment: | Factor | Question | |--------|----------| | Blast Radius | How many systems are touched or break if this changes? | | Data Safety | Can this corrupt saves, PlayerPrefs, or global state? | | Test Coverage | Are critical paths tested? Score: High/Med/Low. |

4. Diagram & Documentation

Create Mermaid diagrams and write the report:

• Diagrams: Create an Execution Flow (flowchart TD) and Structure (classDiagram).
• Template: Mandatory read_skill_file("unity-standards", "references/plan/investigation-template.md").
• Output: Save to Documents/Investigations/{SystemName}_{YYYY-MM-DD}.md.

Quality Checklist

• [ ] Executive Summary covers purpose and key findings.
• [ ] Every claim has a file:line citation.
• [ ] At least one Mermaid diagram renders correctly.
• [ ] Risk table includes severity, evidence, and mitigation.
• [ ] Side effects and event chains are documented.

---

Standards

Load unity-standards for convention context:

• code-standards/lifecycle-async-errors.md — Order of execution rules.
• code-standards/architecture-systems.md — Architecture patterns.
• plan/investigation-template.md — The mandatory report template.
• other/unity-mcp-routing-matrix.md — MCP tool routing for scene/asset inspection.