qa-project-context

Files (2)

• SKILL.md
• examples.md · references/

SKILL.md (first lines)

<objective>
This skill writes the single file every other QA skill reads. Without it, each skill
re-asks "what framework? what CI? where do tests live?" from scratch and gives generic
advice. It produces `.agents/qa-project-context.md` in the project root, capturing product,
tech stack, test stack, CI/CD, environments, quality goals, risk areas, team, and
conventions — with no `[bracketed placeholders]` left behind.
</objective>

Downstream skills consume specific sections: Risk Areas feeds `risk-based-testing` and
`test-strategy`; Conventions → Selectors feeds `playwright-automation` and `test-reliability`;
Quality Goals feeds `qa-metrics`; Tech Stack feeds every automation skill. Fill those sections
well and the rest of the library gets sharper for free.

## Discovery Questions

First, check whether `.agents/qa-project-context.md` already exists — if it does, read it and
skip every section already filled (no `[brackets]`). Then scan the repo for config files (see
Codebase Detection) and present detected values for confirmation rather than asking blind.
Walk the remaining questions **section by section**, never all at once.

### Product
- What is the product called, and what does it do in one sentence?
- What type is it? (SaaS, e-commerce, media, mobile app, API service, internal tool) — changes which flows matter.
- What are the production, staging, and development URLs?
- What are the 5–10 most critical user journeys? ("If this breaks, we get paged at 2am.") This list drives every other skill's coverage priorities.

### Tech Stack
- Frontend framework and language? Backend framework, language, and API style (REST, GraphQL, tRPC, gRPC)?
- Database, cache layer, ORM? Hosting, CDN, monitoring?
- Monorepo? If yes, list each app separately (see Monorepo note) — sharding and detection differ.

### Test Stack
- E2E tests today? Framework, config location, test directory. Same for unit, API, visual, performance.
- If a framework is detected from config files, populate Test Stack with its name + version + path — don't re-ask.
- Zero test infrastructure? That's a valid answer; record "None selected yet" and note a default (see Core Principle 3).

### CI/CD
- Platform? When do tests run (every push, PR only, nightly, manual)? Sharding/parallelism?
- What blocks a deploy, and what artifacts are saved (screenshots, reports, coverage)?

### Environments
- How many environments, with URLs? How close is staging to production (infra, data shape, third-party integrations)?
- Mock services or real APIs in development? — environment parity drives test reliability.

### Quality Goals
- Coverage targets today? Flake tolerance? Suite-duration budgets? Metrics tracked or wanted?
- No targets yet? Suggest realistic ones by maturity (see Quality Goals section).

### Risk Areas
- Which parts cause the most production incidents? Which integrations are flakiest (payment, email, third-party APIs)?
- Where is churn high and coverage low? Score everything with Impact × Likelihood (see Risk Areas section).

### Team
- How many QA engineers, and their specializations? Developer-to-QA ratio? Methodology (Scrum, Kanban, Shape Up)?
- When does QA engage (shift-left during spec, or after dev)? — sets the automation ownership model.

### Conventions
- Test file naming pattern? Co-located or separate? Branching strategy and PR requirements?
- Selector strategy for E2E? Test-data strategy (factories, fixtures, seeded DB, API-per-test)?

## Core Principles

1. **One file is the source of truth for the whole library.** Every skill reads
   `.agents/qa-project-context.md` first. Duplicating its facts into other docs guarantees
   drift — keep stack, goals, and risks here and let other skills reference them.

2. **Capture the real state, not the aspiration.** If there are no E2E tests, write "None
   selected yet," not a wish. Downstream skills route on what's true: a missing framework
   triggers a setup suggestion; a fake one sends them building on sand.

3. **Detect before you ask; recommend a default only when there's nothing to detect.**
   Read `package.json` and config files first and confirm what you find. Tool *recommendations*
   belong to the specialized skills — the one exception is a project with zero test
   infrastructure, where you note **Playwright** (E2E) and **Vitest** (unit) as defaults in the
   Test Stack and hand off to `playwright-automation` / `unit-testing`. This is the single
   carve-out to the "no recommendations" rule; everywhere else, just record.

4. **Risk Areas is the highest-leverage section — never skip it.** It is the direct input to
   `risk-based-testing` and `test-strategy`. Push for at least 3–4 entries scored by impact and
   likelihood even when the user says "everything's fine."

## Codebase Detection

Scan for these before asking about the stack. Present detected values for confirmation; when a
test config is found, write the framework name into Test Stack rather than re-asking.

| File | Indicates |
|------|-----------|
| `package.json` | Node.js project — check `dependencies` for the framework |
| `next.config.*` | Next.js |
| `nuxt.config.*` | Nuxt/Vue |
| `angular.json` | Angular |
| `astro.config.*` | Astro |
| `react-router.config.ts` | React Router 7 / Remix |
| `requirements.txt` / `pyproject.toml` | Python project |
| `go.mod` | Go project |
| `playwright.config.*` | Playwright is set up → populate Test Stack E2E |
| `cypress.config.*` | Cypress is set up → populate Test Stack E2E |
| `vitest.config.*` / `jest.config.*` | Unit test framework → populate Test Stack Unit |
| `.github/workflows/` | GitHub Actions CI |
| `.gitlab-ci.yml` | GitLab CI |
| `Jenkinsfile` | Jenkins |
| `docker-compose.*` | Docker-based environments |
| `wrangler.*` | Cloudflare Workers |
| `vercel.json` | Vercel hosting |
| `bun.lock` / `bun.lockb` | Bun runtime |
| `pnpm-workspace.yaml` / `turbo.json` / `nx.json` | Monorepo — handle per the Monorepo note |
| `src-tauri/tauri.conf.json` | Tauri desktop app |
| `.claude/` | Project uses Claude Code skills/agents |
| `.claude-plugin/plugin.json` | Project ships a Claude Code plugin |
| `AGENTS.md` | Codex / multi-agent workflow conventions |

## Workflow: Creating the Context File

1. **Check for existing context.** Look for `.agents/qa-project-context.md` in the project root.
2. **If absent:** create `.agents/` if needed, scaffold the section structure, run the Discovery
   Questions starting with Product, and write the file once filled.
3. **If present with placeholders:** read it, list which sections are complete vs. unfilled, ask
   only about the unfilled sections, then update — preserve completed sections untouched.

From ExelAlfanso/puppets, MIT.

More from ExelAlfanso/puppets