Bug Hunt

Purpose

Locate and fix the root cause of a bug with minimal scope. A correct fix beats a fast guess.

When to Use

• A specific, reproducible bug needs fixing.
• A test is failing and the cause is unclear.
• An unexpected behavior needs a targeted fix.

For complex, persistent, or multi-component bugs, use systematic-debugging instead.

Inputs

• Bug description or reproduction steps.
• Relevant error messages or stack traces.
• Access to the codebase and test suite.

Workflow

1. Reproduce — Trigger the bug reliably before writing any code.
2. Identify — Find the true failing layer, not just the first place the error surfaces.
3. Fix — Apply the minimal change at the root cause.
4. Test — Add or update a focused test that would have caught this bug.

Output

Root cause: 
Fix: 
Verification: 
Residual risk: 

Verification

• [ ] Bug reproduced before fix was written
• [ ] Root cause identified (not just symptom location)
• [ ] Fix is minimal — no unrelated changes bundled in
• [ ] Test added or updated to prevent regression

Failure Modes

• Fixing the symptom — Error location ≠ root cause. Trace backward until the origin is found.
• Skipping reproduction — Fixes written without a reliable reproduction often miss the actual bug.
• Missing test — Without a regression test, the same bug is likely to return.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yeaight7
• Source: yeaight7/agent-powerups
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.