Nw Mikado Method Agent Skill

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