Maintain Context

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.

1. 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.
2. 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.
3. 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:

• A term (the canonical name this project uses)
• Its meaning in this project's vocabulary
• An _Avoid_: line listing forbidden synonyms — words that mean the same thing in everyday speech but collide with something else here

If the entry isn't disambiguating a term, it doesn't belong in CONTEXT.md. Put it in a README or design doc instead.

Inline-update pattern

Capture entries the moment a term resolves. Do not batch glossary updates for end-of-session.

Forbidden: Batching glossary updates for end-of-session. Capture them inline as terms are resolved. Batched updates miss context — the reason a term was forbidden gets lost between the conversation and the writeup.

When the user says "let's call them subscribers, not users" — open CONTEXT.md right then, write the entry, confirm the _Avoid_: list with the user. The five-second update is worth more than a thirty-minute end-of-session pass that has lost half the nuance.

The _Avoid_: alias-list pattern

Every term lists forbidden synonyms with a one-clause reason. The reason is what makes the rule stick.

## Subscriber
A customer record with `subscription_status = active`. Has access to paid features.
_Avoid_: user (too generic), member (legacy term from v1), client (means something else in marketing).

See references/context-format.md for full structure and three worked examples.

Cross-reference with code

When the user states behavior — "Subscribers get a 30-day trial" — verify against the code before recording it. Use Grep for the relevant constant or model field. If the code disagrees, stop and ask which is wrong. Do not record a glossary entry or ADR that contradicts the codebase: one of them is going to be wrong, and the artifact that's supposed to disambiguate will become the thing that confuses people.

Project layout — read docs/agents/domain-docs.md first

Before writing or reading any glossary entry or ADR, check whether the repo has docs/agents/domain-docs.md. That file (written by /setup-project-skills) declares whether this repo uses a single-context or multi-context layout, which controls where CONTEXT.md and docs/adr/ live.

• If docs/agents/domain-docs.md exists: read it. A single-context layout puts CONTEXT.md at the repo root and ADRs at docs/adr/. A multi-context monorepo puts them per-app at apps/<app>/CONTEXT.md and apps/<app>/docs/adr/. Use the declared paths — do not invent your own.
• If docs/agents/domain-docs.md is missing: default to single-context (root CONTEXT.md and docs/adr/) and surface one prompt: "This repo isn't configured for Skill-Madness yet. Run /setup-project-skills to make the layout choice durable; I'll use single-context defaults for this entry." Do not silently assume — the wrong default in a monorepo lands an entry in the wrong vault.

Lazy file creation

Do not create CONTEXT.md or docs/adr/ until there is a real entry to put in them. If they don't exist when this skill triggers, ask once: "Should I create CONTEXT.md / docs/adr/ now?" Get explicit consent. Empty scaffolding signals "this project documents things" when it doesn't yet.

ADR workflow

When all three gate conditions hit:

1. Propose the ADR out loud: "This looks ADR-worthy — hard to reverse (schema), surprising (we picked event-sourcing over CRUD), real trade-off (loses ad-hoc queryability). Want me to write it?"
2. On yes, draft per references/adr-format.md and save to docs/adr/NNNN-title.md with the next sequential number.
3. Status starts as Accepted if the decision is live; Proposed if still under debate.

For uncertain cases, see references/three-condition-gate.md — five scenarios walked through with the right call named.

Compose with

• grill-me — surfaces decisions and terminology that should be captured here.
• architecture-rescue — when joining an unfamiliar codebase, this skill is where the recovered understanding lands.