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.
When to use
Section titled “When to use”- Bug fixes with clear scope
- Small features or focused improvements
- Quick investigations where a separate
/michi-explorefeels like overkill - Targeted refactoring within a known area
- Any work that doesn’t warrant a formal plan doc, verification scenarios, and structured debrief
What it does
Section titled “What it does”The skill encodes the questions Michi asks, not the artifacts Michi produces. Artifacts emerge when the work demands them.
Six disciplines apply throughout:
- Surface assumptions. Before acting, state what you’re assuming. Name new assumptions as they appear. When you’re wrong, say so.
- 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.
- 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. - 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.
- 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.
- 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).
What it produces
Section titled “What it produces”- A write-up that rolls up by scope. There is no
docs/workshop/directory. Inside an active epic, learnings go to the epic’sjournal.md, or toplans/<plan>.mdfor a milestone-sized step. A substantive workshop with standalone design decisions becomes a flat-file epic atdocs/epics/<topic>.md. Bug fixes and small workshops get adocs/journal.mdentry. 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 todocs/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
Key things to know
Section titled “Key things to know”- 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-explorefor “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.