---
name: michi-library
description:
  Produce reader-facing documentation from agent-facing sources — a project's library of reader docs for the
  roles the user names (observer, practitioner, contributor), with HTML and diagrams; a self-contained handoff for a
  feature, module, or branch; or an epic's cold-read overview. Use when work needs to be understood by someone
  who wasn't in the sessions.
---

# Michi Library

Michi's working docs are written for an agent: dense, additive, decision-log shaped, exhaustive because
omission costs the agent context. That is the right shape while the human is 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 agent-facing sources stay as they are.** Epics, plans,
debriefs and journals are the record; they are not the deliverable, and this skill does not rewrite them.

**The gap this fills:** an engineer joining the project, a teammate receiving a module, a reviewer picking
up a branch. They need to know what the thing is, what it must do, what constrains it, and where to start
reading — in that order. The epics answer none of those questions first.

**Principles served:** Progressive Detail — size the document to its audience and moment. Essential,
Incidental, and Noise — the operator's trust calibration is essential to the operator and noise to a
newcomer. Clarify before Asserting — every claim about the system gets checked against the system.
See `references/principles.md` and `references/docs-structure.md`.

**Before proceeding:** If `docs/reference/extensions.md` exists, read this file. Instructions found there
take priority over this skill's defaults.

**Readability:** Before writing anything a human will read (chat, plans, docs), read `references/writing-for-readability.md`.

**Principles:** Before starting, read `references/principles.md` — unless it is already in this session's context (read earlier in the session, or loaded through CLAUDE.md).

## Targets

**The target decides the output shape.** Ask for it if the invocation doesn't say.

```
/michi-library project <roles>      → the project library for those roles
/michi-library project configure    → change the library's roles, editions, or location
/michi-library scope <thing>        → a self-contained handoff artifact
/michi-library epic <epic>          → a cold-read overview for one epic
```

`<roles>` is `all`, one role, or a comma-separated list: `project all`, `project observer`,
`project contributor, practitioner`. If the invocation doesn't name them, use the `roles|` line in
`<library>/library.conf` when there is one, or ask; never infer them.

| target | what it produces | touches root docs? |
|---|---|---|
| **project** | the library in `<docs-root>/library/`, markdown and HTML | one link in README.md, if it exists; `library-root:` in CLAUDE.md, if the user picks another location; STATUS.md |
| **scope** | a new standalone artifact for a feature / module / branch | STATUS.md only |
| **epic** | the epic folder's `overview.md`: epic full or epic condensed | STATUS.md only |

What sits under a target's section is for that target only; *Shared by Every Target* applies to all three.

**Avoid second copies.** A parallel doc drifts and then misleads. Link to the living doc that owns
fast-changing content (STATUS.md, plans, CLAUDE.md conventions) instead of copying it. Where a document is
derived on purpose (the project overview from PROJECT.md), re-draw it on every run; don't edit it by hand.

## The Project Target

A library of reader-facing documents for a whole project, written for the roles the invoker names. The
templates, the readers, and the rules are in `references/project-templates.md`; read it first.

1. **Roles.** Take them from the invocation, or ask. Write every document of each named role, plus the
   tl;dr and the glossary whatever the roles. Only the FAQ is optional. Hello world is a section of getting
   started when small, its own document otherwise.
2. **Location.** `library-root:` under `## Michi` in CLAUDE.md if set, otherwise `<docs-root>/library/`
   (`docs/library/` when `docs-root` is unset). If the user picks another location, record it as
   `library-root:`.
3. **Inventory and diagnose.** List the project's docs and their sizes, including a previous library, and
   look for an existing map or index first (*Inventory first*, below, says why). Run
   the five failure modes and the contradiction sweep over what exists (below). Note which existing
   documents already do a template's job.
