How-To FAQ
Questions that come up while using Michi. For “what is Michi and why” questions, see the introduction FAQ.
Do I have to bootstrap? Can’t I just start?
Section titled “Do I have to bootstrap? Can’t I just start?”Bootstrap once, per project. It creates the doc structure — CLAUDE.md, PROJECT.md,
STATUS.md, the docs/ layout — that every other skill reads and writes. Without it, each
session starts cold. It’s a one-time cost; see Bootstrap Michi. After
that you never run it again (except to close gaps).
Do I need the full plan → session → debrief process for every change?
Section titled “Do I need the full plan → session → debrief process for every change?”No. That’s the epic process — for multi-milestone work. A bounded
change — a flag, a small feature, a bug fix — uses /michi-workshop,
which runs the same iteration cycle with far less ceremony. Match the ceremony to the work.
Workshop is about less ceremony, never less rigor.
How do I tell a task from an epic?
Section titled “How do I tell a task from an epic?”If the work fits one focused pass, it’s a task — use a workshop. If it needs planning and lands in stages, each producing something that works, it’s an epic. When in doubt, start as a workshop; if it grows, escalate.
The work turned out bigger than I expected mid-task. Now what?
Section titled “The work turned out bigger than I expected mid-task. Now what?”Escalate. If a workshop reveals a design decision, a schema change, or work spanning multiple
systems, stop and switch to /michi-planning. Escalating is the
correct response to discovering the work is larger than it looked — not a failure. The
task guide covers the escalation signals.
What’s the difference between Paired and Entrusted mode?
Section titled “What’s the difference between Paired and Entrusted mode?”Paired — you’re present, in a tight loop, reviewing each step. Entrusted — the agent has wider initiative and you review at gates. The first epic on any project is always Paired; Entrusted is earned once verification infrastructure and shared context can carry the autonomy. Moving back to Paired when something is uncertain isn’t regression. See Modes.
The agent says it’s done — how do I know it actually is?
Section titled “The agent says it’s done — how do I know it actually is?”This is the most common failure mode: “done” defaults to “code written, unit tests pass.” That’s necessary, not sufficient. Real verification runs the scenarios co-designed in planning and checks the acceptance criteria one by one. If the agent says “I believe it passes” or “pending your review” without showing output — push back. Evidence before claims: run the command, read the result. See Verification.
The agent keeps making the same mistake. What do I do?
Section titled “The agent keeps making the same mistake. What do I do?”That’s its own use case — Improve Your Agent Practice. Export
your session transcripts and read them: a correction that recurs is a missing or poorly-stated
rule. Fold it into CLAUDE.md. A permission prompt that recurs is a tuning problem. The fix
comes from the evidence in the transcripts, not from guessing.
Does Michi work for non-code work — research, docs, planning?
Section titled “Does Michi work for non-code work — research, docs, planning?”Yes. The iteration cycle is the same; only what you verify against changes — exit criteria instead of test scenarios. Research and Explore is built for investigative work, and epics can be non-code (a research effort, a roadmap, a documentation push).
How do I keep a long effort from drifting?
Section titled “How do I keep a long effort from drifting?”The plan doc. It’s a contract — scope, acceptance criteria, verification — written before implementation and checked against during it. It survives context compaction when conversation memory doesn’t. And each milestone’s debrief feeds the next one’s planning, so later milestones build on what earlier ones learned instead of repeating them. See Plan Docs.
Do I need all the skills?
Section titled “Do I need all the skills?”No. The core loop is bootstrap, planning, session, debrief. Workshop covers small work; explore covers investigation. The rest (sustainability, pr-prep, scenario-test-builder, docs-site) you reach for when the work calls for them. The cheatsheet maps each use case to the skills it actually needs.
What’s the iteration cycle, in one line?
Section titled “What’s the iteration cycle, in one line?”Explore → Brainstorm → Plan → Execute → Verify → Document — applied to every piece of work, at every scale, each pass leaving you with more than you started. It’s the backbone every guide here runs on. See The Iteration Cycle.