intentarchitect/intent.modules/module-context-capture

Skill: module-context-capture

CONTEXT.md is a module's durable knowledge layer — the why behind its design. The code records what a module does; CONTEXT.md records the reasoning that would otherwise leave with the session that decided it.

Where It Lives

Inside the module project folder — e.g. Modules/Intent.Modules.X/CONTEXT.md. One per module.

• Never at the repository root — there is no global CONTEXT.md.
• Never in a transient or build-state folder — those get cleared; this must survive.
• Never inside an intent / .intent metadata folder.

When A Module Has No CONTEXT.md

Create one, but not on arrival. A CONTEXT.md written before there is anything to record is a template with headings and no content, and the next session learns to skip it.

Write the file at the moment the first durable decision actually lands — a design choice with a rejected alternative, an invariant something else now depends on, a constraint discovered the hard way. Start with the Purpose section and that one entry. Let it grow from there.

Read It Before You Modify

Before changing a module, read the CONTEXT.md of every module you are about to touch. It tells you which constraints are deliberate, and which code is load-bearing for reasons the code itself does not explain.

If your intended change conflicts with `CONTEXT.md`, stop and flag the conflict. Do not

silently "improve" a design that was chosen on purpose. Either the context is stale — in which case

update it deliberately, as part of this change — or the change is wrong. Both need a decision, not

an assumption.

What Goes In

Dependency Versions Change The Contract

A module is written against a particular version of each module it depends on. When one of those modules changes an interface, type, role or behaviour this module relies on between versions, the code alone does not say which version it was written for or what the older form looked like.

Record it whenever you move a dependency to a new version, adapt to a changed interface, or raise a version floor because of one: the version the module now targets, what changed and in which version, how this module adapted, and why the floor sits where it does.

When you read CONTEXT.md before a change, compare each recorded version against the one the module references now. A dependency that has since moved further may have changed again, so check its interface before relying on what is recorded.

A change in an Intent Architect module or SDK interface between versions is a contract change like any other, not a defect, so it belongs here.

What Stays Out

• Transient task state, progress trackers, TODO lists — this file outlives the task.
• Anything already recorded elsewhere: release notes, module documentation, generated code.
• Anything trivially rediscoverable by reading the module source.
• Problems with Intent Architect itself — see below.

Intent Architect Problems Go To The User, Not Into CONTEXT.md

CONTEXT.md records decisions about this module. A problem with Intent Architect itself is not one of them: the Software Factory, a designer, module installation or caching, the Intent MCP tools, or any other part of the platform misbehaving, reporting something untrue, or needing a workaround.

Recorded in CONTEXT.md, such a problem becomes a permanent workaround that nobody reports, and the next session reads a platform defect as a deliberate constraint of the module.

Instead, tell the user as soon as you find it, so they can bring it to the Intent Architect support team's attention. Say what happened, how to reproduce it, and any workaround you used to keep going.

The one exception is a genuine limitation of the Intent Architect API or SDK — something it does not offer by design, as opposed to something that malfunctions. For example: a registration base class with no hook for what the module needs, or a module setting type that cannot express a condition. Record it together with the module design decision it forced. If you cannot tell whether something is a limitation or a defect, treat it as a defect and report it.

Write At Decision Time

Record the entry when the decision is made, not reconstructed at the end. A decision written up late is written from memory, and by then the alternatives that were rejected — the most valuable part — are usually gone.

The same applies to correction. When a decision is superseded, update or remove the entry then. A confidently wrong CONTEXT.md is worse than none, because the next session trusts it.

Suggested Shape

# Context: [Module Name]
 
## Purpose
[What this module is responsible for, in two or three sentences.]
 
## Architectural Decisions
-**[Decision]** — [why; what was rejected and why]
 
## Invariants & Constraints
-[Rule that must hold, and what breaks if it does not]
 
## Module Interactions
-**[Other module]** — [how they relate; what is broadcast, consumed, or assumed]
  -Written against [version]. [Version] → [version]: [what changed, and how this module adapted]
 
## Superseded
-[Decision that no longer holds, and what replaced it]

Checklist

• [ ] CONTEXT.md exists in the module project folder — not the repo root, not a transient folder
• [ ] A module with no CONTEXT.md had one created once its first durable decision landed
• [ ] Every module modified by this change had its CONTEXT.md read first
• [ ] New decisions recorded with reasoning, including rejected alternatives
• [ ] Superseded entries updated or removed — no stale claims left standing
• [ ] Any dependency interface change this module adapted to is recorded with the version it now targets
• [ ] Any conflict between the change and existing context was surfaced, not silently resolved
• [ ] Any Intent Architect defect met along the way was reported to the user for the Intent support team, not recorded here — only a genuine API or SDK limitation is recorded, with the decision it forced