Runs a real-user manual QA pass against any web/mobile/desktop app and turns the results into a Bug Review Board (BRB) feedback loop. Use whenever the user says "QA this", "test phase N", "run a manual test plan", "act as a real user", "find UX bugs", "sign off this build", "file a bug report", or "is this ready to ship?" — even if they only describe the symptoms ("the signup flow feels broken", "check what's wrong before we move on", "we finished feature X"). Drives the trifecta: PM (verifies user-promise), QA (executes scenarios from a real user's perspective), and Engineer (flags invalidated assumptions). Repo-agnostic, browser-tool-agnostic, scaffolds folders for bug reports + run reports + coordinator merges with P0/P1/P2 priorities. Works alongside cursor-ide-browser, browser-use, Playwright, manual driving, or any future browser tool.
How this skill is triggered — by the user, by Claude, or both
Slash command
/running-bug-review-board:running-bug-review-boardThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill runs a **real-user QA pass** on an app and feeds the output into a
references/browser-playbook.mdreferences/bug-filing.mdreferences/discovering-the-app.mdreferences/gate-merge.mdreferences/parallel-coordinator.mdreferences/sequential-wrapup.mdreferences/session-hygiene.mdreferences/templates/bug-report.mdreferences/templates/coordinator-merge.mdreferences/templates/run-report.mdreferences/templates/sequential-prompt.mdreferences/templates/shard-prompt.mdreferences/templates/test-plan.mdreferences/test-accounts.mdreferences/test-plan.mdreferences/workflow.mdscripts/scaffold-qa.shThis 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, and a final YES/NO sign-off the team can act on. It generalizes a battle-tested workflow that already shipped phase QA on Mokuhoe — the techniques are repo-agnostic.
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.
For every pass, wear all three hats:
Do not fix product code unless the user explicitly asks. Test, document, file bugs, hand off.
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 for the full investigation playbook. The short version:
If the user says "QA this app" but no docs exist, ask — see references/discovering-the-app.md § Asking the user. Common questions: "Where's the test account playbook?", "Which viewport(s) are primary?", "Where's the sign-up entry point?".
1. Scope → which surface / phase / build
2. Discover → product intent + recent change + open bugs
3. Plan → manual test plan (scenarios, IDs, expected, gates)
4. Prepare → env, build, test accounts, viewport
5. Mode → parallel coordinator OR sequential wrap-up
6. Execute → real-user scenarios with evidence
7. File bugs → P0/P1/P2 with reproduction steps
8. Merge → results + verdict (YES/NO + open P0/P1)
9. Hand off → next QA agent (if NO) or engineering (if blockers)
Detail in references/workflow.md.
| Situation | Mode | Reference |
|---|---|---|
| Fresh full pass on a phase, multi-agent OK | Parallel coordinator | references/parallel-coordinator.md |
| Prior parallel run stalled or partial | Sequential wrap-up | references/sequential-wrapup.md |
| Solo agent, small surface | Sequential, ordered top-to-bottom | references/sequential-wrapup.md |
| Re-testing 1–3 fixed bugs after engineering shipped | Sequential, scoped to bug Test IDs | references/sequential-wrapup.md |
| No test plan exists yet | Generate plan first | references/test-plan.md |
| Phase doc lists features not yet implemented in code | Stop. Tell user — QA needs a working build | — |
If the target repo has no QA folder structure yet, run the bundled scaffolder to create it:
bash <skill>/scripts/scaffold-qa.sh "$REPO_ROOT" PHASE_NUM [SLUG]
It creates (idempotent — won't overwrite existing files):
<repo>/docs/qa/
├── README.md # how QA works in this repo
├── phase-NN-<slug>-manual-test-plan.md # filled-in skeleton
├── bug-reports/
│ ├── README.md # index + status workflow
│ ├── _template.md # bug template
│ └── assets/ # screenshots
└── runs/ # per-shard + coordinator merges
If a different layout already exists in the repo (e.g. tests/manual/,
qa/, an issue tracker), adopt that layout — do not duplicate it.
convex/users.ts or the API layer alone.+test email reuse silently poisons fresh-user
flows.| Level | Definition | Action |
|---|---|---|
| P0 | Blocks core flow; data loss; auth bypass; security | Phase cannot ship; halt QA pass until triaged |
| P1 | Feature broken or wrong; workaround exists | Blocks current phase sign-off |
| P2 | Cosmetic, edge case, accessibility, dev console noise | Defer to polish phase or release hardening |
When in doubt between P0 and P1, choose P0 if a user could land in a non-recoverable state or lose data.
Every pass ends with a coordinator merge doc whose top line reads:
Phase N ready? YES — all gates ☑, no open P0/P1. Phase N ready? NO — list open P0/P1 + remaining unrun scenarios + a one-paragraph handoff prompt for the next QA agent.
If NO, the merge doc must be paste-ready into a new conversation. The next agent should not need to rediscover state. See references/gate-merge.md.
Default to cursor-ide-browser MCP when running inside Cursor. If the session is in another tool or browser MCP is missing, fall back per the ladder in references/browser-playbook.md:
Whatever tool, the playbook is the same: navigate → snapshot → act on fresh refs → capture evidence → unlock when done. The reference covers each tool's specifics.
| Path | What |
|---|---|
docs/qa/phase-NN-<slug>-manual-test-plan.md | (if newly generated) |
docs/qa/runs/QA-<shard>-run-YYYY-MM-DD.md | Per-shard results |
docs/qa/runs/COORDINATOR-MERGE-YYYY-MM-DD.md | Merge + verdict |
docs/qa/bug-reports/BUG-NNN-*.md + assets/BUG-NNN/ | Each defect |
docs/QA_GATES.md (or your repo's equivalent) | Gate boxes updated |
| Phase doc § QA status | Sign-off note + link to merge |
Adapt paths to whatever the target repo already uses.
scripts/scaffold-qa.sh REPO_ROOT PHASE_NUM [SLUG] — creates the QA
folder layout and seeds skeletons in any repo.| Don't | Why |
|---|---|
| Mark scenarios PASS from code inspection | Users don't experience source |
| Defer P0 bugs to "next phase" | Foundation bugs cascade everywhere |
| Trust prior PASS marks without re-running on a fresh build | Regressions appear from unrelated work |
| Run multiple QA agents on one browser tab | Auth providers throttle; sessions bleed |
| Edit the phase doc to match buggy behavior | Hides the regression — file a bug instead |
| File a bug without Steps to reproduce | Engineering can't act on it |
| Test only the happy path | The happy path is what engineers tested already |
If during the pass you find:
Stop testing. Surface the finding. The user decides whether to escalate to engineering or carve a smaller phase. Continuing wastes time on a foundation that needs replacing.
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub rayfernando1337/rayfernando-skills --plugin running-bug-review-board