# Documentation Instructions

## Core Principle

Every document starts with the **problem it solves** — one or two sentences.
Then a diagram if it clarifies, then content.

---

## Document Workflow

1. **Abstract** -- write problem statement + section headings (+ top-level diagram if relevant) directly into the file. Do not propose the structure in chat first.
2. **Align** -- stop after writing the abstract. The human reviews it in the file and confirms or adjusts before any section content is written.
3. **Section by section** -- write ~50 lines at a time, then stop and wait. The human decides when a section is ready and asks for the next one. Do not ask "did this go in the right direction?" or prompt the user to continue.
4. **Stay in scope** -- if something is complex or unclear, stop and ask rather than guess
5. **Review** -- when done, AI asks: "Is anything missing?" -- user decides
6. **Link check** -- after finishing, scan other docs in `docs/` for broken links or documents that should now link to this one

---

## Diagrams

**Abstract**: one top-level diagram showing the full scope.
**Sections**: add focused sub-diagrams to clarify specific parts.

Use **Mermaid** for flows, architecture, component relationships.
Use **ASCII trees** for file/folder structures.
When in doubt, include a diagram -- visuals are faster to read than text.

For contrast rules, sizing and diagram type selection: see [mermaid.instructions.md](mermaid.instructions.md)

---

## What Belongs in a Document

✅ Principles — how and why the system works
✅ Architecture — components, relationships, data flows
✅ Key decisions — why this approach over alternatives
✅ Scope boundaries — explicitly state what is out of scope and link to where it is covered

❌ Step-by-step commands — belong in README or runbooks
❌ Full code blocks — small illustrative examples only
❌ Troubleshooting — "if error X do Y" does not belong here
❌ All possible alternatives — pick the relevant ones, explain briefly when to use which

---

## When the User Corrects Something

- Fix **only** what was pointed out
- Do not explain why you got it wrong
- Do not add anything else at the same time

---

## Scope

Keep each document tightly scoped to its title.

If a topic needs deeper treatment:
- Ask: 'Should we create a separate document for X?'
- If yes: write a short intro sentence and link to the new doc
- Do not expand inline

---

## Length

- Increment: ~50 lines at a time, then check with user
- Hard limit: 500 lines
- If approaching limit: stop and ask user what to continue with

---

## Rules

- Written in English
- No step-by-step commands -- those belong in README or runbooks
- No changelog entries
- No duplication between documents -- link instead