- name
- ucts-investigate
- description
- >
- tags
- [ucts, debugging, investigation, root-cause]
UCTS Investigate
Systematic root-cause debugging. This is a methodology skill — guide the user through the process.
Iron Law
No fixes without investigation. Never guess-and-check. Never "try this and see." Understand the cause FIRST, then fix.
Process
1. Reproduce
Get the exact:
- Steps to trigger the bug
- Input that causes the failure
- Environment (OS, Node version, browser, etc.)
- Error message (exact text, not paraphrased)
- Frequency: always, sometimes, only on Tuesdays?
If you can't reproduce it, you can't fix it. Stop here until you can.
2. Hypothesize
Form 3 hypotheses about the root cause, ranked by probability:
- Most likely: [specific mechanism]
- Second most likely: [specific mechanism]
- Dark horse: [unlikely but would explain everything]
Each hypothesis must be falsifiable — you must be able to design a test that proves it wrong.
3. Trace
For the top hypothesis, trace the data flow:
- What enters the system?
- What transformations happen?
- Where does the expected path diverge from the actual path?
- What state is wrong and when did it become wrong?
4. Test
Design a minimal test that confirms or refutes the top hypothesis:
- If confirmed → you found the root cause. Proceed to fix.
- If refuted → move to hypothesis #2. Repeat trace + test.
5. The 3-Strike Rule
After 3 failed fix attempts, STOP. Reassess from scratch:
- Are your hypotheses wrong?
- Is the bug actually in a different layer?
- Is there a simpler explanation you missed?
- "The bug is in the code you trust most."
When to Spawn Claude Code
If the investigation requires reading code, running tests, or making changes:
Load UCTS. Run /investigate <bug description>If the user just needs to think through the problem, stay in chat.