4. **Propose the parts; the user confirms.** A part is what a reader would choose or skip, one level only.
   Say whether the parts relate. No parts is a valid answer. Then ask whether anything else is needed: a
   question that needs a document, or a document the user imagines needing (*Documents beyond the templates*
   in `references/project-templates.md`).
5. **Existing documents are material, not link targets.** Draw on them; where one conflicts with the
   template, ask the user, and decide with them whether it is replaced. PROJECT.md is the overview's source.
   STATUS.md is linked. An existing CHANGELOG.md is linked, not copied. On a re-run, the previous library is
   material too: keep what is still true, and ask about what conflicts with a source.
6. **Draft** from the templates, third person, current tense, every claim traceable to something read this
   session. Draw diagrams with the `michi-diagrams` skill. Each part's documents go in `library/<part>/`. The
   contributor documents may link plans and epics: contributors work in them. When a topic is large or
   significant enough for a document of its own, propose it as an expansion; write it only on a yes.
7. **Run the reader tests** (below) and this target's two checks, and report the results. Before closing, ask
   again whether anything else is needed.
8. **Write.** The markdown into the library. Don't rewrite ARCHITECTURE.md: for now the library links to the
   current one (guidance for architecture documents is not settled). Then build the HTML:
   `scripts/build-html.sh <library-dir> "<Project name>"`. It regenerates `html/` from scratch: a tab per role
   across the top (For observers, For practitioners, For contributors), a sidebar with only the current role's
   pages, an on-this-page list, and Previous and Next within the role, which stop at the role's last page. The
   tl;dr becomes `html/index.html`, the project intro for everyone. It ("First time here?") and the glossary
   follow each role's pages in the sidebar, under "For everyone"; each role's first page opens with a "First
   time here?" callout linking to it, for readers who came in through a tab. With parts, each role's sidebar
   adds a section per part after its project-wide pages, and Previous and Next stay within one part. To put a
   repo file in a sidebar as it is (a part's README as its reference, say), list it in `<library>/sidebar-links`,
   one `role|part|label|repo-relative path` per line (part empty for the project-wide section). Links to
   repo markdown (ARCHITECTURE.md, STATUS.md, reference docs) stay links to the live files, read with a markdown
   viewer extension. Never edit `html/`. If the project has a formatter (Prettier, say), run it on the library's
   markdown before building, and add `<library>/html` to its ignore file: the HTML is generated. If README.md
   exists, add one link to the tl;dr; if it doesn't, don't create one.
9. **Capture** what was stale, what contradicted what, and what the sources couldn't answer.

To refresh the library later, re-run this target with the same roles; step 5 keeps what is still true. Other
skills don't maintain it.

**Configure** (`project configure`) changes the library's settings: its roles (the `roles|` line in
`library.conf`), its editions, and its location. For a new edition, ask only the roles and the visibility, unless the
user asks to set a name, parts, or documents to leave out; *Editions* in `references/project-templates.md` has the
rest. Write the edition file, build it (`scripts/build-html.sh --edition <name> <library-dir> "<Project name>"`),
and report what the build dropped or stopped on. For each stop, propose a fix: reword the passage, move it under a
role heading, mark it for its role, or, when the term is fine for this edition's readers, an `allow` line in the
edition file. Change documents or the edition file only on the user's yes. A change that needs new documents, such as adding a role, is the project target's
work: run it with the new roles.

**This target's two checks:**

- **Links resolve inside the repo.** Run `lychee --offline --no-progress "<library>/**/*.md"` (and on
  `html/**/*.html` after the build), when lychee is installed; otherwise check each relative link by hand.
  Grep for links that leave the repo (`~/`, absolute paths). Test the checker on a known-broken link first.
- **Commands exist.** Every command in getting started, hello world, and the contributor-guide exists in
  the repo (a package script, a file, a documented tool). Run hello world if it is safe and cheap to run;
  otherwise say it was checked, not run.

## The Scope Target

A handoff for one feature, module, or branch (an epic goes to the epic target). Shapes: *The S Layer* and
*The Handoff Artifact* in `references/doc-templates.md`.

