Mikado Method Skill
A skill for guiding developers through the Mikado Method: a disciplined, graph-driven approach to safe, incremental refactoring that keeps the codebase in a working state at all times.
What is the Mikado Method?
Named after the Pickup Sticks game (Mikado), where you must remove the topmost sticks without disturbing the pile before reaching the high-value stick at the bottom. In software, your goal (the "Mikado") sits beneath a pile of dependencies. The method surfaces those dependencies visually so you can remove them one by one, safely.
Core Definitions
| Term | Meaning |
|---|---|
| Goal | The root node. What you ultimately want to achieve. Circle it twice. |
| Prerequisite | A dependency that must be resolved before its parent node can be done. |
| Leaf node | A node with no further prerequisites. Safe to implement immediately. |
| Mikado Map | The full tree of goal + prerequisites. Your "save game" for the refactoring. |
| Revert | Undoing all changes to return to a stable state. The map survives; the broken code does not. |
The Core Loop
1. SET GOAL → Write the goal as the root node. Circle it twice.
2. BE NAIVE → Attempt to implement the goal directly in the code.
3. OBSERVE BREAKS → Compiler errors, failing tests, or broken behavior = prerequisites.
4. MAP → Add each prerequisite as a child bubble connected to the current node.
5. REVERT → Undo ALL changes immediately. Return to green/stable state.
6. PICK A LEAF → Choose any leaf node (no children) and repeat the loop from step 2.
7. COMMIT LEAF → Once a leaf is implemented cleanly without breakage, commit it.
8. PRUNE THE GRAPH → Remove the committed leaf. Reveal new leaves. Continue upward.⚠️ The revert step is non-negotiable. It feels counterintuitive to throw away "hard work," but the thought process IS the work — it produced the map.
Quick Reference Card
MIKADO LOOP
───────────
① Write goal (root) → circle it twice
② Attempt naively in code
③ Every error = a prerequisite bubble
④ REVERT (always, immediately)
⑤ Pick a leaf → repeat from ②
⑥ Leaf passes cleanly → commit → prune
⑦ Repeat until goal is reached
RULES
─────
• Never build on broken code
• One atomic change per commit
• No behavior changes in refactoring commits
• Leaves only touch one concern
• The map is the work — protect itCommon Mistakes to Correct
| Mistake | Correction |
|---|---|
| Fixing errors in place instead of reverting | "Revert now. Add these errors as prerequisite nodes instead." |
| Building on top of broken code | "This violates the core rule. Revert to green before continuing." |
| One giant commit with multiple changes | "Split into one commit per leaf node." |
| Skipping the graph for "small" refactors | "Start with even a 3-node graph. It prevents scope creep." |
| Using mocks to avoid test data setup pain | "Use Test Data Builders as Mikado leaf nodes instead." |
| Long-lived refactoring branches | "Work on main. Only commit leaves that don't break anything." |
Output Format
When helping a user apply the Mikado Method, always produce:
1. The Mikado Map (Mermaid diagram)
graph TD
G(["🎯 GOAL: <goal name>"]) --> P1["Prerequisite A"]
G --> P2["Prerequisite B"]
P1 --> L1["🟢 Leaf: step 1"]
P1 --> L2["🟢 Leaf: step 2"]
P2 --> L3["🟢 Leaf: step 3"]Use 🟢 for current leaves, ⬜ for unreachable prerequisites, ✅ for completed nodes.
2. Ordered implementation plan
A numbered list of leaf-first steps, each with the atomic refactoring gesture, a one-line verification test, and the suggested commit message.
3. Revert reminder
After any naive attempt: "Revert now — git checkout. — your map is saved, the broken code is not needed."
Read On Demand
| Read When | File |
|---|---|
| Starting a graph, populating prerequisites, evaluating leaves | Graph Building |
| Execution order, committing strategy, legacy code, large refactors, hygiene rules | Execution & Situations |