DevEx.md - Context as Infrastructure

# DevEx.md - Developer Experience Guide
<!-- Onboarding, productivity, debugging workflows, team conventions -->
<!-- Everything a developer needs to be effective from day one -->
<!-- Last updated: YYYY-MM-DD -->

## Onboarding Checklist

### Before Day 1 (Manager/IT Handles)
- [ ] GitHub organization access granted with correct team membership
- [ ] Slack workspace invitation sent - join #engineering, #team-[your-team], #deploys, #incidents
- [ ] Email and calendar access configured
- [ ] 1Password vault access for development secrets
- [ ] Hardware ordered and shipped (if remote)
- [ ] Welcome doc sent with links to this guide and team wiki

### Day 1: Access and Environment
- [ ] Complete the development environment setup (see `codev.md`)
- [ ] Clone the main repository and run the application locally
- [ ] Run the full test suite - all tests should pass on a clean setup
- [ ] Get added to the on-call rotation calendar (shadow only for first 4 weeks)
- [ ] Schedule 30-minute 1-on-1 with your team lead
- [ ] Schedule 15-minute intro chats with each team member (your lead will suggest who)
- [ ] Read the project README, architecture docs, and recent ADRs in `/docs`

### Week 1: Learn by Reading
- [ ] Review the last 10 merged PRs to understand the team's review process and code style
- [ ] Read the coding standards document (`coding.md`) front to back
- [ ] Shadow a team member during their on-call shift or incident response
- [ ] Attend your first standup, sprint planning, and retro
- [ ] Explore the monitoring dashboards (Datadog/Grafana) to understand system health
- [ ] Deploy your first change to staging (even if it is a typo fix)
- [ ] Submit your first PR and get it reviewed and merged

### Weeks 2-4: Build Confidence
- [ ] Pick up a small bug fix or improvement ticket from the backlog
- [ ] Pair program with a senior engineer on a medium-complexity feature
- [ ] Write your first integration or E2E test
- [ ] Give feedback on the onboarding process - what was confusing or missing?
- [ ] Update one documentation page with something you learned the hard way
- [ ] Participate in at least one code review as a reviewer (ask questions freely)

### Month 2+: Full Contributor
- [ ] Own a feature from design through deployment
- [ ] Participate in on-call rotation (initially with a shadow/backup)
- [ ] Contribute to architecture discussions and ADRs
- [ ] Mentor the next new hire using the improved onboarding process

## IDE Setup and Productivity

### VS Code Power User Shortcuts

#### Navigation
```
Ctrl+P              Quick file open (fuzzy search by filename)
Ctrl+Shift+O        Go to symbol in current file
Ctrl+T              Go to symbol across entire workspace
F12                 Go to definition
Alt+F12             Peek definition (inline preview)
Ctrl+Shift+F        Search across all files
Ctrl+G              Go to line number
Alt+Left/Right      Navigate back/forward in cursor history
```

#### Editing
```
Ctrl+D              Select next occurrence of current selection
Ctrl+Shift+L        Select ALL occurrences of current selection
Alt+Up/Down         Move current line up/down
Shift+Alt+Up/Down   Duplicate current line up/down
Ctrl+Shift+K        Delete entire line
Ctrl+/              Toggle line comment
Shift+Alt+A         Toggle block comment
F2                  Rename symbol across all files
Ctrl+.              Quick fix / code action menu
```

#### Terminal and Panels
```
Ctrl+`              Toggle integrated terminal
Ctrl+Shift+`        Create new terminal
Ctrl+B              Toggle sidebar visibility
Ctrl+J              Toggle bottom panel
Ctrl+\              Split editor vertically
```

### Shell Aliases and Shortcuts

Add these to your `.bashrc`, `.zshrc`, or PowerShell profile to speed up daily workflows:

