Project Brain

Project brain

The brain holds what mxcli cannot compute about this project. Two halves:

• Decisions — why a pattern was chosen here, which marketplace version broke what, what a recurring mxbuild error means in this app.
• Open questions — what is not decided yet, so it is not silently forgotten and rediscovered expensively later.
• The plan — the requirements being built from and the slices they are grouped into, when the source is a specification document, a prototype or a conversation rather than GitHub issues.

The plan half matters because hours of work can otherwise leave no trace: a Word document and a chat transcript are not in git, so a session that resumes later has no idea what it was building towards, and neither does the next person.

It lives in docs/brain/, is committed, and is reviewed in a pull request like any other change.

The rule that makes it work

Anything mxcli can answer does not belong here. Entities, microflows, pages, bindings, references, callers, dead assets — all queryable. A note that transcribes any of them is a note that will disagree with the project the moment someone edits the model, and it will disagree silently.

Before writing anything down, ask whether a command answers it:

mxcli -p app.mpr -c "list entities"
mxcli -p app.mpr -c "list callers of MyModule.ACT_Thing"
mxcli -p app.mpr -c "describe microflow MyModule.ACT_Thing"

If one does, do not record it. Record only the negative space — the reason, the constraint, the history that no query can reach.

Reading it

docs/brain/
  project.md           cross-cutting decisions
  modules/<Module>.md  decisions anchored to one module
  plan/<slice>.md      requirements for one deliverable slice

When building: read project.md, plus the shard for each module you are about to touch. That set is known before the work starts.

When planning, or when picking up work: read the plan. mxcli brain plan first — it says which slices are outstanding — then the shard for the slice you are working on.

Never read the whole directory. A large project has dozens of shards, and reading them all reinstates exactly the context cost the split removed. If you do not know which modules you are touching yet, read project.md and come back.

mxcli brain brief produces that set for you, so the rule above does not depend on judgement:

mxcli brain brief --slice 07-planning     # project + the modules that slice's
                                          # requirements anchor into + its plan
mxcli brain brief --module Sales          # project + Sales, no plan

The modules are derived from the slice's requirement anchors — you do not tell it which modules the slice touches, because that is what you opened the brief to find out. The pack goes to stdout and its size to stderr, so it pipes.

This matters most when each slice runs in its own session or sub-agent: the pack is then re-read from a cold start every slice, and reading the whole store instead is roughly three times the tokens.

Writing to it

An agent captures; a person promotes. Capturing is free and reversible; promotion is the human's call about what is worth committing.

mxcli brain capture "Orders are committed by Finance, not Sales" \
  -a @Sales.Order -a @Finance.ACT_Post -p app.mpr

The first line becomes the entry's title and the rest becomes its body, so a one-argument capture can still carry an explanation:

mxcli brain capture "Marketplace Administration 4.5.0 breaks the login flow
It changes Account's password-policy handling; we pinned 4.3.2 until the
custom login microflow is reworked." -a @Administration.Account -p app.mpr

Then leave it. mxcli lint reminds the developer that something is staged.

Recording requirements and slices

When the source of truth is outside git — a specification document, a prototype, a long conversation — record it as requirements grouped into slices before building. Otherwise the work is invisible: not in an issue, not in a commit message, and gone from the session that resumes tomorrow.

mxcli brain capture "Orders must be approvable by a manager" \
  --slice 02-approvals -a @Sales.ACT_Order_Approve -p app.mpr

--slice is the only signal needed. It files the entry in plan/02-approvals.md and makes it a requirement rather than a decision.

Slices are ordered by name, so a numeric prefix is how a roadmap is sequenced: 01-accounts, 02-approvals, 03-reporting. That is your choice, not something mxcli maintains.

A requirement's anchor points forward

This is the difference that matters, and it is why requirements are not simply more decisions:

So anchor a requirement at what you are going to build. @Sales.ACT_Order_Approve before that microflow exists is correct, not a mistake.

Never anchor a requirement at a bare module. @Sales resolves the instant the module exists — long before any of the work inside it — so the requirement reports built with nothing done. mxcli brain capture --requirement refuses it and names the alternative, because the failure is silent and flattering: the plan shows progress that has not happened and nothing else disagrees. Anchor at a document the slice actually creates. (Measured on a real project: two requirements anchored at a module both read as built after slice 01.)

