codebase-onboarding

Codebase Onboarding

Analyze any codebase and generate production-quality onboarding documentation tailored to the audience. Produces architecture overviews with system diagrams, annotated key file maps, step-by-step local setup guides, common developer task runbooks, debugging guides with real error solutions, and contribution guidelines. Supports Markdown, Notion, and Confluence output formats.

Core Capabilities

• Architecture analysis — tech stack identification from manifests/lockfiles, system boundary mapping, Mermaid data-flow diagrams, dependency graphs, module ownership.
• Key file annotation — surface the 20 most important files and why they matter; mark entry points, config hubs, shared utilities, and files dangerous to modify without coordination.
• Setup guide generation — prerequisites with exact versions, git clone-to-tests steps, env-var docs, infra setup (Docker/DB/cache), and a verification checklist.
• Task runbooks — add an API endpoint, run/write tests, create & apply migrations, deploy to staging/production, add a dependency safely.
• Debugging guide — common errors with exact messages and fixes, log locations by environment, diagnostic SQL/CLI queries, local reproduction of production issues.
• Audience-aware output — tailored additions for junior developers, senior engineers, and contractors; Markdown / Notion / Confluence formats.

Keywords: codebase onboarding, developer experience, documentation, architecture overview, setup guide, debugging guide, contribution guidelines, code walkthrough, new hire onboarding

When to Use

• Onboarding a new team member (junior, senior, or contractor)
• After a major refactor that made existing docs stale
• Before open-sourcing a project
• Creating a team wiki page for a service you own
• Self-documenting before a long vacation or team transition
• Preparing for a compliance audit that requires documentation

Clarify First

Before generating the docs, confirm these inputs. If any is unknown or vague, ASK — do not assume:

• Target codebase path — which project to analyze (the input all three scripts scan)
• Audience — junior developer, senior engineer, or contractor (tailors which sections appear and at what depth)
• Output format — Markdown, Notion, or Confluence (sets the generated document format)

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

Tools

Tool	Purpose	Command
architecture_mapper.py	Analyze project structure and generate a high-level architecture map	python scripts/architecture_mapper.py /path/to/project --json
onboarding_generator.py	Scan a project directory and generate an onboarding guide	python scripts/onboarding_generator.py /path/to/project --json
setup_validator.py	Validate a project's development setup completeness	python scripts/setup_validator.py /path/to/project --json

All tools accept an optional directory argument (default: current directory) and --json for machine-readable output.

References

Load the reference that matches the task — keep this file lean and pull detail on demand:

• references/fact-gathering-and-patterns.md — the Phase 1 fact-gathering shell commands and the Phase 2 architecture-pattern classification table. Read when analyzing a codebase before writing docs.
• references/documentation-templates.md — the architecture overview, key file map, local setup, and debugging guide templates plus audience-specific (junior/senior/contractor) additions. Read when generating the actual onboarding documents.
• references/quality-and-best-practices.md — quality verification checklist, common pitfalls, best practices, a troubleshooting matrix, and success criteria. Read before shipping onboarding docs.

Scope & Limitations

This skill covers:

• Generating architecture overviews, key file maps, setup guides, task runbooks, and debugging guides from codebase analysis
• Audience-aware documentation tailored for junior developers, senior engineers, and contractors
• Output in Markdown, Notion, and Confluence formats
• Quality verification checklists and freshness audit processes

This skill does NOT cover:

• Automated API reference generation from code annotations — see engineering/changelog-generator for release-oriented docs or engineering/api-design-reviewer for API quality
• Continuous documentation pipelines or CI-triggered doc builds — see engineering/ci-cd-pipeline-builder for pipeline automation
• Security-focused documentation such as threat models or access control matrices — see engineering/skill-security-auditor for security auditing
• Runbook generation for incident response and production operations — see engineering/runbook-generator for operational runbooks

Integration Points

Skill	Integration	Data Flow
engineering/runbook-generator	Onboarding task runbooks can seed operational runbooks for production incident response	Onboarding runbook templates → Runbook Generator for ops-grade expansion
engineering/api-design-reviewer	API route analysis from Phase 1 feeds into API design quality reviews	Discovered API endpoints → API Design Reviewer for consistency checks
engineering/database-schema-designer	Database schema files identified during key file mapping inform schema design reviews	Schema file paths and ORM type → Schema Designer for migration planning
engineering/tech-debt-tracker	Technical debt items surfaced during architecture analysis should be logged for tracking	Architecture analysis findings → Tech Debt Tracker backlog entries
engineering/ci-cd-pipeline-builder	CI/CD config discovered in Phase 1 can be validated and improved by the pipeline builder	CI config paths and workflow list → Pipeline Builder for optimization
engineering/dependency-auditor	Dependency counts and lockfiles gathered in Phase 1 feed directly into security and license audits	Package manifests and lockfiles → Dependency Auditor for vulnerability scanning