Skip to content

Commit 279bc72

Browse files
breadonceebreadoncee
committed
feat(skills): add cross-cutting skills
Add 5 cross-cutting skills: create-postmortem (blameless, Google SRE + 5 Whys), create-retro (with previous action item tracking), create-stakeholder-update (BLUF communication), create-runbook (copy-pasteable operational procedures), and create-onboarding-guide (day 1/week 1/month 1 structure).
1 parent a269350 commit 279bc72

5 files changed

Lines changed: 874 additions & 0 deletions

File tree

‎skills/create-onboarding-guide/SKILL.md‎

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
---
2+
name: create-onboarding-guide
3+
description: Create a developer onboarding guide when the user asks to write onboarding docs, create a getting started guide, document the setup process, or help new developers ramp up
4+
owner: chalk
5+
version: "1.0.0"
6+
metadata-version: "1"
7+
allowed-tools: Read, Glob, Grep, Bash, Write
8+
argument-hint: "[project name, team, or specific onboarding focus]"
9+
---
10+
11+
# Create Onboarding Guide
12+
13+
## Overview
14+
15+
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.
16+
17+
## Workflow
18+
19+
1. **Read all available documentation** — Scan the full `.chalk/docs/` directory tree:
20+
- `.chalk/docs/product/` for product profile, PRDs, user stories, and roadmap
21+
- `.chalk/docs/engineering/` for architecture docs, ADRs, runbooks, and incident history
22+
- `.chalk/docs/ai/` for analysis documents and research
23+
- Root `.chalk/docs/` for any overview or index documents
24+
Build a mental map of what documentation exists and what gaps remain.
25+
26+
2. **Inspect the codebase** — Use `Bash` and `Glob` to understand the project structure:
27+
- Package manager and dependency files (package.json, requirements.txt, go.mod, etc.)
28+
- Build and run scripts
29+
- Test framework and test file patterns
30+
- Environment configuration (.env.example, config files)
31+
- CI/CD configuration
32+
- Linting and formatting tools
33+
34+
3. **Parse the onboarding scope** — From `$ARGUMENTS`, identify:
35+
- Which project or team the guide is for
36+
- Whether the guide targets a specific role (frontend, backend, full-stack, etc.)
37+
- Any specific areas the user wants emphasized
38+
If not specified, create a general full-stack onboarding guide.
39+
40+
4. **Build the Day 1 section** — Environment setup and first commit:
41+
- Step-by-step setup instructions with copy-pasteable commands
42+
- How to run the application locally
43+
- How to run the test suite
44+
- A "hello world" first task: a small, safe change that exercises the full development workflow (edit, test, commit, PR)
45+
Verify setup steps against actual project files (package.json scripts, Makefile targets, etc.).
46+
47+
5. **Build the Week 1 section** — Architecture and first real contribution:
48+
- Curated reading list from existing docs, ordered from foundational to detailed
49+
- Simplified architecture overview (key services, data flow, external dependencies)
50+
- A starter task: a real but well-scoped issue that builds understanding
51+
- Key concepts the developer must understand to be effective
52+
- Common gotchas that trip up new team members (based on incident reports, ADRs, and codebase patterns)
53+
54+
6. **Build the Month 1 section** — Ownership and cross-cutting concerns:
55+
- Feature ownership expectations
56+
- Cross-cutting concerns: authentication, logging, error handling, deployment, monitoring
57+
- How to navigate the codebase for common tasks
58+
- Who to ask about what (mapped to teams or roles, not individuals)
59+
60+
7. **Create the reading list** — Order all `.chalk/docs/` files into a recommended reading sequence:
61+
- Start with product profile and architecture overview
62+
- Then PRDs and ADRs relevant to the developer's area
63+
- Then runbooks and operational docs
64+
- Mark which docs are "required reading" vs. "reference"
65+
66+
8. **Identify gaps** — Flag any onboarding needs that are not covered by existing documentation:
67+
- Missing setup instructions
68+
- Undocumented architecture decisions
69+
- Tribal knowledge that should be written down
70+
List these as "Documentation TODOs" at the end of the guide.
71+
72+
9. **Determine the next file number** — List files in `.chalk/docs/ai/` to find the highest numbered file. Increment by 1.
73+
74+
10. **Write the file** — Save to `.chalk/docs/ai/<n>_onboarding_guide.md`.
75+
76+
11. **Confirm** — Present the guide with a summary of what is covered, the recommended reading list, and any documentation gaps that need to be filled.
77+
78+
## Onboarding Guide Structure
79+
80+
```markdown
81+
# Developer Onboarding Guide
82+
83+
**Project**: <project name>
84+
**Last Updated**: <YYYY-MM-DD>
85+
**Target Audience**: <role or "all developers">
86+
87+
## Day 1: Setup and First Commit
88+
89+
### Environment Setup
90+
91+
Prerequisites:
92+
- <language runtime> (version <X.Y+>)
93+
- <package manager>
94+
- <database or other local services>
95+
- <any other tools>
96+
97+
Step-by-step:
98+
99+
1. **Clone the repository**
100+
```bash
101+
git clone <repo-url>
102+
cd <project-name>
103+
```
104+
105+
2. **Install dependencies**
106+
```bash
107+
<install command>
108+
```
109+
110+
3. **Configure environment**
111+
```bash
112+
cp .env.example .env
113+
# Edit .env with the following values:
114+
# <explain each required variable>
115+
```
116+
117+
4. **Start local services**
118+
```bash
119+
<command to start database, etc.>
120+
```
121+
122+
5. **Run the application**
123+
```bash
124+
<run command>
125+
```
126+
You should see: <expected output or URL>
127+
128+
6. **Run the test suite**
129+
```bash
130+
<test command>
131+
```
132+
Expected: All tests pass. If not, check <common fix>.
133+
134+
### Your First Commit
135+
136+
Complete this task to verify your setup and learn the workflow:
137+
138+
**Task**: <small, safe change — e.g., "Add your name to CONTRIBUTORS.md" or "Update a log message">
139+
140+
1. Create a branch: `git checkout -b onboarding/<your-name>`
141+
2. Make the change: <specific instructions>
142+
3. Run tests: `<test command>`
143+
4. Commit and push: `git commit -m "<message>"` && `git push`
144+
5. Open a PR following the team's PR template
145+
146+
This exercises: branching, local development, testing, and the PR process.
147+
148+
## Week 1: Architecture and First Contribution
149+
150+
### Recommended Reading (Ordered)
151+
152+
| Order | Document | Type | Required |
153+
|-------|----------|------|----------|
154+
| 1 | <product profile> | Product Context | Yes |
155+
| 2 | <architecture doc> | Technical | Yes |
156+
| 3 | <key ADR> | Decision Record | Yes |
157+
| 4 | <relevant PRD> | Product Requirements | Recommended |
158+
| 5 | <runbook> | Operations | Reference |
159+
160+
### Architecture Overview
161+
162+
<Simplified description of the system architecture: key services, how they communicate, data flow, external dependencies. Use a text diagram if helpful.>
163+
164+
```
165+
<simple ASCII architecture diagram>
166+
```
167+
168+
### Key Concepts
169+
170+
To be effective in this codebase, understand these concepts:
171+
172+
1. **<Concept>** — <what it is and why it matters in this project>
173+
2. **<Concept>** — <explanation>
174+
3. **<Concept>** — <explanation>
175+
176+
### Common Gotchas
177+
178+
Issues that trip up every new team member:
179+
180+
- **<Gotcha>** — <what happens and how to fix it>
181+
- **<Gotcha>** — <explanation>
182+
- **<Gotcha>** — <explanation>
183+
184+
### Starter Task
185+
186+
**Task**: <a real, well-scoped issue that a new developer can complete in 2-3 days>
187+
188+
Why this task: <what the developer will learn by completing it>
189+
190+
Resources:
191+
- Relevant code: `<file paths>`
192+
- Related doc: `<doc reference>`
193+
194+
## Month 1: Ownership and Cross-Cutting Concerns
195+
196+
### Cross-Cutting Concerns
197+
198+
| Concern | How It Works | Key Files | Documentation |
199+
|---------|-------------|-----------|---------------|
200+
| Authentication | <brief description> | <paths> | <doc link> |
201+
| Error Handling | <brief description> | <paths> | <doc link> |
202+
| Logging | <brief description> | <paths> | <doc link> |
203+
| Deployment | <brief description> | <paths> | <doc link> |
204+
| Monitoring | <brief description> | <paths> | <doc link> |
205+
206+
### Navigating the Codebase
207+
208+
Common tasks and where to find them:
209+
210+
| Task | Where to Look | Example |
211+
|------|---------------|---------|
212+
| Add a new API endpoint | `<path>` | `<example file>` |
213+
| Add a database migration | `<path>` | `<example file>` |
214+
| Add a new UI component | `<path>` | `<example file>` |
215+
| Add a test | `<path>` | `<example file>` |
216+
217+
### Who to Ask About What
218+
219+
| Area | Team/Role | Channel |
220+
|------|-----------|---------|
221+
| <area> | <team or role> | <how to reach them> |
222+
| <area> | <team or role> | <how to reach them> |
223+
224+
## Documentation Gaps
225+
226+
The following onboarding needs are not covered by existing documentation and should be written:
227+
228+
- [ ] <missing doc or knowledge area>
229+
- [ ] <missing doc or knowledge area>
230+
```
231+
232+
## Output
233+
234+
- **File**: `.chalk/docs/ai/<n>_onboarding_guide.md`
235+
- **Format**: Plain markdown, no YAML frontmatter
236+
- **First line**: `# Developer Onboarding Guide`
237+
238+
## Anti-patterns
239+
240+
- **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.
241+
- **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.
242+
- **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.
243+
- **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.
244+
- **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.
245+
- **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).
246+
- **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.

0 commit comments

Comments
 (0)