| name | developer-onboarding-advanced |
| description | Advanced developer onboarding — Architecture Tour (codebase walkthrough by request), anchor files, domain glossary, GitHub Issue onboarding checklist template, knowledge sharing patterns (pair programming, ADRs, Loom), and onboarding metrics (Time to First PR). |
Developer Onboarding — Advanced
This skill extends developer-onboarding with codebase navigation, structured knowledge transfer, and metrics. Load developer-onboarding first.
When to Activate
- Creating an Architecture Tour document for a complex codebase
- Building a domain glossary so new hires understand the business domain
- Setting up a GitHub Issue template for new hire onboarding checklists
- Designing a structured pair-programming schedule for the first 4 weeks
- Measuring Time to First PR and diagnosing where onboarding breaks down
Codebase Navigation Strategies
Architecture Tour — a guided walk through the codebase
An Architecture Tour is a document or walkthrough that explains the codebase through the lens of a real request:
## Architecture Tour: What happens when a user places an order?
### 1. HTTP Request arrives
**File:** `src/api/routes/orders.ts` — the Express route handler
- Validates the JWT token (`src/middleware/auth.ts`)
- Parses and validates the request body with Zod
### 2. Business logic
**File:** `src/services/OrderService.ts` — the core domain logic
- Checks inventory availability (`InventoryRepository`)
- Calculates pricing including discounts
- Emits `order.created` domain event
### 3. Persistence
**File:** `src/repositories/OrderRepository.ts` — Prisma ORM
- Inserts the order in a database transaction
- Updates inventory counts atomically
### 4. Async processing
**File:** `src/workers/OrderProcessor.ts` — BullMQ worker
- Processes payment via Stripe
- Sends confirmation email
- Fires webhook to customer's registered endpoint
### 5. Tests
**File:** `tests/services/OrderService.test.ts` — unit tests
**File:** `tests/integration/orders.test.ts` — integration tests with real DB
**File:** `tests/e2e/checkout.spec.ts` — Playwright E2E
Anchor files — the 10 files every team member should know
Pin these in your README or CONTRIBUTING.md:
## Key Files
| File | Purpose |
|------|---------|
| `src/app.ts` | Express app initialisation — all middleware registered here |
| `src/config.ts` | All environment variables and their defaults |
| `src/domain/errors.ts` | All application error types |
| `prisma/schema.prisma` | Database schema — single source of truth |
| `src/services/AuthService.ts` | Authentication and session management |
| `src/services/OrderService.ts` | Core business logic for orders |
| `tests/helpers/test-setup.ts` | Test utilities used in all test files |
| `.github/workflows/ci.yml` | CI pipeline — what runs on every PR |
| `docker-compose.yml` | Local infrastructure (DB, Redis, queues) |
| `docs/decisions/` | Architecture Decision Records — why things are the way they are |
Domain Glossary
Extract and document domain-specific terminology that is not obvious to outsiders:
## Glossary
| Term | Meaning |
|------|---------|
| **Fulfillment** | The process of picking, packing, and shipping an order |
| **Merchant** | A business selling products through our platform (not a customer) |
| **SKU** | Stock Keeping Unit — unique identifier for a specific product variant |
| **Chargeback** | A payment reversal initiated by the customer's bank |
| **Net settlement** | The payment to the merchant after platform fees are deducted |
| **Webhook fanout** | Delivering a single event to multiple registered endpoints |
Onboarding Checklist as GitHub Issue
Create this as a GitHub Issue Template so every new hire gets their own checklist:
<!-- .github/ISSUE_TEMPLATE/onboarding.md -->
---
name: Developer Onboarding
about: Track onboarding progress for a new team member
title: 'Onboarding: [Name]'
labels: onboarding
assignees: ''
---
## Week 1 — Setup & First PR
- [ ] Local environment running (`./scripts/setup.sh` succeeded)
- [ ] All tests passing locally
- [ ] Read CONTRIBUTING.md
- [ ] Completed Architecture Tour (read `docs/architecture/arc42.md`)
- [ ] Reviewed 5 recent PRs to understand coding style
- [ ] First PR merged (can be a documentation fix)
- [ ] Introduced to Slack channels and key contacts
- [ ] Buddy assigned: @___
## Week 2 — First Bug Fix
- [ ] Completed Code Archaeology session with buddy
- [ ] Reviewed ADRs in `docs/decisions/` (understand why key decisions were made)
- [ ] First bug fix PR opened and merged independently
- [ ] Able to run and write tests without help
- [ ] Reviewed oncall runbook (if applicable)
## Week 3–4 — First Feature
- [ ] First feature ticket picked from backlog
- [ ] Architecture decision made (ADR drafted if needed)
- [ ] Feature implemented with tests (TDD)
- [ ] Feature deployed to staging and verified
- [ ] Onboarding feedback submitted (see link below)
## Feedback
Please submit your onboarding feedback after 30 days:
[Onboarding Survey](https://forms.example.com/onboarding-feedback)
Knowledge Sharing Patterns
Structured pair programming (first 4 weeks)
| Week | Session type | Goal |
|---|
| 1 | Codebase walkthrough with buddy | Navigate independently |
| 2 | Pair on a bug fix | Debug and test patterns |
| 3 | Pair on a feature | Design and implementation |
| 4 | New hire leads, buddy observes | Confirm independence |
Architecture Decision Records (ADRs)
New hires should read ADRs before asking "why is it this way?". Every significant decision must have an ADR — see skill adr-writing.
ls docs/decisions/YYYY-MM-DD-*.md
Video walkthroughs (Loom)
For complex operational processes, a 10-minute Loom is worth more than a 5-page doc:
High-value Loom topics:
- Deployment process (staging → production, feature flags)
- Incident response: how to triage, who to call, where to look
- Database migration workflow (safe, zero-downtime patterns)
- Running load tests and reading results
Store links in CONTRIBUTING.md or the internal wiki — not in Slack (messages get lost).
Onboarding Metrics
Track these to identify where onboarding breaks down:
| Metric | How to measure | Target |
|---|
| Time to First PR | GitHub API: first_closed_pr.date - hire_date | ≤ 2 days |
| Time to First Independent Feature | Manually tracked in onboarding issue | ≤ 4 weeks |
| Setup success rate | ./scripts/setup.sh exit code logged to monitoring | ≥ 95% |
| Onboarding NPS | Anonymous survey at 30 days (scale 0–10) | ≥ 8 |
| Question frequency | Count Slack @-mentions of senior devs from new hire | Decreasing after week 2 |
gh pr list --author "@username" --state merged --json mergedAt \
| jq -r '.[0].mergedAt'
When metrics are bad:
- Time to First PR > 5 days → fix the setup script or CONTRIBUTING.md
- Setup success rate < 90% → run the setup on a fresh VM in CI weekly
- Onboarding NPS < 7 → run onboarding retrospective with recent hires
- Questions not decreasing → identify the knowledge gap and document it
Quick Reference
New hire arrives:
1. Create onboarding GitHub issue from template
2. Assign buddy
3. Run: ./scripts/setup.sh
4. Read: CONTRIBUTING.md
5. Complete: Architecture Tour
6. First task: small PR (doc fix, test, good-first-issue)
Codebase archaeology order:
1. git log --oneline -30 — recent history
2. git log --format=: --name-only | sort | uniq -c | sort -rn — hotspots
3. madge / pydeps / go mod graph — architecture
4. Read anchor files (listed in CONTRIBUTING.md)
5. Architecture Tour document
When onboarding feels broken:
1. Measure Time to First PR
2. Run make doctor on a fresh machine
3. Survey recent hires (anonymous)
4. Fix the root cause — never "just ask someone"
Reference
developer-onboarding — code archaeology, CONTRIBUTING.md patterns, automated setup scriptsadr-writing — Architecture Decision Records format and templatesarc42-c4 — arc42 architecture documentation with C4 diagrams
