Bughunt

Bughunt

An offensive, hotspot-driven bug-hunting workflow. Where the autoreview skill (/review) is a defensive gate on your own diff, bughunt assumes the code is guilty and goes looking for hidden defects in the riskiest parts of the target with explicit coverage reporting.

Read this hub first, run recon, then open only the spokes your hunt plan selects.

Mission

Find the bugs that tests, linters, and a tired reviewer miss — and make each claim carry evidence. The output is a ranked, evidence-backed report, not a vibe. Default behavior is report-only: hunt, document, hand fixing to a human or the autoreview skill (/review). Never edit product code unless the user asks.

What makes this powerful (not just a checklist)

1. A deterministic spine — a bundled zero-dependency toolkit (bughunt.py) ranks hotspots by churn × complexity × boundary × test-gap, surfaces pain signals (aged TODOs, config drift, risky deps), and owns structured findings: fingerprint, dedupe, suppress, baseline-diff, and render to markdown/HTML/SARIF with CI exit codes. See tooling.md. Degrades to a pure-markdown pipeline when python3 is absent.
2. Breadth via fan-out — split the target into a grid of (lens × hotspot) cells and run them as independent parallel hunters, so every risky area is examined through every relevant lens. A capability ladder runs the same phases on whatever fan-out machinery the tool has — the Workflow tool, an external coding-CLI fan-out (Composer 2.5 / Grok via cursor-agent, the fast variant), parallel Tasks, or a sequential walk. See orchestration.md.
3. Depth via specialized lenses + platform catalogs — 13 lenses, each a distinct adversarial discipline (bugs, perf, DX, UX, supply-chain, data safety); each platform catalog encodes that ecosystem's specific footguns.
4. Signal via mandatory verify + triage — a skeptic pass tries to refute every finding before it's reported (verification.md); survivors are confidence-rated, cross-validated, and reproduced by triage.

First principle: signal over noise

A short list of real, reproducible bugs beats a long list of maybes. Every reported finding names its evidence (file:line + trace + trigger + impact) and its confidence. Speculative items are quarantined in their own section — never mixed in. Before reporting anything, try to kill it (see the false-positive filter in triage). If it survives, report it.

Operating principles

• Assume guilt. The code is wrong until you've checked. Read it for what it does, not what it's supposed to do.
• Evidence-first. No file:line + trace + trigger + impact → it's a question, not a finding.
• Do not overstate proof. Static skeptic-upheld findings are Probable unless reproduced or traced beyond plausible refutation. Runtime/property-test proof is what earns Confirmed.
• Report, don't edit. This skill is read-only by default. Surface and prove bugs; hand fixing to a human or the autoreview skill (/review). Only edit code if the user asks.
• Scope before you scale. On a large/unfamiliar repo, do recon and confirm scope/budget with the user before launching a deep hunt (see recon-and-scoping.md).
• Be honest about coverage. Always state what you examined and what you did not.
• Enforce verification and coverage in CI. ci runs must merge with --require-verified --require-coverage --strict so skipped skeptic verdicts or missing coverage metadata fail instead of becoming trusted findings.
• Don't invent bugs. A clean result is a valid, valuable outcome — see When the hunt finds nothing below. Never pad the report to look productive.

Modes

Default to the mode the request implies; ask only if genuinely ambiguous.

The hunt loop

Execute in order. Spokes carry the detail.

Toolkit & capability ladder

The hunt has a deterministic spine and a portable execution model, so it works the same on Claude Code, Cursor, or Codex.

• Toolkit — bughunt.py (zero-dependency, stdlib python3) under scripts/ does the non-judgment work: rank hotspots, mine pain signals, audit deps, and fingerprint/dedupe/suppress/baseline-diff/render the findings. The automated dependency support is strongest for npm/Python-style manifests; other ecosystems rely more on platform catalogs and agent inspection. Always probe python3 --version first. If it's missing, run the markdown fallback — rank by the recon heuristics, keep findings in markdown, skip SARIF; nothing in the toolkit is required for the hunt to work.
• Capability ladder (orchestration.md) — same five phases (Recon → Hunt → Verify → Merge → Report) on every rung: (A) invoke the shipped hunt-workflow.js when the Workflow tool is available; (A-CLI) the shipped hunt-cursor.mjs to fan out Composer 2.5 / Grok hunters via cursor-agent — the fast variant, and the highest rung available inside Cursor; (B) parallel Tasks on standard Claude Code; (C) a sequential walk on single-agent tools. Verify is mandatory on every rung, and always on a strong reasoner even when hunters run on a fast model.

Example: one trip through the loop (condensed)

A small Node API repo, deep hunt:

1. Recon — detects Express + Postgres. Trust boundaries: HTTP routes, SQL. Hotspots by churn + boundary: routes/invoices.js (recently changed, near auth + SQL, no tests), lib/pricing.js (money math), db/query.js.
2. Fan-out grid — dispatch hunters: auth-access × routes/invoices.js, taint × routes/invoices.js, logic-correctness × lib/pricing.js, resource-performance × db/query.js. Platform catalog: web.
3. Hunters report (evidence-backed candidates):
   • auth-access: GET /invoices/:id loads by id with no ownership check → IDOR.
   • logic-correctness: discount applied after tax in applyDiscount() → wrong total.
   • resource-performance: invoice list issues one query per line item → N+1.
4. Merge & cross-validate — three distinct findings, no dupes; taint hunter found nothing new (SQL is parameterized — correctly not reported).
5. Triage — IDOR = High-Confirmed (wrote a failing test: user A reads user B's invoice); discount = High-Probable (traced values: $100 + 10% tax then −10% = $99, expected $90); N+1 = Medium-Probable.
6. Report — three findings, ranked, each with repro/trace; recommend fixing then /review. No product-code edits made; .bughunt/ report/state files may be written.

When the hunt finds nothing

A clean result is a real outcome — report it honestly, never invent findings. Emit a short report stating: what was examined (which lenses × hotspots), what was deliberately out of scope, your confidence level, and any Speculative items worth a human glance. "I hunted X with lenses Y and found no confirmed defects; here's the coverage" is a valid deliverable.

Lens index (analysis disciplines)

Read on demand — only the lenses the hunt plan selects.

Platform index (ecosystem footguns)

Pick the one(s) recon identifies.

Spoke index

When not to use

• Just reviewing your own session diff for quality → the autoreview skill (/review).
• You already have one suspected bug to assess → triage directly.
• You want to harden one function dynamically → fuzz directly.

Related skills

• triage — scoring, repro, and the report format bughunt emits
• fuzz — confirm Probable findings dynamically
• the autoreview skill (/review) — the recommended fix/quality gate after reporting
• verify / /verify — drive the real app to reproduce a runtime-only bug