Bug Finder

---
name: bug-finder
description: "Scan a whole repository, or just its recent changes, for real bugs and security vulnerabilities, then open one GitHub issue per bug with a full report: context, actual vs expected, impact, the code with the bug marked, a reproduction or logical proof, the introducing commit and author, and a recommended fix. Runs the code to confirm each bug, ranks by what a maintainer would actually fix, dedupes against existing issues, and caps output so the tracker gets a short, high-signal list. Use when the user says find bugs, scan the repo for bugs, what's broken in this codebase, hunt for bugs, security scan, find vulnerabilities, open issues for the bugs you find, audit the last week of commits, or review everything that merged since the release. Repo-scoped, not diff-scoped: a code review covers one change, this hunts the codebase that already shipped."
compatibility: "Needs git, bash, and the GitHub CLI (gh) authenticated against the target repository. Works in any agent that can run shell commands. Parallel subagents are used when available but not required."
---

# Bug finder

Finding bugs is easy. Picking the bugs that matter is hard.

Point any agent at a codebase and it will produce hundreds of "findings." Most of them are not worth reading, let alone fixing, and an issue tracker full of them trains the team to ignore everything you file. The value of this skill is the opposite: a short list, every item real, every item proven by running code, every item one a maintainer would fix if they saw it.

Three rules drive everything below:

1. **Run the code.** A bug you have not reproduced, or proven with a tight logical argument from the code itself, is a guess. Guesses do not become issues.
2. **Select hard.** Aim to file the top one percent of what you can find. Ten strong issues beat fifty plausible ones.
3. **Never file the same bug twice.** Check the tracker before you write, and leave a fingerprint so future runs can check against you.

The output is GitHub issues, one per bug, in the report format in `references/report-template.md`. Read that file before writing any issue. The helper scripts referenced below live in this skill's `scripts/` directory, next to this file; call them by that full path, since you will be working from inside the target repo.

## 0. Parse the request

Arguments the user may include in the request, all optional:

| Argument | Meaning | Default |
| --- | --- | --- |
| `recent [7d]` | Only hunt in code changed in the window (duration or ISO date) | full repo |
| `path <dir>` | Only hunt inside this directory | whole repo |
| `security` | Only report security vulnerabilities | all bug kinds |
| `author <login>` | Only code introduced by this GitHub user | anyone |
| `--repo owner/name` | Where to open issues | the `origin` remote |
| `--depth quick\|standard\|deep` | How many candidates get verified and how many issues get filed (presets below) | asked, or standard |
| `--max N` | Cap on ordinary bugs filed this run, overriding the depth preset | from depth |
| `--dry-run` | Write the report and drafted issues, open nothing | off |
| `--yes` | Skip the confirmation gate before filing | off |

Infer the repo from `git remote get-url origin`. Confirm `gh auth status` works before doing hours of work you cannot publish.

### Depth

Depth is the one setting people cannot guess until they have seen a run, because it decides how many candidates get verified before time runs out. Three presets:

| Depth | Scope if none given | Candidates verified | Ordinary bugs filed | Rough time |
| --- | --- | --- | --- | --- |
| `quick` | `recent 30d` | the 15 strongest | up to 5 | about 10 minutes |
| `standard` | full repo | up to 60 | up to 10 | about 45 minutes |
| `deep` | full repo | every candidate | up to 15 | an hour or more |

Verified security vulnerabilities are filed at every depth regardless of the cap.

If the request names a depth, or passes `--yes`, or is clearly a scheduled or scripted run, do not ask anything; default to `standard`. Otherwise ask the user exactly one question before starting: which depth they want, with the three rows above as the options. Use your agent's structured question tool if it has one; if not, ask in a single plain message listing the three options and wait for the answer. Do not ask about scope, repository, or labels; the request already carries those. This is the only question the skill asks before the confirmation gate in step 6.

## 1. Set up the environment and get the code running

The edge over a shallow scanner is that you build the dev environment and exercise the code. Do that before you hunt. Read the project's agent instructions file if it has one, the README, and the package manifest. Install dependencies. Run the test suite once and record the baseline (how many pass, how many fail, how long it takes). If the suite is green and fast, integration tests are usually a cheaper and more reliable way to exercise endpoints than booting the app. Boot it only when something you need to prove has no test-level entry point.

Note what you can execute: unit tests, a REPL, a dev server, a CLI, a one-off script runner. You will need these in step 3. If nothing runs, say so in the final report and lower your confidence bar accordingly. You will lean on logical proof instead of reproduction, and you should file fewer issues.

While the suite runs, build two lists that the hunters will need.

**The spec inventory.** The project has already written down most of its rules: policy and design docs under `docs/`, class and file headers that state an invariant ("this cap bounds new capture spend", "a dead event must not overwrite the live one"), tests that pin a contract, and closed issues that fought for a behavior. Skim those sources and write the stated rules to `.bug-finder/spec.md`, one line each with where it is written. Twenty to sixty lines is typical. Hunters test code against this list; a clause in a policy doc with no implementation is one of the most reliable bug shapes there is, and nobody finds it without reading the doc.

**The churn ranking.** List merged pull requests from the last sixty days by lines changed (`gh pr list --state merged --limit 100 --json number,title,additions,deletions,mergedAt`). In a typical run a third of the real bugs live in the two or three largest, because a three-thousand-line PR got the same review as a thirty-line one. The top few become hunting areas of their own in step 2.

## 2. Hunt for candidates

Read `references/hunting-patterns.md` for what to look for and where. The short version: the highest-yield bugs are