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 40 | up to 10 | about 30 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.