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 architecture audit," "first 30 days," "QA mentorship," "joining QA team." Not for: setting up QA on a brand-new project from scratch — use `qa-start`. Related: qa-start, qa-project-context, shift-left-testing, ai-qa-review.
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.
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?
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.
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.
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
Is there an existing test framework? If yes: how healthy is it? If no: framework selection is step one (see test-strategy skill).
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.
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
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)
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.
Create this document for your project. It is the primary reference for anyone writing tests. It has six sections:
Architecture Overview — framework, language, config location, and the annotated directory tree.
How to Run Tests — the full set of run commands (all tests, single file, grep, headed, debug, UI mode, per-browser, report).
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.
How to Debug Failures — local vs CI failure playbooks and common failure-pattern decoder.
Common Patterns and Conventions — project-specific examples for auth fixtures, data factories, assertion specificity, and selector priority.
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
{ adminPage, userPage }
Data factory
helpers/factories.ts
Creates test data via API
createTestUser({ role: 'editor' })
API client
helpers/api-client.ts
Direct API calls for setup/teardown
apiClient.delete('/users/' + id)
Accessibility helper
helpers/a11y.ts
axe-core wrapper
checkAccessibility(page, testInfo)
Assertions
helpers/assertions.ts
Custom matchers
toHaveToast('Saved')
Page Objects Walk-Through
Show the existing page objects and explain:
Base page class and its contract (abstract path, waitForReady)
How component objects compose with page objects
Naming conventions (file name matches route: checkout.page.ts for /checkout)
How to add a new page object (copy-modify pattern from the simplest existing one)
CI Pipeline Walk-Through
Open the CI configuration and trace through:
What triggers the pipeline (push, PR, schedule)
What stages run and in what order
Where test artifacts go (reports, traces, screenshots)
How to find and interpret a failed test in CI
How to re-run a failed job
Mentorship Patterns
Pair on First 3 Tests
The experienced team member sits with the new person for their first three tests:
Test 1: Navigator/Driver. Experienced person explains the approach and makes key decisions. New person types and asks "why?" at each step. Goal: understand the workflow.
Test 2: Co-pilots. Both contribute equally. New person makes more decisions, experienced person fills gaps. Goal: build confidence.
Test 3: Observer. New person drives entirely. Experienced person observes and gives feedback only when asked or when the approach would cause problems. Goal: independence.
Review All PRs for First 2 Weeks
Every PR from the new person gets a thorough, supportive review for the first two weeks. Not just "LGTM" -- specific feedback on:
Pattern adherence (are they using page objects correctly?)
Selector strategy (are they using stable locators?)
Assertion quality (are assertions specific enough?)
Test isolation (any shared state risks?)
Naming (does the test name describe behavior?)
After two weeks, reduce to standard review depth.
Testing Buddy System
Assign a testing buddy -- a specific person the new team member can ask any question without hesitation. The buddy:
Checks in daily for the first week ("What are you stuck on?")
Is available for ad-hoc questions without scheduling
Reviews all PRs with educational comments (explain the "why")
Introduces the new person to team norms and unwritten rules
Progressive Responsibility Ramp
Week 1-2: Write tests for existing, well-understood features (smoke, basic flows)
Week 3-4: Write tests for current sprint stories (with pairing available)
Week 5-6: Write tests independently, review others' PRs
Week 7-8: Contribute to test architecture (new fixtures, utilities, page objects)
Month 3+: Lead test planning for a feature area, mentor the next new person
Anti-Patterns
Sink or Swim Onboarding
Giving a new person repository access, pointing them at the README, and expecting them to figure it out. This produces weeks of wasted time, bad habits learned from trial and error, and early attrition. Structured onboarding with pairing pays for itself in the first sprint.
Tutorial-Only Onboarding
Spending two weeks on framework tutorials and toy exercises before touching the real codebase. Tutorials teach syntax; they do not teach project conventions, domain knowledge, or team workflow. Minimize tutorials (1-2 hours max) and move to real tests quickly.
No Documentation, All Tribal Knowledge
When the answer to every question is "ask Sarah," the team has a bus factor of one and onboarding depends entirely on Sarah's availability. Document conventions in .agents/qa-project-context.md and the framework walkthrough. If something is important enough to explain verbally, it is important enough to write down.
Perfectionism Paralysis
Expecting the new person's first test to be perfect. The first test should be functional and following basic conventions. Code quality improves with each PR review cycle. Blocking a first PR on style nits or advanced patterns destroys confidence and delays the first win.
Ignoring the Onboarding Experience
Not soliciting feedback from the person being onboarded. They experienced the process firsthand and know exactly what was missing, confusing, or wasted time. Conduct a 15-minute feedback session at the end of week 2 and week 4. Use their feedback to improve onboarding for the next person.
Copy-Paste Without Understanding
The new person copies an existing test, changes the locators and URL, and calls it done. The test works but they do not understand why. Pairing and code review should focus on the "why" behind each pattern. If someone cannot explain why a fixture is structured a certain way, they will misuse it when the context differs.
Verification
Prove the artifacts hold before declaring onboarding complete. Cheapest check first.
The first merged test is stable, not lucky. Run it repeated to rule out flakiness, then confirm CI is green.
The audit doc is complete, not a stub. Open the findings doc and confirm all five dimensions (coverage/distribution, reliability, CI health, technical debt, conventions) are filled, and findings are categorized into strengths / gaps / risks / quick wins / strategic work. A startup that scoped out the audit (see team_maturity) records that decision instead.
The context file parses and is populated..agents/qa-project-context.md exists and carries framework, critical paths, team structure, and risk areas — not a high-level placeholder.
Done When
At least one working test merged to the repo, passing in CI, and stable across 3 local repeats (--repeat-each=3 exits 0) — proves the local and pipeline setup end-to-end.
Test architecture audit doc exists with all five dimensions filled and findings categorized (strengths, gaps, risks, quick wins, strategic work) — or, for a startup team_maturity, the doc records the explicit decision to scope it out.
Every Week-1 Day-1/2 setup item has a recorded owner and a target date; blocking items are filed as tracked tickets.
.agents/qa-project-context.md exists and is populated with framework, critical paths, team structure, and risk areas (not a placeholder).
Test framework selected with rationale recorded (evaluated alternatives, decision written down) — or marked N/A when inheriting an existing framework.
Reference Files (in references/)
framework-walkthrough.md — The full framework walkthrough template: architecture overview, run commands, new-test step-by-step and template, debug playbooks, conventions, and help routing.
audit-worksheets.md — Copy-and-fill worksheets for the test architecture audit (coverage, reliability, CI health, technical debt, conventions).
Related Skills
qa-project-context -- The project context file is the foundation for onboarding. Create it if it does not exist; update it as part of onboarding.
playwright-automation -- Framework-specific patterns, page object model, fixtures, and CI integration for Playwright-based projects.
shift-left-testing -- Introduces the new person to the team's shift-left practices: Three Amigos, PR review, Definition of Done.
test-strategy -- Understanding the overall testing strategy gives the new person context for why tests are structured the way they are.
test-reliability -- Understanding flaky test patterns and quarantine management helps the new person avoid creating unreliable tests.
1---2name: qa-project-bootstrap3description: 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 architecture audit," "first 30 days," "QA mentorship," "joining QA team." Not for: setting up QA on a brand-new project from scratch — use `qa-start`. Related: qa-start, qa-project-context, shift-left-testing, ai-qa-review.4license: MIT5---67<objective>
8A 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.
910**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.
11</objective>
1213## Quick Route
1415This skill serves three distinct jobs. Identify yours, jump to the section, skip the rest.
1617| Situation | Jump to | Output |
18|-----------|---------|--------|
19| Onboarding a **new person** to an existing team | First 30 Days Checklist → Mentorship Patterns | A 30-day ramp plan with owners and dates |
20| Inherited an **existing suite** with no onboarding/docs | Test Architecture Audit (scope by `team_maturity`) | A 1-2 page findings doc, five dimensions |
21| Need the **reference doc** for anyone writing tests | Framework Walkthrough Template | A project-specific walkthrough.md |
2223A real onboarding usually needs all three; a quick health check needs only the audit.
2425---
2627## Discovery Questions
2829### Who Is Being Onboarded?
30311. **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.
32332. **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.
34353. **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.
3637### Project State
38394. **Is there an existing test framework?** If yes: how healthy is it? If no: framework selection is step one (see `test-strategy` skill).
40415. **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.
42436. **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.
4445### Access and Tooling
46477. **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.
4849---
5051## Core Principles
5253### 1. Time to First Merged Test Is the Success Metric
5455The 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.
5657### 2. Progressive Complexity
5859Start 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.
6061### 3. Document Tribal Knowledge
6263Every 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.
6465### 4. Pair First, Solo Second
6667The 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.
6869### 5. Make the Easy Path the Right Path
7071If 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.
7273> **Calibrate to your team maturity** (set `team_maturity` in `.agents/qa-project-context.md`):
74> - **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.
75> - **growing** — Full 30-day plan: framework selection, CI integration, coverage baseline, team conventions documented.
76> - **established** — 30-day plan plus: audit existing suite for anti-patterns, propose tooling upgrades, establish metrics baseline, schedule recurring quality reviews.
7778---
7980## First 30 Days Checklist
8182### Week 1: Environment, Access, and Orientation
8384**Day 1-2: Setup**
85- [ ] Repository cloned and building locally
86- [ ] All environment variables configured (`.env.local`, test credentials)
87- [ ] Application running locally (frontend + backend + database)
88- [ ] Test suite runs locally and passes (or known failures are documented)
89- [ ] IDE configured with recommended extensions (test runner plugin, linter, formatter)
90- [ ] Access granted: CI dashboard, staging environment, bug tracker, team channels
9192**Day 3-4: Orientation**
93- [ ] Read `.agents/qa-project-context.md` (or create it if it does not exist)
94- [ ] Walk through the test directory structure with a team member
95- [ ] Understand the test pyramid: how many unit, integration, and E2E tests exist
96- [ ] Review the CI pipeline: what runs on PR, what runs nightly, what blocks merge
97- [ ] Identify the top 5 critical user flows (these will be the first testing targets)
98- [ ] Attend one Three Amigos or sprint planning session as an observer
99- [ ] **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.
100101**Day 5: First Small Win**
102- [ ] Run a single test in debug/headed mode and understand what it does
103- [ ] Modify one assertion in an existing test, verify it fails as expected, revert
104- [ ] Read 3 existing tests and annotate what each section does (setup, action, assertion)
105106### Week 2: First Real Test
107108- [ ] Identify a simple, low-risk test to write (page loads, element visibility, basic navigation)
109- [ ] Write the test using existing page objects and fixtures (pair with a team member)
110- [ ] Run the test locally, ensure it passes reliably (3 consecutive runs)
111- [ ] Open a PR, receive feedback, iterate
112- [ ] Test passes in CI
113- [ ] **First test merged**
114115### Week 3: Sprint Contribution
116117- [ ] Pick up a sprint story's QA work (with mentorship)
118- [ ] Write tests covering the story's acceptance criteria
119- [ ] Identify at least one edge case not covered by acceptance criteria
120- [ ] Participate actively in Three Amigos or story refinement (ask questions)
121- [ ] Review one existing PR for test quality (using the PR review checklist from `shift-left-testing`)
122123### Week 4: Independence Milestones
124125- [ ] Write and merge a multi-step E2E test without pairing
126- [ ] Participate in bug triage and articulate testing gaps
127- [ ] Contribute to `.agents/qa-project-context.md` with new learnings
128- [ ] Present test results/findings at sprint review or team standup
129- [ ] Self-assess: which test patterns feel comfortable? Which need more practice?
130131---
132133## Test Architecture Audit
134135When 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.
136137**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:
138- **startup** — Skip the full audit. Confirm one path is covered and one framework runs; spend the saved hours getting a first test merged.
139- **growing** — Run all five dimensions once to establish a baseline; defer recurring reviews.
140- **established** — Full five-dimension audit plus recurring quality reviews on a schedule (e.g. monthly), with the findings doc tracked over time.
141142### What to Assess
143144Assess five dimensions, each with a fill-in worksheet:
145146- **Coverage and Distribution** — test counts by layer, pyramid shape, code coverage and trend.
147- **Reliability** — flaky test rate, top flakiest tests, quarantine count and age.
148- **CI Health** — full suite and per-stage duration, parallelism, pass rate, retry rate.
149- **Technical Debt** — skipped tests, `waitForTimeout`/`force: true` usage, hardcoded data, assertionless tests, deprecated APIs, stale AI-generated tests, stale feature flags.
150- **Conventions** — page objects, fixtures, factories, naming, shared utilities, tagging.
151152See `references/audit-worksheets.md` for the copy-and-fill worksheets covering all five dimensions.
153154### Audit Output
155156Produce a short document (1-2 pages) summarizing findings, categorized as:
157158- **Strengths:** What the existing suite does well (preserve and learn from these)
159- **Gaps:** Missing coverage areas, undertested critical paths
160- **Risks:** Flaky tests, stale quarantines, declining coverage
161- **Quick Wins:** Improvements achievable in 1-2 sprints (fix flaky tests, add missing happy-path coverage)
162- **Strategic Work:** Improvements requiring sustained investment (refactor test architecture, add integration layer)
163164---
165166## Framework Walkthrough Template
167168Create this document for your project. It is the primary reference for anyone writing tests. It has six sections:
1691701. **Architecture Overview** — framework, language, config location, and the annotated directory tree.
1712. **How to Run Tests** — the full set of run commands (all tests, single file, grep, headed, debug, UI mode, per-browser, report).
1723. **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.
1734. **How to Debug Failures** — local vs CI failure playbooks and common failure-pattern decoder.
1745. **Common Patterns and Conventions** — project-specific examples for auth fixtures, data factories, assertion specificity, and selector priority.
1756. **Where to Find Help** — the routing table for questions about patterns, failures, product behavior, and docs.
176177See `references/framework-walkthrough.md` for the full template with all code blocks, directory trees, and command lists to copy and adapt.
178179---
180181## Codebase Orientation Guide
182183Walk through these areas with the new person in a 60-90 minute session.
184185### Test Directory Structure Tour
186187Walk through the actual directory tree, explaining:
188- Why tests are organized this way (by feature, not by type)
189- Where to find page objects for each product area
190- Where shared utilities live and what they do
191- Where test data and fixtures are defined
192- Where CI configuration lives
193194### Shared Utilities Inventory
195196| Utility | Location | Purpose | Example |
197|---------|----------|---------|---------|
198| Auth fixture | `fixtures/auth.fixture.ts` | Provides authenticated sessions | `{ adminPage, userPage }` |
199| Data factory | `helpers/factories.ts` | Creates test data via API | `createTestUser({ role: 'editor' })` |
200| API client | `helpers/api-client.ts` | Direct API calls for setup/teardown | `apiClient.delete('/users/' + id)` |
201| Accessibility helper | `helpers/a11y.ts` | axe-core wrapper | `checkAccessibility(page, testInfo)` |
202| Assertions | `helpers/assertions.ts` | Custom matchers | `toHaveToast('Saved')` |
203204### Page Objects Walk-Through
205206Show the existing page objects and explain:
207- Base page class and its contract (abstract `path`, `waitForReady`)
208- How component objects compose with page objects
209- Naming conventions (file name matches route: `checkout.page.ts` for `/checkout`)
210- How to add a new page object (copy-modify pattern from the simplest existing one)
211212### CI Pipeline Walk-Through
213214Open the CI configuration and trace through:
215- What triggers the pipeline (push, PR, schedule)
216- What stages run and in what order
217- Where test artifacts go (reports, traces, screenshots)
218- How to find and interpret a failed test in CI
219- How to re-run a failed job
220221---
222223## Mentorship Patterns
224225### Pair on First 3 Tests
226227The experienced team member sits with the new person for their first three tests:
2282291. **Test 1: Navigator/Driver.** Experienced person explains the approach and makes key decisions. New person types and asks "why?" at each step. Goal: understand the workflow.
2302. **Test 2: Co-pilots.** Both contribute equally. New person makes more decisions, experienced person fills gaps. Goal: build confidence.
2313. **Test 3: Observer.** New person drives entirely. Experienced person observes and gives feedback only when asked or when the approach would cause problems. Goal: independence.
232233### Review All PRs for First 2 Weeks
234235Every PR from the new person gets a thorough, supportive review for the first two weeks. Not just "LGTM" -- specific feedback on:
236- Pattern adherence (are they using page objects correctly?)
237- Selector strategy (are they using stable locators?)
238- Assertion quality (are assertions specific enough?)
239- Test isolation (any shared state risks?)
240- Naming (does the test name describe behavior?)
241242After two weeks, reduce to standard review depth.
243244### Testing Buddy System
245246Assign a testing buddy -- a specific person the new team member can ask any question without hesitation. The buddy:
247- Checks in daily for the first week ("What are you stuck on?")
248- Is available for ad-hoc questions without scheduling
249- Reviews all PRs with educational comments (explain the "why")
250- Introduces the new person to team norms and unwritten rules
251252### Progressive Responsibility Ramp
253254```
255Week 1-2: Write tests for existing, well-understood features (smoke, basic flows)
256Week 3-4: Write tests for current sprint stories (with pairing available)
257Week 5-6: Write tests independently, review others' PRs
258Week 7-8: Contribute to test architecture (new fixtures, utilities, page objects)
259Month 3+: Lead test planning for a feature area, mentor the next new person
260```
261262---
263264## Anti-Patterns
265266### Sink or Swim Onboarding
267268Giving a new person repository access, pointing them at the README, and expecting them to figure it out. This produces weeks of wasted time, bad habits learned from trial and error, and early attrition. Structured onboarding with pairing pays for itself in the first sprint.
269270### Tutorial-Only Onboarding
271272Spending two weeks on framework tutorials and toy exercises before touching the real codebase. Tutorials teach syntax; they do not teach project conventions, domain knowledge, or team workflow. Minimize tutorials (1-2 hours max) and move to real tests quickly.
273274### No Documentation, All Tribal Knowledge
275276When the answer to every question is "ask Sarah," the team has a bus factor of one and onboarding depends entirely on Sarah's availability. Document conventions in `.agents/qa-project-context.md` and the framework walkthrough. If something is important enough to explain verbally, it is important enough to write down.
277278### Perfectionism Paralysis
279280Expecting the new person's first test to be perfect. The first test should be functional and following basic conventions. Code quality improves with each PR review cycle. Blocking a first PR on style nits or advanced patterns destroys confidence and delays the first win.
281282### Ignoring the Onboarding Experience
283284Not soliciting feedback from the person being onboarded. They experienced the process firsthand and know exactly what was missing, confusing, or wasted time. Conduct a 15-minute feedback session at the end of week 2 and week 4. Use their feedback to improve onboarding for the next person.
285286### Copy-Paste Without Understanding
287288The new person copies an existing test, changes the locators and URL, and calls it done. The test works but they do not understand why. Pairing and code review should focus on the "why" behind each pattern. If someone cannot explain why a fixture is structured a certain way, they will misuse it when the context differs.
289290---
291292## Verification
293294Prove the artifacts hold before declaring onboarding complete. Cheapest check first.
2952961. **The first merged test is stable, not lucky.** Run it repeated to rule out flakiness, then confirm CI is green.
297 - `npx playwright test <new-test> --repeat-each=3` exits 0 (3 consecutive passes locally)
298 - The PR's CI check is green on the same test
2992. **The audit doc is complete, not a stub.** Open the findings doc and confirm all five dimensions (coverage/distribution, reliability, CI health, technical debt, conventions) are filled, and findings are categorized into strengths / gaps / risks / quick wins / strategic work. A startup that scoped out the audit (see `team_maturity`) records that decision instead.
3003. **The context file parses and is populated.** `.agents/qa-project-context.md` exists and carries framework, critical paths, team structure, and risk areas — not a high-level placeholder.
301302## Done When
303304- At least one working test merged to the repo, passing in CI, and stable across 3 local repeats (`--repeat-each=3` exits 0) — proves the local and pipeline setup end-to-end.
305- Test architecture audit doc exists with all five dimensions filled and findings categorized (strengths, gaps, risks, quick wins, strategic work) — or, for a startup `team_maturity`, the doc records the explicit decision to scope it out.
306- Every Week-1 Day-1/2 setup item has a recorded owner and a target date; blocking items are filed as tracked tickets.
307- `.agents/qa-project-context.md` exists and is populated with framework, critical paths, team structure, and risk areas (not a placeholder).
308- Test framework selected with rationale recorded (evaluated alternatives, decision written down) — or marked N/A when inheriting an existing framework.
309310## Reference Files (in `references/`)
311312- **framework-walkthrough.md** — The full framework walkthrough template: architecture overview, run commands, new-test step-by-step and template, debug playbooks, conventions, and help routing.
313- **audit-worksheets.md** — Copy-and-fill worksheets for the test architecture audit (coverage, reliability, CI health, technical debt, conventions).
314315## Related Skills
316317- **qa-project-context** -- The project context file is the foundation for onboarding. Create it if it does not exist; update it as part of onboarding.
318- **playwright-automation** -- Framework-specific patterns, page object model, fixtures, and CI integration for Playwright-based projects.
319- **shift-left-testing** -- Introduces the new person to the team's shift-left practices: Three Amigos, PR review, Definition of Done.
320- **test-strategy** -- Understanding the overall testing strategy gives the new person context for why tests are structured the way they are.
321- **test-reliability** -- Understanding flaky test patterns and quarantine management helps the new person avoid creating unreliable tests.
Run npx skillmds add petrkindlmann/qa-project-bootstrap in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
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 architecture audit," "first 30 days," "QA mentorship," "joining QA team." Not for: setting up QA on a brand-new project from scratch — use `qa-start`. Related: qa-start, qa-project-context, shift-left-testing, ai-qa-review. It is listed under Security on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Capability flags: reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.
petrkindlmann (@petrkindlmann) published this skill. Their other Agent Skills are listed on their SkillMD profile.
petrkindlmann