# Documentation Workflow for LLMs

LLM agents are amnesiac by default: every session starts from zero. The only
thing that survives a session boundary is what you stored in an external
system. Documentation is therefore not bureaucracy — it is how you keep
being *yourself* across sessions.

## The Three Layers

| Layer | Where | What | When |
|---|---|---|---|
| Memory | `POST /memory` | durable facts, decisions, mistakes, credentials | the moment you learn it |
| Worklog | `POST /worklog/:task_id` | task progress, errors, milestones | after each meaningful step |
| Changelog | repo `CHANGELOG.md` + commit | user-visible changes | with every code change |

## Layer 1: Memories

Store a memory **when the fact is new**, not when the session ends. Sessions
crash; context windows overflow; a "I'll write it down later" is a fact that
never happened.

Pick the right category:

- `identity` — who you are, your role, your siblings
- `project` — state and decisions of a project
- `mistake` — what went wrong and the lesson (the most valuable category)
- `skill` — how something is done (step lists, commands)
- `credentials` — tokens, endpoints, paths (never in chat or code)
- `context` — session state worth carrying over

Use `confidence` honestly (1.0 = verified, 0.5 = assumption) and tag
consistently — memories are found by tag and key, not by prose.

```
POST /memory
{ "content": "...", "category": "mistake", "key": "pg-params-42p18",
  "tags": ["postgres","dynamic-sql"], "priority": "high", "confidence": 1.0 }
```

## Layer 2: Worklogs

The worklog is the progress journal of one task. It answers "what exactly
happened while solving this?" for every future reader — including future you.

```
POST /worklog/my-task-123 { "kind": "start",    "content": "Reproduced the bug" }
POST /worklog/my-task-123 { "kind": "progress", "content": "Fix in src/db.ts:142" }
POST /worklog/my-task-123 { "kind": "error",    "content": "42P18 — param type undetermined" }
POST /worklog/my-task-123 { "kind": "close",    "summary": "Fixed, 24/24 tests green" }
```

Rule of thumb: **one entry per decision or discovery**, not per hour. Errors
belong in the log immediately — they are the most useful entries later.

## Layer 3: Changelog and Commits

Code changes are documentation too:

- **Commit message**: what changed and *why*, with the task/user reference in
  parentheses. First line under 72 characters, imperative mood.
- **CHANGELOG.md**: one entry per user-visible change, grouped as
  Added / Changed / Fixed / Removed, with the version and date.

A fix without a changelog entry is invisible to everyone who did not read
the diff.

## Anti-Patterns

- **Memory dumps at session end.** Context is gone by then — store
  continuously.
- **Prose memories.** "Maybe the database thing was somewhere in the config"
  is unfindable. Use precise keys, tags and content structure.
- **Silent retries.** Every failed attempt belongs in the worklog; the next
  agent will otherwise repeat it.
- **Chat as storage.** Chat history is not a knowledge base — extract the
  durable facts into memories.

## A Complete Loop

1. Learn something → `POST /memory` (now)
2. Start a task → `POST /worklog/:id {kind:"start"}`
3. Every step/error → `POST /worklog/:id {kind:"progress"|"error"}`
4. Change code → commit + CHANGELOG entry
5. Finish → `POST /worklog/:id {kind:"close", summary}`
6. Mark the task done → `GET /mind/task/:id/complete`

The next session — or a sibling agent picking up your task — can then
reconstruct everything: the task list says *what*, the worklog says *how*,
the memories say *why*.