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 factory.

When to use

• 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

What it does

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

Five 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. 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. If you need a formal plan doc with exit criteria, you need the full factory.
3. 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.
4. 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.
5. 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.

The natural flow: Orient (read the code, understand context) 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

• Workshop doc at docs/workshop/<topic>.md — a compressed document with plan, results, and learnings in one place. Not every workshop produces a doc; sometimes the code and commits are the artifact.
• STATUS.md update if the project state changed
• Code changes with tests

Key things to know

• The workshop is deliberately lightweight. If the workshop doc is growing past a page, 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.