---
name: michi-sustainability
description: >-
  Assess and maintain system health — code quality, test quality, architectural alignment, and knowledge capture —
  from a brief within-milestone check to a deep between-epic review. Optional sub-modes: reuse audit (libraries that
  would replace hand-rolled code), doc drift audit with token-tax measurement, doc compress at epic close, and
  archive candidates. Use between milestones or epics, when the user asks for a health check, or when closing,
  compressing or archiving an epic, auditing docs for staleness, or looking for code a library should replace.
---

# Michi Sustainability Check

Assess and maintain long-term system health. Invoke between milestones, between epics, or whenever accumulated work
needs a step-back review. This skill is **flexible** — select from the menu based on context and scale.

**Principles served:** Sustain the system (core purpose). Iterate spirally (each check leaves the system better for the
next iteration). Surface assumptions (identify drift or unchallenged assumptions). See `references/principles.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).

**Multi-project repos:** If the repo has `multi-project: true` in CLAUDE.md, name the scope at session start:

- **Sub-project scope:** review code/docs/tests under `tools/<name>/` + `docs/<name>/`.
- **Umbrella (ROOT) scope:** review umbrella-level code + `docs/ROOT/` working docs + repo-root CLAUDE.md /
  PROJECT.md / STATUS.md / ARCHITECTURE.md (umbrella identity docs live at repo root).
- **Cross-sub-project health checks** (shared infra, repo-wide coding standards): span all sub-projects; findings
  promote to repo-root CLAUDE.md (as repo-wide rules) or `docs/ROOT/reference/` (as cross-project patterns).

## When to Use

| Context                | Scope                                                      | Time      |
| ---------------------- | ---------------------------------------------------------- | --------- |
| **Within a milestone** | Light — focused on work just completed                     | 10-15 min |
| **Between milestones** | Medium — accumulated work across the current epic          | 30-60 min |
| **Between epics**      | Deep — overall direction, design coherence, process health | 1-2 hours |

The session skill includes a brief sustainability step before each commit (within-milestone scope). This skill is for
broader reviews that don't fit inside a milestone's implementation flow.

## Menu

Select what's relevant. Not everything applies every time.

**Framing findings.** As you work through the menu, categorize what you find into four buckets: **done** (working as
intended), **in progress** (partial, with known next steps), **known gap** (missing, but we know it's missing), and
**unknown gap** (missing, and we only just noticed). Unknown gaps are the valuable discoveries — the ones that wouldn't
surface without deliberate review. Name them explicitly so they don't fade back into invisibility.

### Code Quality, Test Quality, Architectural Alignment

Read `references/health-checklists.md` and work through its *Code Quality*, *Test Quality* and *Architectural
Alignment* checklists. (`michi-second-look` applies the same checklists from outside the session.)

### Knowledge and Questions

- [ ] **Question lifecycle** — Open questions: any resolved by recent work? New ones raised? Any open too long?
- [ ] **Journal update** — Capture learnings, gotchas, discoveries in the epic's `journal.md`. What would a future
      session need to know?
- [ ] **Discussion items** — Anything to raise with the human? Add to the plan doc's `## Discussion` or the epic's
      journal.
- [ ] **Assumption check** — Planning-phase assumptions that turned out wrong? New unstated assumptions to surface?
- [ ] **Applied coding principles** — Patterns in the codebase demonstrating design judgment not yet captured in
      `docs/reference/code-style.md`? Examples: a clean what/how separation, a well-structured test showing the
      project's testing philosophy, a naming pattern revealing intent. If undocumented, a future session may not follow
      them.
- [ ] **Memory hygiene** — Review `docs/memory.md` if it exists. Memories still accurate? Anything superseded by
      CLAUDE.md rules, code-style.md, or other docs? Prune what's stale. Challenge memories that have calcified into
      unexamined rules. Keep focused on collaboration patterns — if drifting toward journal territory, trim.

### Direction (between-epic scope)

- [ ] **Overall trajectory** — Does the direction still make sense? Has anything changed that should shift priorities?
- [ ] **Principles alignment** — Living the north stars (minimize latency, sustain the system) or drifting?
- [ ] **Knowledge base health** — Docs current? Anything important missing? Stale docs misleading?
- [ ] **Process retrospective** — What should change about how the next epic is run? Skill updates, template changes,
      verification improvements?
