create-onboarding-guide

Create Onboarding Guide

Overview

Generate a structured developer onboarding guide by reading all available .chalk/docs/ documentation and curating it into a progressive learning path. The guide follows a Day 1 / Week 1 / Month 1 structure, starting with environment setup and a first commit, then expanding to architecture understanding and feature ownership. Every step is concrete and runnable — no "ask around" or tribal knowledge assumptions.

Workflow

Read all available documentation — Scan the full .chalk/docs/ directory tree:
- .chalk/docs/product/ for product profile, PRDs, user stories, and roadmap
- .chalk/docs/engineering/ for architecture docs, ADRs, runbooks, and incident history
- .chalk/docs/ai/ for analysis documents and research
- Root .chalk/docs/ for any overview or index documents Build a mental map of what documentation exists and what gaps remain.

Inspect the codebase — Use Bash and Glob to understand the project structure:
- Package manager and dependency files (package.json, requirements.txt, go.mod, etc.)
- Build and run scripts
- Test framework and test file patterns
- Environment configuration (.env.example, config files)
- CI/CD configuration
- Linting and formatting tools
Parse the onboarding scope — From $ARGUMENTS, identify:
- Which project or team the guide is for
- Whether the guide targets a specific role (frontend, backend, full-stack, etc.)
- Any specific areas the user wants emphasized If not specified, create a general full-stack onboarding guide.
Build the Day 1 section — Environment setup and first commit:
- Step-by-step setup instructions with copy-pasteable commands
- How to run the application locally
- How to run the test suite
- A "hello world" first task: a small, safe change that exercises the full development workflow (edit, test, commit, PR) Verify setup steps against actual project files (package.json scripts, Makefile targets, etc.).
Build the Week 1 section — Architecture and first real contribution:
- Curated reading list from existing docs, ordered from foundational to detailed
- Simplified architecture overview (key services, data flow, external dependencies)
- A starter task: a real but well-scoped issue that builds understanding
- Key concepts the developer must understand to be effective
- Common gotchas that trip up new team members (based on incident reports, ADRs, and codebase patterns)
Build the Month 1 section — Ownership and cross-cutting concerns:
- Feature ownership expectations
- Cross-cutting concerns: authentication, logging, error handling, deployment, monitoring
- How to navigate the codebase for common tasks
- Who to ask about what (mapped to teams or roles, not individuals)
Create the reading list — Order all .chalk/docs/ files into a recommended reading sequence:
- Start with product profile and architecture overview
- Then PRDs and ADRs relevant to the developer's area
- Then runbooks and operational docs
- Mark which docs are "required reading" vs. "reference"
Identify gaps — Flag any onboarding needs that are not covered by existing documentation:
- Missing setup instructions
- Undocumented architecture decisions
- Tribal knowledge that should be written down List these as "Documentation TODOs" at the end of the guide.
Determine the next file number — List files in .chalk/docs/ai/ to find the highest numbered file. Increment by 1.
Write the file — Save to .chalk/docs/ai/<n>_onboarding_guide.md.
Confirm — Present the guide with a summary of what is covered, the recommended reading list, and any documentation gaps that need to be filled.

Onboarding Guide Structure

# Developer Onboarding Guide

**Project**: <project name>
**Last Updated**: <YYYY-MM-DD>
**Target Audience**: <role or "all developers">

## Day 1: Setup and First Commit

### Environment Setup

Prerequisites:
- <language runtime> (version <X.Y+>)
- <package manager>
- <database or other local services>
- <any other tools>

Step-by-step:

1. **Clone the repository**
   ```bash
   git clone <repo-url>
   cd <project-name>

Install dependencies
```
<install command>
```

Configure environment

cp .env.example .env
# Edit .env with the following values:
# <explain each required variable>

Start local services
```
<command to start database, etc.>
```
Run the application
```
<run command>
```
You should see:
Run the test suite
```
<test command>
```
Expected: All tests pass. If not, check .

Your First Commit

Complete this task to verify your setup and learn the workflow:

Task: <small, safe change — e.g., "Add your name to CONTRIBUTORS.md" or "Update a log message">

Create a branch: git checkout -b onboarding/<your-name>
Make the change:
Run tests: <test command>
Commit: git add <files> && git commit -m "<message>"
Push: git push -u origin onboarding/<your-name>
Open a PR following the team's PR template

This exercises: branching, local development, testing, and the PR process.

Week 1: Architecture and First Contribution

Order	Type	Required
1	Product Context	Yes
2	Technical	Yes
3	Decision Record	Yes
4	Product Requirements	Recommended
5	Operations	Reference

Architecture Overview

<simple ASCII architecture diagram>

Key Concepts

To be effective in this codebase, understand these concepts:

Common Gotchas

Issues that trip up every new team member:

Starter Task

Task: <a real, well-scoped issue that a new developer can complete in 2-3 days>

Why this task:

Resources:

Relevant code: <file paths>
Related doc: <doc reference>

Month 1: Ownership and Cross-Cutting Concerns

Cross-Cutting Concerns

Concern	How It Works	Key Files	Documentation
Authentication
Error Handling
Logging
Deployment
Monitoring

Navigating the Codebase

Common tasks and where to find them:

Task	Where to Look	Example
Add a new API endpoint	`<path>`	`<example file>`
Add a database migration	`<path>`	`<example file>`
Add a new UI component	`<path>`	`<example file>`
Add a test	`<path>`	`<example file>`

Who to Ask About What

Area	Team/Role	Channel

Documentation Gaps

The following onboarding needs are not covered by existing documentation and should be written:


## Output

- **File**: `.chalk/docs/ai/<n>_onboarding_guide.md`
- **Format**: Plain markdown, no YAML frontmatter
- **First line**: `# Developer Onboarding Guide`

## Anti-patterns

- **Information dump without ordering** — Dropping 20 documents on a new developer and saying "read these" is not onboarding. Documents must be ordered from foundational to detailed, with required vs. reference clearly marked.
- **No runnable first task** — A developer who cannot run the app and make a change on Day 1 will lose confidence and momentum. The "hello world" task must be completable in under 2 hours with the setup instructions provided.
- **Assuming tribal knowledge** — "Ask Sarah about the auth system" is not documentation. If knowledge exists only in someone's head, the onboarding guide should flag it as a documentation gap, not encode the dependency on a specific person.
- **Outdated setup steps** — Setup instructions that fail on the first command destroy trust in the entire guide. Verify all commands against actual project files. Include version requirements and common failure modes.
- **No architecture context** — Jumping into code without understanding the system architecture leads to local optimizations and broken mental models. The Week 1 architecture overview provides the map before the developer starts navigating the territory.
- **Missing "who to ask"** — New developers need to know which team owns what. Map areas of responsibility to teams and roles, not individuals (people change roles; team responsibilities are more stable).
- **No documentation gap tracking** — If the onboarding guide cannot cover a topic because no documentation exists, that gap must be explicitly listed. Otherwise the gap persists invisibly and every new developer hits the same wall.

About this skill