mikado

name	mikado
description	Mikado method workflow for complex refactorings. Use when the user invokes /mikado, mentions "mikado graph", or wants to break a large code change into safe, incremental steps with automatic revert-on-failure.

Mikado Method

Structured workflow for tackling complex code changes using the Mikado method: set a goal, try naively, record prerequisites on failure, revert, and work leaves-first until the goal becomes trivial.

Directory layout

All state lives in .mikado/ at the repository root.

.mikado/
  current.md -> my-goal.md      # symlink to the active graph
  my-goal.md                    # a Mikado graph file
  another-goal.md               # another graph (inactive)

Ensure .mikado/ is git-ignored (append to .git/info/exclude so the project's .gitignore is not touched).

Graph file format

Each graph file has two sections: a Graph (scannable checklist) and Details (rich context for nodes that need it).

Nodes that have a corresponding heading in the Details section get a short [#id] tag linking to it. Self-explanatory nodes omit the tag.

# Mikado: Extract shared utils

## Graph

- [ ] Extract shared utils into `@app/utils` package [#goal]
  - [ ] Move date helpers to shared package
    - [x] Create `@app/utils` package scaffolding
    - [ ] Resolve circular dep between `core` and `helpers` [#circular_dep]
  - [ ] Update all import paths

## Details

### #goal -- Extract shared utils into `@app/utils` package

The backend and frontend both have duplicate date/string utilities.
We want a single shared package to reduce drift.

### #circular_dep -- Resolve circular dep between `core` and `helpers`

`core/index.ts` imports from `helpers/date`, but `helpers/date` imports
`core/types`. Need to extract the shared types into a leaf package first,
or inline the two types that `helpers/date` actually uses.

Graph rules

• - [ ] = not yet done
• - [x] = completed and committed
• Deeper nesting = must be done first
• A node is actionable when all its children (if any) are [x]
• The goal is achieved when the top-level item can be checked off

Node ID rules

• IDs are short lowercase slugs using underscores (not hyphens), so they behave as a single word in Vim: [#circular_dep], [#goal]
• Only add a [#id] tag to a node if it has a matching ### #id heading in the Details section. Omit the tag for self-explanatory nodes.
• When adding new prerequisite nodes, generate a short descriptive slug using underscores as separators

Details section rules

• Heading format: ### #id -- short label
• Only add a details entry when the node needs context beyond its one-line label (rationale, links, code references, gotchas)
• Keep details concise -- a few lines, not paragraphs

Invocation modes

1. /mikado goal "<description>"

Create a new Mikado graph:

1. Slugify the description to produce a filename (e.g. "Extract shared utils" -> extract-shared-utils.md).
2. Create .mikado/<slug>.md with the goal as the single top-level item.
3. Symlink .mikado/current.md -> .mikado/<slug>.md.
4. Ensure .mikado/ is in .git/info/exclude.
5. Show the user the created graph and confirm the goal.

2. /mikado switch "<slug-or-partial>"

Switch the current.md symlink to a different existing graph file.

3. /mikado list

List all graph files in .mikado/, indicate which is current, and show progress (done/total counts).

4. /mikado later "<description>"

Add a follow-up item (non-blocking, not a prerequisite) attached to the current step. Follow-ups are work identified while tackling a step but which shouldn't block its completion -- things to revisit later.

1. Determine the current step: the actionable leaf most recently being worked on (or the one the user just confirmed in Step B of the main loop). If ambiguous, ask the user which step to attach to.
2. Append the item to a ## Follow-ups section at the bottom of the current graph file, creating the section if it doesn't exist. Format: - [ ] <description> (from: <current-step-label>)
3. Follow-ups are never promoted to graph nodes automatically. They live outside the prereq tree so they don't gate progress on the goal. The user decides later whether to turn any into real nodes, address them ad-hoc, or drop them.

5. /mikado (no arguments -- the main loop)

This is the core cycle. Run it repeatedly to make incremental progress.

Step A -- Load state

• Read .mikado/current.md. If missing, ask the user for a goal (then behave like goal).
• Parse the graph. Find all actionable leaf nodes (unchecked items whose children, if any, are all checked).

Step B -- Pick the next leaf

• If multiple actionable leaves exist, present them and ask the user which one to tackle. If only one, confirm it with the user briefly.

Step C -- Attempt the change

• Try to implement the chosen leaf node naively.
• Run the project's build / type-check / tests if available (read CLAUDE.md or ask the user how to verify). If you are unsure what verification to run, ask the user.

Step D -- Evaluate the result

If the change works (builds, tests pass):

• Tell the user: "Leaf done. Nothing broke. You can review the diff and commit when ready."
• Do NOT commit automatically. Wait for the user.
• When the user commits (or asks you to), mark the leaf as [x] in the graph file.
• If the completed leaf's parent now has all children checked, note that the parent is now actionable.

If something breaks:

• Identify what went wrong.
• Explain to the user what broke and what prerequisites you think need to be added. Do NOT update the graph or revert changes yet.
• Stop and let the user inspect the local changes. The user may want to look at the diff, verify your conclusions, or adjust the plan.
• Wait for the user to explicitly tell you to:
  • Update the graph (add the new prerequisites), and/or
  • Revert the local changes (git checkout -- .)
• Only then perform those actions.

Step E -- Report

• Show the current state of the graph (what's done, what's next).
• Stop and wait for the user to invoke /mikado again or give other instructions.

Important rules

• Never commit autonomously. Only commit when the user explicitly asks.
• Never revert autonomously. When something breaks, report your findings and let the user decide when to revert. Always confirm with the user before running git checkout.
• Ask before complex decisions. If a leaf is ambiguous or the prerequisites are unclear, ask the user rather than guessing.
• Keep the graph file updated. It is the single source of truth.
• One leaf at a time. Do not try to tackle multiple leaves in one cycle.
• Respect existing commits. Never amend, rebase, or rewrite history.