- [ ] **Trust calibration** — What mode are we in (Paired, Entrusted)? Should it change based on demonstrated quality?
      Reason to tighten the loop?

## Optional: Reuse Audit

The "Reuse Over Reinvention" principle says: prefer existing libraries over custom code when the library genuinely
simplifies. This sub-mode turns that principle into a systematic scan of a module or area. **Not default** — offer it
when the code shows the signals, then run only if the human agrees.

**Signals the code might warrant an audit:** see *Reuse Audit: Signals* in `references/health-checklists.md`. If
none are present, skip.

**If the human agrees to run the audit:**

1. **Scope it.** One module or directory at a time. Read every file in scope before evaluating anything — get the full
   picture of patterns and constraints (dependency injection, factory functions, etc.) before proposing changes.
2. **List candidates.** For each, note what it would replace, how many lines, and which files.
3. **Evaluate each candidate against the pass/fail criteria** in *Reuse Audit: Criteria*
   (`references/health-checklists.md`). A library earns its place only if it passes all of the positive criteria and
   none of the disqualifiers.

### Audit Output

Produce two sections. The second is as valuable as the first.

**Recommended replacements.** For each winner:

- What it replaces — specific functions, line ranges, files
- Package — name, weekly downloads, what it does
- Why it earns its place — net line reduction, duplication removed, edge cases delegated
- Edge cases — anything the library doesn't handle that the current code does; how to bridge (options, thin wrapper)
- Changes needed — file-by-file
- Test impact — which existing tests should still pass, which may need adaptation

**Evaluated and skipped.** Table form:

| Candidate | Verdict | Why |
|-----------|---------|-----|
| `deepmerge` for X | Skip | Current merge is shallow. 30 lines of clear code. |
| `execa` for Y | Skip | Would force sync→async. Small gain, large ripple. |
| `chalk` for Z | Skip | UX improvement, not simplification. Different initiative. |

The skipped table documents the thoroughness of the audit and explains why seemingly obvious replacements were
rejected. Don't skip the skipped table — it's the record that the judgment was applied, not just the wins.

## Optional: Doc Drift Audit

A safety net for currency gaps that escaped recent debriefs. Sustainability is a layer of defense beyond the per-debrief
Pass 2 — that pass is scoped to the just-shipped milestone; this audit is cross-project and catches what individual
debriefs missed.

**Signals the project might warrant a doc-drift audit:**

- Multiple milestones have shipped since the last sustainability check
- Recent sessions have touched mechanisms referenced in `docs/reference/` (env files, build/deploy commands, file
  layouts, named tools or scripts)
- A human or agent recently encountered a stale doc by accident (the IDE flagged it; a question revealed it; a
  cold-start session got tripped up)
- ARCHITECTURE.md hasn't been touched in 2+ epics
- The auto-loaded docs have grown since they were last measured, or have never been measured

If none of these, skip — the per-debrief Pass 2 is doing its job.

**If the human agrees to run the audit:**

1. **Scope it.** Either "all of `docs/reference/`," "ARCHITECTURE.md," or a specific subset. Don't try the whole corpus.
2. **For each doc in scope:** read it cold. For every concrete claim (a file path, a function name, a tool, a procedure,
   an env-file convention), verify against current code or current state.
3. **Categorize findings:**
   - **Wrong** — the doc states something contradicted by current reality. Fix or flag.
   - **Stale-ish** — the doc isn't wrong but is missing recent additions. Note for next debrief.
   - **Stamp-only** — the doc is correct; refresh the `last-verified:` stamp.
   - **Growing / Oversized** — from the measurement below.
4. **Output:** a findings list (per-doc, per-finding) plus a summary table — "audited / wrong / stale-ish / current."

**Measure the token tax.** Correctness is half of currency; the other half is weight. The token tax is what sits in
context on every turn before any work starts — system prompt, tools, skills, and the auto-loaded docs. Ask the human
to run `/context` and paste it: the agent cannot run it, and it is the real number, where a byte count is an estimate.
The *Memory files* section shows the whole doc chain — `CLAUDE.md` and its `@`-refs, `.claude/rules/` pointers, the
user profile. The docs are the part this audit can change; keep the whole tax in view while working on them.

- Record one dated line in the project journal: the total at session start, the memory-files figure, the project's
  share, the three largest files, the active profile and mechanisms attaching the measured material, and the
  effective client/model/effort. Mark unavailable fields unknown; do not infer them.