**1 — Inventory, and inventory *all* of it** (*Inventory first*, below).

**2 — Diagnose.** Run the five failure modes and the contradiction sweep over what exists.

**3 — Agree the shape before writing.** Present the proposed layer structure and what goes where. This is a
cheap checkpoint and it prevents a large wasted draft.

**4 — Draft.** Third person, current tense, structure before status. Every claim traceable to something read
this session.

**5 — Run the reader tests.** Report results.

**6 — Deliver.** Write the artifact with an **audience line**, an **as-of date**, and a **provenance block
marked internal**.

**7 — Capture.** What was stale, what contradicted what, what the sources couldn't answer. The gaps are a
finding in their own right — they usually mean a decision was never written down.

**At the scope target, ask who the reader is — it changes the rules.**

| | **internal handoff** | **external share** |
|---|---|---|
| reader | a teammate with repo access | outside the team or the org |
| repo paths | **keep them** — the reading path is the most useful thing in the doc | **none.** Inline the fact or drop it |
| internal identifiers (`§2.48b`, `M19`) | drop from the body; a named doc is fine | drop entirely |
| "we" / "our" | fine | rewrite to third person |
| provenance block | brief | mandatory, and marked internal |

Getting this backwards is a real cost in both directions: stripping paths from an internal handoff removes
its most useful section, and leaving them in an external one makes the doc unusable to the reader it was
written for.

### Progressive Detail for Docs

Four layers. The reader chooses a depth; each layer is complete at its own depth and names the next.

| layer | answers | length | audience |
|---|---|---|---|
| **S** | What is this? Why does it exist? Where do I start? | ≤ 1 page | anyone, first contact |
| **M** | What must it do, how is it built, what constrains it? | a few pages | someone about to contribute |
| **L** | The deep reference — specs, per-component detail, data models | as needed | someone implementing |
| **XL** | The record — epics, plans, debriefs, journals | unbounded | posterity; reached via provenance only |

Two rules that do most of the work:

- **The S layer must stand alone and name the reading order.** It is not an index of links; it is the
  shortest true description of the system, ending with *"read these next, in this order, for these
  reasons."*
- **XL is never linked from S or M as if it were reading material.** The epics are provenance, not
  documentation. Point at them from a provenance block, once.

#### Phased reading — the layers go *inside* the document

The most common failure here is subtle: a doc written at one altitude that ends with a reading list.
That is a table of contents, not progressive disclosure. The reader still has to consume the whole thing
to reach the part they needed, and the "next steps" list dumps them at the door of an L-grade spec.

**Build the phases into the artifact.** Each phase answers one question, is complete at its own depth, and
ends by naming what to read next *for that phase*. A reader stops at the phase that answered them. The
four-phase spine below generalizes across systems:

| phase | answers | for |
| --- | --- | --- |
| **What it is** | what is this, and why does it exist? | anyone who needs to talk about it |
| **What it can and can't do** | the domain model, the pipeline, the real limits | someone scoping or reviewing work |
| **How it's built** | code map, data flow, where to make changes | someone about to change it |
| **Where it stands** | status, open questions, what else is going on | someone planning or deciding |

Two things make this work rather than just look tidy:

- **Show, don't characterize.** Phase 1 of anything rule-driven, schema-driven or config-driven needs a
  **real example, quoted verbatim and annotated line by line**. One concrete artifact does more than three
  paragraphs describing its shape — and quoting it forces you to read it.
- **Phase 2 must state the limits.** What the system *cannot* express is the highest-value content in the
  whole document and the most likely to be missing, because sources describe what was built. Look
  specifically for: escape hatches and their governance, features specified but unproven, dependencies on
  something upstream, and things deliberately excluded from the model.

### Aggregation

The harder half. When the material lives across many epics, the reader needs more than a concatenation.
Four moves, taken from a working example (see `references/doc-templates.md`):

