Contenido del repositorio de origen con títulos, ejemplos, código, tablas, enlaces e imágenes preservados.
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. Must define two things: a starting point (what's true now) and success criteria (what "done" looks like). A goal missing either is not actionable — decompose it until you find a prerequisite that has both. 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 → ask: does this still serve the goal?
→ no: discard, do NOT commit, pick the next leaf
→ yes: 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." |
| Committing a leaf just because it's green | "Passing isn't enough — does it actually serve the goal? If not, discard it and move to the next prerequisite." |
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 restore <touched files>` — your map is saved, the broken code is not needed." (Scope the revert to the files you touched; git checkout . would discard all uncommitted work, not just the naive attempt.)
Read On Demand
| Read When | File |
|---|---|
| Starting a graph, populating prerequisites, evaluating leaves, shared prerequisites | Graph Building |
| Execution order, committing strategy, legacy code, large refactors, hygiene rules, non-actionable goals | 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 .agents/skills/skill-optimizer/rules/release-gates.md.