- Compare with the last recorded line. **Growing** — larger than last time with no matching growth in what is in
  flight. **Oversized** — one file dominating the chain, or a doc loading that no current work needs. (A rough guide,
  not a rule: a tax under ~50k tokens is comfortable; toward ~80k it is worth attention.)
- For each finding, propose the cut by the same rule every time: what is essential stays; stale, wrong or duplicated
  content goes; content in the wrong place moves to the right one; older material need not be preserved in full. The
  human approves before anything is removed.
- Anything in the list that is not this project's — another profile's instructions, a stray import — is a finding for
  the human. It cannot be fixed in the docs.

The skipped table discipline applies — record what you read and judged current, not just what you fixed. That's the
record that the audit was actually thorough.

## Optional: Doc Compress

Epic-close compression. Pairs with Archive Candidates as a two-step closing flow: **compress → archive**.
Use when "this epic is done," before the directory moves to `docs/archive/`.

Most Michi docs support work-in-progress — plans, per-milestone debriefs, journal entries, scratch notes,
drafts of decisions. They earn their weight *during* the epic. After the epic ships, that weight competes with
active work for the reader's attention and adds nothing the code itself doesn't already convey.

**The codebase is the authoritative source.** Doc mass that duplicates or competes with what's in the code is a
tax on future sessions — agent and human alike. Compression cuts the tax. What survives is what the code cannot
deliver: a primer pointing at where key things live, an explanation of *why* a decision was made, context that
wouldn't be obvious from reading the diff.

**Scope:** the closing epic's `docs/epics/<epic>/` tree, or any analogous closing directory with comparable
doc mass.

### What Survives

Only these:

- **Revised `spec.md`** — rewritten to reflect what was *actually delivered*, not what was originally proposed.
  Overview of the real requirements; summary of the final milestones (which often diverge from the original
  plan). Captures result, not the messy path that got there — **and what was asked for and not delivered.** A
  requirement that was dropped, narrowed or deferred stays visible as such, with the reason if it is known.
  Compression shortens the record; it does not turn an unmet requirement into a success.
- **Revised `verification/test-plan.md`** — overview of how the epic was verified. Light on details; the automated tests
  are the long-lived artifact, and this doc points at them and explains the approach.
- **`memory.md`, `journal.md`, `STATUS.md` if local to the epic** — preserved as historical record of how the work
  unfolded.

Everything else gets cut: per-milestone plans with checked-off steps, individual milestone debriefs, drafts of
decisions that have since landed in code, scratch notes, exploration docs whose conclusions have been absorbed
elsewhere.

### The Test

For anything you're tempted to keep in place, ask: *can a future reader get this from the code alone?* If yes,
cut.

For anything you're tempted to cut, ask: *will someone in six months need this — to understand **why** a
decision was made, or **where** to find a key piece of the system?* If yes, the right move is usually
**promote** to a project-level reference doc, not keep in place. The epic dir is not a permanent home.

### Procedure

Work through these in order:

1. **Inventory** the epic's docs. List what's there so the cut/promote/revise decisions are visible.
2. **Promote** non-survivor material that has value beyond the epic. Confirm each promotion with the human —
   the call of "earns a permanent home" is the human's. Common targets:
   - Patterns → `docs/reference/patterns.md` (or `patterns/<category>/<slug>.md` if the project uses the
     hierarchical convention).
   - Landmarks and durable decisions → project-level `docs/memory.md` Landmarks section or
     `docs/reference/key-decisions.md`.
3. **Revise `spec.md`** — rewrite as an overview of actual requirements and the milestones actually shipped.
   Drop original-plan *detail* that didn't survive. Keep any original *requirement* that was not met, marked as
   not met.
4. **Revise `verification/test-plan.md`** — light overview of the verification approach. Point at the long-lived
   automated tests rather than restating them.
5. **Cut** plans, per-milestone debriefs, scratch notes, in-progress discussion docs that have served their
   purpose. Keep any epic-local `memory.md` / `journal.md` / `STATUS.md`.
6. **Present the compressed directory for human review.** Surface what survived, what was promoted where, and
   what was cut. Human approves before Archive Candidates runs.

### Hand-off

Compress is step one of a two-step closing flow: **compress** (revise + promote + cut) → **archive** (`git mv`
to `docs/archive/epics/<name>-MMDDYY/`). They're intentionally separated — compression involves judgment;
archive is mechanical. Keep them distinct so the judgment work has a clean review point before the move.

