Mikado Method
Use for complex refactoring where direct implementation causes cascading failures across multiple classes/modules.
When to Use
- Refactoring goal affects multiple classes/modules | Direct implementation causes cascade of failures
- Dependencies not immediately clear | High risk of breaking existing functionality
Core Process
Cycle: Set Goal > Experiment > Visualize prerequisites > Revert to working state.
Treat compilation/test failures as valuable information -- each failure reveals a prerequisite node in the dependency graph. Revert keeps codebase shippable at all times.
Discovery-Tracking Protocol
Commit immediately after each dependency discovery to preserve exploration history and enable interrupt/resume.
Commit Formats
- Dependency:
Discovery: [Class.Method(params)] requires [Prerequisite] in [File:Line]
- False leaf:
Discovery: False leaf - [Node] blocked by [Dependency]
- Exploration complete:
Discovery: No new dependencies found - exploration complete for [GoalArea]
- Ready:
Ready: True leaves identified - [Count] leaves ready for execution
Exhaustive Exploration Algorithm
Sequence: EXPERIMENT > LEARN > GRAPH > COMMIT GRAPH > REVERT
- Experiment: Attempt naive implementation of stated goal
- Learn: Capture ALL compilation and test failures immediately
- Graph: Create concrete prerequisite nodes with exact specifications
- Commit Graph: Commit discovery with mandatory format
- Revert: Revert ALL code changes to maintain clean state
Termination Criteria
- Every apparent leaf candidate systematically attempted | No new dependencies emerge from leaf attempts
- Tree structure stable across multiple exploration cycles | True leaves confirmed with zero prerequisites
Concrete Node Specification
Nodes require method-level specificity:
- Method signatures:
ClassName.MethodName(parameter types) -> ReturnType
- File locations:
src/Services/UserService.cs, line 45
- Access modifiers: public | private | internal | protected
- Refactoring technique: Extract Method | Move Method | etc.
- Atomic transformation: Rename | Extract | Inline | Move | Safe Delete
- Code smell target: Long Method | Feature Envy | etc.
Tree File Management
File Structure
- Directory:
docs/mikado/ | Filename: <goal-name>.mikado.md
- Format:
- [ ] pending, - [x] completed | Indentation: 4 spaces per nesting level
- Dependencies indented deeper than dependents
Tree Structure Rules
- Root goal at 0 indentation
- Direct dependencies at 4-space indentation
- Sub-dependencies at 8-space, continuing per level
- Child nodes must complete before parent nodes
- Nodes at same indentation level are independent (parallelizable)
Two-Mode Operation
Exploration Mode
- Attempt naive implementation of refactoring goal
- Capture compilation/test failures with full details
- Create concrete prerequisite nodes with method-level specificity
- Add dependencies to tree file with proper indentation nesting
- Commit tree discovery only (specific format)
- Revert code changes completely except tree file
- Repeat until no new dependencies discovered
Execution Mode
- Identify deepest indentation level with incomplete nodes
- Select only true leaves (most nested, zero prerequisites)
- Execute one leaf at a time for safety
- Complete all nodes at current level before moving up
- Never attempt parent node until all children complete
- Implement minimal possible change per leaf
- Validate with full test execution
- Commit implementation, update tree marking node complete
- Proceed bottom-up to next true leaf
Tree Example
- [ ] Goal: Replace direct DB calls in OrderController with repository pattern
- [ ] Update OrderController constructor to use IOrderRepository
- [ ] Implement SqlOrderRepository : IOrderRepository
- [ ] Create IOrderRepository interface
- [ ] Define GetOrderById(int orderId) -> Order? method signature
- [ ] Define SaveOrder(Order order) -> Task method signature
- [ ] Add constructor SqlOrderRepository(IDbContext context)
- [ ] Verify IDbContext is registered in DI container
- [ ] Implement GetOrderById method
- [ ] Handle null order case with OrderNotFoundException
- [x] Create OrderNotFoundException class
- [ ] Register IOrderRepository in DI container
- [ ] Remove IDbContext _context field from OrderController
Execution order: deepest leaves first, working up level by level.
Timeboxed Experimentation
10-minute timebox per attempt. If change can't be made in 10 min, it's too complex -- break down further.
- Success: commit, check off node, move to next
- Fail: revert, identify missing prerequisites, write subgoals
Goal Definition
Convert technical goals to stakeholder-understandable business value:
- Correct: "Customer address is retrieved using the latest version of the third-party API for improved reliability"
- Incorrect: "Update third-party API to version X"
Integration with TDD
- All Mikado execution steps maintain passing tests (green bar)
- Each leaf execution = one atomic commit with tests passing
- If any step breaks tests, revert immediately and reassess dependencies
- Baby steps rhythm: test-commit-integrate every small change