Skip to content
Michi v2026.11.16
Save the Tokens

michi-workshop

The workshop skill is Michi’s everyday carry tool. It applies the same rigor as the full planning-session-debrief lifecycle but with less ceremony. Use it for work that fits in your head — when the pocket Leatherman is enough and you don’t need the full cycle.

  • Bug fixes with clear scope
  • Small features or focused improvements
  • Quick investigations where a separate /michi-explore feels like overkill
  • Targeted refactoring within a known area
  • Any work that doesn’t warrant a formal plan doc, verification scenarios, and structured debrief

The skill encodes the questions Michi asks, not the artifacts Michi produces. Artifacts emerge when the work demands them.

Six disciplines apply throughout:

  1. Surface assumptions. Before acting, state what you’re assuming. Name new assumptions as they appear. When you’re wrong, say so.
  2. Mind the Complexity and Uncertainty. Small is not the same as safe. On load-bearing logic, tightly constrained brownfield code, an ambiguous named pattern, or a codebase the agent hasn’t worked in, the workshop keeps its light ceremony but tightens the posture: shorter turns, more checkpoints, Crawl/Walk pacing. When the reading is Mixed, the agent confirms pacing with you before defaulting to Run.
  3. Plan and agree. Always make a plan, always get agreement. The plan scales to the work — a few bullets in conversation for small tasks, a brief written plan for medium tasks (a flat-file epic at docs/epics/<topic>.md, the active epic’s plan dir, or a journal entry). If you need a formal plan doc with exit criteria, you need planning and session.
  4. Verify before claiming done. Three questions, answered before starting: How will you know when you’re done? How can you verify it? How will you demonstrate nothing broke? Then use TDD, run the full test suite, and flag new scenarios that emerged.
  5. Capture decisions. When a choice is made, note what was decided, what the alternatives were, and why. A few sentences is fine — but captured, not lost.
  6. Know when to escalate. The hardest discipline. Recognize when scope is expanding, decisions affect things outside this task, or you need verification infrastructure you don’t have. Flag it and let the human decide whether to switch to a full session.

Bug-fix mode. Invoked as /michi-workshop bugfix <description> or /michi-workshop bug <description>, the workshop takes a leaner posture: reproduce and diagnose the root cause first, fix only this bug, and turn the reproduction case into the regression test before running the full suite. Docs are light by default, usually a docs/journal.md entry, and the agent asks you if more seems warranted. If the fix turns out to need design discussion or touches several subsystems, it offers to switch to a full session.

The natural flow: Orient (read the code, understand context; if the work sits inside an epic with a north-stars.md, read that too, since a quick fix that trades one of your fixed points is not quick) then Agree (state plan, answer verification questions) then Work (implement with TDD) then Verify (full test suite, demonstrate it works) then Capture (write up what happened).

  • A write-up that rolls up by scope. There is no docs/workshop/ directory. Inside an active epic, learnings go to the epic’s journal.md, or to plans/<plan>.md for a milestone-sized step. A substantive workshop with standalone design decisions becomes a flat-file epic at docs/epics/<topic>.md. Bug fixes and small workshops get a docs/journal.md entry. For a trivial fix, the commit message can be the whole record. If the work changed behavior that users, callers or other projects already relied on, the workshop also writes a Behavior change: paragraph to docs/journal.md (what it was, what it is now, what relies on it), since a workshop usually has no debrief to do it.
  • STATUS.md update if the project state changed
  • Code changes with tests
  • The workshop is deliberately lightweight. If the scope is expanding, or you’re making decisions that affect things outside the task, that’s a signal to escalate to full Michi.
  • “Same rigor, less ceremony” is the operating principle. Assumptions still get surfaced, verification still happens, decisions still get captured — just without the formal plan doc, scenario co-design, and structured debrief.
  • Investigation is part of workshop. You don’t need a separate /michi-explore for “let me understand this bug before fixing it.”
  • After a workshop, if the work stayed small, you’re done. If it grew, escalate to /michi-planning. If it revealed something worth investigating further, /michi-explore.

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