1. Re-ground: State the project, the current branch (use the

   _BRANCH

   value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
2. Simplify: Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called.
3. Recommend:

   RECOMMENDATION: Choose [X] because [one-line reason]

4. Options: Lettered options:

   A) ... B) ... C) ...

1. {step}

1. Check if a PR already exists for this branch:

   gh pr view --json baseRefName -q .baseRefName

   If this succeeds, use the printed branch name as the base branch.
2. If no PR exists (command fails), detect the repo's default branch:

   gh repo view --json defaultBranchRef -q .defaultBranchRef.name

3. If both commands fail, fall back to

   main

   .

git diff

git log

git fetch

git merge

gh pr create

https://myapp.com

http://localhost:3000

--quick

--exhaustive

--regression .gstack/qa-reports/baseline.json

.gstack/qa-reports/

Output to /tmp/qa

Focus on the billing page

Sign in to user@example.com

Import cookies from cookies.json

• Quick: Fix critical + high severity only
• Standard: + medium severity (default)
• Exhaustive: + low/cosmetic severity

if [ -n "$(git status --porcelain)" ]; then
  echo "ERROR: Working tree is dirty. Commit or stash changes before running /qa."
  exit 1
fi

_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
B=""
[ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/gstack/browse/dist/browse" ] && B="$_ROOT/.claude/skills/gstack/browse/dist/browse"
[ -z "$B" ] && B=~/.claude/skills/gstack/browse/dist/browse
if [ -x "$B" ]; then
  echo "READY: $B"
else
  echo "NEEDS_SETUP"
fi

NEEDS_SETUP

1. Tell the user: "gstack browse needs a one-time build (~10 seconds). OK to proceed?" Then STOP and wait.
2. Run:

   cd <SKILL_DIR> && ./setup

3. If

   bun

   is not installed:

   curl -fsSL https://bun.sh/install | bash

mkdir -p .gstack/qa-reports/screenshots

1. Project-scoped test plans: Check

   ~/.gstack/projects/

   for recent

   *-test-plan-*.md

   files for this repo
   bash

   SLUG=$(git remote get-url origin 2>/dev/null | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-')
   ls -t ~/.gstack/projects/$SLUG/*-test-plan-*.md 2>/dev/null | head -1

2. Conversation context: Check if a prior

   /plan-eng-review

   or

   /plan-ceo-review

   produced test plan output in this conversation
3. Use whichever source is richer. Fall back to git diff analysis only if neither is available.

/qa

1. Analyze the branch diff to understand what changed:
   bash

   git diff main...HEAD --name-only
   git log main..HEAD --oneline

2. Identify affected pages/routes from the changed files:
   • Controller/route files → which URL paths they serve
   • View/template/component files → which pages render them
   • Model/service files → which pages use those models (check controllers that reference them)
   • CSS/style files → which pages include those stylesheets
   • API endpoints → test them directly with

     $B js "await fetch('/api/...')"

   • Static pages (markdown, HTML) → navigate to them directly
3. Detect the running app — check common local dev ports:
   bash

   $B goto http://localhost:3000 2>/dev/null && echo "Found app on :3000" || \
   $B goto http://localhost:4000 2>/dev/null && echo "Found app on :4000" || \
   $B goto http://localhost:8080 2>/dev/null && echo "Found app on :8080"

   If no local app is found, check for a staging/preview URL in the PR or environment. If nothing works, ask the user for the URL.
4. Test each affected page/route:
   • Navigate to the page
   • Take a screenshot
   • Check console for errors
   • If the change was interactive (forms, buttons, flows), test the interaction end-to-end
   • Use

     snapshot -D

     before and after actions to verify the change had the expected effect
5. Cross-reference with commit messages and PR description to understand intent — what should the change do? Verify it actually does that.
6. Check TODOS.md (if it exists) for known bugs or issues related to the changed files. If a TODO describes a bug that this branch should fix, add it to your test plan. If you find a new bug during QA that isn't in TODOS.md, note it in the report.
7. Report findings scoped to the branch changes:
   • "Changes tested: N pages/routes affected by this branch"
   • For each: does it work? Screenshot evidence.
   • Any regressions on adjacent pages?

1. Find browse binary (see Setup above)
2. Create output directories
3. Copy report template from

   qa/templates/qa-report-template.md

   to output dir
4. Start timer for duration tracking

$B goto <target-url>
$B snapshot -i -a -o "$REPORT_DIR/screenshots/initial.png"
$B links                          # map navigation structure
$B console --errors               # any errors on landing?

• __next

  in HTML or

  _next/data

  requests → Next.js

• csrf-token

  meta tag → Rails

• wp-content

  in URLs → WordPress
• Client-side routing with no page reloads → SPA

links

snapshot -i

$B goto <page-url>
$B snapshot -i -a -o "$REPORT_DIR/screenshots/page-name.png"
$B console --errors

qa/references/issue-taxonomy.md

1. Visual scan — Look at the annotated screenshot for layout issues
2. Interactive elements — Click buttons, links, controls. Do they work?
3. Forms — Fill and submit. Test empty, invalid, edge cases
4. Navigation — Check all paths in and out
5. States — Empty state, loading, error, overflow
6. Console — Any new JS errors after interactions?
7. Responsiveness — Check mobile viewport if relevant:
   bash

   $B viewport 375x812
   $B screenshot "$REPORT_DIR/screenshots/page-mobile.png"
   $B viewport 1280x720

1. Take a screenshot before the action
2. Perform the action
3. Take a screenshot showing the result
4. Use

   snapshot -D

   to show what changed
5. Write repro steps referencing screenshots

$B screenshot "$REPORT_DIR/screenshots/issue-001-step-1.png"
$B click @e5
$B screenshot "$REPORT_DIR/screenshots/issue-001-result.png"
$B snapshot -D

1. Take a single annotated screenshot showing the problem
2. Describe what's wrong

$B snapshot -i -a -o "$REPORT_DIR/screenshots/issue-002.png"

qa/templates/qa-report-template.md

1. Compute health score using the rubric below
2. Write "Top 3 Things to Fix" — the 3 highest-severity issues
3. Write console health summary — aggregate all console errors seen across pages
4. Update severity counts in the summary table
5. Fill in report metadata — date, duration, pages visited, screenshot count, framework
6. Save baseline — write

   baseline.json

   with:
   json

   {
     "date": "YYYY-MM-DD",
     "url": "<target>",
     "healthScore": N,
     "issues": [{ "id": "ISSUE-001", "title": "...", "severity": "...", "category": "..." }],
     "categoryScores": { "console": N, "links": N, ... }
   }

• Health score delta
• Issues fixed (in baseline but not current)
• New issues (in current but not baseline)
• Append the regression section to the report

• 0 errors → 100
• 1-3 errors → 70
• 4-10 errors → 40
• 10+ errors → 10

• 0 broken → 100
• Each broken link → -15 (minimum 0)

• Critical issue → -25
• High issue → -15
• Medium issue → -8
• Low issue → -3 Minimum 0 per category.

• Check console for hydration errors (

  Hydration failed

  ,

  Text content did not match

  )
• Monitor

  _next/data

  requests in network — 404s indicate broken data fetching
• Test client-side navigation (click links, don't just

  goto

  ) — catches routing issues
• Check for CLS (Cumulative Layout Shift) on pages with dynamic content

• Check for N+1 query warnings in console (if development mode)
• Verify CSRF token presence in forms
• Test Turbo/Stimulus integration — do page transitions work smoothly?
• Check for flash messages appearing and dismissing correctly

• Check for plugin conflicts (JS errors from different plugins)
• Verify admin bar visibility for logged-in users
• Test REST API endpoints (

  /wp-json/

  )
• Check for mixed content warnings (common with WP)

• Use

  snapshot -i

  for navigation —

  links

  command misses client-side routes
• Check for stale state (navigate away and back — does data refresh?)
• Test browser back/forward — does the app handle history correctly?
• Check for memory leaks (monitor console after extended use)

1. Repro is everything. Every issue needs at least one screenshot. No exceptions.
2. Verify before documenting. Retry the issue once to confirm it's reproducible, not a fluke.
3. Never include credentials. Write

   [REDACTED]

   for passwords in repro steps.
4. Write incrementally. Append each issue to the report as you find it. Don't batch.
5. Never read source code. Test as a user, not a developer.
6. Check console after every interaction. JS errors that don't surface visually are still bugs.
7. Test like a user. Use realistic data. Walk through complete workflows end-to-end.
8. Depth over breadth. 5-10 well-documented issues with evidence > 20 vague descriptions.
9. Never delete output files. Screenshots and reports accumulate — that's intentional.
10. Use

    snapshot -C

    for tricky UIs. Finds clickable divs that the accessibility tree misses.

• Quick: Fix critical + high only. Mark medium/low as "deferred."
• Standard: Fix critical + high + medium. Mark low as "deferred."
• Exhaustive: Fix all, including cosmetic/low severity.

• Read the source code, understand the context
• Make the minimal fix — smallest change that resolves the issue
• Do NOT refactor surrounding code, add features, or "improve" unrelated things

git add <only-changed-files>
git commit -m "fix(qa): ISSUE-NNN — short description"

• One commit per fix. Never bundle multiple fixes.
• Message format:

  fix(qa): ISSUE-NNN — short description

• Navigate back to the affected page
• Take before/after screenshot pair
• Check console for errors
• Use

  snapshot -D

  to verify the change had the expected effect

$B goto <affected-url>
$B screenshot "$REPORT_DIR/screenshots/issue-NNN-after.png"
$B console --errors
$B snapshot -D

• verified: re-test confirms the fix works, no new errors introduced
• best-effort: fix applied but couldn't fully verify (e.g., needs auth state, external service)
• reverted: regression detected →

  git revert HEAD

  → mark issue as "deferred"

1. Re-run QA on all affected pages
2. Compute final health score
3. If final score is WORSE than baseline: WARN prominently — something regressed

.gstack/qa-reports/qa-report-{domain}-{YYYY-MM-DD}.md

SLUG=$(git remote get-url origin 2>/dev/null | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-')
mkdir -p ~/.gstack/projects/$SLUG

~/.gstack/projects/{slug}/{user}-{branch}-test-outcome-{datetime}.md

• Fix Status: verified / best-effort / reverted / deferred
• Commit SHA (if fixed)
• Files Changed (if fixed)
• Before/After screenshots (if fixed)

• Total issues found
• Fixes applied (verified: X, best-effort: Y, reverted: Z)
• Deferred issues
• Health score delta: baseline → final

"QA found N issues, fixed M, health score X → Y."

TODOS.md

1. New deferred bugs → add as TODOs with severity, category, and repro steps
2. Fixed bugs that were in TODOS.md → annotate with "Fixed by /qa on {branch}, {date}"

1. Clean working tree required. Refuse to start if

   git status --porcelain

   is non-empty.
2. One commit per fix. Never bundle multiple fixes into one commit.
3. Never modify tests or CI configuration. Only fix application source code.
4. Revert on regression. If a fix makes things worse,

   git revert HEAD

   immediately.
5. Self-regulate. Follow the WTF-likelihood heuristic. When in doubt, stop and ask.