## Optional: Archive Candidates

Looking for `docs/` artifacts that should be moved to `docs/archive/`. This is a sustainability responsibility, not
a debrief one — debriefs are scoped to the just-shipped milestone and rarely cross over to "what about that closed
epic from three months ago." The longer the gap between archive sweeps, the more accumulation sits next to active
work, making it harder to see what's current.

**Scope of this sub-mode:** `docs/epics/`, `docs/reference/`, and `docs/sidebars/` if it exists in this project.
**Not** memory.md or STATUS.md — those have their own hygiene and belong to debriefs. Don't lump them in here.

**Signals worth a scan:**

- An epic just closed (and its dir is sitting in `docs/epics/` next to active work)
- `docs/epics/` contains directories for milestones long shipped, where new sessions wouldn't read them
- `docs/sidebars/` has entries whose findings have fully landed in reference docs or epic plans
- A reference doc has been explicitly superseded — by another doc, by a memory rule flagging it as misleading, or
  by a code-level change that invalidated its contents
- A multi-epic period has passed since the last archive sweep

**Candidates to surface (with one-line justification each):**

- Closed epic directories → `docs/archive/epics/<name>-MMDDYY/`
- Sidebars whose output is captured elsewhere → `docs/archive/sidebars/<name>-MMDDYY.md`
- Reference docs explicitly superseded → `docs/archive/reference/<name>-MMDDYY.{md|json|...}`

### The `-MMDDYY` Suffix Convention

Archived names carry a date suffix indicating when the move happened. Format is **MMDDYY** (e.g., `050126` for
May 1, 2026):

- Folder: `docs/archive/epics/chat-plugin-050126/`
- File: `docs/archive/sidebars/v2-legacy-deploy-050126.md`
- File: `docs/archive/reference/elasticsearch-bookmarks-mapping-050126.json`

Two purposes: (1) you can tell at a glance when something was archived; (2) it prevents name conflicts if the
original name is reused later (a new "chat-plugin" epic doesn't collide with the archived one).

Use `git mv` for git-tracked artifacts to preserve history. Who runs it follows the project's git policy
(CLAUDE.md): the human, or the agent where the policy allows it. For bulk archive sweeps (more than ~5 files),
surface the list and confirm before running.

### Don't Archive

- Sidebars or epics inside the active epic — wait for the whole epic to close, then archive together
- Reference docs the human still actively cites (`code-style.md`, `local-dev.md`, etc.) even when contents look
  stale; staleness is a debrief Pass 2 concern, not an archive concern
- Anything that other epics still cite as historical record. Cross-references in journals are fine; the original
  doc often still earns shelf space if newer work cites it

The human decides what gets moved. Archiving is destructive-feeling and benefits from a human eye on each call.
Surface candidates in the findings; once approved, the `git mv` runs per the project's git policy (confirm the full
list before bulk sweeps).

## Output

The sustainability check produces:

1. **Findings** — logged in the plan doc's `## Notes` (within-milestone) or the epic's `journal.md` (between
   milestones/epics)
2. **Action items** — immediate fixes (refactoring, test additions) or deferred items for the next milestone's plan
3. **Discussion items** — questions and observations for human review
4. **Process observations** — insights about methodology → epic's `journal.md`

**Inputs-vs-outputs check before finalizing.** Sustainability checks often read substantial source material — recent
commits, multiple files, journals, prior debriefs. Before closing out, ask of each significant source what it held that
must survive — a decision, a constraint, an open uncertainty, a piece of evidence — and check each is in the findings.
Use the inputs as a checklist for those, not for volume: three findings that kept them beat thirteen that restate
what was read.

### Update STATUS.md (and journal)

If the sustainability check produced findings that shift what's active or what's next, or if it changed the project's
health picture, update STATUS.md before closing out — and the relevant `journal.md` if you wrote to it.

Follow the **STATUS reflex** in `references/ground-rules.md` — fix, subtract, stamp. Not conditional on "anything
significant changed."

For deeper checkpoint-style outputs (readiness assessments, milestone-end reviews), `references/checkpoint-doc-formats.md`
offers optional structured formats — Readiness Checklist, Assessment-doc tables, Operational Guide. Use when the
lightweight Output above isn't enough.