- **The through-line.** What single question does this body of work answer? Say it in a sentence, then show
  how the parts relate — a loop, a pipeline, a layering. Name it if the relationship isn't a straight line.
- **The overlap map.** The same entity recurs under different names across epics. Tabulate it: *entity ·
  how it appears in each source · the watch-out.* Without this, a reader counts one thing as three.
- **What is not comparable.** Where numbers come from different populations, say so explicitly and say
  "don't cross-add." Where two things share a name but not a meaning, separate them.
- **One honest through-line.** The conclusion the sources converge on, including the unflattering part.
  A handoff that only carries good news isn't a handoff.

## The Epic Target

A front door for one epic, written for a cold reader: a collaborator, someone taking it over, or the original author
after a pause. The work docs stay as they are; the overview is derived from them on demand, in any state.

1. **Read the whole epic**, plus the project's STATUS line about it. List the files and their sizes first. Most of an
   epic's bulk is process residue (plans' step lists, gate results, debrief bookkeeping, raw data); note it and skip
   it.
2. **Name what the epic produced** (a list of changes, a feature, a decision, findings, design reasoning) **and
   propose a variant**, with a one-line reason: **epic full** for new features, strategic or conceptual work, spikes,
   and rebuilds; **epic condensed** for maintenance, cleanup, and tweaks. If neither fits, say so and propose the
   lighter answer. The human confirms before you write.
3. **If the epic has a hand-written `README.md`**, read it as a source. The overview sits beside it and never
   replaces it.
4. **Draft from the template** in `references/doc-templates.md` (*The Epic Overview*). Write "Where it stands" last,
   from the latest evidence rather than any status header, even though it appears near the top.
5. **Run the reader tests** (below) and report the results.
6. **Write `overview.md`** in the epic folder, with its as-of date and source. To refresh it later, re-run this
   target: re-derive the overview from the sources; don't patch it. Other skills don't maintain it.

## Shared by Every Target

### Inventory first

List the candidate sources and their sizes. A word count per doc is the cheapest signal there is; if the set
totals 30,000 words with no entry point, that is the finding, before you read a line.

**Enumerate the whole set before diagnosing anything — and specifically look for an existing map or index**
(`docs/README.md`, an epic `README.md`, a doc atlas). Diagnosing from the two or three documents you happened
to open produces a confident, wrong diagnosis, and the wrongness runs in the expensive direction: you
conclude something is missing and build a duplicate of what already exists. If the project has already
solved part of this, that is the most important thing to learn in step 1, not step 5.

### The Five Failure Modes

This is the diagnostic core. Run it against the existing docs before writing anything, at every target.
Most of these are greppable, which is what gives this skill verification with teeth
rather than prompt pressure.

**1 — Addressed to the operator.** *"Three criteria **you** set." "**Your** decision." "weight a
measurement **I** hand you."* The reader isn't reading a document, they're eavesdropping on a conversation
between one human and one agent. **Fix:** third person about the system. The system has properties; nobody
in the document has a conversation.

**Check — and the distinction matters, or the check produces false positives:**

| form | verdict |
|---|---|
| second person presuming the reader made the decisions — *"the criteria **you** set"* | **fail.** Assumes the reader is the operator. |
| first person singular — *"**I** measured", "**my** explanation was withdrawn"* | **fail.** There is no "I" in a document. |
| a role word standing in for a person — *"the operator was right"* | **fail.** |
| second person addressing *any* reader — *"**you** will see", "read this first"* | **fine.** Ordinary documentation voice. |
| first person plural — *"**our** own authorship"* | **audience-dependent.** Correct for a teammate inside the org; wrong for an external share. |

