# QA Flow

> Run a guided browser-based QA flow against a local or staging URL using the persistent browser runtime when available.

- Skill: `munlucky/qa-flow` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add munlucky/qa-flow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/munlucky/qa-flow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: munlucky (https://skillmd.com/u/munlucky)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/munlucky/qa-flow

---


# QA Flow

## Role

Verify a user-facing flow in a real browser session and return a compact pass/fail report.

## Status

This skill is an optional verification-bundle member.
It can run browser smoke checks when a target URL is available, or run a conversational QA triage path when the user reports issues.
It is not part of the default verification chain unless a workflow explicitly selects guided browser QA.

## Inputs

- target URL
- optional flow name such as `smoke`, `auth`, `checkout`, or `dashboard`
- optional auth/setup notes
- optional user-reported issue or QA notes
- optional GitHub issue export intent

## Intended Runtime Path

Primary path:

- `<MOONSHOT_RELAY_HOME>/bin/browserctl`

Fallback path:

- `skills/browser-verifier/SKILL.md`
- `agents/verification/verify-runtime.sh`

## Usage

```bash
/qa-flow --url=http://localhost:3000 --flow=smoke
/qa-flow --url=https://staging.example.com --flow=auth
/qa-flow --url=http://localhost:3000 --flow=dashboard --notes="requires seeded admin user"
```

## Workflow

1. Validate the target URL.
2. Start or reuse the persistent browser session.
3. Navigate to the page and collect an initial snapshot.
4. Execute flow-specific steps.
5. For critical `SCN-*`, prefer the full depth path: open -> act -> mutate -> persist -> recover.
6. Capture failures with screenshots or log excerpts when possible.
7. Return a pass/fail/warn summary with concrete next actions.

## Conversational QA Triage

When the user is reporting bugs instead of asking for a browser smoke run:

1. Ask at most 2-3 short clarification questions only if expected behavior, actual behavior, or reproduction steps are missing.
2. Explore relevant project docs and domain terms in the background when available.
3. Decide whether the report is one issue or several independently fixable issues.
4. Produce durable issue drafts focused on user-visible behavior.
5. If GitHub export is explicitly requested and the GitHub tool/CLI is available, create issues in dependency order and return URLs.

Issue drafts must:

- use project domain language
- describe expected vs actual behavior
- include reproduction steps
- avoid file paths and line numbers unless the user asks for tactical implementation notes
- include AFK/HITL classification when agent handoff is expected
- include a TDD fix-plan outline for confirmed bugs

## Flow Contract

Each flow should eventually define:

- entry URL
- prerequisite state
- expected visible markers
- critical interactions
- runtime evidence depth: `smoke` or `open-act-mutate-persist-recover`
- pass/fail conditions
- normalized trace metadata path produced by `scripts/verification-plane.mjs normalize-browser-trace`
- verification plane linkage: `plane=browser`, `status`, `tracePath`, and `evidenceDepth`

## Output Contract

- flow name
- target URL
- runtime used
- pass/fail status
- runtime evidence depth
- critical scenario smoke-only warnings
- issues found
- suggested fixes or follow-up checks
- issue drafts or issue URLs when QA triage is requested
- evidence paths such as screenshots, console excerpts, or QA report updates when available
- browser trace metadata under `.moonshot-relay/browser-artifacts/<runId>/<goalId>/<flow>/trace-metadata.json` when run/goal identity is available

## Failure Policy

- If browser runtime is missing, report setup gap and recommend the current `browser-verifier` fallback.
- If a flow is not yet implemented, report that explicitly instead of running partial checks silently.
- If a critical scenario only has smoke/page-load evidence, return `warn` and block clean-finish wording until deep interaction evidence exists.
- If reproduction steps are missing, do not invent them; ask a targeted question or mark the issue draft as blocked on reproduction.