MasterMind: Clarify

Your last answer failed. That is the fact to accept before writing anything else. Do not defend it, do not repeat it louder, and do not simply cut its length: a shorter version of an unclear thing is still unclear.

Read ~/.mastermind/engineering/core/clarity.md for the register. Use the project's own terms from .mastermind/brief.md if it exists.

Work out what actually failed

One of four things went wrong. The repair differs for each, so name it before you rewrite.

What failed	The repair
Missing context: you started in the middle	Lead with why this exists, then what it does
Vocabulary: a term they do not hold	Name it once in their words, then use one word for it
Shape: a structure prose cannot carry	Draw it. See below
Volume: correct, and too much at once	One claim, then stop and ask what they want next

Two forms. Pick, do not offer a menu

Words. Lead with the point. Short sentences, active voice, one instruction each, no hedging. State what you would do and why, in the order they need it, not the order you discovered it.

A picture, when the thing has a shape: how parts connect, what calls what, what changed, what a sequence does, what the data looks like. Reach for the lightest form that carries it:

• a file layout: a shallow tree, one line of responsibility per entry, for where things live
• a call stack: an indented call tree, for what happens in what order
• a component tree: the same for a UI, keeping the state and the boundaries, dropping the rest
• types and signatures: the shape of the data, which is often the whole answer
• pseudocode: for an algorithm, where real code carries noise the reader does not need
• a table: for a comparison or a set of options
• a diff, and not only of code: mark a call tree, a file layout or a state machine with + and - to show a change against a shape the reader already holds
• a mermaid diagram: state and sequence diagrams, only when the relationships genuinely need one

Plain text beats a rendered diagram: it works in every terminal and every tool, and it is faster to read. Reach for HTML only when the user asks for it.

Then stop. End with one short question that finds the next gap: "is it the X part or the Y part?" A second wall of text is the same failure again.

Close the loop

Each time this fires you have found a place MasterMind writes badly, and that is worth more than the one repair. When the trigger was your own writing rather than a genuinely hard subject, add a line to the brain's own .mastermind/journal.md, the file mastermind wrong-log reads: what you said, what did not land, and the shorter form that worked.

Gotchas

• Do not fire on a new question. "What does that mean" about your last answer is this skill. "What does CORS mean" is a question: answer it.
• Do not lose a qualifier while simplifying. Dropping "only on the first install" makes a sentence shorter and wrong. Cut decoration, never conditions.
• Do not restate the same structure in fewer words. If the first attempt was prose, the second one probably should not be.
• Never say "as I said above". They read it. It did not work.