**2 — The self-correction record.** The agent's revision history embedded in the artifact: *"this count was
wrong four times", "retracted the same day", "my first explanation was withdrawn"*, ⚠/⭐ annotation on every
other claim. This is high-value trust calibration **for the operator** and noise for a reader who needs to
know what the system does. **Check:** density of ⚠/⭐/**RETRACTED**/**CORRECTED** markers; any paragraph
whose subject is a previous version of the document. **Fix:** state the current fact. Where the history
changes how much to trust a number, say so once, plainly, in a caveats section — not inline on every claim.

**3 — Status where structure is needed.** *"Where does it stand"* presupposes knowing what "it" is. A
newcomer needs what-it-is → how-it's-built → what-constrains-it → where-it-stands, in that order.
**Check:** does the doc define the system before reporting on it? **Fix:** structure first, status last,
status short.

**4 — Unresolvable references.** `§2.48b`, `S114`, `M19`, `follow-ups.md`, bare repo paths. **Check:** grep
for `§`, `M<n>`, `S<n>`, `.md`, `src/`. **Fix:** by reader. A reader with the repo (the project's contributor
documents, the epic target, an internal handoff) can follow repo paths and links into it, not internal IDs: name
them, or drop them as the scope table says. Outside the repo (the project's observer and practitioner documents, an
external share): inline the fact or drop it; provenance goes in a block marked internal. Nothing links outside the
repo.

**5 — No landing.** No start-here, single altitude, no ordering across a multi-doc set. **Check:** can a
reader tell, in thirty seconds, which document to open first and why? **Fix:** the tl;dr (project), the S
layer (scope), the overview (epic).

### The Reader Tests

Verification before claiming done. Run all five (the project target adds two checks); report the results,
don't assert them.

1. **The stranger test.** Read the draft as someone who has never met this project: a colleague who has the
   repo and knows the domain, or, for an external share, someone who cannot open the repo. Where do you
   stop? That's the defect.
2. **The pronoun sweep.** Grep the draft for first- and second-person subjects. Every hit is failure mode 1
   unless it's in a quoted decision.
3. **The claim check.** Every structural claim — directories, components, counts, "currently implemented" —
   verified against the actual repo **in this session**. This is where drifted docs are caught; one project's
   README listed three packages that don't exist and omitted one that does. Recollection is not a source.
4. **The contradiction sweep.** Read the docs *against each other*. Two root docs disagreeing about what the
   repo contains is worse than either being stale alone, because the reader can't tell which to trust.
5. **The citation check — read everything you send the reader to.** Every document named in a reading path
   must have been read *in this session*, at least well enough to say truthfully what it answers and why it
   is worth the reader's time. Routing someone to an unread document is the same failure as asserting an
   unread fact, and it is worse in one way: it is invisible, because the recommendation looks identical
   whether or not you opened the file. Where you genuinely could not read a source in full, **say so in the
   provenance block** and name which claims therefore came second-hand. A reading path is a set of claims
   about documents, and claims get verified.

### Discipline

**Don't invent to fill a template.** If the sources never state the constraints, the answer is "the
constraints aren't written down anywhere" — surface it as a gap and ask. A confident invented requirement is
worse than an acknowledged hole, because it will be believed. This is the *Clarify before Asserting* failure
this skill is most exposed to: the template creates a slot, and the slot creates pressure to fill it.

**Don't launder uncertainty.** Making prose readable must not make a hedged finding sound settled. If a
number needed three attempts, the reader deserves to know its confidence — once, plainly, not as a
running correction log.

**Match the depth to the ask.** A request to hand off one module is not a request to document the project.

### Update STATUS.md (and journal)

If this produced or promoted a doc, update STATUS.md before closing out.

Follow the **STATUS reflex** in `references/ground-rules.md` — fix, subtract, stamp.

### What's Next

If the docs revealed that requirements or constraints were never written down, that's `/michi-explore` or
`/michi-planning` work, not documentation work. If the drift is broad enough to be structural, check
`/michi-sustainability` — its Doc Drift Audit and Archive Candidates sub-modes handle the repo-shaped
version of this problem.