btseytlin/ultrapack / skills/udebug
udebug
VerifiedUse on any bug, test failure, or unexpected behavior before proposing a fix. Enforces four-phase root-cause investigation — reproduce, pattern-match, hypothesize, fix — with a hard rule against symptom patches.
Debug
Reproduce the failure before claiming a fix. A controlled repair experiment may establish the cause of an uncertain numerical or learning failure.
When to invoke
Any technical issue: test failure, production bug, unexpected behavior, performance regression, build break, integration failure. Especially when:
- Under time pressure (makes guessing tempting)
- You already tried 1+ fixes
- The problem "seems simple" (simple-looking bugs still have root causes)
Phase 1 — Reproduce the problem and trace the data
You cannot fix what you cannot observe. Start by making the bug happen on demand, then follow the bad value back to where it came from.
Phase 2 — Pattern analysis against a working example
Bugs rarely occur in isolation. Find similar code that works, understand why it works, then enumerate every difference.
Phase 3 — Single hypothesis, minimal test
One cause at a time. Stacked guesses turn fixes into guesses about guesses.
Phase 4 — Implement one fix, verify, stop at three failed attempts
Use the reproduced failure and controlled experiments to select a coherent repair.
Condition-based waiting — never use sleep(N) for timing bugs
A sleep that "seems long enough" is a bomb on a fuse. Poll for the actual condition with a bounded timeout:
deadline = time.time() + timeout
while time.time() < deadline:
if condition():
break
time.sleep(0.1)
else:
raise TimeoutError(f"condition not met in {timeout}s")
Defense in depth — validate one or two layers past the fix
Once the root cause is fixed, add validation at the next layer so the same class of bug can't re-enter silently:
- Validate inputs at component boundaries
- Crash loudly on contract violations
- Log state transitions in long-running processes
Don't scatter defensive code everywhere. One or two layers past the fix is enough.
Anti-whack-a-mole — find the pattern before closing
Before marking the fix done, name the failure pattern and check the relevant code for the same cause. Fix matches only when they belong to the approved request. Report unrelated matches without editing them. A small fix is not permission to expand scope.
Red flags — STOP, return to Phase 1
When root cause really is environmental
After systematic investigation, if the issue is timing, external, or truly non-deterministic:
- Document what you investigated
- Implement appropriate handling (retry, timeout with condition polling, loud error)
- Add logging / monitoring for future occurrences
But most "no root cause" verdicts are incomplete investigations. Double-check before settling for this.
Terminal state
Fix verified with reproduction → return to up:uverify if in a task workflow, or commit and move on.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |