Original source pages and recordings require authorized access. The full article text here is public.
Web developers already trust tests for known requirements, but fast-moving UI work also needs cheap exploratory passes that click through real app state. This technique gives local agents a practical browser-facing QA job: find weird UX and state bugs before users do.
Copy-paste workflow
When to use: When you want to surface state bugs and UX dead ends a happy-path check would miss. This launches many cheap agents that click around in weird, non-obvious ways from assigned perspectives, recording findings to discardable QA files.
Copy-paste prompt
Run a "5 Monkeys" QA swarm on <APP/FEATURE>. The point is to find state bugs and UX dead ends the happy path would never reveal — so do NOT just walk the happy path.
1. Assign yourself (or each worker agent) a PERSPECTIVE lens and stay in character:
expert power user / brand-new first-time user / a grandparent / impatient power user.
2. Explore WEIRD, non-obvious paths explicitly:
- keyboard shortcut sequences
- back/forward navigation mid-flow
- repeated/rapid clicks on the same control
- toggling modes back and forth
- partial or abandoned flows (start, then bail)
Try to break state, not to succeed.
3. Write findings to a DISCARDABLE numbered QA markdown file (e.g. .notes/qa-01.md). These are cheap — regenerate freely.
4. After the runs, collate the findings and keep ONLY the useful ones.
Guardrails: keep rigorous tests for stable business logic — don't over-test UI you still expect to reshape daily. If you use a browser agent, script the auth/login path explicitly: cookies are NOT shared.
How it works
- Each agent gets a perspective lens (expert, brand-new user, grandparent, power user) and explores the app in character.
- Agents deliberately explore weird paths — shortcut sequences, back navigation, repeated clicks, mode toggles, partial/abandoned flows — instead of the happy path, which is where state bugs hide.
- Findings go to discardable numbered QA markdown files (cheap, regenerate freely); collate afterward and keep only the useful ones.
- Keep rigorous automated tests for stable business logic; don't over-test UI you still expect to reshape daily.
- If using a browser agent, script the auth/login path explicitly — cookies are not shared between agents.
- Reference: Agent Browser.
Reusable skill
Install as ~/.agents/skills/five-monkeys-qa/SKILL.md, then restart Codex.
---
name: five-monkeys-qa
description: Trigger when you want to surface state bugs and UX dead ends a happy-path check would miss — launch perspective-based agents that explore weird, non-obvious paths and write findings to discardable QA files. Do NOT use to replace rigorous tests for stable business logic.
---
# 5 Monkeys QA
Launch cheap perspective-based agents that explore the app in weird, non-obvious ways to surface state bugs and UX dead ends the happy path would never reveal. Findings go to discardable QA files.
## Steps
1. Assign each agent a PERSPECTIVE lens and have it stay in character:
- expert power user
- brand-new first-time user
- a grandparent
- impatient power user
2. Explore WEIRD, non-obvious paths explicitly (not the happy path):
- keyboard shortcut sequences
- back/forward navigation mid-flow
- repeated / rapid clicks on the same control
- toggling modes back and forth
- partial or abandoned flows (start, then bail)
3. Each agent writes findings to a DISCARDABLE numbered QA markdown file (e.g. `.notes/qa-01.md`). They are cheap — regenerate freely.
4. Collate the findings and keep ONLY the useful ones.
## Guardrails
- Keep rigorous automated tests for STABLE business logic — this does not replace them, and don't over-test UI you still expect to reshape daily.
- If using a browser agent, script the auth/login path explicitly — cookies are NOT shared.
Scenarios
Authenticated dashboard weird-path pass
Role: As a frontend engineer shipping an authenticated Next.js dashboard
A Next.js app has a local dev server, a login flow, route-level navigation, filter panels, modal dialogs, and a dashboard state that often changes during product iteration.
As a frontend engineer, I want several perspective-driven agents to explore non-happy-path dashboard behavior, so that I can catch stuck state, broken back navigation, and confusing UI before merging.
Agent brief
Run a 5 Monkeys QA swarm against the authenticated dashboard. First inspect the repo for the dev command and any documented test user or seeded auth flow. Start the app locally using the repo’s normal command, such as npm run dev, pnpm dev, or the command documented in package.json/README. Create .notes/qa-dashboard-swarm.md as a discardable numbered QA file. Assign five lenses: expert power user, brand-new first-time user, grandparent/inexperienced user, impatient power user, and distracted returning user. For each lens, use a browser workflow against localhost and deliberately avoid only confirming the happy path. Try: login, navigate to the dashboard, open filters, toggle modes, click the same controls repeatedly, use browser back/forward mid-flow, abandon a modal halfway through, refresh after changing state, and return to the page. Record each finding with: perspective, exact path, expected behavior, observed behavior, severity, and whether it looks like stable business logic or fast-changing UI. Expected output: .notes/qa-dashboard-swarm.md plus a short final summary of the 3-7 useful findings only.
Implementation references
package.json
README.md
cmux --json tree
cmux read-screen
cmux markdown open .notes/qa-dashboard-swarm.md --direction right
Browser verification
Use an agent-browser-style pass or CMUX browser pane against the local URL. Take an accessibility snapshot after login, click through navigation and controls, fill the login form using explicit test credentials or signup instructions from the repo, use back/forward after reaching nested dashboard states, then evaluate whether visible state, URL, and focused controls still agree.
Definition of done
- A discardable .notes/qa-dashboard-swarm.md file exists with numbered findings grouped by perspective.
- The browser proof includes local URL, login path used, at least one snapshot or screenshot reference, and notes on back/forward, repeated-click, and toggle behavior.
- The final triage separates useful findings from noise and marks which issues deserve durable tests because they touch stable business logic.
Failure modes and mitigations
- The agent only walks the happy path; mitigate by requiring each perspective to perform at least three weird-path moves before writing conclusions.
- The agent assumes existing browser cookies; mitigate by scripting login/signup explicitly and recording the auth path used.
Checkout flow state-bug hunt before release
Role: As a full-stack web developer preparing a checkout or billing flow for release
A local ecommerce or SaaS checkout flow has plan selection, quantity changes, discount code entry, payment-step navigation, validation messages, and browser history interactions.
As a full-stack developer, I want agents to attack the checkout flow from different user perspectives, so that I can find state mismatches and UX dead ends without overbuilding brittle tests for UI that may still change.
Agent brief
Run the 5 Monkeys technique on the checkout/billing flow. Treat stable pricing, totals, validation rules, and submitted payloads as serious business logic; treat copy, spacing, and visual layout notes as flexible UI findings unless they block the user. Create .notes/qa-checkout-five-monkeys.md. Start the local app and document the exact command. Assign lenses: expert buyer, brand-new customer, grandparent/inexperienced user, impatient power user, and skeptical returning customer. In the browser, test non-obvious paths: change plan then press back, enter then remove a coupon, rapidly change quantity, start checkout then abandon before payment, refresh on a later step, use keyboard navigation where controls are visible, and retry after validation errors. Capture console errors, visible state, URL, and any mismatch between displayed total and expected total. Expected output: a discardable QA file, a concise release-risk summary, and recommendations for which findings should become durable automated tests.
Implementation references
package.json
playwright.config.* if present
.notes/qa-checkout-five-monkeys.md
Browser verification
Use Playwright, a CMUX browser pane, or an agent-browser-style snapshot/click/fill/evaluate loop. Fill checkout inputs, click plan and coupon controls, use browser back/forward between checkout steps, refresh after a partial flow, and evaluate the DOM text for totals, validation messages, and disabled/enabled button state.
Definition of done
- A .notes/qa-checkout-five-monkeys.md file lists exact reproduction paths for each useful checkout finding.
- Browser evidence includes the local URL, console-log notes, visible totals or validation text, and the action sequence that triggered each issue.
- The final review identifies which findings should become durable tests because they protect stable business logic.
Failure modes and mitigations
- The agent treats all UI observations as test-suite requirements; mitigate by explicitly classifying stable business logic separately from fast-changing UI.
- The agent reports vague concerns without reproduction steps; mitigate by requiring every useful finding to include exact clicks, form inputs, URL/history moves, and observed result.
Stress-test a pricing-plan upgrade flow
Role: As a growth engineer owning a SaaS pricing page and upgrade checkout
A pricing page has monthly/yearly toggles, plan comparison cards, a coupon field, and an upgrade checkout modal. Happy-path tests pass, but users keep finding weird state bugs after toggling billing periods, backing out of checkout, and switching plans.
As a trial user comparing plans, I want billing toggles, coupon validation, selected plan state, and checkout recovery to stay consistent, so that I can upgrade without losing trust in the pricing flow.
Agent brief
Run a 5 Monkeys QA pass against the local pricing and upgrade flow. Assign five perspectives: brand-new trial user, impatient mobile user, keyboard-only user, existing customer changing plans, and skeptical QA engineer. Each perspective should explore weird paths: toggle monthly/yearly repeatedly, apply invalid and valid coupons, switch plans after opening checkout, use back/forward, refresh mid-flow, and try keyboard navigation. Each worker writes one discardable QA file under `.notes/qa/pricing-<perspective>.md` with steps, expected result, observed result, screenshot or browser transcript path, severity, and whether the issue is reproducible. Collate findings into `.notes/qa/pricing-summary.md` and recommend only the highest-value fixes.
Implementation references
package.json scripts
local pricing route and checkout/modal source files
cmux browser snapshot/click/fill/evaluate commands or existing Playwright tests
Browser verification
Use a CMUX browser pane, Playwright if already present, or an agent-browser-style snapshot/click/fill/evaluate loop. Open the local pricing route, snapshot plan names and billing toggle state, click monthly/yearly, open checkout for each plan, fill coupon codes, use back/forward and refresh, and capture visible selected-plan text plus console errors after each odd path.
Definition of done
- Five perspective-specific QA markdown files exist under
.notes/qa/. - The summary separates reproducible product bugs from preference notes and one-off observations.
- At least one browser receipt exists per high-severity finding: screenshot, accessibility snapshot, console output, or Playwright trace.
- Recommended fixes are ranked by user impact and implementation risk, not by which worker found them first.
Failure modes and mitigations
- The workers all follow the same happy path; mitigate by assigning explicit perspectives and weird-path instructions before they start.
- The agent turns observations into permanent tests too early; mitigate by keeping findings discardable until the team decides which behavior should become stable.
- The QA pass uses real payment/customer data; mitigate with local fixtures, test cards, or mocked checkout state only.
Implementation notes
- Keep the QA files explicitly discardable under .notes/ so agents can regenerate them as the UI changes.
- For browser verification, tell the agent the login or signup path; do not assume cookies, private session state, or authenticated browser context.
- The useful receipt is not a large pile of findings. It is a short triage of reproducible weird-path issues, with noisy observations removed.
- Keep rigorous automated tests for stable business logic such as checkout totals, permissions, data persistence, and validation rules.
- Use CMUX browser panes, agent-browser-style snapshots/click/fill/evaluate, or Playwright when live UI behavior matters more than source inspection.
- Grounded in the uploaded scenario bundle. :contentReference[oaicite:0]{index=0}
Boundaries and caveats
- Do not turn discardable QA files into a permanent Storybook-style or full integration-test framework.
- Do not introduce tools that were only mentioned but not taught as the technique for this workflow.
- Do not assume browser agents inherit the developer's cookies or private authenticated state.
- Do not use worktrees by default for this playbook; keep the scenario focused on the single selected toolkit technique.
- Do not claim the swarm replaces stable business-logic tests.
Agent reference map
Existing 5 Monkeys prompt
Use it as the canonical copy-paste behavior contract for perspective lenses, weird-path exploration, discardable QA files, and browser-auth guardrails.
Existing five-monkeys Codex skill
Use it to keep the agent behavior aligned with the toolkit technique instead of inventing a new QA framework.
Validated lesson 05 references
Treat this as ground truth for taught concepts: perspective prompting, discardable QA files, 5 Monkeys exploration, CMUX state, browser-driving tools, and video-driven intent extraction.
Lesson 05 validation notes
Use it to avoid reintroducing details removed during validation, especially anything only mentioned in chat or not taught as a workflow.
CMUX state and pane commands
Use these commands when the agent needs to inspect the active workspace, read terminal output, or open a live Markdown QA tracker.
cmux --json tree; cmux read-screen; cmux markdown open .notes/qa-dashboard-swarm.md --direction right