QA Project Context

Section Guidance

What makes a good entry in each section. The blank template ships at .agents/qa-project-context.md in the qaskills repo.

Product. Key user flows must be specific and testable: "Buyer searches products, adds to cart, checks out with Stripe, receives confirmation email" — not "user uses the app." This list is what every test skill uses to prioritize. Aim for 5–10.

Tech Stack. Record frontend, backend, database, hosting separately. Pin versions only when they change the testing approach (App Router vs. Pages Router differ materially). Don't copy a version just because an example shows one — read it from package.json.

Test Stack. For each tool: framework name + version, config location, test directory. No infrastructure yet is valid — write "None selected yet" and the recommended default (Principle 3).

Monorepo. List each frontend app as its own Tech Stack and Test Stack entry; keep the shared API/backend as one entry. Shard E2E per app (a change in apps/admin shouldn't run apps/storefront E2E), and note in CI/CD which path filters gate which app's suite. Detection hint: turbo.json / pnpm-workspace.yaml / nx.json. See references/examples.md.

CI/CD. Answer what other skills need: what blocks a deploy, how fast feedback is, what evidence is preserved.

Environments. Note how staging diverges from production — a different DB engine in staging means staging-green tests can still fail in prod.

Quality Goals. Concrete and measurable only. Pick starting targets by maturity:

Write them as numbers: "80% line coverage measured by Istanbul," "flake rate <2% over a rolling 30-day window," "full E2E under 15 min with 4 shards." Never "we want great quality."

Risk Areas. Use the table — columns Area, Risk Level, Business Impact, Notes — and score with Impact × Likelihood:

• Critical (test first): high impact + high likelihood (payment flow with known edge cases).
• Important: high impact + low likelihood (auth — catastrophic if broken, rarely changes).
• Monitor: low impact + high likelihood (notification formatting — breaks often, low severity).
• Backlog: low impact + low likelihood (admin settings — stable, rarely used).

At least 3 entries, never vague ("everything breaks").

Team. Record actual headcount and the dev:QA ratio — it sets the automation ownership model:

Conventions. Selector strategy especially — playwright-automation and test-reliability read it to generate matching selectors. Default to data-testid for stability (data-testid="invoice-create-button", kebab-case). If the team prefers semantic/ARIA selectors for accessibility-aware testing, record concrete tokens — role="button", role="heading", getByRole('link', { name: ... }) — and the tradeoff: ARIA roles double as a11y assertions and survive markup churn, but are less stable than data-testid when copy or roles change, so pin a name/level to keep them unambiguous.

Anti-Patterns

1. Asking all questions at once

Dumping 30 questions is overwhelming and gets shallow answers. Walk section by section, Product first.

2. Leaving [brackets] in the final file

If the user has no answer, record the actual state ("None — no E2E framework selected yet"), not a placeholder. Placeholders left in the file silently break every downstream skill that parses it.

3. Inventing information

Detect the stack from package.json, requirements.txt, or config files — then confirm with the user before writing. Don't guess a database or hosting provider.

4. Skipping Risk Areas

The single most valuable section for downstream skills. Push for at least 3–4 scored entries even when the user insists everything is fine.

5. Recommending tools beyond the zero-infra default

This skill records current state; tool selection belongs to playwright-automation, unit-testing, and the other specialized skills. The only recommendation you make here is the Playwright + Vitest default when there is no test infrastructure at all (Principle 3).

Verification

Prove the produced file is complete, smallest check first. From the project root:

test -f .agents/qa-project-context.md \
  && ! grep -q '\[.*\]' .agents/qa-project-context.md \
  && echo "context complete: file exists, no placeholders"

Exit 0 with the message means the file exists and every [bracketed placeholder] is gone. A non-zero exit means either the file is missing or placeholders remain — fix those before handing off to any other skill. Then eyeball that all nine section headers are present:

grep -c '^## ' .agents/qa-project-context.md   # expect >= 9

Done When

• .agents/qa-project-context.md exists in the project root and grep -q '\[.*\]' returns non-zero (no bracketed placeholders remain).
• All nine sections are present: Product, Tech Stack, Test Stack, CI/CD, Environments, Quality Goals, Risk Areas, Team, Conventions.
• Product lists at least 5 specific, testable key user flows (no "user uses the app").
• Test Stack names the actual frameworks + versions + paths in use, or states "None selected yet" with the recommended default noted.
• Risk Areas table has at least 3 entries scored by impact and business impact.
• Quality Goals are concrete numbers (coverage %, flake %, durations) — not aspirational prose.
• Team section shows actual headcount and the dev:QA ratio (or "solo").

Related Skills

• qa-start — bootstraps QA on a brand-new project end-to-end and calls this skill as its first step. Use qa-start when no QA exists yet; use this skill directly to (re)fill context.
• risk-based-testing — turns the Risk Areas section into a prioritized risk matrix. Run it after this skill when the question is "where do we focus testing?"
• test-strategy — consumes Risk Areas, Quality Goals, and Team to set multi-quarter direction.
• qa-metrics — tracks the Quality Goals defined here; both reference the same targets.
• playwright-automation / unit-testing — set up E2E / unit frameworks after the Test Stack section is filled; they read Conventions for selector and naming strategy.
• ci-cd-integration — wires the pipeline described in the CI/CD section.

Reference Files (in references/)

• examples.md — two complete filled-in context files (SaaS and a multi-site publisher) plus the monorepo Tech/Test Stack layout.