```bash
# Git shortcuts
alias gs='git status'
alias gd='git diff'
alias gds='git diff --staged'
alias gc='git commit -m'
alias gca='git commit --amend --no-edit'
alias gp='git push'
alias gpl='git pull --rebase'
alias gl='git log --oneline --graph -20'
alias gb='git branch --sort=-committerdate | head -10'
alias gco='git checkout'
alias gcb='git checkout -b'

# Project shortcuts
alias dev='pnpm dev'
alias test='pnpm test'
alias lint='pnpm lint'
alias build='pnpm build'
alias studio='pnpm db:studio'

# Docker shortcuts
alias dcu='docker compose up -d'
alias dcd='docker compose down'
alias dcl='docker compose logs -f'
alias dcp='docker compose ps'

# Quick navigation
alias proj='cd ~/projects/atlas'
alias docs='cd ~/projects/atlas/docs'
```

### Development Workflow: Fast Feedback Loop

The most productive development setup uses 3 terminal panes:

```
+----------------------------------+------------------+
|                                  |                  |
|  Terminal 1: Dev Server          |  Terminal 2:     |
|  $ pnpm dev                     |  Test Watcher    |
|                                  |  $ pnpm test     |
|  (auto-reloads on file save)     |  --watch         |
|                                  |                  |
+----------------------------------+------------------+
|                                                     |
|  Terminal 3: Ad-hoc commands                        |
|  $ git status / pnpm lint / psql / etc.             |
|                                                     |
+-----------------------------------------------------+
```

**The cycle**: Save file -> Dev server hot-reloads -> Check browser -> Tests auto-run -> Fix failures -> Repeat.

## Debugging Workflows

### Frontend Debugging

**React DevTools** (Browser Extension):
- Components tab: Inspect component tree, props, state, and hooks
- Profiler tab: Record renders to find unnecessary re-renders
- Highlight updates: Enable "Highlight updates" to see what re-renders on state change

**Network Tab Debugging**:
```
1. Open Chrome DevTools (F12)
2. Go to Network tab
3. Filter by "Fetch/XHR" to see API calls
4. Click a request to see:
   - Request headers and body
   - Response status and body
   - Timing breakdown
5. Right-click a request -> "Copy as cURL" to reproduce in terminal
```

**Console Debugging** (when breakpoints are overkill):
```typescript
// Structured logging for complex objects
console.table(users);                    // Tabular display of arrays/objects
console.group('Order Processing');       // Collapsible log group
console.log('Subtotal:', subtotal);
console.log('Tax:', tax);
console.groupEnd();
console.dir(complexObject, { depth: 4 }); // Deep object inspection
```

### Backend Debugging

**VS Code Debugger** (preferred method):
1. Set breakpoints by clicking the gutter (left of line numbers)
2. Press F5 or select "Next.js: Server" from the debug dropdown
3. Trigger the code path (make an API call, load a page)
4. Use the debug panel: Step Over (F10), Step Into (F11), Continue (F5)
5. Inspect variables in the Variables panel, add expressions to Watch

**Database Query Debugging**:
```bash
# Enable Prisma query logging
# In .env:
DEBUG="prisma:query"

# Or inspect queries directly:
psql postgresql://atlas:atlas_dev_password@localhost:5432/atlas_dev

# Find slow queries:
SELECT query, calls, mean_time, total_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;
```

### "It Works on My Machine" Checklist

When something works locally but fails for someone else (or in CI):

1. **Compare Node versions**: `node --version` (must match `.nvmrc`)
2. **Compare branch state**: `git branch`, `git log -3`, `git status`
3. **Check environment variables**: diff `.env` files (redact secrets)
4. **Check dependencies**: `pnpm list --depth=0` (compare package versions)
5. **Check Docker services**: `docker compose ps` (are all services healthy?)
6. **Try a clean install**: `rm -rf node_modules && pnpm install`
7. **Try a fresh database**: `pnpm db:reset`
8. **Check disk space**: `df -h` (Docker can fill up disks)

## Common Gotchas

### 1. Hot Reload Not Working
**Symptom**: You save a file but the browser does not update.
**Fix**:
```bash
# Check if the dev server is actually running
# If you see "EADDRINUSE", another process has the port
# Kill it and restart:
kill -9 $(lsof -t -i :3000)
pnpm dev
```

### 2. Prisma Client Out of Sync
**Symptom**: TypeScript shows errors on Prisma model types that you know exist.
**Fix**:
```bash
pnpm prisma generate
# Then restart the TS server in VS Code:
# Ctrl+Shift+P -> "TypeScript: Restart TS Server"
```

