maintain-context

Incrementally maintain two artifacts as conversations happen: CONTEXT.md (the project's domain glossary) and docs/adr/ (decision records). Both compound in value only if you keep them honest, narrow, and rare.

Ownership. This skill owns docs/adr/ exclusively (as a directory, so it takes precedence over pattern ownership) plus the CONTEXT.md glossary file. docs/adr/ is an explicit carve-out from docs-agent's broader docs/ ownership — without it, docs/ would silently swallow the ADR subtree. docs-agent reads docs/adr/ for context but never writes there. See the canonical map in the orchestrator's references/file-ownership.md.

The three-condition ADR gate

Before writing an ADR, all three must be true. Miss any one and skip — the next ADR will not be a worse decision because this one wasn't recorded.

Hard to reverse. Rolling back costs real time or money. Schema migrations, public API shapes, vendor lock-in, contractual commitments. Reversible defaults (a flag, a CSS choice, a folder name) don't qualify.
Surprising without context. A new contributor would not derive this from the code in front of them. They'd reach for the obvious answer and be wrong. If the code self-documents the choice, no ADR.
Real trade-off involved. There were viable alternatives, and choosing this one closed some doors. If the alternative was nonsense ("we could have not used HTTPS"), there's no decision to record — only a fact.

Why this gate matters: an ADR folder full of routine choices reads like noise, and people stop opening it. Rarity is the whole point. When all three conditions hit, the ADR is worth writing because it captures information that will be lost otherwise.

CONTEXT.md is a glossary

Not a spec. Not a scratchpad. Not implementation notes. Each entry is: