ComputerConnection/skills/onboard

Onboarding Guide Generator: $ARGUMENTS

Create the guide you wish you had on day one.

---

Scope: Internal Team Onboarding

This skill produces documentation for new team members:

• Developers joining your team
• Internal conventions and workflows
• Tribal knowledge and gotchas
• "Who to ask" for what

For external/public documentation (users, API consumers, contributors), use /docs instead.

| Use /onboard for | Use /docs for | |------------------|---------------| | ONBOARDING.md | README.md | | Team workflows | Public contribution guide | | Internal gotchas | API reference | | "Who to ask" | Public setup instructions | | Role-specific paths | General usage docs |

---

Role-Based Onboarding

If --role is specified, customize the guide:

Frontend Developer Path

Focus areas:

• Component architecture and patterns
• State management approach
• Styling conventions
• Build and dev server setup
• Browser testing workflow

Key files to highlight:

find . -name "*.tsx" -o -name "*.css" -o -name "*.scss" | head -20
grep -r "useState\|useEffect\|createContext" --include="*.tsx" -l | head -10

Backend Developer Path

Focus areas:

• API structure and routing
• Database setup and migrations
• Authentication/authorization
• Testing strategy
• Deployment process

Key files to highlight:

find . -name "routes*" -o -name "controller*" -o -name "service*" | head -20
grep -r "router\|app\.get\|app\.post" --include="*.ts" -l | head -10

Fullstack Developer Path

Include both paths above, plus:

• How frontend and backend communicate
• Shared types/contracts
• End-to-end testing
• Local development with both running

---

Philosophy

• Assume nothing - New devs don't know your conventions
• Explain the why - Context prevents future mistakes
• Show the path - From setup to first commit
• Reveal the gotchas - What bit you, will bite them
• Keep it current - Outdated onboarding is cruel

---

Phase 1: Project Discovery

Project Snapshot

# Project basics
tree -L 2 -I 'node_modules|__pycache__|.git|dist|build|.venv' .

# Tech stack
cat package.json 2>/dev/null | head -30
cat Cargo.toml 2>/dev/null | head -30
cat requirements.txt 2>/dev/null

# Recent activity
git log --oneline -20
git shortlog -sn --since="6 months ago" | head -10

Project Profile

┌─────────────────────────────────────────────────────────────┐
│  PROJECT: [Name]                                            │
├─────────────────────────────────────────────────────────────┤
│  What it does: [one sentence]                               │
│  Tech stack: [languages/frameworks]                         │
│  Repo age: [X months/years]                                 │
│  Active contributors: [count]                               │
│  Size: [~lines of code]                                     │
│  Complexity: [Low/Medium/High]                              │
└─────────────────────────────────────────────────────────────┘

---

Phase 2: Generate Onboarding Doc

ONBOARDING.md Structure

# Onboarding Guide: [Project Name]

> Welcome! This guide will get you productive in [project] as fast as possible.

## What This Project Does

[2-3 paragraphs explaining:]
- What problem does this solve?
- Who uses it?
- Why does it exist?

## The 10-Minute Setup

### Prerequisites

Before you start, make sure you have:

- [ ] [Tool 1] version X+ (`tool --version` to check)
- [ ] [Tool 2] version X+
- [ ] Access to [service/resource]
- [ ] [Account/credentials] from [person/place]

### Step-by-Step Setup

