Onboard a new QA engineer to an existing codebase, or audit an existing test architecture. Produces a 30-day ramp plan: codebase orientation, framework walkthrough, test architecture audit, mentorship pairing, and first-test guidance. Use when: "QA onboarding," "new tester," "ramp up," "test archite

<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. Situation Jump to Output Onboarding a new person to an existing team First 30 Days Checklist → Mentorship Patterns A 30 day ramp plan with owners and dates Inherited an existing suite with no onboarding/docs Test Architecture Audit (scope by team maturity ) A 1 2 page findings doc, five dimensions Need the reference doc for anyone writing tests Framework Walkthrough Template A project specific walkthrough.md 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. 2. 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. 3. 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 4. Is there an existing test framework? If yes: how healthy is it? If no: framework selection is step one (see test strategy skill). 5. 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. 6. 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 7. 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 [ ] Participate actively in Three Amigos or story refinement (ask questions) [ ] Review one existing PR for test quality (using the PR review checklist from shift left testing ) Week 4: Independence Milestones [ ] Write and merge a multi step E2E test without pairing [ ] Participate in bug triage and articulate testing gaps [ ] Contribute to .agents/qa project context.md with new learnings [ ] Present test results/findings at sprint review or team standup [ ] Self assess: which test patterns feel comfortable? Which need more practice? Test Architecture Audit When joining an existing project, assess the health of the test suite before writing new tests. This audit takes 2 4 hours and produces a clear picture of the current state. Scope the audit by team maturity (from .agents/qa project context.md ) — a one size fits all audit wastes a startup's time and underserves an established team: startup — Skip the full audit. Confirm one path is covered and one framework runs; spend the saved hours getting a first test merged. growing — Run all five dimensions once to establish a baseline; defer recurring reviews. established — Full five dimension audit plus recurring quality reviews on a schedule (e.g. monthly), with the findings doc tracked over time. What to Assess Assess five dimensions, each with a fill in worksheet: Coverage and Distribution — test counts by layer, pyramid shape, code coverage and trend. Reliability — flaky test rate, top flakiest tests, quarantine count and age. CI Health — full suite and per stage duration, parallelism, pass rate, retry rate. Technical Debt — skipped tests, waitForTimeout / force: true usage, hardcoded data, assertionless tests, deprecated APIs, stale AI generated tests, stale feature flags. Conventions — page objects, fixtures, factories, naming, shared utilities, tagging. See references/audit worksheets.md for the copy and fill worksheets covering all five dimensions. Audit Output Produce a short document (1 2 pages) summarizing findings, categorized as: Strengths: What the existing suite does well (preserve and learn from these) Gaps: Missing coverage areas, undertested critical paths Risks: Flaky tests, stale quarantines, declining coverage Quick Wins: Improvements achievable in 1 2 sprints (fix flaky tests, add missing happy path coverage) Strategic Work: Improvements requiring sustained investment (refactor test architecture, add integration layer) Framework Walkthrough Template Create this document for your project. It is the primary reference for anyone writing tests. It has six sections: 1. Architecture Overview — framework, language, config location, and the annotated directory tree. 2. How to Run Tests — the full set of run commands (all tests, single file, grep, headed, debug, UI mode, per browser, report). 3. How to Write a New Test (Step by Step) — the six step location/reuse/write/run/PR flow plus the Arrange Act Assert test template. 4. How to Debug Failures — local vs CI failure playbooks and common failure pattern decoder. 5. Common Patterns and Conventions — project specific examples for auth fixtures, data factories, assertion specificity, and selector priority. 6. Where to Find Help — the routing table for questions about patterns, failures, product behavior, and docs. See references/framework walkthrough.md for the full template with all code blocks, directory trees, and command lists to copy and adapt. Codebase Orientation Guide Walk through these areas with the new person in a 60 90 minute session. Test Directory Structure Tour Walk through the actual directory tree, explaining: Why tests are organized this way (by feature, not by type) Where to find page objects for each product area Where shared utilities live and what they do Where test data and fixtures are defined Where CI configuration lives Shared Utilities Inventory Utility Location Purpose Example Auth fixture fixtures/auth.fixture.ts Provides authenticated sessions { ad

qa-project-bootstrap