qa-project-bootstrap
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.
kindlmann · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add petrkindlmann/qa-skills --skill qa-project-bootstrapAbout this skill
name: qa-project-bootstrap
description: >-
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.
license: MIT
metadata:
author: kindlmann
version: "2.0"
category: process
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-strategyskill). -
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.
Read the complete source ↗Calibrate to your team maturity (set
team_maturityin.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