\`\`\`bash
# 1. Clone and enter
git clone [repo-url]
cd [project-name]

# 2. Install dependencies
[install command]

# 3. Set up environment
cp .env.example .env
# Edit .env with values from [source]

# 4. Initialize database (if applicable)
[db setup command]

# 5. Verify it works
[test/run command]
\`\`\`

### "It's Not Working" Troubleshooting

**Problem**: [Common issue 1]
**Solution**: [How to fix]

**Problem**: [Common issue 2]
**Solution**: [How to fix]

---

## Understanding the Codebase

### Project Structure

\`\`\`
[project]/
├── src/                 # [What's in here]
│   ├── components/      # [What's in here]
│   ├── services/        # [What's in here]
│   └── utils/           # [What's in here]
├── tests/               # [What's in here]
├── config/              # [What's in here]
└── docs/                # [What's in here]
\`\`\`

### Key Files to Know

| File | Purpose | When You'll Touch It |
|------|---------|---------------------|
| `src/main.ts` | Application entry point | Rarely |
| `src/config.ts` | All configuration | When adding config |
| `src/routes/` | API endpoints | Adding new APIs |
| `.env` | Local secrets | Setup only |

### Architecture Overview

[Diagram showing main components and how they connect]

\`\`\`
┌─────────┐     ┌─────────┐     ┌─────────┐
│ Frontend│────►│   API   │────►│Database │
└─────────┘     └─────────┘     └─────────┘
\`\`\`

[Brief explanation of data flow]

---

## How We Work

### Development Workflow

\`\`\`
1. Create branch from main: git checkout -b feat/your-feature
2. Make changes
3. Run tests: [test command]
4. Commit with conventional commits: git commit -m "feat: add thing"
5. Push and create PR: gh pr create
6. Get review, address feedback
7. Merge after approval
\`\`\`

### Branch Naming

- `feat/description` - New features
- `fix/description` - Bug fixes
- `refactor/description` - Code refactoring
- `docs/description` - Documentation

### Commit Messages

We use [conventional commits / your format]:

\`\`\`
feat: add user authentication
fix: resolve null pointer in checkout
docs: update API documentation
refactor: simplify order processing
\`\`\`

### Code Style

- [Linter]: Run `[lint command]` before committing
- [Formatter]: Run `[format command]` or use editor integration
- [Style guide]: See [link to style guide if exists]

### Testing

\`\`\`bash
# Run all tests
[test command]

# Run specific test
[specific test command]

# Run with coverage
[coverage command]
\`\`\`

**Testing expectations:**
- All new features need tests
- Bug fixes need regression tests
- Aim for [X]% coverage on new code

---

## Key Concepts

### Domain Terminology

| Term | Meaning |
|------|---------|
| [Term 1] | [Definition in our context] |
| [Term 2] | [Definition in our context] |
| [Term 3] | [Definition in our context] |

### Important Patterns

**[Pattern 1]**: We use [pattern] because [reason]. You'll see this in [locations].

**[Pattern 2]**: We use [pattern] because [reason]. You'll see this in [locations].

### External Dependencies

| Service | Purpose | Docs | Local Alternative |
|---------|---------|------|-------------------|
| [Service 1] | [What it does] | [link] | [how to mock/stub] |
| [Service 2] | [What it does] | [link] | [how to mock/stub] |

---

## Common Tasks

### Adding a New [Feature Type]

1. Create [file] in [location]
2. Register in [config file]
3. Add tests in [test location]
4. Update [docs if needed]

Example: [link to example PR]

### Adding a New [API Endpoint]

1. Define route in [file]
2. Add controller in [file]
3. Add service logic in [file]
4. Write tests in [file]

Example: [link to example PR]

### Debugging Tips

- **Logs**: Check `[log location]` or run `[log command]`
- **Database**: Use `[db inspect command]` to check data
- **API**: Use `[api tool]` to test endpoints
- **Frontend**: React DevTools, Network tab

---

## Gotchas and Tribal Knowledge

### Things That Will Bite You

1. **[Gotcha 1]**: [What happens and how to avoid]
2. **[Gotcha 2]**: [What happens and how to avoid]
3. **[Gotcha 3]**: [What happens and how to avoid]

### "Why Is It Like This?"

**Q: Why do we [weird pattern]?**
A: Because [historical reason / technical constraint]

**Q: Why don't we just [obvious solution]?**
A: We tried it, but [reason it didn't work]

### Known Issues / Tech Debt

- [ ] [Issue 1] - [workaround]
- [ ] [Issue 2] - [workaround]

---

## Getting Help

### Who To Ask

| Topic | Person | Slack/Contact |
|-------|--------|---------------|
| [Area 1] | [Name] | @handle |
| [Area 2] | [Name] | @handle |
| General | [Name] | @handle |

### Resources

- **Internal docs**: [link]
- **Slack channel**: #[channel]
- **Confluence/Wiki**: [link]
- **Runbooks**: [link]

### Your First Week Checklist

- [ ] Complete this setup guide
- [ ] Join Slack channels: #[channel1], #[channel2]
- [ ] Get access to [services]
- [ ] Schedule intro with [person]
- [ ] Read [important doc]
- [ ] Pick up a "good first issue"
- [ ] Make your first commit!

---

*Last updated: [date]*
*Maintainer: [person]*

---

Phase 3: Extract Project-Specific Content

Identify Key Concepts

# Find domain terminology
grep -r "interface\|type\|class" --include="*.ts" src/ | head -20

# Find main entry points
find . -name "main.*" -o -name "index.*" -o -name "app.*" | head -10

# Find configuration
find . -name "config*" -o -name ".env*" -o -name "settings*" | head -10

# Find patterns/conventions
grep -r "service\|controller\|repository\|handler" --include="*.ts" -l src/

Identify Gotchas

Look for:

• TODO/FIXME/HACK comments
• Complex conditionals
• Workarounds
• Legacy code
• Known issues in git history

# Find gotcha hints
grep -rn "TODO\|FIXME\|HACK\|XXX\|WORKAROUND" --include="*.ts" --include="*.js" src/

---

Phase 4: Interview Questions

If information is missing, ask Zach:

┌─────────────────────────────────────────────────────────────┐
│  ONBOARDING INFO NEEDED                                     │
├─────────────────────────────────────────────────────────────┤
│  For complete onboarding docs, I need to know:              │
│                                                             │
│  Setup:                                                     │
│  • What prerequisites should new devs have?                 │
│  • Any special access/credentials needed?                   │
│  • Common setup issues people hit?                          │
│                                                             │
│  Workflow:                                                  │
│  • What's the PR/review process?                            │
│  • Branch naming convention?                                │
│  • Commit message format?                                   │
│                                                             │
│  Culture:                                                   │
│  • Who should new people talk to?                           │
│  • What Slack channels matter?                              │
│  • What gotchas have bitten people?                         │
│                                                             │
│  Context:                                                   │
│  • What business problem does this solve?                   │
│  • Who are the users?                                       │
│  • What's the history?                                      │
└─────────────────────────────────────────────────────────────┘

---

Phase 5: Output

Deliverables

1. ONBOARDING.md - Complete onboarding guide
2. GLOSSARY.md (optional) - Domain terms
3. ARCHITECTURE.md (if missing) - System overview
4. Update README.md - Link to onboarding guide

Quality Checklist

• [ ] Can someone go from zero to running in <30 minutes?
• [ ] Are prerequisites clearly listed?
• [ ] Are common issues addressed?
• [ ] Is the architecture understandable?
• [ ] Are the gotchas documented?
• [ ] Is it clear who to ask for help?
• [ ] Is there a "first week" checklist?

---

Mentorship & Support Structure

Buddy System Recommendation

## Your Onboarding Buddy

You've been paired with: **[Name]** (@slack-handle)

Your buddy will:
- Answer "dumb questions" (there are none)
- Review your first few PRs with extra context
- Have a 15-min daily sync your first week
- Be your go-to for "how do we do X here?"

Don't hesitate to ping them!

Escalation Path

## When You're Stuck

1. **Try for 15 minutes** - Google, docs, code search
2. **Ask your buddy** - They're here to help
3. **Post in #[dev-channel]** - Team knowledge
4. **Grab someone senior** - For architectural questions

Rule: Never stay stuck for more than 30 minutes without asking.

---

Anti-Patterns

• "Just ask someone" (not documented)
• Assuming prior knowledge
• Out-of-date setup instructions
• Missing the "why"
• No troubleshooting section
• Forgetting about access/credentials
• Not explaining tribal knowledge
• No clear escalation path for stuck developers
• Treating onboarding as a one-time event (should be iterative)

---

Output

1. Project analysis summary
2. Complete ONBOARDING.md
3. Identified gotchas and tribal knowledge
4. List of questions for Zach (if needed)
5. Quality checklist status