| name | mikado-method |
| description | Enforce and guide the Mikado Method for *large, graph-driven* refactors where a single naive change cascades into many failing call sites. The skill enforces the full Mikado loop: goal → naive attempt → map prerequisites → revert → implement leaves → commit → repeat.
TRIGGER when: user mentions Mikado Method, dependency untangling, circular dependencies, "breaking everything" on a refactor, change cascading across many files, ripple effects, large-scale legacy refactor with tight coupling, untangling tightly-coupled modules, splitting a big refactor into safe steps, or wanting to work on main without a long-lived feature branch. Also trigger on "graph-based refactor", "prerequisite tree", or "Mikado graph".
DO NOT USE when: the change is small/in-place (single method, single class, simple rename) — use `refactoring` instead for code smells and Extract Method-style work. If the feature hasn't been scoped yet, consider `kano` first to validate it's worth doing.
|
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. |
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 it
Common 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 |
Benchmark
Scenario: .benchmarks/scenarios/mikado-method-001-revert-discipline.md
| Model | Without | With | Delta |
|---|
| claude-opus-4-8 | 29% | 100% | +71% |
| claude-sonnet-4-6 | 29% | 100% | +71% |
| claude-haiku-4-5 | 14% | 57% | +43% |
PASS (run 2026-06-25). Large gains (opus/sonnet +71) — baselines don't apply always-revert + one-commit-per-leaf + the 3-part output unaided. haiku reaches only 57% with the skill (weaker map/revert adherence) — candidate for a haiku-targeted salience pass. Gate per skill-optimizer/release-gates.md.
