---
name: create-doc
description: "Create project documentation following PostPilot's documentation conventions. Use when: creating new docs, writing feature docs, adding README files, documenting a subsystem. Actions: create doc, write doc, document, add doc."
---

# Create Documentation

You are creating documentation for the PostPilot project. Always follow the conventions defined in [docs/DOCUMENT_CONVENTION.md](docs/DOCUMENT_CONVENTION.md).

## Core Conventions (Summary)

### Progressive Disclosure
- Overview documents link to detailed documents
- README.md = overview/index for a directory
- Detailed docs focus on one specific topic

### Document Structure

**Overview documents (README.md):**
- Brief intro
- Key Concepts
- Related Documents (links)
- Quick Reference

**Detailed feature documents:**
- **Features** — what it does, when to use it
- **Flow** — step-by-step process, decision points
- **Data Models** — schemas, file formats, entity relationships
- **Files** — links to source code (relative paths)

### File Naming
- kebab-case: `file-based-storage.md`
- Descriptive: `collection-storage.md` not `collections.md`
- Place under `docs/<feature-domain>/`

### Writing Style
- Brief: focus on "what" and "why", not "how"
- Link to source files instead of duplicating code
- Use bullet points, tables, file trees
- No large code blocks — link to source instead

### Cross-References
- Internal docs: `[Topic](relative-path.md)`
- Source files: `[file.ts](../path/to/file.ts)` or `[file.ts:42](../path/to/file.ts)`
- External: full URLs

## Workflow

### Step 1: Understand the Request

Identify:
- **What** to document (feature, subsystem, concept)
- **Where** it belongs in `docs/` (existing domain or new directory)
- **Type**: overview (README.md) or detailed feature doc

### Step 2: Explore Before Writing

- Read existing docs in the target directory to avoid duplication
- Read relevant source files to understand the feature
- Check if a parent README.md needs to be created or updated

### Step 3: Create the Document

Follow the appropriate structure:
- For a new feature domain: create `docs/<domain>/README.md` (overview) + detailed docs
- For a new topic in an existing domain: create `docs/<domain>/<topic>.md` + update the domain README.md

### Step 4: Update Cross-References

- Add a link to the new doc from its parent README.md
- Add links to/from related documents if applicable

## Checklist Before Finishing

- [ ] Follows Features → Flow → Data Models → Files structure (for detailed docs)
- [ ] Links to source files instead of duplicating code
- [ ] Cross-references to related documents included
- [ ] Brief and focused — no unnecessary detail
- [ ] Proper heading hierarchy (H1 → H2 → H3)
- [ ] File name uses kebab-case
- [ ] Parent README.md updated with link to new doc