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

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.