dev-onboarding-builder

What this skill does

# Developer Onboarding Builder

Create frictionless first-day experiences for new team members.

## Core Workflow

1. **Assess prerequisites**: Identify required tools and access
2. **Create setup guide**: Step-by-step environment configuration
3. **Design first task**: Choose appropriate starter assignment
4. **Add time estimates**: Set expectations for each step
5. **Document common issues**: Preemptive troubleshooting
6. **Introduce team**: Context on people and structure
7. **Provide codebase tour**: Walkthrough of key areas

## Onboarding Documentation Structure

### ONBOARDING.md Template

````markdown
# Welcome to [Team/Project Name]! 🎉

This guide will help you get set up and productive on your first day.

**Estimated completion time:** 2-3 hours

## Before You Start

### Access Checklist

- [ ] GitHub organization access
- [ ] Slack workspace invitation
- [ ] Email account setup
- [ ] VPN credentials (if remote)
- [ ] Cloud console access (AWS/GCP/Azure)
- [ ] CI/CD dashboard access
- [ ] Project management tool (Jira/Linear)

### Tools to Install

- [ ] Node.js 20+ (via [Volta](https://volta.sh/))
- [ ] pnpm 8+
- [ ] Docker Desktop
- [ ] PostgreSQL 15+
- [ ] VS Code or preferred editor
- [ ] Git configured with your work email

## Day 1: Environment Setup

### Step 1: Clone Repository (5 min)

```bash
git clone [email protected]:company/project-name.git
cd project-name
```
````

**Why:** Get the codebase on your machine

**Troubleshooting:**

- SSH key not working? See [GitHub SSH setup](https://docs.github.com/en/authentication/connecting-to-github-with-ssh)
- Permission denied? Ask your manager to verify GitHub access

### Step 2: Install Dependencies (10 min)

```bash
# Install Volta (Node version manager)
curl https://get.volta.sh | bash

# Install dependencies
pnpm install
```

**Expected output:** "Dependencies installed successfully"

**Troubleshooting:**

- `pnpm not found`? Restart terminal or run `volta install pnpm`
- Installation hangs? Check VPN connection

### Step 3: Configure Environment (10 min)

```bash
# Copy environment template
cp .env.example .env
```

**Edit `.env` with these values:**

```
DATABASE_URL=postgresql://postgres:password@localhost:5432/projectname_dev
REDIS_URL=redis://localhost:6379
API_KEY=ask-team-for-dev-key
```

**Get credentials from:**

- Database: Local setup (see next step)
- API keys: Ask @alice or @bob on Slack #dev-onboarding
- External services: Check 1Password vault "Dev Credentials"

**Troubleshooting:**

- Can't find credentials? Post in #dev-onboarding
- Missing env var? Check .env.example for all required variables

### Step 4: Setup Database (15 min)

```bash
# Start PostgreSQL with Docker
docker run --name project-postgres \
  -e POSTGRES_PASSWORD=password \
  -p 5432:5432 \
  -d postgres:15

# Run migrations
pnpm db:migrate

# Seed with test data
pnpm db:seed
```

**Expected output:** "Migration complete. Database seeded."

**Verify:** Open http://localhost:5432 and check for tables

**Troubleshooting:**

- Port 5432 already in use? Kill existing process: `lsof -ti:5432 | xargs kill`
- Migration fails? Drop and recreate: `pnpm db:reset`

### Step 5: Start Development Server (5 min)

```bash
pnpm dev
```

**Expected output:**

```
✓ Ready on http://localhost:3000
```

**Test:** Open http://localhost:3000 - you should see the homepage

**Troubleshooting:**

- Port 3000 in use? Kill process or change PORT in .env
- Build errors? Clear cache: `rm -rf .next && pnpm dev`

### Step 6: Run Tests (5 min)

```bash
pnpm test
```

**Expected output:** All tests passing ✓

**If tests fail:**

- First time? This is a bug! Report in #dev-help
- Known issue? Check #dev-help pinned messages

## Day 1: Your First Task

### Task: Fix a Starter Issue

We've labeled some issues as `good-first-issue` for new team members.

**Goal:** Successfully complete one small PR to learn our workflow

**Steps:**

1. Browse [good first issues](https://github.com/company/project/labels/good-first-issue)
2. Pick one that interests you (or ask for suggestion in #dev-onboarding)
3. Comment on the issue: "I'll take this!"
4. Create a branch: `git checkout -b fix/issue-123-description`
5. Make your changes
6. Write/update tests
7. Run `pnpm lint` and `pnpm test`
8. Commit following [conventions](./CONTRIBUTING.md#commit-messages)
9. Push and create PR
10. Request review from your mentor

**Estimated time:** 2-4 hours

**Success criteria:**

- [ ] Branch created with proper name
- [ ] Code changes made
- [ ] Tests written/updated
- [ ] All checks passing
- [ ] PR created with description
- [ ] Code reviewed and merged

**Mentors:** @alice (backend), @bob (frontend), @charlie (full-stack)

## Day 2-3: Codebase Tour

### Project Structure Overview

```
src/
├── app/              # Next.js routes (start here!)
│   ├── api/          # API endpoints
│   └── (auth)/       # Authentication pages
├── components/       # React components
│   ├── ui/           # Base UI components
│   └── features/     # Feature-specific components
├── lib/              # Utilities and helpers
│   ├── api/          # API client
│   ├── hooks/        # Custom React hooks
│   └── utils/        # Helper functions
├── services/         # Business logic layer
└── types/            # TypeScript definitions
```

### Key Files to Understand

| File                 | What It Does            | When You'll Touch It    |
| -------------------- | ----------------------- | ----------------------- |
| `src/app/layout.tsx` | Root layout & providers | Adding global providers |
| `src/lib/db.ts`      | Database client         | Database queries        |
| `src/lib/auth.ts`    | Authentication logic    | Auth-related features   |
| `src/middleware.ts`  | Request middleware      | Adding auth/redirects   |

### Walking Tour (Read These Files in Order)

1. **`src/app/page.tsx`** - Homepage (entry point)
2. **`src/app/api/users/route.ts`** - Simple API endpoint
3. **`src/services/user.service.ts`** - Business logic example
4. **`src/components/ui/button.tsx`** - UI component pattern
5. **`src/lib/hooks/useUser.ts`** - Custom hook example

**Exercise:** Find the code that handles user registration. Hint: Start at the API route!

### Common Patterns

**API Route Pattern**

```typescript
// src/app/api/[resource]/route.ts
export async function GET(req: Request) {
  // 1. Validate auth
  // 2. Parse request
  // 3. Call service layer
  // 4. Return response
}
```

**Service Layer Pattern**

```typescript
// src/services/[resource].service.ts
export class UserService {
  async create(data: CreateUserDto) {
    // 1. Validate data
    // 2. Business logic
    // 3. Database operation
    // 4. Return result
  }
}
```

## Week 1: Learning Path

### Day 1

- [ ] Complete environment setup
- [ ] Fix first issue
- [ ] Meet your team (schedule 1:1s)

### Day 2-3

- [ ] Read codebase tour documents
- [ ] Complete second issue (medium complexity)
- [ ] Review 2-3 PRs from teammates

### Day 4-5

- [ ] Work on first feature (with mentor pairing)
- [ ] Attend team standup/planning
- [ ] Set up development tools (linters, extensions)

## Team Structure

### Engineering Team

**Alice (@alice)** - Tech Lead

- Approves architecture decisions
- Code review on complex PRs
- Ask: System design questions

**Bob (@bob)** - Senior Backend Engineer

- Database and API expert
- Ask: Backend, performance questions

**Charlie (@charlie)** - Senior Frontend Engineer

- UI/UX implementation
- Ask: React, styling questions

**Your Manager (@manager)**

- Weekly 1:1s on Fridays 2pm
- Career development discussions
- Ask: Process, priorities, career questions

### Communication Channels

- **#dev-general** - General development discussion
- **#dev-help** - Ask questions, get unstuck
- **#dev-onboarding** - New member support
- **#dev-releases** - Release announcements
- **#dev-alerts** - Production alerts

### Meeting Schedule

- **Daily Standup** - 10:00 AM (15 min)
- **Sprint Planning** - Mondays 2:00 P