Help us improve
Share bugs, ideas, or general feedback.
From agentops
Systematic bug investigation using a 4-phase workflow (Root Cause → Pattern → Hypothesis → Fix) and proactive audit sweeps. Outputs diagnosis reports and optional fix commits.
npx claudepluginhub boshu2/agentops --plugin agentopsHow this skill is triggered — by the user, by Claude, or both
Slash command
/agentops:bug-huntThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **Quick Ref:** 4-phase investigation (Root Cause → Pattern → Hypothesis → Fix). Output: `.agents/research/YYYY-MM-DD-bug-*.md`
references/audit-fix-rescan-cycle.mdreferences/audit-report-template.mdreferences/bug-hunt.featurereferences/bug-report-template.mdreferences/convergence-criteria.mdreferences/deadlock-and-hang-triage.mdreferences/debugger-attach-triage.mdreferences/failure-categories.mdreferences/multi-pass-bug-hunting.mdscripts/validate.shskill.spec.jsonSystematic debugging methodology for finding and fixing bugs through root cause analysis. Covers reproduce-investigate-hypothesize-fix-prevent workflow, evidence-based diagnosis, and bug category strategies.
Enforces systematic root cause investigation before proposing fixes for bugs, test failures, unexpected behavior, performance problems, and build failures.
Hunts down and fixes bugs using a systematic debugging process: reproduce, gather evidence, hypothesize, test, find root cause, and implement fix.
Share bugs, ideas, or general feedback.
Quick Ref: 4-phase investigation (Root Cause → Pattern → Hypothesis → Fix). Output:
.agents/research/YYYY-MM-DD-bug-*.md
YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.
Systematic investigation to find root cause and design a complete fix — or proactive audit to find hidden bugs before they bite.
Requires:
.agents/ output directories; create them explicitly if absent| Mode | Invocation | When |
|---|---|---|
| Investigation | /bug-hunt <symptom> | You have a known bug or failure |
| Audit | /bug-hunt --audit <scope> | Proactive sweep for hidden bugs |
Investigation mode uses the 4-phase structure below. Audit mode uses systematic read-and-classify — see Audit Mode.
| Phase | Focus | Output |
|---|---|---|
| 1. Root Cause | Find the actual bug location | file:line, commit |
| 2. Pattern | Compare against working examples | Differences identified |
| 3. Hypothesis | Form and test single hypothesis | Pass/fail for each |
| 4. Implementation | Fix at root, not symptoms | Verified fix |
For failure category taxonomy and the 3-failure rule, read skills/bug-hunt/references/failure-categories.md.
For audits or pre-release sweeps that need more than one pass, route through skills/bug-hunt/references/audit-fix-rescan-cycle.md (multi-pass methodology) and use skills/bug-hunt/references/convergence-criteria.md to decide when to stop.
For proactive sweeps that need fresh-eyes rescans, also load references/multi-pass-bug-hunting.md.
For stuck commands, deadlocks, retry storms, blocked subprocesses, or hangs, load references/deadlock-and-hang-triage.md before changing code.
When the target process is live, hung, or only reproducible under debugger observation, load references/debugger-attach-triage.md before attaching or changing ptrace/sysctl settings.
Given /bug-hunt <symptom>:
Before investigating, check for prior learnings about this area of the codebase:
if command -v ao &>/dev/null; then
ao lookup --query "<symptom-keywords> bug patterns" --limit 3 2>/dev/null || true
fi
Apply retrieved knowledge: If learnings are returned, check each for applicability to the current bug. For applicable learnings (e.g., prior bugs in same area, known fragile patterns), include as investigation leads and cite by filename. Record: ao metrics cite "<path>" --type applied 2>/dev/null || true
Prior bug reports, fix patterns, and known fragile areas reduce investigation time.
First, reproduce the issue:
Read error messages carefully. Do not skip or skim them.
If the bug can't be reproduced, gather more information before proceeding.
Find where the bug manifests:
# Search for error messages
grep -r "<error-text>" . --include="*.py" --include="*.ts" --include="*.go" 2>/dev/null | head -10
# Search for function/variable names
grep -r "<relevant-name>" . --include="*.py" --include="*.ts" --include="*.go" 2>/dev/null | head -10
Find when/how the bug was introduced:
# When was the file last changed?
git log --oneline -10 -- <file>
# What changed recently?
git diff HEAD~10 -- <file>
# Who changed it and why?
git blame <file> | grep -A2 -B2 "<suspicious-line>"
# Search for related commits
git log --oneline --grep="<keyword>" | head -10
USE THE TASK TOOL (subagent_type: "Explore") to trace the execution path:
Based on tracing, identify:
Search the codebase for similar functionality that WORKS:
# Find similar patterns
grep -r "<working-pattern>" . --include="*.py" --include="*.ts" --include="*.go" 2>/dev/null | head -10
Identify ALL differences between:
Document each difference.
State your hypothesis clearly:
"I think X is wrong because Y"
One hypothesis at a time. Do not combine multiple guesses.
Make the SMALLEST possible change to test the hypothesis:
Check failure count per skills/bug-hunt/references/failure-categories.md. After 3 countable failures, escalate to architecture review.
Before writing code, design the fix:
Write a test that demonstrates the bug BEFORE fixing it.
Fix at the ROOT CAUSE, not at symptoms.
Run the failing test - it should now pass.
If the bug is in a high-complexity function, consider /refactor after fix to prevent recurrence.
When invoked with --audit, bug-hunt switches to a proactive sweep. No symptom needed — you're hunting for bugs that haven't been reported yet.
/bug-hunt --audit cli/internal/goals/ # audit a package
/bug-hunt --audit src/auth/ # audit a directory
/bug-hunt --audit . # audit recent changes in repo
Identify target files from the scope argument:
# Find source files in scope
find <scope> -name "*.go" -o -name "*.py" -o -name "*.ts" -o -name "*.rs" | head -50
If scope is . or broad (>50 files), narrow to recently changed files:
git log --since="2 weeks ago" --name-only --pretty=format: -- <scope> | sort -u | head -30
Read every file in scope line by line. For each file, check:
| Category | What to Look For |
|---|---|
| Resource Leaks | Unclosed handles, orphaned processes, missing cleanup/defer |
| String Safety | Byte-level truncation of UTF-8, unsanitized input |
| Dead Code | Unreachable branches, unused constants, shadowed variables |
| Hardcoded Values | Paths, URLs, repo-specific assumptions that won't work elsewhere |
| Edge Cases | Empty input, nil/zero values, boundary conditions |
| Concurrency | Unprotected shared state, goroutine leaks, missing signal handlers |
| Error Handling | Swallowed errors, missing context, wrong error types |
Key discipline: Read line by line. Do not skim. The proven methodology (5 bugs found, 0 hypothesis failures) came from careful reading, not heuristic scanning.
USE THE TASK TOOL (subagent_type: "Explore") for large scopes — split files across parallel agents.
For each finding, assign severity:
| Severity | Criteria | Examples |
|---|---|---|
| HIGH | Data loss, security, resource leak, process orphaning | Zombie processes, SQL injection, file handle leak |
| MEDIUM | Wrong output, incorrect defaults, silent data corruption | UTF-8 truncation, hardcoded paths, wrong error code |
| LOW | Dead code, cosmetic, minor inconsistency | Unreachable branch, unused import, style violation |
Performance bugs (slow queries, memory leaks, N+1) → escalate to /perf for deeper analysis.
For audit report format, read skills/bug-hunt/references/audit-report-template.md.
Write to .agents/research/YYYY-MM-DD-bug-<scope-slug>.md.
Report to user with a summary table:
| # | Bug | Severity | File | Fix |
|---|-----|----------|------|-----|
| 1 | <description> | HIGH | <file:line> | <proposed fix> |
Include failure count (hypothesis tests that didn't confirm). Zero failures = clean audit.
When running --audit, check for missing bug-finding test coverage:
BF4 — Chaos/Negative Testing (highest bug-finding power): For every file that makes external calls (APIs, databases, filesystems), verify:
If any boundary lacks failure injection → flag as finding (severity: significant).
BF5 — Script Functional Testing: For every .sh script that calls external tools (oc, kubectl, helm):
If scripts lack functional tests → flag as finding (severity: moderate).
BF1 — Property-Based Testing: For every data transformation (parse/render/serialize):
Reference: the test pyramid standard in /standards for full BF level definitions and per-language tooling.
For bug report template, read skills/bug-hunt/references/bug-report-template.md.
Tell the user:
Common bug patterns to check:
User says: /bug-hunt "tests failing on CI but pass locally"
What happens:
.agents/research/2026-02-13-bug-test-failure.mdResult: Root cause identified as missing ENV variable in CI configuration. Fix applied and verified.
User says: /bug-hunt "feature X broke after yesterday's deployment"
What happens:
git log --since="2 days ago" to find recent commitsgit bisect to identify exact breaking commitResult: Regression traced to commit abc1234, type conversion error fixed at root cause in validation logic.
User says: /bug-hunt --audit cli/internal/goals/
What happens:
.go files in the goals package.agents/research/2026-02-24-bug-goals-go.mdResult: 5 concrete bugs with severity, file:line, and proposed fix — ready for implementation without debugging.
| Problem | Cause | Solution |
|---|---|---|
| Can't reproduce bug | Insufficient environment context or intermittent issue | Ask user for specific steps, environment variables, input data. Check for race conditions or timing issues. |
| Git archaeology returns too many commits | Broad search or high-churn file | Narrow timeframe with --since flag, focus on specific function with git blame, search commit messages for related keywords. |
| Hit 3-failure limit during hypothesis testing | Multiple incorrect hypotheses or complex root cause | Escalate to architecture review. Read failure-categories.md to determine if failures are countable. Consider asking for domain expert input. |
| Bug report missing key information | Incomplete investigation or skipped steps | Verify all 4 phases completed. Ensure root cause identified with file:line. Check git blame ran for responsible commit. |
references/bug-hunt.feature — Executable spec: 4-phase root-cause investigation, fix-the-cause-not-symptom, --audit sweep, cited artifact (soc-qk4b)