find-bugs
Read-only bug audit of the current branch vs a base ref. Dispatches subagents per stack (Go, JS/TS, etc.), consolidates findings, produces a prioritized report. Does not fix. Usage: /find-bugs [base-r
SKILL.md.claude/skills/find-bugs/SKILL.md
GitHubSkill: /find-bugs
Bug Audit — Read-Only
Audit the current branch for bugs without touching code. Produces a prioritized report; user decides what to fix.
Steps
Step 1 — Determine scope
BASE="${1:-main}"
# If on a feature branch: diff vs base
if git rev-parse --verify "$BASE" >/dev/null 2>&1; then
DIFF=$(git diff "$BASE"...HEAD)
else
if git rev-parse --verify --quiet HEAD~10 >/dev/null; then
BASE=HEAD~10
else
BASE=$(git rev-list --max-parents=0 HEAD | tail -1)
fi
DIFF=$(git diff "$BASE"...HEAD)
fi
# Fallback: on main with no base arg → recent commits
if [[ -z "$DIFF" ]]; then
DIFF=$(git log --since='2 weeks ago' -p --no-merges)
fi
echo "Auditing $(git rev-parse --abbrev-ref HEAD) vs $BASE"
echo "Diff size: $(echo "$DIFF" | wc -l) lines"
If diff > 2000 lines: warn and ask if user wants to narrow scope (specific files or commits) before proceeding.
Step 2 — Read project context
head -100 CLAUDE.md 2>/dev/null
cat .claude/context-essentials.md 2>/dev/null
# Detect stack
cat go.mod 2>/dev/null | head -3
cat package.json 2>/dev/null | jq -r '(.dependencies // {}) + (.devDependencies // {}) | keys | join(", ")' 2>/dev/null
# Changed files by type
git diff "$BASE"...HEAD --name-only | sort
Step 3 — Dispatch stack-aware subagents
Dispatch in parallel based on detected stack. Each subagent gets:
- The full diff
- Project context (CLAUDE.md / context-essentials.md excerpt)
- Stack-specific checklist (below)
Always dispatch — Generic bug finder:
Checklist:
- Null/nil dereference on unchecked return values
- Resource leaks (files, connections, goroutines not closed/cancelled)
- Unhandled errors silently discarded (
_ = err, barecatch {}) - Off-by-one in loops, slice bounds, index arithmetic
- Race conditions: shared mutable state accessed from goroutines/async
- Incorrect error propagation (wrapping lost, status code swallowed)
- Context not propagated into blocking calls
- Missing timeout on external calls (HTTP, DB, queue)
If .go files changed — Go reviewer:
Additional checklist:
defer f.Close()missing after open (cursor/file leak)sync.Mutexcopied by valuego func()capturing loop variable by reference (pre-Go 1.22)http.Response.Bodynot closedcontext.WithCancelleak (cancel not called on all paths)- Integer overflow in slice/index math
iotamisuse in const blocks
If .ts / .tsx / .js files changed — JS/TS reviewer:
Additional checklist:
awaitmissing on async calls (fire-and-forget)- Unhandled promise rejection
useEffectmissing dependency array or stale closureJSON.parsewithout try/catch- Type assertion
as Xhiding runtime mismatch undefinedaccess on optional chaining result used as non-optional
If DB/ORM files changed (any stack) — DB reviewer:
Additional checklist:
- Query result not closed / cursor leak
- Missing transaction rollback on error path
- N+1 query pattern introduced
- Unique constraint not enforced at app level (only in migration)
- Index missing for new filter/sort introduced in diff
Step 4 — Consolidate
Merge all subagent reports:
- Deduplicate by
(file, line)— keep highest severity, merge bodies - Remove findings already caught by
make lint/ linter output - Remove "consider adding X" without concrete evidence in the diff
Step 5 — Report
# Bug audit — <branch> vs <base> — <date>
## Critical — block merge
- `file.go:42` **nil deref**: `resp.Body` read before nil check after `http.Get` error path.
Fix: check `err != nil` before using `resp`.
## High
- ...
## Medium
- ...
## Low / nits
- ...
---
Findings: <N> total (<critical> critical, <high> high, <medium> medium, <low> low)
Save to /tmp/<project>-bugs-<short-sha>.md and print inline.
Final message:
"<N> findings. Address with Edit or a dedicated fix subagent."
Constraints
Read-only. No edits, no commits, no
git checkout.Cite file:line for every finding — no location = skip it.
Differentiate certainty: "definite bug" vs "potential hazard" vs "worth checking".
Severity guide:
Level Definition Critical Definite crash, data corruption, or security hole in the diff High Likely bug under realistic conditions; resource leak Medium Potential bug; depends on caller contract not visible in diff Low Minor hazard, defensive improvement, nit
Anti-patterns
- ❌ Generic "consider adding error handling" without showing which call and why.
- ❌ Severity inflation — not everything is critical.
- ❌ Reproducing what
make lint/go vetalready reports. - ❌ Flagging code not present in the diff.