michi-sustainability
The sustainability skill assesses long-term system health. It is a menu-driven review that scales from a quick check on recent work to a deep between-epic retrospective. The session skill includes a brief sustainability step before each commit; this skill is for broader reviews that don’t fit inside a milestone’s implementation flow.
When to use
Section titled “When to use”- Within a milestone (10-15 min) — focused check on work just completed, when the built-in session sustainability step isn’t enough
- Between milestones (30-60 min) — review accumulated work across the current epic before starting the next milestone
- Between epics (1-2 hours) — deep review of overall direction, design coherence, and process health before starting new work
What it does
Section titled “What it does”The skill presents a menu of review areas. You select what’s relevant — not everything applies every time.
Code quality. Scan recent changes for duplication, unclear naming, functions doing too many things. Check separation of concerns — could you reuse the logic with a different UI? Flag dead code from recent work.
Test quality. Are mocks at I/O boundaries (not between internal modules)? Do test names describe behavior? Is test data human-readable? Do tests assert on outcomes rather than implementation details? Is the suite fast enough for tight feedback without being so shallow it loses meaning?
Architectural alignment. Does accumulated code match the intended architecture? Has design drifted in a direction that should be acknowledged or corrected? Are naming conventions and patterns consistent? For multi-package projects, are boundaries clean and contracts explicit?
Knowledge and questions. Review open questions — any resolved by recent work? New ones raised? Capture learnings and gotchas in the journal. Check planning-phase assumptions that turned out wrong. Look for applied coding principles in the codebase that aren’t yet documented in code-style.md. Review docs/memory.md for stale or superseded content.
Direction (between-epic scope). Does the overall trajectory still make sense? Are we living the north stars or drifting? Is the knowledge base current? What should change about how the next epic is run? Should the autonomy mode (Paired vs. Entrusted) change based on demonstrated quality?
Beyond the menu, there are four optional sub-modes. None has its own command: the agent offers one when it sees the signals, and runs it only if you agree.
- Reuse audit. Scans one module or directory at a time for hand-rolled code that a well-maintained library would replace with a real simplification. It reports recommended replacements and a table of candidates it evaluated and skipped, with the reason for each.
- Doc drift audit. Reads the docs in scope cold and checks every concrete claim (a path, a function, a procedure) against the current code. Each finding is wrong, stale-ish, or current, and current docs get their
last-verified:stamp refreshed. It also measures the token tax — everything loaded into context before any work starts. The agent can’t measure this itself: it asks you to run/contextand paste the output, then records one dated line in the project journal and flags docs that are growing or oversized. Cuts follow one rule: what is essential stays; stale, wrong or duplicated content goes. You approve before anything is removed. - Doc compress. The first step in closing an epic. It rewrites the epic’s
spec.mdto describe what was actually delivered (keeping any unmet requirement, marked as not met), after checking that each change to existing behavior has its record in the project-level journal, and itsverification/test-plan.mdas a short overview, promotes anything of lasting value to project-level docs with your confirmation, and deletes the rest: per-milestone plans, milestone debriefs, scratch notes. You review the compressed directory before anything is archived. - Archive candidates. The second step. It lists closed epics, finished sidebars and superseded reference docs to move under
docs/archive/, with a date suffix such asdocs/archive/epics/chat-plugin-050126/. Once you approve, the moves run withgit mv, by you or by the agent as your project’s git policy says; for a sweep of more than about five files the agent confirms the full list first.
What it produces
Section titled “What it produces”- Findings logged in the plan doc’s Notes section (within-milestone) or the epic’s journal (between milestones/epics)
- Action items — immediate fixes (refactoring, test additions) or items deferred to the next milestone’s plan
- Discussion items for human review
- Process observations about methodology, captured in the journal
- Reuse audit report, if that audit runs: recommended library replacements, file by file, and the candidates evaluated and skipped
- Doc drift findings, if that audit runs: a per-doc list plus a summary table of docs audited, wrong, stale-ish and current
Key things to know
Section titled “Key things to know”- This is a flexible skill — select from the menu based on what the current moment needs. A between-milestone check might only need code quality and test quality. A between-epic review might touch everything.
- The sustainability check explicitly looks for applied coding principles that are being followed in the codebase but not yet documented. This prevents good patterns from being lost between sessions.
- Memory hygiene is part of the knowledge review — pruning stale memories and challenging ones that have calcified into unexamined rules.
- Docs have weight as well as accuracy. The doc drift audit checks both: whether docs are still correct, and how much they cost in context on every turn.
- Doc compress and archive candidates change files in your repo: compress deletes and rewrites files in an epic directory, and archiving moves them with
git mv. Both wait for your approval. - If the sustainability check reveals significant drift or accumulated debt, it may indicate the need for a dedicated refactoring milestone in the next planning cycle.
For the full agent instructions, see the SKILL.md source.