/running-bug-review-board

name: running-bug-review-board
description: >-
  Runs real-user QA, manual test plans, UX bug hunts, build sign-off,
  bug filing, and bug triage for web or iOS/iPadOS apps. Use when asked
  "QA this", "is this ready to ship?", or similar. Produces P0/P1/P2
  bug reports, YES/NO phase sign-off, tracker sync guidance, and an
  HTML QA dashboard; keeps Interactive BRB triage in a separate session.

Running the Bug Review Board (BRB) QA pass

This skill runs a **real-user QA pass** on an app and feeds the output into a Bug Review Board: a folder of structured bug reports, per-pass run reports, a self-contained HTML dashboard, and a final YES/NO sign-off the team can act on. Engineering's tracker (Linear / GitHub / Jira / Notion) syncs bi-directionally so QA and engineering stay in step.

It generalizes a battle-tested workflow that already shipped phase QA on Mokuhoe — the techniques are repo-agnostic.

Why this exists

Most engineers test their own code. They confirm what they wrote works. That misses the bugs **real users hit first** — stale state across flows, mobile overflow, copy that lies, paths that 404 mid-onboarding, race conditions between auth and routing.

This skill simulates a real user. The QA agent acts like a careful, mildly unforgiving customer who does not read the source code.

Two workflows — Auto QA and Interactive BRB

The skill splits the work into two distinct modes that share artifacts but **run in separate sessions** on purpose:

• **Auto QA pass** — the agent drives the app, runs scenarios, files

bugs, generates the HTML report, writes a verdict. Optimized for thoroughness and speed.

• **Interactive BRB** — a *different* agent meets with the user to

triage open / in-progress / fixed bugs. Runs the bi-directional pull first, applies pattern-based heuristics to surface duplicates and clusters, walks each bug, flips statuses, syncs to the tracker, regenerates HTML, writes minutes. Optimized for shared judgment.

Keep them separate. Running BRB inside an auto pass lets triage bias contaminate discovery and confuses attribution. See [references/brb-interactive.md](references/brb-interactive.md).

The trifecta — three hats, one pass

For every pass, wear all three hats:

• **Product Manager.** Confirm the build delivers the user-visible

promise documented in the product spec or phase doc. If it does not, that is a product gap, not a bug — flag it in the run report.

• **QA.** Execute every scenario from a real user's perspective on the

primary supported viewport(s). Capture evidence (snapshot, console, server data when relevant). Pass / Fail / Blocked.

• **Engineer.** Watch for invalidated assumptions: phase doc says "X

uses function Y" but Y was renamed; new client orchestration appeared in a flow the docs say is server-driven; fields exist in UI that aren't in the spec. **Finding gaps is the point** — don't reverse- engineer the docs to match buggy behavior.

Do **not** fix product code unless the user explicitly asks. Test, document, file bugs, hand off.

Discover the app first (or you'll write bad tests)

Before writing a single test, understand the **intent** of the app — what the customer is hired to do with it. See [references/discovering-the-app.md](references/discovering-the-app.md) for the full investigation playbook. The short version:

1. Read the product spec / README / landing page / pitch deck (in that priority order) for what the app **promises**. 2. Read the phase doc (or current sprint plan) for what was **just built**. 3. Read prior QA gates / checklists for what passed before — regressions are your highest-value finds. 4. Read the bug-reports index — open bugs are scenarios you must re-test first. 5. **Detect the project type(s).** A repo can ship more than one app — a **web + iOS monorepo** is common — so **collect every surface whose signals are present** instead of stopping at the first hit. Two disambiguation rules resolve *overlapping signals inside a single app*; they are **not** a reason to skip a genuinely separate surface:

• **Electron / Tauri beats Web app for the same app.** An Electron /

Tauri project (`electron`, `@electron/`, `@tauri-apps/` in `package.json`, or `electron-builder.yml` / `tauri.conf.json`) also contains `package.json` and web framework deps, but those deps belong to the desktop app — count it **once** as a desktop app, do **not** also count it as a separate **Web app**.

• **macOS vs iOS on a shared `*.xcodeproj` / `*.xcworkspace`.** A bare

Xcode project is shared between the two, so don't classify on it alone — require a platform-specific marker (below).

The surfaces, with the playbook each activates:

• **Electron / Tauri desktop app** → use

[computer-use-playbook.md](references/computer-use-playbook.md). (On non-macOS hosts where Computer Use is unavailable, the playbook's graceful-degradation table directs you to drive the app's dev-server URL via [browser-playbook.md](references/browser-playbook.md) instead.)

• **Web app** (web framework deps without Electron / Tauri markers) → use

[browser-playbook.md](references/browser-playbook.md).

• **iOS / iPadOS app** (an iOS-specific marker is present — `.iOS(...)`,

`platform :ios`, `UIDeviceFamily`, or an `ios/` directory) → use [ios-simulator-playbook.md](references/ios-simulator-playbook.md).

• **Native macOS app** (a macOS-specific marker is present — `.macOS(...)`,

a `.app` bundle, or `LSMinimumSystemVersion` — and no iOS marker) → use [computer-use-playbook.md](references/computer-use-playbook.md).

• **Mixed (monorepo)** — signals for two or more distinct surfaces

above (e.g. web framework deps **and** an iOS marker) → run **every** matched playbook; the test plan gets per-platform scenario blocks. A web match must **never** short-circuit a co-located iOS (or macOS) pass