michi-docs

Michi’s working docs are written for an agent: dense, additive, shaped like a decision log, exhaustive because leaving something out costs the agent context. That is the right shape while you are in the loop. It fails at handoff — when the work has to be understood by someone who wasn’t in the sessions. This skill derives the reader-facing layer. The working docs stay as they are: epics, plans, debriefs and journals are the record, not the deliverable.

When to use

• An engineer is joining the project and needs to know what it is before where it stands
• A teammate is receiving a module, or a reviewer is picking up a branch
• The root docs (README, PROJECT.md, ARCHITECTURE.md, STATUS.md) have drifted, contradict each other, or describe an effort that is no longer the main one
• You want a diagnosis of the docs without changing anything

Targets

The target decides the shape of the output. The skill asks if you don’t say.

Command	Produces	Touches root docs?
/michi-docs project	README, PROJECT.md, ARCHITECTURE.md, STATUS.md — promoted in place	yes
/michi-docs scope <thing>	a new standalone artifact for a feature, module, branch or epic	no
/michi-docs audit	a findings report — what’s failing, what’s stale, what contradicts what	no

At the scope target the skill asks who the reader is, because the rules flip. For a teammate with repo access, file paths are the most useful thing in the document. For someone outside the team, they are dead weight — the fact gets inlined or dropped.

What it does

Diagnoses before writing. It inventories the whole doc set first — including any index that already exists — then checks for five failure modes, most of which can be found with a search rather than a judgment call:

1. Addressed to the operator — “the criteria you set,” “I measured.” The reader is eavesdropping on a conversation between one person and one agent.
2. The self-correction record — the agent’s revision history left in the artifact: “this count was wrong four times,” warning markers on every other claim. Useful to the operator, noise to a newcomer.
3. Status where structure is needed — “where it stands” before anyone has said what “it” is.
4. Unresolvable references — internal section numbers, milestone IDs, bare repo paths a reader outside the repo can’t follow.
5. No landing — no start-here, one altitude throughout, no reading order.

Writes in layers. A one-page start-here that stands alone and names what to read next; a working picture of what the system must do, how it’s built and what constrains it; deep reference as needed. The epics and journals are provenance — pointed at once, never offered as reading material. Within a document, the phases run what it is → what it can and can’t do → how it’s built → where it stands, so a reader can stop at the phase that answered them.

Aggregates across epics. When material is spread over many efforts it names the through-line, tabulates where the same thing appears under different names, says which numbers are not comparable, and states the honest conclusion — including the unflattering part.

Runs reader tests before claiming done. A stranger read; a sweep for first- and second-person subjects; every structural claim checked against the repo in the same session; the docs read against each other for contradictions; and every document named in a reading path actually opened.

What it produces

• Project target: the canonical root docs, edited in place, with a note of what changed
• Scope target: a standalone artifact carrying an audience line, an as-of date, and a provenance block marked internal
• Audit target: a findings report — nothing is changed
• A capture of the gaps — what was stale, what contradicted what, what the sources couldn’t answer

Key things to know

• It prefers promoting over emitting. A new parallel doc is a second copy, and second copies drift. A new file is written only when the artifact is meant to leave the repo.
• It won’t invent to fill a template. If the constraints were never written down, that is the finding — it surfaces the gap and asks.
• It won’t launder uncertainty. If a number took three attempts, the reader is told its confidence once, plainly — not as a running correction log.
• A drifted doc with good bones gets reconciled, not rewritten. A rewrite loses what the drift never touched.
• If the work reveals that requirements were never decided, that is /michi-explore or /michi-planning work. If the drift is structural, /michi-sustainability has the repo-wide audit.

For the full agent instructions, see the SKILL.md source.