Onboarding Helper Skill

Generate comprehensive onboarding documentation and guides for new developers joining your team or project.

Instructions

You are an onboarding and developer experience expert. When invoked:

Assess Onboarding Needs:
- Project complexity and technology stack
- Team size and structure
- Development workflow and processes
- Domain knowledge requirements
- Common onboarding challenges
Create Onboarding Materials:
- Welcome documentation
- Development environment setup guides
- Codebase architecture overview
- First-task tutorials
- Team processes and conventions
Organize Learning Path:
- Day 1, Week 1, Month 1 goals
- Progressive complexity
- Hands-on exercises
- Checkpoint milestones
- Resources and references
Document Team Culture:
- Communication channels
- Meeting schedules
- Code review practices
- Decision-making processes
- Team values and norms
Enable Self-Service:
- FAQ sections
- Troubleshooting guides
- Links to resources
- Who to ask for what
- Common gotchas

Onboarding Documentation Structure

Complete Onboarding Guide Template

# Welcome to [Project Name]! 👋

Welcome! We're excited to have you on the team. This guide will help you get up to speed quickly and smoothly.

## Table of Contents
1. [Overview](#overview)
2. [Day 1: Getting Started](#day-1-getting-started)
3. [Week 1: Core Concepts](#week-1-core-concepts)
4. [Month 1: Making Impact](#month-1-making-impact)
5. [Team & Processes](#team--processes)
6. [Resources](#resources)
7. [FAQ](#faq)

---

## Overview

### What We're Building
We're building a modern e-commerce platform that helps small businesses sell online. Our platform handles:
- Product catalog management
- Shopping cart and checkout
- Payment processing (Stripe integration)
- Order fulfillment and tracking
- Customer relationship management

**Our Mission**: Make e-commerce accessible to businesses of all sizes.

**Our Users**: Small to medium business owners with 10-1000 products.

### Technology Stack

**Frontend**:
- React 18 with TypeScript
- Redux Toolkit for state management
- Material-UI component library
- React Query for API calls
- Vite for build tooling

**Backend**:
- Node.js with Express
- PostgreSQL database
- Redis for caching
- Stripe for payments
- AWS S3 for file storage

**Infrastructure**:
- Docker for local development
- Kubernetes for production
- GitHub Actions for CI/CD
- AWS (EC2, RDS, S3, CloudFront)
- DataDog for monitoring

### Project Statistics
- **Started**: January 2023
- **Team Size**: 12 engineers (4 frontend, 5 backend, 3 full-stack)
- **Codebase**: ~150K lines of code
- **Active Users**: 5,000+ businesses
- **Monthly Transactions**: $2M+

---

## Day 1: Getting Started

### Your First Day Checklist

- [ ] Complete HR onboarding
- [ ] Get added to communication channels
- [ ] Set up development environment
- [ ] Clone the repository
- [ ] Run the application locally
- [ ] Deploy to your personal dev environment
- [ ] Introduce yourself to the team
- [ ] Schedule 1:1s with your manager and buddy

### Access & Accounts

**Required Accounts**:
1. **GitHub** - Source code ([github.com/company/project](https://github.com))
   - Request access from @engineering-manager
2. **Slack** - Team communication
   - Channels: #engineering, #frontend, #backend, #general
3. **Jira** - Project management ([company.atlassian.net](https://company.atlassian.net))
4. **Figma** - Design files
5. **AWS Console** - Production access (read-only initially)
6. **DataDog** - Monitoring and logs

**Development Tools**:
- Docker Desktop
- Node.js 18+ (use nvm)
- PostgreSQL client (psql or pgAdmin)
- Postman or Insomnia (API testing)
- VS Code (recommended, see extensions below)

### Environment Setup

#### 1. Install Prerequisites

**macOS**:
```bash
# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

# Install Docker Desktop
brew install --cask docker

# Install PostgreSQL client
brew install postgresql@14

Windows:

# Install using Chocolatey
choco install nodejs-lts docker-desktop postgresql14

2. Clone Repository

# Clone the repo
git clone git@github.com:company/ecommerce-platform.git
cd ecommerce-platform

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env.local

3. Configure Environment Variables

Edit .env.local:

# Database (local Docker)
DATABASE_URL=postgresql://postgres:password@localhost:5432/ecommerce_dev

# Redis
REDIS_URL=redis://localhost:6379

# Stripe (use test keys)
STRIPE_SECRET_KEY=sk_test_... # Get from @backend-lead
STRIPE_PUBLISHABLE_KEY=pk_test_...

# AWS S3 (dev bucket)
AWS_ACCESS_KEY_ID=... # Get from @devops
AWS_SECRET_ACCESS_KEY=...
AWS_S3_BUCKET=ecommerce-dev-uploads

# Session
SESSION_SECRET=your-random-secret-here

Where to get credentials:

Stripe test keys: 1Password vault "Development Secrets"
AWS credentials: Request from @devops in #engineering
Session secret: Generate with openssl rand -base64 32

4. Start Development Environment

# Start Docker services (PostgreSQL, Redis)
docker-compose up -d

# Run database migrations
npm run db:migrate

# Seed database with sample data
npm run db:seed

# Start development server
npm run dev

Expected output:

✔ Database migrated successfully
✔ Seeded 100 products, 50 users
✔ Server running on http://localhost:3000
✔ API available at http://localhost:3000/api

5. Verify Installation

Open your browser to http://localhost:3000

You should see the application home page with sample products.

Test credentials:

Email: test@example.com
Password: password123

Troubleshooting:

Port 3000 in use: Kill the process with lsof -ti:3000 | xargs kill -9
Database connection failed: Check Docker is running with docker ps
Module not found: Delete node_modules and run npm install again

See Troubleshooting Guide for more help.

VS Code Setup

Recommended Extensions:

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "ms-azuretools.vscode-docker",
    "eamodio.gitlens",
    "orta.vscode-jest",
    "prisma.prisma"
  ]
}

Settings (.vscode/settings.json):

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib"
}

Your First Commit

Let's make a simple change to verify your setup:

Create a branch:
```
git checkout -b test/your-name-setup
```

Add your name to the team page: Edit src/pages/About.tsx:

const teamMembers = [
  // ... existing members
  { name: 'Your Name', role: 'Software Engineer', joinedDate: '2024-01-15' }
];

Test your change:
```
npm run test
npm run lint
```

Commit and push:

git add .
git commit -m "docs: Add [Your Name] to team page"
git push origin test/your-name-setup

Create a PR:
- Go to GitHub
- Click "Compare & pull request"
- Fill out the PR template
- Request review from your buddy

Congrats on your first contribution! 🎉

End of Day 1

You should now have:

✅ Development environment running locally
✅ Application accessible in your browser
✅ First PR created
✅ Access to all team tools and channels

Questions? Ask in #engineering or DM your buddy!

Week 1: Core Concepts

Project Architecture

High-Level Architecture

┌─────────────┐
│   Browser   │
│  (React)    │
└──────┬──────┘
       │ HTTPS
       ▼
┌─────────────┐     ┌──────────────┐
│ API Gateway │────▶│  Auth Service│
│  (Express)  │     │   (JWT)      │
└──────┬──────┘     └──────────────┘
       │
       ├────▶ Product Service
       │
       ├────▶ Order Service
       │
       ├────▶ Payment Service ────▶ Stripe API
       │
       └────▶ User Service
              │
              ▼
         ┌──────────┐
         │PostgreSQL│
         └──────────┘

Directory Structure

ecommerce-platform/
├── client/                 # Frontend React app
│   ├── src/
│   │   ├── components/    # Reusable UI components
│   │   ├── pages/         # Page components
│   │   ├── hooks/         # Custom React hooks
│   │   ├── store/         # Redux store and slices
│   │   ├── api/           # API client functions
│   │   ├── utils/         # Utility functions
│   │   └── types/         # TypeScript type definitions
│   └── tests/             # Frontend tests
│
├── server/                # Backend Node.js app
│   ├── src/
│   │   ├── routes/        # Express route handlers
│   │   ├── controllers/   # Business logic
│   │   ├── services/      # External integrations
│   │   ├── models/        # Database models (Prisma)
│   │   ├── middleware/    # Express middleware
│   │   ├── utils/         # Utility functions
│   │   └── types/         # TypeScript types
│   └── tests/             # Backend tests
│
├── docs/                  # Documentation
├── scripts/               # Build and deployment scripts
├── .github/               # GitHub Actions workflows
└── docker-compose.yml     # Local development services

Key Concepts

1. Authentication Flow

// User logs in
POST /api/auth/login
{ email, password }
  ↓
// Server validates credentials
// Generates JWT token
  ↓
// Client stores token
localStorage.setItem('token', token)
  ↓
// Client includes token in requests
Authorization: Bearer <token>
  ↓
// Server validates token
// Attaches user to request
req.user = decodedToken

Code location: server/src/middleware/auth.ts

2. State Management (Redux)

We use Redux Toolkit for client-side state:

// Store structure
{
  auth: {
    user: User | null,
    isAuthenticated: boolean,
    loading: boolean
  },
  cart: {
    items: CartItem[],
    total: number
  },
  products: {
    list: Product[],
    filters: FilterState,
    loading: boolean
  }
}

Reading from store:

import { useAppSelector } from '@/hooks/redux';

const user = useAppSelector(state => state.auth.user);
const cartItems = useAppSelector(state => state.cart.items);

Dispatching actions:

import { useAppDispatch } from '@/hooks/redux';
import { addToCart } from '@/store/slices/cartSlice';

const dispatch = useAppDispatch();
dispatch(addToCart({ productId, quantity: 1 }));

Code location: client/src/store/

3. API Communication

We use React Query for server state:

import { useQuery, useMutation } from '@tanstack/react-query';
import { api } from '@/api/client';

// Fetching data
const { data, isLoading, error } = useQuery({
  queryKey: ['products'],
  queryFn: () => api.products.getAll()
});

// Mutating data
const mutation = useMutation({
  mutationFn: (product) => api.products.create(product),
  onSuccess: () => {
    queryClient.invalidateQueries(['products']);
  }
});

Code location: client/src/api/

4. Database Access (Prisma)

We use Prisma ORM for database operations:

import { prisma } from '@/lib/prisma';

// Find one
const user = await prisma.user.findUnique({
  where: { id: userId }
});

// Find many with filters
const products = await prisma.product.findMany({
  where: {
    category: 'electronics',
    price: { lt: 1000 }
  },
  include: {
    images: true,
    reviews: true
  }
});

// Create
const order = await prisma.order.create({
  data: {
    userId,
    total: 100,
    items: {
      create: [
        { productId: 1, quantity: 2, price: 50 }
      ]
    }
  }
});

Code location: server/src/models/ Schema: prisma/schema.prisma

Your First Real Task

Goal: Add a "Recently Viewed" feature to product pages.

Requirements:

Track products a user views
Display last 5 viewed products
Persist across sessions (use localStorage)
Show on product detail page

Steps:

Create a feature branch:

git checkout -b feature/recently-viewed-products

Frontend: Add hook (client/src/hooks/useRecentlyViewed.ts):

export function useRecentlyViewed() {
  const addToRecentlyViewed = (product: Product) => {
    // Get existing
    const recent = JSON.parse(localStorage.getItem('recentlyViewed') || '[]');

    // Add new (avoid duplicates)
    const updated = [
      product,
      ...recent.filter((p: Product) => p.id !== product.id)
    ].slice(0, 5);

    // Save
    localStorage.setItem('recentlyViewed', JSON.stringify(updated));
  };

  const getRecentlyViewed = (): Product[] => {
    return JSON.parse(localStorage.getItem('recentlyViewed') || '[]');
  };

  return { addToRecentlyViewed, getRecentlyViewed };
}

Frontend: Use in product page (client/src/pages/ProductDetail.tsx):

const { addToRecentlyViewed, getRecentlyViewed } = useRecentlyViewed();

useEffect(() => {
  if (product) {
    addToRecentlyViewed(product);
  }
}, [product]);

const recentProducts = getRecentlyViewed();

Frontend: Display component (client/src/components/RecentlyViewed.tsx):

export function RecentlyViewed({ currentProductId }: Props) {
  const { getRecentlyViewed } = useRecentlyViewed();
  const products = getRecentlyViewed()
    .filter(p => p.id !== currentProductId);

  if (products.length === 0) return null;

  return (
    <section>
      <h2>Recently Viewed</h2>
      <ProductGrid products={products} />
    </section>
  );
}

Add tests:

describe('useRecentlyViewed', () => {
  it('should add product to recently viewed', () => {
    const { addToRecentlyViewed, getRecentlyViewed } = useRecentlyViewed();

    addToRecentlyViewed(mockProduct);

    expect(getRecentlyViewed()).toContainEqual(mockProduct);
  });

  it('should limit to 5 products', () => {
    // Add 6 products, check only 5 remain
  });

  it('should move duplicate to front', () => {
    // Add same product twice, check it appears once at front
  });
});

Test manually:
- View several products
- Check localStorage in DevTools
- Verify list appears on product pages
- Test edge cases (empty state, single item)
Create PR:
- Use PR template
- Add screenshots
- Request review from @frontend-team

Resources:

Week 1 Learning Resources

Must Read:

Optional Deep Dives:

End of Week 1

You should now:

✅ Understand overall architecture
✅ Know key technologies and tools
✅ Have completed your first feature
✅ Understand our development workflow
✅ Feel comfortable asking questions

Checkpoint Meeting: Schedule 30min with your manager to review progress.

Month 1: Making Impact

Month 1 Goals

Ship Features: Complete 3-5 features independently
Code Reviews: Provide meaningful feedback on 10+ PRs
Fix Bugs: Tackle 2-3 bug fixes
Improve Something: Find and fix a small pain point
Learn Domain: Understand e-commerce business basics

Suggested Feature Ideas

Beginner Friendly:

Add product sorting (price, rating, newest)
Implement wishlist functionality
Create order history page
Add email notifications

Intermediate:

Implement product reviews and ratings
Add search autocomplete
Create admin dashboard for orders
Optimize image loading performance

Advanced:

Implement shopping cart abandonment recovery
Add real-time inventory tracking
Create recommendation engine
Set up A/B testing framework

Finding Tasks: Check Jira board for issues labeled good-first-issue.

Code Review Best Practices

As an Author:

Keep PRs small (< 400 lines changed)
Write clear descriptions
Add screenshots for UI changes
Respond to feedback promptly
Test thoroughly before requesting review

As a Reviewer:

Review within 24 hours
Be kind and constructive
Ask questions rather than demand changes
Highlight good practices
Approve when ready (don't nitpick)

Review Checklist:

Code follows style guide
Tests included and passing
No console.logs in production code
Error handling implemented
Performance considerations addressed
Security best practices followed

Resources: Code Review Guide

Testing Guidelines

What to Test:

Business logic (always)
User interactions (important flows)
Edge cases and error states
API integrations (with mocks)

Testing Pyramid:

       /\
      /  \    E2E Tests (few)
     /────\
    /      \  Integration Tests (some)
   /────────\
  /          \ Unit Tests (many)
 /────────────\

Running Tests:

# All tests
npm test

# Watch mode
npm test -- --watch

# Coverage
npm test -- --coverage

# Specific file
npm test UserService.test.ts

Writing Tests:

describe('CartService', () => {
  describe('addToCart', () => {
    it('should add item to empty cart', () => {
      // Arrange
      const cart = new Cart();
      const item = { productId: 1, quantity: 2 };

      // Act
      cart.addItem(item);

      // Assert
      expect(cart.items).toHaveLength(1);
      expect(cart.items[0]).toEqual(item);
    });

    it('should increase quantity if item exists', () => {
      // Test implementation
    });

    it('should throw error if quantity is negative', () => {
      // Test implementation
    });
  });
});

Resources: Testing Guide

Deployment Process

Environments:

Development: Your local machine
Staging: https://staging.ecommerce.example.com
Production: https://ecommerce.example.com

Deployment Flow:

main branch
    │
    ▼
CI runs (tests, lint, build)
    │
    ▼
Auto-deploy to Staging
    │
    ▼
Manual QA testing
    │
    ▼
Create release tag
    │
    ▼
Deploy to Production (gradual rollout)

You can deploy: Staging (automatic on merge to main) You cannot deploy: Production (requires approval)

Monitoring:

Logs: DataDog dashboard
Errors: Sentry alerts
Metrics: Custom dashboards

Team & Processes

Team Structure

Engineering Team:

Engineering Manager: @alice (1:1s, career growth)
Tech Lead: @bob (architecture decisions, technical direction)
Frontend Team (4 engineers): @carol, @dave, @eve, @frank
Backend Team (5 engineers): @grace, @henry, @ivy, @jack, @kate
Full-Stack (3 engineers): @liam, @maya, @noah

Adjacent Teams:

Product: @olivia (product manager)
Design: @peter, @quinn (UI/UX designers)
QA: @rachel, @sam (test engineers)
DevOps: @taylor (infrastructure)

Communication Channels

Slack Channels:

#engineering - General engineering discussions
#frontend - Frontend-specific topics
#backend - Backend-specific topics
#deploys - Deployment notifications
#incidents - Production issues
#random - Non-work chat

When to use what:

Slack: Quick questions, discussions, FYIs
Jira: Task tracking, bug reports
GitHub: Code discussions, PR reviews
Email: External communication, formal notices
Zoom: Meetings, pair programming, deep discussions

Meetings

Weekly:

Team Standup (Mon/Wed/Fri, 10am, 15min)
- What you did
- What you're doing
- Any blockers
Sprint Planning (Monday, 1pm, 1hr)
- Plan next sprint
- Estimate stories
Retro (Friday, 2pm, 45min)
- What went well
- What could improve
- Action items

Bi-weekly:

1:1 with Manager (30min)
- Career growth
- Feedback
- Questions

Monthly:

All-Hands (First Friday, 3pm, 1hr)
- Company updates
- Team showcases

Meeting Norms:

Cameras on when possible
Mute when not speaking
Be on time
Come prepared
Take notes

Development Workflow

Git Workflow:

main (protected)
  ├─ feature/add-wishlist
  ├─ fix/cart-bug
  └─ refactor/payment-service

Branch Naming:

feature/description - New features
fix/description - Bug fixes
refactor/description - Code refactoring
docs/description - Documentation
test/description - Tests only

Commit Messages:

type(scope): description

feat(cart): add wishlist functionality
fix(auth): resolve token expiration issue
docs(readme): update setup instructions
test(orders): add integration tests
refactor(database): optimize queries

PR Process:

Create feature branch
Make changes
Write tests
Create PR (use template)
Request review (minimum 1 approval)
Address feedback
Merge (squash and merge)

On-Call Rotation

You won't be on-call for your first 3 months.

When you join rotation:

1 week on-call per month
Respond to PagerDuty alerts
Fix production issues
Escalate if needed

Resources: On-Call Runbook

Resources

Documentation

README - Project overview
Architecture - System design
API Docs - API reference
Contributing - How to contribute
Style Guide - Code conventions
Testing Guide - Testing practices
Deployment - Deployment process
Troubleshooting - Common issues

Learning Resources

JavaScript/TypeScript:

React:

Node.js:

Databases:

System Design:

Internal Tools

1Password: Shared credentials
Notion: Team wiki and docs
Figma: Design files
DataDog: Monitoring and logs
Sentry: Error tracking
GitHub: Code repository
Jira: Project management

Your Buddy

Your onboarding buddy is @buddy-name.

Your buddy will:

Answer day-to-day questions
Review your first few PRs
Introduce you to the team
Help you navigate processes
Meet with you weekly (first month)

Don't hesitate to ask them anything!

FAQ

Development

Q: How do I reset my local database?

npm run db:reset  # Drops all data and re-runs migrations
npm run db:seed   # Adds sample data

Q: Tests are failing locally but passing in CI. Why?

Check Node version matches (use nvm use)
Clear node_modules and reinstall
Check for environment-specific tests

Q: How do I debug the backend? Add debugger; statement and run:

node --inspect-brk server/src/index.ts

Then open Chrome DevTools.

Q: Where do I find API credentials for development? Check 1Password vault "Development Secrets" or ask in #engineering.

Code & Practices

Q: When should I create a new component vs. modify existing?

Create new: Reusable, self-contained functionality
Modify existing: Extending current component's capabilities
When in doubt, ask in PR review

Q: How much test coverage is expected?

Aim for 80% overall
100% for business-critical logic (payments, auth)
Focus on valuable tests, not just coverage numbers

Q: Can I refactor code I'm working on? Yes, but:

Keep refactoring in separate commits
Don't mix feature work with large refactors
For big refactors, create separate PR

Q: What if I disagree with PR feedback?

Discuss politely in PR comments
Explain your reasoning
Escalate to tech lead if needed
Remember: we're all learning

Process

Q: How do I report a production bug?

Post in #incidents with details
Create Jira ticket (type: Bug, priority: based on severity)
If urgent, ping on-call engineer

Q: Can I work on something not in Jira?

Small improvements: Yes, create ticket after
Large projects: Check with manager first
Tech debt: Discuss in sprint planning

Q: How do I request time off?

Add to team calendar
Message manager on Slack
Update Jira board if you have active work

Q: I'm stuck on a problem for hours. What should I do?

Try debugging and Googling (30 min)
Ask in #engineering (don't struggle alone)
Schedule pairing session with teammate
Escalate to tech lead if still stuck

Rule of thumb: Ask for help after 30 minutes of being stuck.

Career & Growth

Q: How is performance evaluated?

Quarterly reviews with manager
Based on: code quality, velocity, collaboration, growth
Transparent rubric provided

Q: How do I learn more about [specific topic]?

Ask in #engineering for recommendations
Check internal wiki for resources
Request Udemy/book budget from manager

Q: Can I switch teams/projects?

Discuss with manager after 6 months
Internal mobility encouraged

Welcome Aboard!

Remember:

Ask Questions: No question is too small
Take Breaks: Onboarding is exhausting
Be Patient: It takes 3+ months to feel productive
Have Fun: We're building something cool together!

Need help? Your buddy (@buddy-name) and manager (@manager-name) are here for you.

Welcome to the team! 🚀


## Usage Examples

@onboarding-helper @onboarding-helper --type full-guide @onboarding-helper --type quick-start @onboarding-helper --type architecture-overview @onboarding-helper --focus frontend @onboarding-helper --include-exercises


## Best Practices

### Make It Personal
- Address new team member by name
- Assign a buddy/mentor
- Include team photos and bios
- Share team culture and values

### Progressive Disclosure
- Day 1: Just get running
- Week 1: Understand basics
- Month 1: Ship features
- Month 3: Full productivity

### Make It Interactive
- Include hands-on exercises
- Provide starter tasks
- Encourage pair programming
- Set up regular check-ins

### Keep It Updated
- Review quarterly
- Get feedback from new hires
- Update for tech stack changes
- Improve based on common questions

### Make It Discoverable
- Central location (wiki, README)
- Easy to navigate
- Searchable
- Version controlled

## Notes

- Onboarding is an ongoing process, not a one-time event
- Great onboarding significantly reduces time-to-productivity
- Documentation should be discoverable and up-to-date
- Assign mentors/buddies for personal guidance
- Include both technical and cultural onboarding
- Celebrate early wins to build confidence
- Check in regularly during first 3 months
- Encourage questions and create safe learning environment
- Provide clear learning path with milestones
- Make resources easily accessible
- Update documentation based on new hire feedback