Codebase Onboarding

For a 200-model Laravel app, structured bottom-up analysis is the approach — don't try to document everything at once.

Phase 1: Auto-generate structural map (day 1)

# Extract structure using Artisan
php artisan route:list --json > docs/routes.json
php artisan model:show --json > docs/models.json  # Laravel 9+

# Group models by domain
ls app/Models/ | sort

The analysis produces a domain map:

# Inferred Domain Map

## Users & Auth (7 models)
User, Profile, Role, Permission, Session, ApiToken, PasswordReset

## Orders & Billing (12 models)
Order, OrderItem, Invoice, Payment, Subscription, Plan...

## Fulfillment (6 models)
Shipment, Address, Warehouse, Carrier, TrackingEvent, Label

## [174 remaining models...]

Phase 2: Generate per-domain README stubs (week 1) For each domain, generate a stub the team fills in:

# Billing Domain — STUB
**Models:** Invoice, Payment, Subscription, Plan, Coupon
**Entry points:** POST /api/invoices, GET /api/subscriptions/:id, webhook: stripe.invoice.paid
**TODO:** [document business rules, edge cases, known quirks]

Phase 3: Interview the acquired team Use the auto-generated map as the interview guide — 30 min per domain with the former engineers. Ask them to correct wrong inferences and explain the non-obvious decisions. This gets you from zero to 60% accurate docs in one week.

The onboarding skill flags patterns that imply an undocumented decision — then you write the why.

Step 1: Detect non-obvious patterns

Things the analysis flags as 'unexplained decision':

• Custom middleware that duplicates a framework feature
• axios AND node-fetch both in package.json (why two HTTP clients?)
• Auth handled in two places
• Feature flags implemented three different ways
• An unused dependency that looks like it was replaced but never removed

Step 2: Generate ADR stubs

# ADR-003: Custom JWT middleware instead of Passport.js
**Date:** found via `git log --follow src/middleware/auth.js | tail -1`
**Status:** Accepted
**Context:** TODO — interview original author
**Decision:** Custom validateToken() in middleware/auth.js
**Detected signal:** passport-jwt is in package.json but unused;
  custom validateToken() is called in 47 route files.
**Consequences:** TODO

Step 3: Use git log to anchor each decision

# Find when the custom auth was introduced
git log --oneline --follow src/middleware/auth.js | tail -3
# Then read that commit for context
git show abc1234

Target ADR directory:

docs/adr/
  0001-postgresql-over-mongodb.md
  0002-monorepo-not-separate-repos.md
  0003-custom-auth-middleware.md

The skill generates stubs with detected signals pre-filled. You supply the why from Slack archaeology and team interviews — a 1-hour process per ADR rather than starting from blank.