QA Project Bootstrap

<objective> A new QA engineer pointed at the README and left to "figure it out" burns two weeks learning bad habits by trial and error, and an unaudited inherited suite hides flaky tests and coverage gaps that only surface in production. This skill reduces time to first merged test and produces three concrete artifacts: a 30-day ramp plan, a five-dimension test architecture audit, and a framework walkthrough doc. Every section serves the same metric — a real test merged to main and green in CI, fast.

Before starting: Check for .agents/qa-project-context.md in the project root. If it exists, it answers most discovery questions and provides the technical context for onboarding. If it does not, creating it is the first action item. </objective>

Quick Route

This skill serves three distinct jobs. Identify yours, jump to the section, skip the rest.

A real onboarding usually needs all three; a quick health check needs only the audit.

Discovery Questions

Who Is Being Onboarded?

1. New QA engineer or developer contributing to tests? QA engineers need test strategy context and codebase orientation. Developers contributing tests need framework patterns and conventions. The ramp-up path differs significantly.

1. Experience level with the test framework? First time with Playwright/Cypress/pytest? Experienced but new to this codebase? Advanced and just needs conventions? This determines how much framework walkthrough to include.

1. Solo QA or joining an existing QA team? Solo QA needs to establish conventions from scratch. Joining a team means learning existing patterns and contributing within established norms.

Project State

1. Is there an existing test framework? If yes: how healthy is it? If no: framework selection is step one (see test-strategy skill).

1. Does the project have a `.agents/qa-project-context.md`? If not, creating one is a high-priority onboarding task -- it forces the new person to document what they learn, which benefits the entire team.

1. Is local environment setup documented? Can a new person run the full stack and execute tests within the first day? If setup takes more than 2 hours, the process needs fixing before onboarding.

Access and Tooling

1. Are all required accounts and permissions set up? Repository access, CI dashboard, staging environment, test data accounts, bug tracker, communication channels. Missing access on day one wastes time and creates frustration.

Core Principles

1. Time to First Merged Test Is the Success Metric

The single most important measure of onboarding success is how quickly the new person gets a real test merged into the main branch. Not a tutorial exercise, not a local-only experiment -- a real test that runs in CI and validates real product behavior. Target: within the first two weeks.

2. Progressive Complexity

Start simple, increase difficulty gradually. First test: a smoke test or page-load verification. Second test: a form interaction. Third test: a multi-step user flow. By week three, the new person is writing tests for sprint stories. Throwing someone into the deep end with a complex multi-service flow on day one creates anxiety and bad habits.

3. Document Tribal Knowledge

Every time a new person asks a question that is not answered in documentation, that is tribal knowledge escaping. The onboarding process should capture these answers in permanent form -- ideally in .agents/qa-project-context.md, the framework walkthrough doc, or code comments. The new person is the best person to write this documentation because they know exactly what was missing.

4. Pair First, Solo Second

The first 3 tests should be written in a pair -- the new person driving, an experienced team member navigating. Pairing transfers tacit knowledge (why we do things this way, not just how) and builds confidence faster than reading documentation alone.

5. Make the Easy Path the Right Path

If the correct way to write a test is harder than the wrong way, people will write tests the wrong way. Ensure that test utilities, fixtures, page objects, and data factories make the recommended patterns the path of least resistance. If a new person has to fight the framework to follow conventions, fix the framework.

Calibrate to your team maturity (set team_maturity in .agents/qa-project-context.md): - startup — Focus on days 1–10: get one test framework running and one critical path covered. Skip process ceremony until you have a working baseline. - growing — Full 30-day plan: framework selection, CI integration, coverage baseline, team conventions documented. - established — 30-day plan plus: audit existing suite for anti-patterns, propose tooling upgrades, establish metrics baseline, schedule recurring quality reviews.

First 30 Days Checklist

Week 1: Environment, Access, and Orientation

Day 1-2: Setup

• [ ] Repository cloned and building locally
• [ ] All environment variables configured (.env.local, test credentials)
• [ ] Application running locally (frontend + backend + database)
• [ ] Test suite runs locally and passes (or known failures are documented)
• [ ] IDE configured with recommended extensions (test runner plugin, linter, formatter)
• [ ] Access granted: CI dashboard, staging environment, bug tracker, team channels

Day 3-4: Orientation

• [ ] Read .agents/qa-project-context.md (or create it if it does not exist)
• [ ] Walk through the test directory structure with a team member
• [ ] Understand the test pyramid: how many unit, integration, and E2E tests exist
• [ ] Review the CI pipeline: what runs on PR, what runs nightly, what blocks merge
• [ ] Identify the top 5 critical user flows (these will be the first testing targets)
• [ ] Attend one Three Amigos or sprint planning session as an observer
• [ ] Working with the team's AI assistants: Identify which coding agents the team uses (Claude Code, Codex, Cursor, Gemini CLI, etc.), where their context lives (.agents/qa-project-context.md, CLAUDE.md, AGENTS.md), which prompts/skills are house style, and which tasks the team explicitly does NOT delegate to AI. Produce a short "AI assistants we use, what they're good at, what to never let them do" doc as a Day 4 deliverable. If the team automates Playwright via an agent, note that agent-driven Playwright now has its own @playwright/cli (daemon architecture, playwright-cli commands, token-efficient) — distinct from the npx playwright test runner the framework walkthrough documents.

Day 5: First Small Win

• [ ] Run a single test in debug/headed mode and understand what it does
• [ ] Modify one assertion in an existing test, verify it fails as expected, revert
• [ ] Read 3 existing tests and annotate what each section does (setup, action, assertion)

Week 2: First Real Test

• [ ] Identify a simple, low-risk test to write (page loads, element visibility, basic navigation)
• [ ] Write the test using existing page objects and fixtures (pair with a team member)
• [ ] Run the test locally, ensure it passes reliably (3 consecutive runs)
• [ ] Open a PR, receive feedback, iterate
• [ ] Test passes in CI
• [ ] First test merged

Week 3: Sprint Contribution

• [ ] Pick up a sprint story's QA work (with mentorship)
• [ ] Write tests covering the story's acceptance criteria
• [ ] Identify at least one edge case not covered by acceptance criteria