/brief

name: brief
description: "Write the one thing a person reads after an unattended run — its report — and the lecture notes that prepare them for it, in words they already have."
commands:
  brief: "Write a run's report, or lecture notes on a method it used."
origin: magi

brief

When to use

A run has enough to write up, or only its report is left; or `magi next` lists lecture notes the person asked for.

Method

1. Report: `magi run outline <run> --write` (add `--empty` when nothing big was found: one page). The claims and whether each stands, the chain, the steps and the glossary are in it already; every `<!-- … -->` is yours to replace. 2. Write for one sitting, start to end: motivation → what is and is not shown → what is new → the picture and the core insight (brute force said honestly) → the derivation in chain order, keeping what was decided or is not obvious → decisions → failures worth knowing (at most 5, three lines each) → is it still promising. 3. `magi review drafts/runs/<run>.md` has another agent read it whole. Fix what it names, then `magi run report <run> drafts/runs/<run>.md`; the gate says what a reader would still trip on. 4. Lecture notes: `magi familiar list` shows what was asked for. Write `drafts/lectures/<concept>.md` from the concept card, the `raw/` sources and *the place a claim of this run uses it* — "in [[claim]] it enters like this" — pitched at what the list marks known. Inside a run, register a step first.

Rules

• **Never** coin a name. A term the reader meets is a concept card

(`magi wiki add-concept --name "…" --source "…" --content "…"`) or plain words.

• **Never** cite a claim by its slug alone: quote its statement where it first

appears. A slug means nothing to the person reading.

• A term `magi familiar list` does not mark known is defined at first use, or

linked to its lecture notes.

• Present nothing as established that section 2 marks unreviewed or contested.