documentation

---
name: documentation
description: "Keep the repository's documentation accurate, honest, and synchronized with the code. Use when editing docs, README, AGENTS.md, or ADRs."
generated: true
source: .ai/skills/documentation.md
---

<!--
This file is generated by tools/skills.
Do not edit this file directly.
Edit .ai/skills/documentation.md and run `make generate-ai`.
-->

# Skill: Documentation

## Purpose

Keep the repository's documentation accurate, honest, and synchronized with the
code, so future agents and users can trust it.

## When to Use This Skill

- Editing anything in `docs/`, the `README.md`, or `AGENTS.md`.
- Adding or changing an ADR.
- Shipping a behavior/contract change that documentation must reflect.

## Files to Read First

- `AGENTS.md`
- `docs/README.md` (reading order and index).
- The specific doc/ADR you are changing and any code it describes.
- `.ai/skills/skill-authoring.md` if the doc is a skill.

## Core Principles

- **Be honest about status.** Clearly separate what exists from what is planned;
  use accurate status markers (✅ done / ⏳ planned).
- **Never claim unimplemented features work.** The project is in the foundation
  phase — don't describe the runtime/compiler/API as functioning.
- **Docs follow code.** Update docs in the **same change** as the behavior they
  describe; don't let them drift.
- **Decisions go in ADRs.** A binding architectural decision is recorded as an
  ADR, not buried in prose.
- **Show, don't just tell.** Prefer examples, flows, and small diagrams where
  they clarify.
- **Right file for the right scope:** README = user-facing; AGENTS.md =
  repo-wide rules for agents; ADRs = architectural decisions; `docs/` = design.

## Process

1. **Identify scope.** Decide which file(s) the change belongs in (README vs.
   AGENTS.md vs. docs vs. ADR) — don't scatter the same content.
2. **Write the change** concisely; add an example or flow if it aids
   understanding.
3. **For a new binding decision**, add `docs/adr/NNNN-title.md` using the
   existing ADR format (Status, Context, Decision, Consequences, Alternatives,
   Enforcement).
4. **Sync cross-references**: update indexes (`docs/README.md`,
   `.ai/README.md`) and any links.
5. **Verify honesty**: re-read for any claim that overstates current status.
6. **Validate** with `make check`.

## Checklist Before Finishing

- [ ] No unimplemented feature described as working; status markers accurate.
- [ ] Docs updated in the same change as the behavior/contract.
- [ ] Architectural decisions captured in an ADR (not just prose).
- [ ] Correct file chosen for the scope (README / AGENTS / docs / ADR).
- [ ] Examples/flows added where helpful.
- [ ] Cross-references and indexes updated.
- [ ] Consistent with `AGENTS.md`, README, docs, and ADRs.
- [ ] `make check` passes.

## Common Mistakes to Avoid

- Documenting aspirational behavior as if it already works.
- Editing a contract in prose without a supporting ADR.
- Letting README/AGENTS/docs drift out of sync after a code change.
- Duplicating the same content across multiple files.
- Large rewrites that lose existing structure and history.

## Expected Final Report

State: which docs/ADRs were created or changed and why; confirmation that no
unimplemented feature is claimed as working; any new ADR added; which indexes
and cross-references were updated; and the `make check` result.