# Mikado Method > 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. - Skill: `bsene/mikado-method` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add bsene/mikado-method` - Raw SKILL.md: https://api.skillmd.com/api/skills/bsene/mikado-method/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: bsene (https://skillmd.com/u/bsene) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/bsene/mikado-method --- # 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 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." | | 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) ```mermaid graph TD G(["🎯 GOAL: "]) --> 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, shared prerequisites | [Graph Building](references/graph-building.md) | | Execution order, committing strategy, legacy code, large refactors, hygiene rules, non-actionable goals | [Execution & Situations](references/execution-and-situations.md) | --- ## 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`.