### 3. Stale Docker Data
**Symptom**: Database has old data, tests fail with constraint violations.
**Fix**:
```bash
docker compose down -v    # -v removes volumes (all data)
docker compose up -d
pnpm db:migrate
pnpm db:seed
```

### 4. ESLint/Prettier Conflicts
**Symptom**: ESLint and Prettier fight over formatting, file keeps changing on save.
**Fix**: Ensure `prettier` is the last item in the ESLint `extends` array. Check that VS Code is using the project's Prettier config, not a global one.

### 5. Import Path Errors After Moving Files
**Symptom**: `Cannot find module '@/components/OldPath'` after renaming/moving a file.
**Fix**:
```bash
# Use VS Code's rename symbol (F2) to move files - it updates imports automatically
# Or search for the old import path:
grep -r "OldPath" src/
# And update all references
```

### 6. Tests Flaky in CI
**Symptom**: Tests pass locally but intermittently fail in GitHub Actions.
**Common causes**:
- Timing-dependent assertions (use `waitFor` instead of fixed delays)
- Tests depending on execution order (each test should set up its own data)
- Port conflicts with parallel test runs

## Team Communication

### Daily Standup
- **When**: 10:00 AM local time (async in #standup for remote team members)
- **Format**: What I did yesterday / What I am doing today / Any blockers
- **Rule**: Keep it under 2 minutes. Deep dives go to separate threads.

### Code Review Expectations
- **Response time**: Respond to review requests within 4 business hours
- **Tone**: Be kind, be specific, explain why (not just what)
- **Prefixes**: Use `nit:`, `suggestion:`, `concern:`, `blocker:`, `praise:`
- **Approval**: If only nits remain, approve the PR with your nits noted

### When to Escalate
- **Blocked for 2+ hours**: Post in #engineering with context
- **Production issue**: Post in #incidents, page on-call if user-facing
- **Architecture question**: Open a discussion in #architecture or schedule a 30-min sync
- **Sensitive topic**: DM your team lead directly

### Meeting Culture
- Default to async (Slack thread or doc comment) unless real-time discussion is faster
- All meetings have an agenda shared at least 1 hour before
- Meeting notes posted in the relevant Slack channel within 1 hour of meeting end
- "No meeting Wednesdays" - protect focus time

## Useful Scripts and Automations

### Pre-commit Hook (Runs Automatically via Husky)
```bash
# The project has a pre-commit hook that runs:
# 1. ESLint on staged files (via lint-staged)
# 2. Prettier on staged files
# 3. TypeScript type-check
# If any check fails, the commit is blocked with an error message
```

### Database Snapshot/Restore
```bash
# Save current database state (useful before testing migrations)
pg_dump -h localhost -U atlas atlas_dev > db_snapshot.sql

# Restore from snapshot
psql -h localhost -U atlas atlas_dev < db_snapshot.sql
```

### Quick Performance Check
```bash
# Measure build time
time pnpm build

# Measure test suite time
time pnpm test

# Check bundle size
pnpm build && ls -lh .next/static/chunks/*.js | sort -k5 -h
```

## Key Contacts

- **Team Lead**: [Name] - @[slack-handle] - architecture questions, priority decisions
- **DevOps/Platform**: [Name] - @[slack-handle] - CI/CD, infrastructure, deployment issues
- **Product Manager**: [Name] - @[slack-handle] - requirements, user stories, prioritization
- **Design Lead**: [Name] - @[slack-handle] - UX questions, design specs, accessibility
- **On-Call Rotation**: Check #incidents channel topic for current on-call engineer

## Learning Resources

### Internal
- **Architecture Decision Records**: `/docs/adrs/` in the repository
- **Team Wiki**: [Link to Notion/Confluence]
- **Recorded Tech Talks**: [Link to video library]
- **Pair Programming**: Ask anyone on the team - we all do it regularly

### External
- **Company Learning Budget**: $[amount]/year for conferences, courses, books
- **O'Reilly Safari**: Free access through company subscription
- **Conference Speaking**: Company covers travel + registration if you submit a talk