ai-context-dot-md

AI Context Dot MD

Create or review CONTEXT.md files that give agents the factual substrate needed to reason correctly about code.

---

Mode Detection

• User provides a path to an existing CONTEXT.md → Review Mode
• User asks to create/generate/add a CONTEXT.md → Create Mode
• Ambiguous → ask: (c)reate a new CONTEXT.md or (r)eview an existing one?

---

Create Mode

Step 1 — Placement

Ask the user: "Where should the CONTEXT.md live?"

(r)oot — broad architecture overview
(p)ath — specific directory (provide path)
(m)ultiple — hierarchical (start with root, then children)

If a CONTEXT.md already exists at the chosen path, ask: File exists. (o)verwrite from scratch / (r)eview and update / (Q)uit? If review-and-update, switch to Review Mode first, then apply improvements.

If the scope has fewer than 5 files or a single obvious purpose, suggest: This scope may be too small for a standalone CONTEXT.md — a section in the parent might suffice. (p)roceed anyway / (Q)uit?

Step 2 — Analyze

MANDATORY READ references/knowledge-base.md for principles and patterns.

Before investigating, ask yourself:

• What would confuse a new agent about this scope?
• What terms mean something different HERE than in general usage?
• What can't the agent find by looking? The code already answers what ls, package.json, and config files show — write only what looking cannot find: the unwritten convention, the reason behind a boundary, the gotcha no config confesses.

Investigate the target scope:

• Read directory structure, key files, existing docs (README, AGENTS.md)
• Identify the domain model (entities, relationships, naming conventions in code)
• Map architecture (boundaries, data flow, abstractions)
• Note conventions that aren't obvious from code alone
• Find gotchas and known gaps

Step 3 — Draft

MANDATORY READ references/template.md for structure.

Write sections in priority order: