domains / software-engineering / debug / debug

debug

Skill card

combined

The three copies are not reproductions of one procedure. The first is a Unity-specific API reference for a set of debug skills (unity_diagnose, debug_get_errors, etc.) with parameters and routing rules. The second is a GSD-specific orchestrator that manages persistent debug sessions via subagents and file state. The third is a general-purpose, language-agnostic debugging methodology (reproduce, localize, hypothesize, test, fix, verify). They overlap only in the broad goal of debugging, but each contains material steps and constraints the others lack, so crowning one would hide real alternatives.

Repositories

Other copies

Combined skill

# Debug

## 1. Identify Context
- **Unity Project:** If working in a Unity project, use the Unity Debug Skills module. Start with `unity_diagnose` for a health snapshot. Use `debug_get_errors` or `debug_get_logs` for specific issues. Use `debug_force_recompile` if compilation state is stale (note: triggers Domain Reload).
- **GSD Workflow:** If using the GSD (Get Stuff Done) framework, use the `gsd:debug` skill. It manages persistent sessions in `.planning/debug/`. Use `list` to see active sessions, `continue <slug>` to resume, or provide a new issue description to start a new investigation via the `gsd-debugger` subagent.
- **General Project:** For any other project, follow the general scientific debugging loop below.

## 2. General Debugging Loop
1. **Capture Symptom:** Define observed vs. expected behavior and reproduction steps. If unclear, ask for details.
2. **Reproduce:** Create a deterministic reproduction (failing test, command, or request). If intermittent, find the trigger (timing, data, concurrency).
3. **Localize:** Narrow the failure surface. Bisect code paths or history (`git bisect`). Read actual values at boundaries.
4. **Hypothesize:** Form a single, specific, falsifiable hypothesis about the root cause (not the symptom).
5. **Test:** Design the smallest experiment to confirm or refute the hypothesis. Run it.
   - If refuted, return to Localize/Hypothesize.
   - If confirmed, proceed to Fix.
6. **Fix:** Apply the minimal, targeted change to the root cause. Avoid scope creep or unrelated refactors.
7. **Verify:** Re-run the reproduction to confirm the fix. Run the test suite to check for regressions. Add a regression test.

## 3. Constraints
- **Unity:** Do not use non-existent skills like `debug_compile` or `debug_run`. Use `debug_force_recompile` and `editor_play` respectively.
- **GSD:** Do not fall back to general-purpose agents; use `gsd-debugger` and `gsd-debug-session-manager`.
- **General:** Do not patch symptoms without understanding the cause. Do not skip the verification step.