cskwork/supergoal-skill / skills/supergoal
supergoal
UnverifiedRoute objective-driven development, verification, planning, "teach/explain", codebase learning, and skill evaluation through the Supergoal workflow. Use when Supergoal is requested or an autonomous delivery workflow is needed.
reference/qa.md
View on GitHub# QA - black-box exercise of the running app
QA drives the real app like a user and records observable evidence. Applies to GREENFIELD/LEGACY and
web-bug DEBUG checks.
UI changes are browser app verification: if product code changes a user-facing browser surface, the run
must drive that surface with `agent-browser` and pass `bash templates/qa-gate.sh <vault> browser`.
Lint/typecheck/build/unit/static screenshots can support but not replace browser evidence.
QA-ONLY is the broad regression lane. For "QA only", broad verification, or post-change impact sweep, use
`reference/qa-only.md`'s Impact Matrix. GREENFIELD/LEGACY/DEBUG browser QA stays lean by default, but may
borrow the matrix for high-blast-radius changes.
## Characterization baseline (non-UI code changes)
Use when GREENFIELD / DEBUG / LEGACY work touches shared code/state: function, module, global state,
DB row/schema, config, cache, integration contract.
1. Enumerate consumers, don't guess: for each symbol/state the plan modifies, list its direct
consumers - callers, importers, shared-state readers, contract consumers - via grep/LSP/code
graph, whichever the repo has. Record the consumer list in `QA.md` `## Before`.
2. Cover every enumerated consumer with one of: (a) a characterization baseline saved to
`<vault>/qa/baseline/<neighbor>.txt`, (b) a named existing REAL test the verifier re-runs, or
(c) a named residual-risk line in `QA.md`. A silently uncovered consumer is red.
3. After editing, re-run the same checks and diff against the snapshots.
Unnamed drift is red. Intentional drift must be named in `QA.md`. Characterization is a
regression signal, not a correctness oracle; update snapshots only for intentional bug fixes.
## Scenario stencil (code changes)
Lean default for DEBUG/LEGACY/GREENFIELD code verification:
- Equivalence partitions: normal inputs that should follow the same rule.
- Boundary values: null/undefined/empty/min/max/ordering edges.
- Negative/error paths: rejected inputs, failed dependencies, recovery.
- Regression: previous passing neighbor scenarios the change could break; link to captured baselines.
- Metamorphic relation: when no exact oracle exists, transform equivalent inputs and require equivalent
meaning across outputs. Candidate execution is required; otherwise record named residual risk.
For prod issues that do not reproduce exactly in dev, derive synthetic or similar data from prod evidence
(logs, stack, read-only schema/rows via `reference/db-access.md`) while preserving failure-triggering
properties such as null/boundary/scale/ordering/timing/concurrency. Scrub PII. Do not call one fabricated
green case conclusive; record reproduction fidelity and post-deploy confirmation in the proof.
## Always use the `qa-tester` subagent
Browser dumps/screenshots/logs stay in `qa-tester`. Conductor receives summary + evidence paths only.
## Browser context capture - default and fallback
Use one driver per run. agent-browser is the default browser driver (`reference/agent-browser.md`). Use
`playwright-cli` only when agent-browser cannot complete reliable QA; record why under `Fallback:` and
load `reference/playwright-cli.md`.
1. **Serve.** Start the app from the working tree (or the Verify worktree when one is used), poll
until ready, record URL, tear down at end. Static/single HTML opens via `file://` from that tree.
2. **Get the driver.** `command -v agent-browser`; if absent, `npm install -g agent-browser`, then
`agent-browser install`. If it cannot QA the required flow reliably, switch explicitly per
`reference/playwright-cli.md`; never use an unrecorded substitute.
3. **Drive flows.** `open`, `snapshot` (get `@ref`s), `click`/`type`/`fill`, `screenshot`. Golden
path, edge cases, and a11y must pass. UI/UX jobs also run `reference/ui-ux.md` pre-flight, record a
`UI-tier: Expressive|Functional` line in `## QA`, and enumerate the
text/background pairs to `qa/contrast-pairs.json` — `qa-gate.sh` runs the contrast gate and blocks on FAIL.
4. **Capture the network.** `agent-browser network requests` lists calls; `network request <id>` shows
method + path + status + payload for one. This is the shared evidence for DEBUG `screen -> API` and
LEGACY baseline (below). The Verify step still re-runs the project's REAL tests with no browser.
5. **Capture as-is/to-be.** Same route and viewport:
`qa/as-is-<view>.png` before, `qa/to-be-<view>.png` after. For DEBUG, as-is is the failure and to-be
is fixed behavior.
## Navigation map (load first; build on first entry; self-heal on drift)
Use `.domain-agent/qa/nav-map.md` to avoid rediscovering auth gates, popups, new tabs, and deep routes.
It also gives DEBUG `screen -> API` routing and LEGACY the exact screen/API to baseline. Repo-local and
gitignored; no app-specific selector, route, or credential lives in this skill.
1. **Load first.** Before driving, read `.domain-agent/qa/nav-map.md` if present and navigate by its
entry/auth flow, route list, popup/new-tab triggers, tab-switch notes, and stable selectors.
2. **Build on first entry (when absent).** Within the action budget, do one light mapping pass and save
it: the entry/auth flow; the `screen -> URL` route list; every click that opens a **new tab or
popup** and the resulting target; how to switch the driver to that target; stable selectors for key
controls; and each screen's real API calls from `agent-browser network requests` (method + path).
Write `.domain-agent/qa/nav-map.md` and index it in `index.md`.
3. **Self-heal on drift.** When a saved entry no longer matches the live site - a selector ref is gone,
a route 404s/redirects, a popup opens a different target, or an API path/method changed - re-map only
that slice, correct that row, and bump `config.json.lastUpdated`. Never re-crawl the whole app.
**New tab / popup handling.** Run `agent-browser tab`, switch with `agent-browser tab <tN|label>`, then
re-`snapshot`; record `trigger -> target` in nav-map (`reference/agent-browser.md`).
## API behavior baseline (LEGACY preserve)
Before refactoring or integrating against an existing API, capture its exact behavior so the refactor
preserves it. DEBUG's `screen -> endpoint` only localizes. Save to the run vault
`<vault>/qa/api-baseline-<endpoint>.md`: method + path + status + a representative request and the
response shape (the contract, not every value).
- **UI-reachable** - reach the screen via `qa/nav-map.md` and capture real calls with `agent-browser
network requests` (`network request <id>` for one call's full contract), through `qa-tester`;
promote a confirmed `screen -> API` row back into nav-map.
- **Backend-only (no UI)** - capture at the HTTP level: a recorded curl/HAR or an HTTP probe (e.g. the
`verify` skill) against the running endpoint.
After refactor, re-capture the same call and diff; unintended drift is red (role-loop Verify). Baselines
are per-run vault evidence, never domain pack; strip secrets, tokens, PII.
## Authenticated sessions
Use an agent-browser named session, `state save`/`state load`, or CDP `connect` for real login state
(`reference/agent-browser.md`). The same options exist in the Playwright fallback reference.
## CLI / library
Run an integration smoke: real invocation against a fixture, stdout/stderr/exit-code compared to
known-good output.
## Vault record
Put evidence under `<vault>/qa/` and summarize in `QA.md` `## QA`:
- `Tool: agent-browser` by default; `Tool: playwright-cli` plus `Fallback: agent-browser <reason>` only
when the default cannot complete reliable QA.
- Commands run and pass/fail per check.
- Exact `qa/as-is-<view>.png` and `qa/to-be-<view>.png` paths.
- Served URL and teardown note.
## Exit gate
QA passes only when `bash templates/qa-gate.sh <vault> <browser|cli>` exits 0. Browser runs require
as-is/to-be evidence and the driver record above. Never edit the gate to pass.
## Repeatable script
First QA may be hand-driven. On re-check, save a repeatable agent-browser batch/script; when fallback is
required, save a Playwright spec. Record the path in `## QA`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |