itelescope/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.
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.