qa-only skill (gstack) (part 2)

Part 2 of 2 of qa-only skill (gstack) (qa-only/SKILL.md in garrytan/gstack); the SKILL.md text continues verbatim from the previous part.

SKILL.md (verbatim, continued)

console.log("GSTACK_STEP_OK");
'

Copy both screenshots out of the printed ASIDE_DIR into $REPORT_DIR/screenshots/ and Read them.

Static bugs (typos, layout issues, missing images):

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

aside repl '
const pg = await openTab("<page-url>");
const a = await annotatedScreenshot(pg);
await fs.writeFile(path.join(pwd, "issue-002.png"), Buffer.from(a.base64Image, "base64"));
console.log("ASIDE_DIR=" + pwd); await closeTab(pg); console.log("GSTACK_STEP_OK");
'

Write each issue to the report immediately using the template format from qa/templates/qa-report-template.md.

Phase 6: Wrap Up

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:

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

Regression mode: After writing the report, load the baseline file. Compare:

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

Health Score Rubric

Compute each category score (0-100), then take the weighted average.

Counting

• Deduplicate the same root cause across pages. Use one primary category, first applicable: Links (navigation), Accessibility (access barriers), Functional (behavior), Performance (speed), Visual (layout), Content (copy), UX (friction), Console (remaining errors). No double deductions.
• Exclude untested categories; label partial scores provisional with coverage. None tested: "not scored". Compare only identical coverage.

Console (weight: 15%)

Deduplicate reproducible errors/exceptions by message+source across pages. Exclude warnings, info, and defects scored elsewhere.

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

Links (weight: 10%)

Count unique broken destinations, including client-side routes: repeatable 4xx/5xx, missing routes/anchors, or timeouts. Exclude expected auth redirects and resource/API requests.

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

Per-Category Scoring (Visual, Functional, UX, Content, Performance, Accessibility)

Start at 100; deduct per finding:

• Critical issue → -25
• High issue → -15
• Medium issue → -8
• Low issue → -3 Floor: 0.

Use the highest applicable severity; record impact/workaround:

• Critical: data loss, security/privacy exposure, or core app unusable for all users.
• High: core/major task blocked without a workaround.
• Medium: task impaired but a workaround exists.
• Low: cosmetic/copy/friction issue without lost task completion. Console/Links use counts instead.

Weights

Final Score

Use decimal weights (15% = 0.15): score = Σ (category_score × weight) / Σ tested weights. Round only the final score to the nearest integer (0.5 rounds up).

Framework-Specific Guidance

Next.js

• 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

Rails

• 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

WordPress

• 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)

General SPA (React, Vue, Angular)

• Use snapshot(pg, { interactive: true }) for navigation — the links script 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)

Important Rules

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. You never type them — the user signs in inside Aside. Write [REDACTED] if a repro step has to mention one.
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 annotatedScreenshot(pg) when the tree misses a clickable element. Ref labels drawn on the page find clickable divs the accessibility tree skips; then click by ref or CSS selector.
11. Show screenshots to the user. After every script that saves a screenshot, cp it out of the printed ASIDE_DIR into $REPORT_DIR/screenshots/ and use the Read tool on the copied file so the user can see it inline. This is critical — without it, screenshots are invisible to the user.
12. Never refuse to use the browser. When the user invokes /qa or /qa-only, they are requesting browser-based testing in Aside. Never suggest evals, unit tests, curl, or other alternatives as a substitute. Even if the diff appears to have no UI changes, backend changes affect app behavior — always open the app in the browser and test.
13. Mutating actions on a non-local target need consent. Submitting, creating, deleting, purchasing, or changing settings on anything that is not LOCAL follows the "Invocation is consent to LOOK, not to ACT" rule in BROWSER SETUP — one AskUserQuestion per run, before the first such action.

Output

Write the report to both local and project-scoped locations:

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

Project-scoped: Write test outcome artifact for cross-session context:

eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" && mkdir -p ~/.gstack/projects/$SLUG

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

Output Structure

.gstack/qa-reports/
├── qa-report-{domain}-{YYYY-MM-DD}.md    # Structured report
├── screenshots/
│   ├── initial.jpg                        # Landing page screenshot
│   ├── issue-001-step-1.jpg               # Per-issue evidence
│   ├── issue-001-result.jpg
│   ├── issue-002.png                      # Annotated screenshot (static bugs)
│   └── ...
└── baseline.json                          # For regression mode

Report filenames use the domain and date: qa-report-myapp-com-2026-03-12.md

Capture Learnings

If you discovered a non-obvious pattern, pitfall, or architectural insight during this session, log it for future sessions:

~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"qa-only","type":"TYPE","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"SOURCE","files":["path/to/relevant/file"]}'

Types: pattern (reusable approach), pitfall (what NOT to do), preference (user stated), architecture (structural decision), tool (library/framework insight), operational (project environment/CLI/workflow knowledge).

Sources: observed (you found this in the code), user-stated (user told you), inferred (AI deduction), cross-model (both Claude and Codex agree).

Confidence: 1-10. Be honest. An observed pattern you verified in the code is 8-9. An inference you're not sure about is 4-5. A user preference they explicitly stated is 10.

files: Include the specific file paths this learning references. This enables staleness detection: if those files are later deleted, the learning can be flagged.

Only log genuine discoveries. Don't log obvious things. Don't log things the user already knows. A good test: would this insight save time in a future session? If yes, log it.

Additional Rules (qa-only specific)

11. Never fix bugs. Find and document only. Do not read source code, edit files, or suggest fixes in the report. Your job is to report what's broken, not to fix it. Use /qa for the test-fix-verify loop.
12. No test framework detected? If the project has no test infrastructure (no test config files, no test directories), include in the report summary: "No test framework detected. Run /qa to bootstrap one and enable regression test generation."

Other files in this skill

• SKILL.md.tmpl

Back to garrytan/gstack (Garry Tan's Claude Code skill suite) or Agent skills.