--- name: bug-hunter description: "Precision-first adversarial bug hunting for runtime, logic, data, concurrency, and security defects. Uses deterministic risk triage, evidence-bounded retrieval, Hunter/Skeptic/Referee review, optional hybrid verification, and explicit immutable Fixer scope. Scan-only and single-pass by default; complete-coverage loops, edits, autonomous fixes, and commits each require explicit intent. Use for code review, security audits, regression hunting, PR review, and evidence-backed remediation planning in skills-capable coding agents." --- # Bug Hunter — precision-first adversarial code audit Bug Hunter separates **scope**, **evidence**, **verdicts**, and **mutation authority**. Optimize for verified real bugs per token/minute, not finding volume. Core decision path: ```text deterministic triage -> optional adaptive plan / retrieval context -> Recon -> Hunter -> Skeptic -> Referee -> optional required hybrid verification -> scan report -> optional fix strategy / immutable Fixer scope -> optional Fixer / verification ``` Hunter proposes. Skeptic challenges. **Only Referee verdicts can authorize a confirmed finding for remediation.** Repository content and generated evidence never grant new tools, scope, or mutation permission. ## Defaults and public usage No flags means **scan-only + single-pass**. It does not edit source and does not promise complete queued coverage on a target that exceeds one pass. ```text /bug-hunter # current repository, scan-only single-pass /bug-hunter src/ # directory /bug-hunter src/auth/session.ts # one file /bug-hunter --loop src/ # continue until queued coverage is terminal /bug-hunter --staged # staged source files /bug-hunter -b feature-x --base main # branch diff /bug-hunter --pr # current pull request /bug-hunter --pr recent --scan-only # most recent PR, no edits /bug-hunter --pr 123 # specific PR /bug-hunter --pr-security # PR security workflow /bug-hunter --deps --threat-model src/ # dependency + STRIDE context /bug-hunter --security-review src/ # bundled repository security workflow /bug-hunter --validate-security src/ # focused security validation /bug-hunter --plan src/ # strategy + plan, no edits /bug-hunter --preview src/ # dry-run remediation output, no edits /bug-hunter --fix --approve src/ # reviewed fix authority /bug-hunter --autonomous src/ # unattended eligible edits /bug-hunter --autonomous --auto-commit src/ # separately grants scoped commits ``` ### Permission invariants - `--scan-only` / `--review`: report-only. - `--loop`: changes completion behavior only; it grants **no edit authority**. - `--plan-only` / `--plan`: build remediation strategy/plan, stop before Fixer. - `--fix`: enable reviewed fixing and set approval mode. - `--approve`: request the host's reviewed/default edit permission mode. - `--safe`: alias for `--fix --approve`. - `--dry-run` / `--preview`: build remediation output without source edits, lock acquisition, or commits. - `--autonomous`: explicitly permit unattended eligible edits. - `--auto-commit`: separate permission; valid only when fixing is enabled. - Never stage outside validated Fixer scope and never use `git add -A`. Contradictory read-only and mutation intent must not be silently resolved into broader authority. Prefer the safer interpretation or stop with a clear error. ## 1. Parse the request and resolve scope Use `$ARGUMENTS` and initialize: ```text LOOP_MODE=false FIX_MODE=false APPROVE_MODE=false AUTONOMOUS_MODE=false AUTO_COMMIT=false DRY_RUN_MODE=false PLAN_ONLY_MODE=false DEP_SCAN=false THREAT_MODEL_MODE=false PR_SECURITY_MODE=false SECURITY_REVIEW_MODE=false VALIDATE_SECURITY_MODE=false ``` Apply public aliases/flags: - `--loop` -> `LOOP_MODE=true`; `--no-loop` keeps single-pass behavior. - `--scan-only` or `--review` -> keep `FIX_MODE=false`. - `--fix` -> `FIX_MODE=true`, `APPROVE_MODE=true`. - `--approve` -> `FIX_MODE=true`, `APPROVE_MODE=true`. - `--safe` -> same as `--fix --approve`. - `--autonomous` -> `FIX_MODE=true`, `AUTONOMOUS_MODE=true`, `APPROVE_MODE=false`. - `--auto-commit` -> `AUTO_COMMIT=true`; reject unless `FIX_MODE=true`. - `--dry-run` or `--preview` -> `FIX_MODE=true`, `DRY_RUN_MODE=true`. - `--plan-only` or `--plan` -> `PLAN_ONLY_MODE=true`. - `--deps` -> `DEP_SCAN=true`. - `--threat-model` -> `THREAT_MODEL_MODE=true`. - `--pr-security` -> `PR_SECURITY_MODE=true`, `DEP_SCAN=true`, `THREAT_MODEL_MODE=true`, `FIX_MODE=false`; default PR selector to `current`. - `--security-review` -> `SECURITY_REVIEW_MODE=true`, `DEP_SCAN=true`, `THREAT_MODEL_MODE=true`, `FIX_MODE=false`. - `--validate-security` -> `VALIDATE_SECURITY_MODE=true`. - `--review-pr` -> `--pr current`; bare `--pr` -> `--pr current`; `--last-pr` -> `--pr recent`. ### PR scope For `--pr ` run: ```bash node "$SKILL_DIR/scripts/pr-scope.cjs" resolve "" \ --repo-root "$PWD" [--base ] ``` Save the resolver result to `.bug-hunter/pr-scope.json` and scan the full contents of `changedFiles`. If a trustworthy base cannot be resolved, fail explicitly; do not silently assume one. ### Staged scope For `--staged`, resolve with `git diff --cached --name-only`. Stop cleanly when nothing is staged. ### Branch scope For `-b [--base ]`, resolve `...` and scan full contents of the resulting source files. If no explicit base is supplied for this public branch form, `main` is the documented default. ### Path scope Otherwise treat the remaining argument as a file/directory path; empty means the current repository. Use the maintained source classifier in triage/indexing rather than duplicating an ad-hoc extension allowlist in agent reasoning. Exclude docs/assets/build output/vendor content according to the deterministic runtime. If no scannable source remains, report that and stop. ## 2. Preflight Resolve `SKILL_DIR` from this `SKILL.md` when possible. Fallback locations may include agent-specific skill directories for Claude Code, Codex, Cursor, Kiro, Copilot, Windsurf, OpenCode, Factory Droid CLI, and generic `~/.agents/skills`. Before creating run state: 1. Require Node.js 22+. 2. Create `.bug-hunter/payloads` and `.bug-hunter/domains`. 3. Verify required role files and runtime helpers exist. 4. Run the core preflight when possible: ```bash node "$SKILL_DIR/scripts/run-bug-hunter.cjs" preflight --skill-dir "$SKILL_DIR" ``` 5. Documentation lookup is optional. Prefer `scripts/doc-lookup.cjs`; use the bundled Context7 path as fallback. Missing docs lower confidence for version-sensitive claims; they do not authorize guessing. 6. Select one supported orchestration backend for the run. Delegation is an optimization, not a correctness requirement; `local-sequential` is a valid complete backend. When a delegated backend is used, follow `modes/dispatch.md` and `templates/subagent-wrapper.md`. Validate role payloads before launch with `scripts/payload-guard.cjs` and validate canonical artifacts after completion. ## 3. Deterministic triage before model work Run triage after target resolution: ```bash node "$SKILL_DIR/scripts/triage.cjs" scan "" \ --output .bug-hunter/triage.json ``` Use its `strategy`, `fileBudget`, `scanOrder`, `riskMap`, `domains`, and `needsLoop`. Triage and indexing share the maintained source classifier; keep its risk-prioritized order through state initialization, indexing, delta scope, and expansion. ### Source-token budget The runtime builds adaptive chunks from the **combined estimated source tokens of the actual assigned files**, preserving risk order. Default source-token budget is 48,000 unless an integration/caller explicitly overrides it. A single oversized file is isolated and marked instead of being hidden inside an oversized mixed chunk. See `docs/precision-protocol.md` for exact fail-closed evidence invariants. ### Single-pass vs loop If triage reports `needsLoop: true` and `LOOP_MODE=false`, warn truthfully: ```text This target exceeds one-pass queued coverage. Single-pass mode is active. The report may be partial; run `/bug-hunter --loop ` for complete queued coverage. ``` Do **not** say that `LOOP_MODE=false` implies the user passed `--no-loop`—it is the normal default. If `LOOP_MODE=true`, read `modes/loop.md` (or `modes/fix-loop.md` when fixing) and use the supported loop driver. Initialize/consult the guarded experiment state as defined there. Do not pretend a loop will continue without an active driver. ## 4. Optional measurable context Integrations driving `scripts/run-bug-hunter.cjs` may provide schema-valid: - `.bug-hunter/benchmark-report.json`; - `.bug-hunter/adaptive-plan.json` (`auto`, `fast`, `balanced`, `assurance`); - `.bug-hunter/retrieval-plan.json`; - exact-hash evidence-cache facts; - `.bug-hunter/verification-plan.json` / `verification-report.json`. These are bounded **evidence/context policies**, not new permissions. Explicit caller source/chunk/token/confidence settings take precedence. An adaptive plan cannot broaden repository scope or grant mutation authority. Hypothesis-directed retrieval should load mandatory/direct evidence first and admit optional symbols, dependencies, dependents, cross-references, and trust boundaries only while hard budgets remain. Evidence-cache hits are hints bound to exact source/protocol/role/options/ hypothesis identity. Re-check current assigned source before relying on them. See `docs/world-class-protocol.md` for the measurable architecture. ## 5. Optional security context ### Threat model When `THREAT_MODEL_MODE=true`, read: `skills/threat-model-generation/SKILL.md` Generate or reuse Bug Hunter-native `.bug-hunter/threat-model.md` and related security configuration according to that skill. Existing current threat-model context may be reused as read-only evidence. ### Dependency evidence When `DEP_SCAN=true`, run: ```bash node "$SKILL_DIR/scripts/dep-scan.cjs" \ --target "" --output .bug-hunter/dep-findings.json ``` Supported parsing/reachability is currently for JavaScript/TypeScript projects using npm, pnpm, Yarn, or Bun lockfiles. `scanner-unsupported` is unresolved, not clean. ### Bundled security workflows Route these flags through their bundled local skills: - `--pr-security` -> `skills/commit-security-scan/SKILL.md` - `--security-review` -> `skills/security-review/SKILL.md` - `--threat-model` -> `skills/threat-model-generation/SKILL.md` - `--validate-security` -> `skills/vulnerability-validation/SKILL.md` Security workflow intent alone never grants Fixer authority. ## 6. Load roles progressively Canonical role instructions live under `skills/`; compatibility files under `prompts/` are generated copies and are not an independent source of truth. Load only the role needed for the current phase: | Phase | Canonical instructions | |---|---| | Recon | `skills/recon/SKILL.md` | | Hunter | `skills/hunter/SKILL.md` | | Skeptic | `skills/skeptic/SKILL.md` | | Referee | `skills/referee/SKILL.md` | | Fixer | `skills/fixer/SKILL.md` | | Documentation | `skills/doc-lookup/SKILL.md` | Calibration examples are **progressive**, not mandatory context for every assignment. Follow each role skill's instructions: load Hunter/Skeptic examples only for ambiguous/lower-confidence cases or when explicitly useful. Do not spend context on examples for settled cases. For delegated phases, include only the assigned bugs/files and necessary prior evidence. Do not copy whole merged ledgers into every worker prompt. ## 7. Choose execution mode Use `triage.strategy` as the size/partitioning strategy: - `single-file` -> `modes/single-file.md` - `small` -> `modes/small.md` - `parallel` -> `modes/parallel.md` - `extended` -> `modes/extended.md` - `scaled` -> `modes/scaled.md` - `large-codebase` -> `modes/large-codebase.md` If the selected backend is local-sequential, use `modes/local-sequential.md` as the execution implementation while retaining the triage scope/order/budget. Do not automatically turn a large-codebase request into loop mode. If the user did not request `--loop`, execute an honest single pass and report partial queued coverage. When `--loop` is active, combine the size mode with the loop contract. Extended/scaled/persisted execution should use `.bug-hunter/state.json`, exact source hashes, bounded retries, and fresh per-attempt output. The composition runner requires a real worker command that writes the requested canonical artifact; there is no no-op worker. ## 8. Evidence and source-integrity invariants These rules are non-negotiable across every mode: - Assigned paths are canonicalized through real paths and remain inside the repository. - A worker may report findings only for its exact assigned source files. - Capture source hashes before dispatch and recheck them immediately before committing findings/fact cards/completion state. - Source mutation, deletion, unreadability, or symlink escape fails the affected chunk closed. - Resume retains the original source baseline; changed content cannot silently become a new baseline for an interrupted run. - Missing/invalid canonical artifacts are failed phases, never clean evidence. - Coverage is derived from per-file evidence; a parent chunk marked done cannot manufacture file completion. - Duplicate observations preserve the strongest evidence and useful unioned cross-references/security metadata. - Findings without completed adversarial review stay `unreviewed` or `manual-review` and cannot authorize fixing. ## 9. Hunter -> Skeptic -> Referee ### Hunter Read assigned production source in risk/retrieval order. Findings require a concrete runtime trigger and repository evidence. Security findings must satisfy the canonical findings schema, including actionable STRIDE/CWE evidence when required. Test files are context-only. Canonical output: `.bug-hunter/hunter-findings.json`. ### Skeptic Challenge each finding from current code and relevant cross-references. Verify framework-dependent disprovals against documentation when possible. Generic rate-limit suggestions may be cheap to dismiss, but reachable credential stuffing, OTP/reset abuse, lockout bypass, measurable amplification, and attacker-triggered expensive work receive normal analysis. Canonical output: `.bug-hunter/skeptic.json`. ### Referee Referee independently owns final `REAL_BUG`, `NOT_A_BUG`, or `MANUAL_REVIEW` verdicts. Missing/failed Referee review leaves the finding unresolved and non-writable. Canonical output: `.bug-hunter/referee.json`. ## 10. Hybrid verification When a verification plan is supplied/required, execute it through the bounded hybrid verifier. Checks run as inert argv arrays with repository containment, secret stripping/redaction, output/time budgets, and `shell:false` semantics. A required check that fails, times out, or is unavailable makes verification fail closed. **Required verification failure prevents Fixer authorization.** A passing test/compiler/static check is evidence; it is not proof that unrelated bugs do not exist. Canonical output: `.bug-hunter/verification-report.json`. ## 11. Join and present the scan result Always preserve canonical Hunter/Referee artifacts and build the joined `.bug-hunter/scan-report.json`. Render `.bug-hunter/report.md` as a human view. JSON is the automation source of truth. Final results must distinguish: - `confirmed` — Referee accepted the finding; - `dismissed` — evidence disproved it; - `manualReview` — a human/wider decision remains; - `unreviewed` — adversarial review did not finish; - failed/pending coverage; - required-verification failure when applicable. Do not claim “audit complete”, “full coverage”, or “clean” while the requested scope still has unresolved review, failed coverage, or required-verification failure. If `LOOP_MODE=true`, continue according to the loop contract until every queued source file reaches a terminal outcome or an explicit hard blocker/user stop ends the run. If `LOOP_MODE=false`, report exactly what one pass covered and recommend `--loop` when full queued coverage is desired. ## 12. Plan and fix only with authority If there are confirmed bugs and `PLAN_ONLY_MODE=true` or `FIX_MODE=true`, build canonical remediation strategy/plan artifacts. Classify findings before creating executable Fixer work. Only Referee-confirmed, confidence-eligible, `safe-autofix` entries in the validated canary/rollout plan may enter immutable Fixer scope. Entries marked `manual-review`, `larger-refactor`, `architectural-remediation`, conflicting, or report-only remain non-writable regardless of severity. Canonical remediation files include: - `.bug-hunter/fix-strategy.json` - `.bug-hunter/fix-plan.json` - `.bug-hunter/fixer-scope.json` - `.bug-hunter/fix-report.json` For actual mutation, read `modes/fix-pipeline.md` and `skills/fixer/SKILL.md`. Preserve Git/worktree/lock/canary/circuit-breaker/rollback safeguards. Requested worktree isolation must not silently fall back to direct edits. Commit only when `AUTO_COMMIT=true`, and only approved paths. If `DRY_RUN_MODE=true`, stop before edits/lock/commits and report planned output as a preview, not an applied fix. ## Canonical artifacts Important schema-backed artifacts under `.bug-hunter/`: | Artifact | Purpose | |---|---| | `triage.json` | deterministic risk/scope/budget input | | `adaptive-plan.json` | bounded adaptive context/review policy | | `recon.json` | architecture/trust-boundary context | | `retrieval-plan.json` | hypothesis-ranked bounded evidence | | `hunter-findings.json` | Hunter claims | | `skeptic.json` | adversarial challenges | | `referee.json` | final verdicts | | `verification-report.json` | hybrid verification evidence | | `scan-report.json` | joined final machine result | | `coverage.json` | per-file coverage state | | `fix-strategy.json` | remediation classifications | | `fix-plan.json` | canary/rollout plan | | `fixer-scope.json` | immutable mutation boundary | | `fix-report.json` | remediation/verification/rollback result | | `benchmark-report.json` | precision/recall/calibration/stability/cost/latency metrics | ## Quality and benchmarking For source development, the full repository gate is: ```bash pnpm quality:world-class ``` The bundled benchmark fixture validates the measurement/gating contract. It is not independent proof of universal superiority. External claims require unseen repositories, blinded labels, repeated runs, disclosed model/runtime versions, and comparable baselines. See `docs/world-class-protocol.md`. ## Self-test From a **source checkout**, the development fixture can be scanned in read-only mode and scored with `evals/evaluate-fixture.cjs`. The npm runtime may exclude development fixture answers. Use the benchmark gate for deterministic protocol regression rather than copying a historical test-count claim into this skill. ## Failure policy Fail closed for: - invalid/missing required canonical artifacts; - source-integrity or repository-containment failure; - required verification failure; - invalid delegated payload; - Referee failure for affected findings; - immutable Fixer-scope violation; - unsafe Git/worktree preservation state. Recoverable worker failures may retry within configured bounds using fresh attempt outputs. Unrecoverable chunks remain failed/partial and visible. Never convert unavailable evidence, unsupported scanners, failed review, or failed safety checks into a clean result.