A module role is a fine anchor and resolves like any document — a security requirement anchored at the roles it creates is measured correctly. Anchoring at the documents whose access rules the roles govern works too, and says something slightly different; either is legitimate.

A theme has no model element to anchor at (it is files under theme/, which is the point of mxcli theme). Anchor the branding requirement at the branded layout the slice adds — the model-side half of the same work.

Progress is derived, never written

mxcli brain plan -p app.mpr

SLICE           BUILT  PLANNED   UNANCHORED
01-accounts         1        0
02-approvals        0        1            1

1 of 3 requirements built, across 2 slice(s).

A requirement is built when its anchors resolve against the model. Nothing in the file says "done" — building the thing is what moves the number.

Never write a status into a requirement, and never keep a checklist beside it. A hand-maintained status is wrong the moment someone builds something, and nothing will tell you.

A requirement with no anchor is counted separately as unanchored: it cannot be measured. That is a prompt to anchor it once you know what will implement it, not an error.

Slices have a generous cap, and that is the slicing discipline

A slice holds source material, so its budget is much larger than a decision shard's — and it is not loaded every session. But it is still a budget: a slice too long to read is a slice that should be split.

When to capture a decision

Capture is easy to postpone forever, so it needs a trigger rather than good intentions. Two, and the first is the reliable one:

1. You have had to correct the same thing twice. The second correction is the signal: it will happen a third time to someone else. Capture what the right answer is and why, anchored at whatever you were working on.
2. You chose between real alternatives and the losing one would look reasonable to the next person. Record the choice and what ruled the other out — a decision without its reason gets re-litigated.

If you are unsure whether something qualifies, capture it. Staging costs nothing and is reversible; a person decides what is worth committing.

Recording what is NOT decided

An open question is a decision that has not been made yet. Record it rather than carrying it in your head — the conversation ends, and the question is expensive to rediscover.

mxcli brain capture "Do approvers see rejected orders?
The spec is silent. Affects the overview page and the access rules." \
  --open -a @Sales.Order -p app.mpr

A question's anchors are not checked. It may name something that does not exist — often the question is precisely whether it should — so the staleness rule that keeps decisions honest does not apply to it.

--open combines with --slice: a question about a slice's scope is filed with that slice, and is counted apart from its requirements. An unanswered question is not outstanding scope, so it never inflates the slice.

Answering it turns it into a decision, in place:

mxcli brain resolve <id> "Yes, for 30 days
Agreed with the product owner; drives the overview filter and the access rule."

The entry keeps its id and its position, and the question survives as the answer's context. From that moment its anchors are checked, like any other decision.

mxcli brain check and mxcli lint both report unanswered questions until someone resolves one. That is deliberate: a question nobody answers is the one kind of entry that gets more expensive the longer it sits.

Write the anchor, not the name

@Sales.Order.Status is what makes an entry routable (its module decides the file) and checkable (mxcli brain check verifies it still resolves). The same fact written as prose — "the Status attribute on the Sales order entity" — is neither.

An entry's first anchor decides its shard. An entry with no anchor is cross-cutting and goes to project.md.

An entry may anchor into more than one module — "Sales.Order is committed by Finance.ACT_Post" genuinely spans two — and that is fine as long as one anchor belongs to the shard it is filed in.

Checking it

mxcli brain check -p app.mpr            # every shard
mxcli brain check --changed -p app.mpr  # only shards this branch touched

Two independent things are checked, and only some outcomes are failures:

"Not indexable" is not a problem to fix. Treating it as missing would demand edits to entries that are perfectly current.

Misfiling is a separate axis, not a fourth anchor state: every anchor can resolve and the entry still be in the wrong file.

Size

Each shard has a line budget, and promote refuses rather than letting a shard grow past it. project.md is the tightest — it is the only file loaded every session.

mxcli brain show -p app.mpr

Sizes are computed on every run and deliberately not written down anywhere. A figure in prose is stale the next time anyone promotes.

If a promotion is refused, the answer is to condense or drop, not to raise the cap: the cap is what stops the store becoming a file nobody reads.