openscribe/docs/documentation-policy.md

# Documentation policy

Two separate ideas, both about making the repo the single source of truth so that no
session ever depends on another session's chat history.

## A. State lives in committed markdown, not in the chat

Do not use chat history, context, or cache as memory. They cost tokens to carry and
vanish between sessions. Instead, everything a future session needs is written to the
`state/` directory and committed:

| File | Holds |
|------|-------|
| `PROJECT.md` | Objectives, scope, description, audience. The anchor. |
| `ARCHITECTURE.md` | How the system is built and why it is built that way. |
| `DECISIONS.md` | A dated log of decisions and their rationale. Append, never rewrite history. |
| `TODO.md` | Done / in progress / pending. The current state of play. |
| `NOTES.md` | Working notes, gotchas, environment quirks, dead ends to avoid. |

Update these as part of the work, not as an afterthought. A change to how the system
works is not finished until `ARCHITECTURE.md` or `DECISIONS.md` reflects it.

Templates for all of these are in `templates/`.

## B. Documentation is written in a separate session from the code

The user facing documentation (README, guides, API docs, changelog) is **not** written
in the same session that writes the code. This is deliberate:

- It forces the building session to leave a complete trail. If the code cannot be
  documented later from git history and comments alone, the trail was not good enough.
- It keeps each session cheap and focused. A building session spends its budget
  building; a documentation session spends its budget writing docs.
- It gives the docs a cold, independent reader who documents what the code actually
  says, not what the author remembers intending.

### What the building session must leave behind

So the later documentation session can work with no chat history:

1. **Commit messages with full notes** - what changed, why, and any trade-offs. See
   [Workflow](workflow.md).
2. **A complete PR description** - feature, tools used, what was achieved, how it works.
3. **Code comments that explain intent** - not what a line does (the code shows that)
   but why it exists, what it assumes, and what would break it. Comment for a stranger
   who was not in the room.
4. **Current `state/` files** - especially `ARCHITECTURE.md` and `DECISIONS.md`.

### What the documentation session does

Starts cold. Reads `git log`, the PRs, the code and its comments, and the `state/`
files. Writes the documentation from those alone. If something cannot be understood
from the repo, that is a gap to flag, not a reason to guess or to reach for lost chat
context.