Find Bugs

# /find-bugs

Run a persona agent that explores the configured web app and files GitHub issues for any bugs it finds.

**Usage:** `/find-bugs <persona-id>`
**Example:** `/find-bugs new-user`

The persona id is read from `$ARGUMENTS` and must match a file in `.claude/personas/`.

---

## 1. Pre-flight (mandatory)

Before doing anything else, in this exact order:

1. Use the **Read** tool to load `bughive.config.json`. Validate it against `bughive.config.schema.json` (also via Read). If validation fails (missing required fields, wrong types, malformed JSON), log:

BUGHIVE_RESULT: aborted=invalid_config, error=

and stop.
2. Read `.claude/personas/$ARGUMENTS.json`. Validate it against `.claude/personas/schema.json`. If invalid, log `BUGHIVE_RESULT: aborted=invalid_persona` and stop.
3. Read **all three** Phase 1 skill files:
- `.claude/skills/screenshot-diffing.md`
- `.claude/skills/error-log-reading.md`
- `.claude/skills/reproduction-steps.md`
4. **Startup check**: call Playwright MCP `browser_navigate(config.appUrl)` with a 10-second timeout. If the app does not respond, log:

BUGHIVE_RESULT: aborted=app_unreachable, url=<config.appUrl>

and stop. Do **not** continue exploration against an unreachable app.

---

## 2. Pre-exploration duplicate scan

Before exploring, search GitHub for issues this persona has filed in the last 24 hours:

GitHub MCP search_issues: query: label:persona: created:>=<24h ago>

Build a `known_bugs` list from the results: each entry should record (title, file/area, repro hash). During exploration, if you encounter what looks like a known bug, **do not file a new issue** — instead, comment on the existing one:

Confirmed by at .

This prevents the persona-sweep from re-filing the same bug every 6 hours.

---

## 3. Persona context

You are now operating as the persona described in the loaded JSON. Internalise:

- `prompt` — your overall narrative
- `behaviors.errorHandling`, `behaviors.exploration`, `behaviors.dataEntry`, `behaviors.patience` — drive your decisions
- `forbiddenActions` — actions you must not take
- `bugSeverityBar` — the lowest severity you will file (anything below this is noted but not filed)
- `viewport` — set the browser viewport before navigating
- `focusAreas` — areas of the app to prioritise

You **must not** modify any source code. You are read-only. The fixer agent handles fixes; your job is exploration and bug filing only.

---

## 4. Context budget (CRITICAL — read carefully)

You have a finite context window. Manage it actively:

- **Keep at most the last 2 full screenshots in context.** When you take a third screenshot, replace the oldest screenshot with a 1-line text summary like:

[turn 4 @ /signup] Form had Name/Email/Password/Confirm fields. No console errors. Submit button enabled.

- **Hard turn limit: 25.** Stop exploring after 25 turns regardless of any other limit.
- **Self-check every 5 turns**: estimate context usage. If above 80%, wrap up — file pending bugs and stop.
- **Don't re-screenshot pages you've already analysed** unless you suspect a state change.

---

## 5. Exploration loop

Repeat until **any** of the following is true:
- `issued_count >= guardrails.maxIssuesPerPersonaRun`
- `elapsed_minutes >= persona.sessionBudgetMinutes`
- Turn count >= 25
- Context budget > 80%

Each iteration:

1. **Decide next action** based on your persona's `behaviors` and `focusAreas`. Prefer interactive elements you haven't tried yet. Cycle through pages: landing → signup/login → dashboard → new task → edit task → settings.
2. **Take a before screenshot** (Playwright MCP `browser_take_screenshot`, or `browser_snapshot` for an accessibility tree instead of an image — cheaper on context).
3. **Execute the action** (`browser_click`, `browser_type`, `browser_navigate`, `browser_resize`, `browser_fill_form`, etc.).
4. **Take an after screenshot** (or `browser_snapshot`).
5. **Check the browser console** (`browser_console_messages`) for errors and warnings. Apply the `error-log-reading` skill.
6. **Check network requests** (`browser_network_requests`) for failed calls and slow requests.
7. **Apply screenshot-diffing**: compare before/after for visual anomalies.
8. **Decide whether you found a bug.** Apply the bug-filing gate (next section).

---

## 6. Bug-filing gate (must pass ALL of these before `create_issue`)

A finding is **only** filed as a bug if **every** check passes:

- [ ] **Reproducible**: you can describe the steps that triggered it. No "it just happened".
- [ ] **Evidence**: at least one of — a console error, a failed network request, a visible visual break, a state inconsistency. Cosmetic preferences don't count.
- [ ] **Above the persona's `bugSeverityBar`** — if you'd file this as below the bar, note it in your scratchpad and skip filing.
- [ ] **Not in `known_bugs`** — if it matches a previously filed issue this persona has open, comment on the original instead.
- [ ] **Not in the "What does NOT count as a bug" list** below.

If the finding passes all checks, write the issue body following the `reproduction-steps` skill template (numbered steps, expected/actual, evidence, environment, replay snippet) and call `GitHub MCP create_issue` with these labels:

- `bug` (use `config.labels.bug`)
- `persona:<id>`
- `severity:<critical|high|medium|low>`

Then increment `issued_count` and continue exploring.

### Severity guide

| Severity | Examples |
|----------|----------|
| critical | App crash, white screen, data loss, security vulnerability (XSS, auth bypass) |
| high | Feature completely broken, blocks primary user flow, 5xx error, validation gap that lets bad data through |
| medium | UI glitch, confusing behavior, cosmetic issue with usability impact, mobile layout break |
| low | Minor polish, edge case, console warning with no visible impact |

### What counts as a bug

- JavaScript errors in console
- Net