Skip to content

btseytlin/ultrapack / skills/udebug

udebug

Verified

Use 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.

finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall