small-qa

Lightweight QA skill pack for Claude Code. Five skills that take a TypeScript project from spec to tested, with structured QA plans, automated test generation, and browser-based QA with health scores.

How It Works

You have two phases: planning what to test, then executing those tests. The plan lives in a single file (specs/QA.md) that gets richer over time — scenarios get results, bugs get tagged, and eventually the plan becomes a runnable test suite.

Phase 1: Plan what to test

Run /write-qa.

This skill reads your project's specs (specs/prd.md, specs/technical-spec.md) and produces specs/QA.md — a structured test plan with every user-facing action mapped to scenarios in tables:

Scenario	Path	Expected	Actual	Status
Valid USDC swap	Happy	Quote with output amount
Unknown token DOGE	Unhappy	Error listing valid tokens
Missing auth token	Unhappy	401, "Authentication required"

Every feature gets both happy and unhappy paths. The Expected column has specific outputs, not vague descriptions. If your project has frontend code, scenarios get tagged backend or frontend so the right tool runs them later.

The plan also includes a Triage Tags reference — this becomes important on repeat runs.

Phase 2: Execute the plan

Run /backend-qa.

This skill reads specs/QA.md and works through every scenario:

1. Calls the API, invokes the MCP tool, or runs the command
2. Records what actually happened in the Actual column
3. Marks Pass or Fail in the Status column

When something fails, it fixes the bug inline — diagnose, fix, verify, commit. If multiple scenarios fail from the same root cause (e.g., wrong endpoint path breaks 3 tools at once), it groups them and fixes once instead of diagnosing the same problem three times.

At the end you get a verdict: SHIP, SHIP WITH CAVEATS, or DO NOT SHIP.

If your project has frontend scenarios, /qa handles those separately — clicking through the browser with Playwright, testing forms, checking page renders, and producing a health score.

Phase 3: Triage and repeat

After the first run, your specs/QA.md has results everywhere. Now you tag scenarios:

• [known] — "yes this is a bug, we're tracking it, skip it next time"
• [wontfix: reason] — "this is intentional behavior, not a bug"
• [retest: fixed in commit abc] — "we fixed this, please re-verify"

On the next /backend-qa run, the skill is smart about what to re-execute:

• Skips [known] and [wontfix] rows
• Skips rows that already Pass
• Re-executes [retest] rows and clears the tag
• Only runs new or previously-failed scenarios

This means repeat runs get faster — you're not re-testing 46 scenarios when only 3 changed.

Phase 4: Turn the plan into automated tests

Run /generate-tests.

This reads specs/QA.md and generates actual runnable test files — one test per scenario row:

// QA: specs/QA.md > Section 4 > "Unknown token DOGE"
it("returns error listing valid tokens for unknown token", async () => {
  // ...calls the real API, asserts the real response
});

These live as *.qa.integration.test.ts files, gated behind INTEGRATION=1 so they don't slow down your normal npm test. They run against the real API, not mocks — so if the API changes its response shape, the test catches it.

The .qa. infix keeps them separate from hand-written tests. Each test has a traceability comment pointing back to the exact QA scenario it came from.

Skills

Skill	What it does
/write-qa	Generate QA test plan from specs — maps features to scenario tables
/backend-qa	Execute backend QA scenarios against live APIs, CLIs, MCP servers
/qa	Browser-based QA with Playwright — health scores, fix loop, regression
/generate-tests	Convert QA plan scenarios into *.qa.integration.test.ts files
/qa-review	Orchestrate the full QA pipeline end-to-end

Setup

Step 1: Install the skills

git clone https://github.com/jimmchang/small-qa.git ~/.claude/skills/small-qa

# Symlink each skill to the top level so Claude Code discovers them
for skill in write-qa backend-qa qa generate-tests qa-review; do
  ln -sf ~/.claude/skills/small-qa/$skill ~/.claude/skills/$skill
done

Step 2: Create a spec for your project

/write-qa needs something to read. You don't need a formal PRD — any of these work, in order of quality:

Option A: Write a specs/prd.md (best results)

mkdir -p specs

Then create specs/prd.md:

# PRD: [Project Name]

## What this is
[One paragraph: what the app does, who it's for]

## User Stories

### US-1: [Action name]
**As a** [user type], **I want to** [action], **so that** [outcome].
**Acceptance criteria:**
- Given [context], when [action], then [expected result]
- Given [error case], when [action], then [expected error]

### US-2: [Next action]
(repeat for each feature)

## Out of scope
- [What this does NOT do]

You don't need perfect prose. The skill needs: what the features are, what inputs they take, and what should happen on success and failure.

Option B: Write a specs/technical-spec.md (good for API projects)

# Technical Spec: [Project Name]

## Endpoints / Tools / Commands

### POST /api/thing
- **Input:** `{ name: string, email: string }`
- **Success:** `200 { id: "abc", created: true }`
- **Errors:**
  - Missing name → `400 { error: "name required" }`
  - Invalid email → `400 { error: "invalid email format" }`
  - Duplicate → `409 { error: "already exists" }`

### GET /api/thing/:id
(repeat for each endpoint/tool/command)

Option C: Just have a README.md (minimum viable)

If your project has a decent README with usage examples, /write-qa will work with that. Results won't be as thorough.

Step 3: Run the flow

/write-qa           → generates specs/QA.md from your spec
/backend-qa         → executes the plan, fills in results, fixes bugs
/generate-tests     → turns passing scenarios into integration tests

Step 4: On repeat runs

Edit specs/QA.md to tag triaged scenarios:

• [known] — skip this bug next time
• [wontfix: reason] — intentional, skip permanently
• [retest: reason] — re-verify after a fix

Then run /backend-qa again — it only re-tests what matters.

References

• references/issue-taxonomy.md — Severity levels, issue categories, per-page exploration checklist
• references/qa-report-template.md — Structured report format for browser QA

Prerequisites

• Claude Code
• For /qa (browser QA): Playwright — npx playwright install
• For /generate-tests: vitest or jest in the target project