Create a new documentation file in .chalk/docs/.
Workflow
- Parse the request — Identify the target vertical and topic from
$ARGUMENTS. - Check existing docs — Read filenames in the target directory to find the highest numbered file. The next doc number is
highest + 1. - Draft the doc — Write substantive content, not stubs. Use the structure and tone guidelines below.
- Write the file — Save to
.chalk/docs/<vertical>/<number>_<slug>.md. - Confirm — Tell the user the doc was created with its path and a brief summary.
Verticals
| Vertical | Directory | Use For |
|---|---|---|
| Product | product/ | Vision, strategy, user research, pricing, competitive analysis |
| AI | ai/ | Agent context, codebase orientation, prompt patterns, gotchas |
| Engineering | engineering/ | Architecture, conventions, APIs, runbooks, data flows |
| Root | .chalk/docs/ | Docs that don't fit a vertical |
If the user specifies a vertical ("engineering doc about..."), use it. If ambiguous, infer from content: technical architecture -> engineering, product strategy -> product, agent context -> ai.
Filename Convention
<number>_<snake_case_slug>.md
- Number is sequential within the vertical directory (profile docs are always
0_) - Slug is a short snake_case summary
Doc File Structure
# <Doc Title>
Last updated: <YYYY-MM-DD> (<brief change note>)
## <First Section>
Content...
## <Next Section>
Content...
- No YAML frontmatter (docs are plain markdown)
- First
# Headingis the title - "Last updated" line immediately after the title
- Use
## Headingfor sections - All GFM features supported: tables, checkboxes, strikethrough, code blocks, Mermaid diagrams
Content Guidelines
| Vertical | Tone | Focus |
|---|---|---|
product/ | Business-facing, concise | What and why: user problems, strategy, metrics |
ai/ | Agent-facing, reference-style | Where things are, how they work, gotchas |
engineering/ | Technical, comprehensive | Architecture, conventions, APIs, data flows |