dotfiles/agents/.agents/skills/brainstorm-with-docs/artifacts/context.md

CONTEXT.md — Shared Project Language

CONTEXT.md is a glossary and nothing else. It exists so that the user, the code, and future agents use the same words for the same concepts. It is totally devoid of implementation details, decisions, plans, or work logs.

A single CONTEXT.md lives at the repo root. If a CONTEXT-MAP.md exists at the root, the repo has multiple contexts — read it to find which CONTEXT.md the current topic belongs to.

Create the file lazily — only when the first term is actually worth recording.

Structure

# {Context Name}

{One or two sentences: what this context is and why it exists.}

## Language

**Order**:
A customer's request to purchase one or more items.
_Avoid_: Purchase, transaction

**Invoice**:
A request for payment sent to a customer after delivery.
_Avoid_: Bill, payment request

**Customer**:
A person or organisation that places orders.
_Avoid_: Client, buyer, account

Rules

• Be opinionated. When several words mean the same thing, pick the best one and list the rest under _Avoid_.
• Keep definitions tight. One or two sentences. Define what it is, not what it does.
• Only project-specific terms. General programming concepts (timeouts, retry, cache) don't belong, even if the project uses them heavily. Ask: is this unique to this project's domain, or generic? Only the former belongs.
• Group under subheadings when natural clusters emerge; a flat list is fine otherwise.

What does NOT go in CONTEXT.md

• implementation details
• specs, decisions, or rejected alternatives → spec / ADR
• operational procedures → runbook
• validation rules for the current work → spec
• work logs, temporary notes, speculative ideas