| name | systematic-debugging |
| description | Use when debugging any issue, fixing a bug, investigating unexpected behavior, or when something isn't working as expected — enforces 4-phase root cause process instead of guessing |
Systematic Debugging
Adapted from superpowers:systematic-debugging
The Iron Law
NEVER guess at fixes. Find the root cause FIRST.
Surface symptoms ≠ root cause. Resist the urge to change code before understanding WHY it's broken.
Phase 1: Root Cause Investigation
- Reproduce the bug — Get exact steps, inputs, and environment (Editor version, platform, device)
- State clearly: What SHOULD happen vs what ACTUALLY happens
- Gather evidence:
- Unity Console logs (check for warnings too, not just errors)
- Unity Profiler for performance/GC issues
- JObjectDB Editor window for data state inspection
- Inspector for serialized field values at runtime
- Device logs for mobile (
adb logcat for Android, Xcode console for iOS)
- Isolate: Is it Editor-only, runtime-only, platform-specific, or data-dependent?
Phase 2: Pattern Analysis
Ask yourself:
- Has this happened before? Check
CHANGELOG.md for similar fixes
- Is it timing-related? (Awake vs Start ordering, coroutine lifecycle, async race conditions)
- Is it state-related? (stale PlayerPrefs, missing ScriptableObject reference, uninitialized [Inject] field)
- Is it platform-related? (IL2CPP stripping, Android back button, iOS safe area, Device Simulator)
- Does it only happen with certain data? (empty collections, null JObjectData fields, edge case enum values)
Phase 3: Hypothesis & Testing
- Form ONE hypothesis at a time
- Design a test that would DISPROVE it
- Run the test
- If disproved → next hypothesis. If confirmed → proceed to fix
NEVER test multiple hypotheses simultaneously — you won't know which one was right.
Phase 4: Implementation
- Write the minimal fix
- Verify the original bug is resolved
- Check for regressions — does the fix break anything else?
- Check related code paths — could the same bug exist elsewhere?
Red Flags — STOP
| Thought | Reality |
|---|
| "Let me just try changing this..." | Find root cause first |
| "It's probably X..." | Prove it, don't guess |
| "I fixed it, moving on" | Did you verify? Run the reproduce steps again |
| "Let me change multiple things" | One change per test |
| "I've seen this before" | Every bug is unique until proven otherwise |
