From 645bb2fa68070e5081942796fa4f875d5b5c8eae Mon Sep 17 00:00:00 2001 From: River Bailey Date: Tue, 27 Oct 2026 08:32:30 -0600 Subject: [PATCH 1/7] docs(research): draft Mikado Method skill research --- docs/research/mikado-method-skill.md | 233 +++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) create mode 100644 docs/research/mikado-method-skill.md diff --git a/docs/research/mikado-method-skill.md b/docs/research/mikado-method-skill.md new file mode 100644 index 00000000..bcd68b8e --- /dev/null +++ b/docs/research/mikado-method-skill.md @@ -0,0 +1,233 @@ +# Research: How should the Mikado Method work as a new Han skill? + +The question is how the Mikado Method works and how to build it into a new Han skill that runs the method on a real +codebase. The decision to build a new skill is taken as given; this report covers what the skill should do and where it +should sit. Evidence mode: strict. + +## Summary + +Build one skill that runs the whole Mikado loop, from trying the goal through to finishing it, and keep a person in charge +of the goal and of how the graph grows. The method is well described and stable: try the change the simple way, write +down what breaks, undo the attempt, fix the blockers first, and commit each one only when the tests pass. The skill +belongs in the coding plugin beside `refactor` and `tdd`, because it edits code and runs tests the way they do. + +Two design choices carry most of the risk. The first is how the skill undoes an attempt without throwing away finished +work. The second is how it keeps an agent from patching forward instead of undoing. The loop itself is +well-corroborated. The agent-specific design advice comes from a handful of 2026 blog posts and skill listings, and +nothing measures whether any of it works. + +- **Confidence:** Medium +- **Web search:** used + +## Research Results + +### How the Mikado Method works + +The method is a loop for changes too big or too tangled to make in one step. Ola Ellnestam and Daniel Brolund presented +it from 2010 and published it as a book with Manning in 2014 (A1, A2, A6). Four independent sources describe the same +loop (A1, A2, A3, A5): + +1. Write down the goal. +2. Try the goal the simple, direct way. +3. Let the compiler, the tests, and any other checks show what breaks. +4. Write each break down as a prerequisite under the goal. +5. Undo the attempt. +6. Treat each prerequisite as a new goal and repeat, until an attempt shows no new prerequisites. +7. Make the changes that have no prerequisites of their own, commit each one with the tests passing, and work back up + toward the goal. + +The authors call this a depth-first walk through the change's dependencies (A1). A prerequisite with nothing under it is +a "leaf," and leaves always go first (A2). New obstacles can still show up while working back up, and they become new +branches (A3). + +### The graph is the method's one lasting artifact + +The record of goal and prerequisites, called the Mikado graph, is what survives each undo. It is kept outside the code, +on paper, a whiteboard, plain text, or a diagram tool (A3, A7). Finished nodes are marked done, and the graph can be +attached to a pull request so a reviewer sees why the change took the shape it did (A4, A7). The sources define no +formal notation for it (A3). + +### Where the sources disagree on the details + +The loop's shape is settled, but its mechanics vary from source to source: + +- **What counts as broken.** One source names compilers, tests, analysis, and common sense (A1). Others center on + compile and test failures (A3, A5). A skill has to pick an explicit signal. +- **How to undo.** Sources use a hard git reset (A4), commit the attempt and then revert that commit (A5), or allow a + stash for a promising partial attempt (A3). The original says only "version control or undo" (A1). +- **Timeboxing.** One practitioner caps each attempt at 10 minutes (A4) [single-source]. The others set no limit. +- **Stopping.** The method has no natural end, so a stop condition is needed (A3). One source fixes a completion check + at the start, such as a code search that returns no matches (A4) [single-source]. + +### The method's limits + +All of the evidence on limits comes from practitioners, and no study measures the method's results (A3, A4, A5). +Practitioners name these limits: + +- Without automated tests, nothing can confirm a change is safe (A3). +- Slow builds and tests make every attempt expensive (A3). +- Throwing away an attempt feels wasteful, and the discipline to undo is the hardest part (A3, A4, A5). +- Early rounds produce no committed code (A4). +- Dependencies that do not show up as compile or test failures are hard to discover by trying (A5). + +Uses beyond restructuring code are thin. One source shows removing a library dependency (A5). No source found applies it +to feature work or framework migrations [negative result]. + +### How agents have used it so far + +Agent-driven Mikado exists as a cluster of 2026 practitioner posts and at least four community skills, and none of them +publishes measured results (A9, A10, A11, A12, A13, A14). Evidence here is thin. Two of the three posts share an author +(A9, A11). + +The agent sources agree on four points: + +- **Undo, then record.** Every source undoes the attempt and keeps only the graph (A9, A11, A13, A14). +- **The graph lives in a file.** Most keep it as a markdown checklist in the repository (A9, A11, A13). One keeps it in + an uncommitted folder (A12), and one keeps it only in the agent's working memory (A14). +- **Small leaf commits.** Each finished leaf is one commit, made only when the tests pass (A10, A11, A13). +- **The compiler and tests are the signal** (A9, A10, A13, A14). + +They name three agent-specific failure modes. Agents make sweeping edits across many files, lose track as context grows, +and edit tests to make them pass (A9) [single-source for the test-editing claim]. One author argues that deciding which +failures share a root cause cannot be handed to the agent (A10) [single-source]. A worked example kept a person +confirming the goal and approving each green commit (A11). + +The sources do not settle several questions: + +- No source compares reset, stash, and a separate working copy for the undo. +- No source sets a cap on discovery rounds or handles a graph that keeps growing. One adds a script that checks the + graph for loops (A11) [single-source]. +- No source reports how reliably an agent obeys "undo, don't patch forward." + +### How the new skill fits Han today + +`refactor` and `tdd` are the two Han skills that edit code in a test-gated loop, and both live in the coding plugin +(A17, A18, A19). `refactor` plans every step before its first edit, treats each step's list of files as a contract, and +stops when a step spreads beyond it or two steps in a row fail (A17, A18). Those three rules are the ones Mikado's +discovery half breaks on purpose, which is why an earlier Han report advised against a Mikado mode inside `refactor` +(A25). + +`plan-a-change` already sequences a restructure so each unit leaves the code working, but it does so by reading code and +never by trying a change (A20). That is the real line between it and a Mikado skill: one predicts the dependencies, the +other discovers them by breaking the build. The earlier report flagged the overlap as the main cost of a separate skill +(A25). + +`refactor`'s undo rule matters here. After a recent fix, it forbids restoring files from git, because a restore throws +away any earlier passing step that was not yet committed (A18). Mikado changes that picture. Every finished leaf is +committed, so the last commit always holds every passing step (A4, A5, A11). Restoring to the last commit is safe in +that case, provided the working tree was clean when the run began. That safety condition is drawn here from the two +sources, not stated by either. + +Han already has the pieces a new skill would reuse: + +- A script that detects the project's test command from its manifest (A21). +- A shared rule for how a skill hands control back during pairing (A22). +- A list of skills that `pairing` can drive, which a new skill would join (A23). +- A coverage rule requiring a long-form doc, a README line, and an index entry (A26). + +The entity taxonomy calls a flowchartable process a skill (A24). The Mikado loop is flowchartable, with one exception: +grouping failures into prerequisites takes judgment. + +## Options to Consider + +### O1: One skill for the full loop, with a person gating the goal and the graph + +- **What it is:** A coding-plugin skill that confirms the goal and a completion check, then runs discovery rounds. Each + round tries the change, records new prerequisites in a committed markdown graph, and restores the code to the last + commit. It stops for the person to review the new prerequisites, then works leaves one at a time, committing each + only when the tests pass. It starts only from a clean tree with a passing suite. +- **Trade-offs:** It matches the method as described, and it gives the person the root-cause grouping the sources say an + agent should not own. It costs a stop after every discovery round. It also adds a skill whose sequencing overlaps + `plan-a-change`. It must commit as it goes, where `refactor` commits only when asked. +- **Rests on:** (A1), (A3), (A5), (A10), (A11), (A18), (A20), (A21) +- **Evidence status:** loop corroborated. The human gate rests on two independent practitioner sources. The safety of + the undo is drawn from the codebase and the commit-per-leaf practice. + +### O2: A discovery-only skill that builds the graph and hands leaves to `refactor` or `tdd` + +- **What it is:** The skill runs only the discovery half: try, record, undo. It ends with a graph file. The person then + runs each leaf through `refactor` (or `tdd` for leaves that change behavior). +- **Trade-offs:** Execution reuses existing, tested skills, and the new skill stays small. But a leaf can reveal new + prerequisites while it is being built (A3), and `refactor` has no way to send them back into the graph. The person + becomes the go-between for every leaf. +- **Rests on:** (A3), (A17), (A18), (A20) +- **Evidence status:** corroborated for the fit. No source runs the method split this way. + +### O3: One autonomous skill for the full loop, with a time or attempt budget and no human gate + +- **What it is:** O1's loop with no stops. A budget per attempt (10 minutes in the source) bounds each round, and fixed + commit prefixes record discoveries. +- **Trade-offs:** It is the simplest to run and the least work to review. The budget comes from one source and was + designed for people. Nothing in it guards against an agent editing tests, and no source caps the number of rounds. +- **Rests on:** (A4), (A9), (A13) +- **Evidence status:** single-source for the specifics. + +### O4: Add Mikado to `refactor` instead of building a new skill + +- **What it is:** The earlier report's recommendation. When `refactor` stops on a scope or repeated-failure rule, it + records what blocked the step as prerequisites in its stop report (A25). One community skill does the same, using + Mikado as a fallback inside a refactor loop (A14). +- **Trade-offs:** It is the smallest change, and it adds no overlapping skill. But it never runs discovery on purpose, + so a deep chain of blockers takes several runs. It also does not deliver the new skill that was asked for. +- **Rests on:** (A14), (A18), (A25) +- **Evidence status:** codebase-corroborated for the fit. A14 is single-source. + +## Recommendation + +- **Recommendation:** O1, built with these specific choices. + 1. **Place it in `han-coding`**, beside `refactor` and `tdd`. Route between it and its neighbors in the description: + `plan-a-change` predicts a restructure by reading code, and this skill discovers one by trying it. + 2. **Make the undo safe by construction.** Require a clean tree and a passing suite before the first attempt. Commit + each finished leaf, and commit each graph update separately from the code. Undo an attempt by restoring the code to + the last commit, which then holds every passing step. Never undo across uncommitted work the person made. + 3. **Define "broken" up front** as the resolved test command plus the type-check command where one exists, reusing + the detection script `refactor` uses. + 4. **Keep the graph in a committed markdown file**, a nested checklist where each node carries an ID and what it + requires. Mark a node done only after its green commit. + 5. **Stop for the person at two points:** to confirm the goal and its completion check, and after each discovery round + to review how failures were grouped into prerequisites. Present each stop in the shape the collaborative-stop rule + sets, and add the skill to `pairing`'s list. + 6. **Guard against patching forward.** A red attempt is always undone, never patched. A leaf commit that restructures + code changes no tests. + 7. **Bound discovery with a round count, not a clock.** Treat the exact limit as open, because the only stated budget + (10 minutes) was designed for people. +- **Evidence basis:** The loop, the graph as the lasting artifact, and commit-per-leaf are corroborated across several + independent sources (A1, A2, A3, A4, A5, A11). The plugin placement, the test-detection reuse, and the undo hazard come + from the codebase (A18, A19, A21). The human gate on root-cause grouping rests on two independent practitioner posts + (A10, A11). The no-test-edits rule rests on one source each for the risk and the guard (A9, A14) [single-source]. The + attempt budget in choice 7 is the one part with no evidence behind it, so it is left open rather than fixed. + +## Validation + +Validation has not run yet; this section is filled in after the adversarial pass. + +## Sources + +| ID | Source | Link / location | Retrieved | Trust class | Summary (one line) | Evidence status | +| --- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------- | +| A1 | Øredev 2010 speaker page, Ola Ellnestam | https://archive.oredev.org/oredev2010/2010/speakers/ola-ellnestam | 2026-10-27 | web | Co-author's 7-step "Naive Approach": goal, naive attempt, find breaks, record prerequisites, revert, recurse, leaves first. | corroborated by A2, A3, A5 | +| A2 | InfoQ, "Large scale refactoring" (2010) | https://www.infoq.com/news/2010/08/large-scale-refactoring | 2026-10-27 | web | Graph built from the goal down; leaves have no prerequisites and go first; do not fear reverting. | corroborated by A1, A3 | +| A3 | heise, "Update legacy code step by step with the Mikado method" | https://www.heise.de/en/background/Update-legacy-code-step-by-step-with-the-Mikado-method-11119651.html?seite=all | 2026-10-27 | web | Six-step loop, flexible graph tooling, and limits: no natural end, needs tests and fast builds, unwinding finds new obstacles. | loop corroborated by A1, A2, A5; limits single source | +| A4 | Vinta Software, "The Mikado Method" (2025) | https://www.vintasoftware.com/blog/the-mikado-method | 2026-10-27 | web | 10-minute timeboxed rounds, hard reset on failure, commit per green node, completion check fixed up front. | commit-per-node corroborated by A5, A11; timebox single source | +| A5 | Matthias Noback, "Successful refactoring projects: the Mikado Method" (2021) | https://matthiasnoback.nl/2021/02/refactoring-the-mikado-method/ | 2026-10-27 | web | Worked dependency-removal example; finished prerequisites committed one at a time so every step leaves a working app. | corroborated by A1, A3, A4 | +| A6 | Manning / O'Reilly book pages, *The Mikado Method* (2014) | https://livebook.manning.com/book/the-mikado-method/chapter-1 | 2026-10-27 | web | Confirms authors, publisher, and year; body text was not readable. | single source | +| A7 | mikado.nvie.com | https://mikado.nvie.com/ | 2026-10-27 | web | Graph is the main artifact, usually drawn on paper; tool shares graphs, for example on pull requests. | corroborated by A3, A4 | +| A8 | Martin Fowler, "Parallel Change" | https://martinfowler.com/bliki/ParallelChange.html | 2026-10-27 | web | Expand, migrate, contract keeps code shippable through a change that cannot land in one step. | single source; not a Mikado source | +| A9 | Chaabani, "Taming Agentic Refactoring with the Mikado Method" | https://anischaabani.com/en/blog/mikado-method-ai-agents/ | 2026-10-27 | web | Agent failure modes: sweeping edits, scattered context, tests edited to pass; reverts with a hard reset; versioned graph file. | partly corroborated by A10; same author as A11 | +| A10 | WellAged.dev, "The Mikado Method in the Age of AI Agents" | https://wellaged.dev/posts/mikado-method-ai-agents/ | 2026-10-27 | web | Graph is what survives each step; commit leaves only on green; grouping failures by root cause cannot be delegated to the agent. | corroborated by A9, A11 on revert and graph; root-cause claim single source | +| A11 | Chaabani, "Mikado Method in Action" | https://anischaabani.com/en/blog/mikado-method-example/ | 2026-10-27 | web | Worked agent example: committed checklist graph with IDs and `requires:`, graph commit then code revert, one commit per leaf, human approves each. | single source for format (same author as A9) | +| A12 | nvie/skills "mikado" (skills.sh listing) | https://skills.sh/nvie/skills/mikado | 2026-10-27 | web | Community skill keeps one graph per goal under an uncommitted `.mikado/` folder. | single source; full skill not visible | +| A13 | nWave "nw-mikado-method" (OpenSkillIndex listing) | https://openskillindex.com/skills/nwave-ai-nwave-nw-mikado-method-474589 | 2026-10-27 | web | Community skill: committed checklist graph, revert after every attempt, 10-minute attempts, one leaf at a time, no human gate. | loop corroborated by A9, A11; specifics single source | +| A14 | Oma Refactor skill (TypingMind listing) | https://www.typingmind.com/skills/first-fluke-oma-refactor | 2026-10-27 | web | Mikado as a fallback inside a test-gated refactor loop; refactor commits change no tests; graph held in memory. | single source | +| A15 | Pre-agent Mikado tooling (clokado, mikado_graph_generator, mikado-app) | https://github.com/ahitrin/clokado | 2026-10-27 | web | Pre-agent tooling is graph drawers and small web apps; no IDE plugin or CLI found. | single search pass (snippets only) | +| A16 | Kent Beck, "make the change easy, then make the easy change" | https://tidyfirst.substack.com/p/hinge | 2026-10-27 | web | States the enabling-change-first rule; no source ties it to Mikado directly. | corroborated across two Beck posts | +| A17 | `refactor` skill, plan step | `han-coding/skills/refactor/SKILL.md:110-124` | n/a | codebase | Plans every refactoring, with evidence and a file list, before the first edit. | codebase anchor | +| A18 | `refactor` skill, execute, undo, and stop rules | `han-coding/skills/refactor/SKILL.md:128-155` | n/a | codebase | One change then the full suite; undo only the step's own edits, never restore from git; stop on scope spread or two failures in a row. | codebase anchor | +| A19 | `refactor` skill description | `han-coding/skills/refactor/SKILL.md:3-12` | n/a | codebase | Test-gated loop in the coding plugin; routes multi-module restructure planning to `plan-a-change`. | codebase anchor | +| A20 | `plan-a-change` skill | `han-planning/skills/plan-a-change/SKILL.md:3-10`, `:312-315` | n/a | codebase | Sequences change units so each leaves the code working, by reading code, never by trying a change. | codebase anchor | +| A21 | Test-command detection script | `han-coding/skills/refactor/scripts/detect-refactor-context.sh:26-94` | n/a | codebase | Infers the project's test command from its manifest (npm, pytest, go, cargo, and others). | codebase anchor | +| A22 | Collaborative-stop rule | `han-core/references/collaborative-stop-rule.md` | n/a | codebase | Shared contract for how a skill detects the collaborative flag and what a stop presents. | codebase anchor | +| A23 | `pairing` skill, flagged skills | `han-core/skills/pairing/SKILL.md:87-89` | n/a | codebase | Lists the skills `pairing` can drive collaboratively: tdd, refactor, design-an-api, iterative-plan-review, plan-implementation. | codebase anchor | +| A24 | Entity taxonomy | `han-plugin-builder/skills/guidance/references/plugin-entity-taxonomy.md` | n/a | codebase | A flowchartable, repeatable process is a skill; contextual judgment is an agent. | codebase anchor | +| A25 | Earlier Han research on Mikado in `refactor` | `docs/research/mikado-method-refactor.md` on branch `research/mikado-method-refactor` | n/a | codebase | Advised against a Mikado mode in `refactor` and a separate skill; recommended fixing the undo, then recording prerequisites at stops. | codebase anchor (prior research) | +| A26 | Coverage rule | `docs/templates/coverage-rule.md` | n/a | codebase | Every new skill needs a long-form doc, a plugin README line, and an index entry in the same change. | codebase anchor | From 4dc3e5a162e752fcbefaffeee0ae6c4f708d2481 Mon Sep 17 00:00:00 2001 From: River Bailey Date: Tue, 27 Oct 2026 08:37:07 -0600 Subject: [PATCH 2/7] docs(research): apply adversarial validation to Mikado skill research --- docs/research/mikado-method-skill.md | 415 +++++++++++++++++++-------- 1 file changed, 294 insertions(+), 121 deletions(-) diff --git a/docs/research/mikado-method-skill.md b/docs/research/mikado-method-skill.md index bcd68b8e..4400c660 100644 --- a/docs/research/mikado-method-skill.md +++ b/docs/research/mikado-method-skill.md @@ -1,20 +1,21 @@ # Research: How should the Mikado Method work as a new Han skill? The question is how the Mikado Method works and how to build it into a new Han skill that runs the method on a real -codebase. The decision to build a new skill is taken as given; this report covers what the skill should do and where it -should sit. Evidence mode: strict. +codebase. The decision to build a new skill is taken as given; this report covers what the skill should do, how it +should share work with the skills Han already has, and where it should sit. Evidence mode: strict. ## Summary -Build one skill that runs the whole Mikado loop, from trying the goal through to finishing it, and keep a person in charge -of the goal and of how the graph grows. The method is well described and stable: try the change the simple way, write -down what breaks, undo the attempt, fix the blockers first, and commit each one only when the tests pass. The skill -belongs in the coding plugin beside `refactor` and `tdd`, because it edits code and runs tests the way they do. +Build a new skill that owns the Mikado graph and the discovery rounds, and hands each finished-out step to the +`refactor` or `tdd` skill to carry out. The method is well described and stable: try the change the simple way, write +down what breaks, undo the attempt, fix the blockers first, and commit each one only when the tests pass. Han already +has skills that make one small change safely under passing tests, so the new skill should reuse them rather than build a +third way to do that. -Two design choices carry most of the risk. The first is how the skill undoes an attempt without throwing away finished -work. The second is how it keeps an agent from patching forward instead of undoing. The loop itself is -well-corroborated. The agent-specific design advice comes from a handful of 2026 blog posts and skill listings, and -nothing measures whether any of it works. +The hardest part is undoing a deliberately wide attempt without losing anyone's work. Restoring files from git, the +method practitioners use, is only safe under a short list of conditions the skill has to check, and nothing settles +whether a throwaway copy of the code is the better choice. The loop itself is well-corroborated. The agent-specific +design advice comes from a handful of 2026 blog posts and skill listings, and nothing measures whether any of it works. - **Confidence:** Medium - **Web search:** used @@ -24,8 +25,8 @@ nothing measures whether any of it works. ### How the Mikado Method works The method is a loop for changes too big or too tangled to make in one step. Ola Ellnestam and Daniel Brolund presented -it from 2010 and published it as a book with Manning in 2014 (A1, A2, A6). Four independent sources describe the same -loop (A1, A2, A3, A5): +it from 2010 and published it as a book with Manning in 2014 (A1, A2, A6). The authors' own talk, a news report on it, +and two independent practitioner write-ups describe the same discovery loop (A1, A2, A3, A5): 1. Write down the goal. 2. Try the goal the simple, direct way. @@ -33,12 +34,12 @@ loop (A1, A2, A3, A5): 4. Write each break down as a prerequisite under the goal. 5. Undo the attempt. 6. Treat each prerequisite as a new goal and repeat, until an attempt shows no new prerequisites. -7. Make the changes that have no prerequisites of their own, commit each one with the tests passing, and work back up - toward the goal. +7. Make the changes that have no prerequisites of their own, and work back up toward the goal. -The authors call this a depth-first walk through the change's dependencies (A1). A prerequisite with nothing under it is -a "leaf," and leaves always go first (A2). New obstacles can still show up while working back up, and they become new -branches (A3). +Practitioners add that each finished prerequisite is committed only with the tests passing, so every commit leaves a +working system (A4, A5, A11). The authors call the whole loop a depth-first walk through the change's dependencies (A1). +A prerequisite with nothing under it is a "leaf," and leaves always go first (A2). New obstacles can still show up while +working back up, and they become new branches of the graph (A3). ### The graph is the method's one lasting artifact @@ -51,7 +52,7 @@ formal notation for it (A3). The loop's shape is settled, but its mechanics vary from source to source: -- **What counts as broken.** One source names compilers, tests, analysis, and common sense (A1). Others center on +- **What counts as broken.** The original names compilers, tests, analysis, and common sense (A1). Others center on compile and test failures (A3, A5). A skill has to pick an explicit signal. - **How to undo.** Sources use a hard git reset (A4), commit the attempt and then revert that commit (A5), or allow a stash for a promising partial attempt (A3). The original says only "version control or undo" (A1). @@ -61,7 +62,7 @@ The loop's shape is settled, but its mechanics vary from source to source: ### The method's limits -All of the evidence on limits comes from practitioners, and no study measures the method's results (A3, A4, A5). +All of the evidence on limits comes from practitioners. The search found no study that measures the method's results. Practitioners name these limits: - Without automated tests, nothing can confirm a change is safe (A3). @@ -70,31 +71,31 @@ Practitioners name these limits: - Early rounds produce no committed code (A4). - Dependencies that do not show up as compile or test failures are hard to discover by trying (A5). -Uses beyond restructuring code are thin. One source shows removing a library dependency (A5). No source found applies it -to feature work or framework migrations [negative result]. +Uses beyond restructuring code are thin. One source shows removing a library dependency (A5). The search found no source +applying the method to feature work or framework migrations. ### How agents have used it so far -Agent-driven Mikado exists as a cluster of 2026 practitioner posts and at least four community skills, and none of them -publishes measured results (A9, A10, A11, A12, A13, A14). Evidence here is thin. Two of the three posts share an author -(A9, A11). +Agent-driven Mikado exists as three 2026 practitioner posts and three community skill listings, and none publishes +measured results (A9, A10, A11, A12, A13, A14). Evidence here is thin. Two of the three posts share an author (A9, A11), +so they count as one voice, and the listings are the skill authors' own descriptions. The agent sources agree on four points: - **Undo, then record.** Every source undoes the attempt and keeps only the graph (A9, A11, A13, A14). - **The graph lives in a file.** Most keep it as a markdown checklist in the repository (A9, A11, A13). One keeps it in an uncommitted folder (A12), and one keeps it only in the agent's working memory (A14). -- **Small leaf commits.** Each finished leaf is one commit, made only when the tests pass (A10, A11, A13). -- **The compiler and tests are the signal** (A9, A10, A13, A14). +- **Small leaf commits.** Each finished leaf is one commit, made only when the tests pass (A10, A11). +- **The compiler and tests are the signal** (A9, A13). -They name three agent-specific failure modes. Agents make sweeping edits across many files, lose track as context grows, -and edit tests to make them pass (A9) [single-source for the test-editing claim]. One author argues that deciding which -failures share a root cause cannot be handed to the agent (A10) [single-source]. A worked example kept a person -confirming the goal and approving each green commit (A11). +They name three agent-specific failure modes: agents make sweeping edits across many files, lose track as context grows, +and edit tests to make them pass (A9) [single-source]. One author argues that deciding which failures share a root cause +cannot be handed to the agent (A10) [single-source]. A worked example kept a person confirming the goal and approving +each green commit, which is a different gate (A11). -The sources do not settle several questions: +The sources leave several questions open: -- No source compares reset, stash, and a separate working copy for the undo. +- No source compares reset, stash, and a separate throwaway copy of the code for the undo. - No source sets a cap on discovery rounds or handles a graph that keeps growing. One adds a script that checks the graph for loops (A11) [single-source]. - No source reports how reliably an agent obeys "undo, don't patch forward." @@ -104,130 +105,302 @@ The sources do not settle several questions: `refactor` and `tdd` are the two Han skills that edit code in a test-gated loop, and both live in the coding plugin (A17, A18, A19). `refactor` plans every step before its first edit, treats each step's list of files as a contract, and stops when a step spreads beyond it or two steps in a row fail (A17, A18). Those three rules are the ones Mikado's -discovery half breaks on purpose, which is why an earlier Han report advised against a Mikado mode inside `refactor` -(A25). +discovery half breaks on purpose. That is the case against putting discovery inside `refactor`, and the case for a +separate skill that runs discovery and then hands each leaf to `refactor`, where its rules fit. + +`refactor`'s stop rules are also exactly Mikado's signal. A step that spreads past its files, or fails twice, is a step +with prerequisites nobody has found yet (A18). A skill that owns the graph can read that stop as a discovery and add the +blockers as new nodes. One community skill joins the two the same way, falling back to Mikado inside a test-gated +refactor loop (A14) [single-source]. Han's entity taxonomy allows a skill to invoke other skills for fixed sub-steps +(A24). `plan-a-change` already sequences a restructure so each unit leaves the code working, but it does so by reading code and never by trying a change (A20). That is the real line between it and a Mikado skill: one predicts the dependencies, the -other discovers them by breaking the build. The earlier report flagged the overlap as the main cost of a separate skill -(A25). +other discovers them by breaking the build. + +### Relationship to the earlier Han report on Mikado + +An earlier Han report advised against a separate Mikado skill (A25). It recommended fixing `refactor`'s undo step first, +then recording blockers as prerequisites when `refactor` stops. Its rejected separate-skill option ran the full loop and +handed each leaf to `refactor`, which is close to what this report now recommends. It rejected that option because the +suite would carry two places that order a large restructure, and it judged the agent posts and tools too weak to carry +the decision. + +Three things differ now. The undo fix has shipped, which removes the hazard that report cared most about (A18). The +decision to build a new skill is taken, so this report weighs how to build it, not whether. And the overlap cost the +earlier report named still stands; it is managed here by routing text and by reusing `refactor` rather than duplicating +it, not removed. The earlier report lives only on an unmerged branch, so the link to it may break. + +### The undo problem -`refactor`'s undo rule matters here. After a recent fix, it forbids restoring files from git, because a restore throws -away any earlier passing step that was not yet committed (A18). Mikado changes that picture. Every finished leaf is -committed, so the last commit always holds every passing step (A4, A5, A11). Restoring to the last commit is safe in -that case, provided the working tree was clean when the run began. That safety condition is drawn here from the two -sources, not stated by either. +`refactor` forbids restoring files from git, because a restore throws away any earlier passing step that was not yet +committed (A18). Mikado changes that picture: every finished leaf is committed, so the last commit holds every passing +step (A4, A5, A11). A restore to the last commit is safe in that case, but only when every one of these holds. These +conditions are drawn here from git's behavior and the codebase, not stated by any source: -Han already has the pieces a new skill would reuse: +- The project is a git repository, and the run is on a branch where commits are expected. +- The tree is clean before each attempt, tracked and untracked files alike, and nothing has changed since the skill + last checked. A person's edit during a run is indistinguishable from an attempt's edit, and a restore would wipe it. +- The graph update is committed before the code is restored, or the restore wipes the newly found prerequisites. +- Files the attempt created are removed too, by path, from a before-and-after listing. A plain restore leaves them + behind, and a blanket `git clean` would also remove files the person left untracked. +- The full suite is re-run after every undo. Ignored and generated state (build output, installed packages, caches) is + not reverted by a restore and can make the next run pass or fail for the wrong reason. -- A script that detects the project's test command from its manifest (A21). -- A shared rule for how a skill hands control back during pairing (A22). -- A list of skills that `pairing` can drive, which a new skill would join (A23). -- A coverage rule requiring a long-form doc, a README line, and an index entry (A26). +A throwaway copy of the code avoids most of those hazards. Running each attempt in a separate git worktree (a second +checkout of the same repository in another folder) leaves the person's working tree untouched, and the undo is deleting +the copy. Its costs are a fresh install of dependencies per copy and a hard requirement on git. No source compares the +two approaches. -The entity taxonomy calls a flowchartable process a skill (A24). The Mikado loop is flowchartable, with one exception: -grouping failures into prerequisites takes judgment. +### What a new skill must ship with + +Han's conventions add required work to any new skill (A22, A23, A26): + +- A long-form doc, a plugin README line, and a skills-index entry, in the same change. +- An entry in `pairing`'s list of skills it can drive, plus the collaborative-stop text inside the new skill. +- Routing lines in the descriptions of `refactor` and `plan-a-change` that point to the new skill, so a reader does not + see three overlapping triggers for a large restructure. ## Options to Consider -### O1: One skill for the full loop, with a person gating the goal and the graph +### O1: One skill that runs discovery and carries out every leaf itself -- **What it is:** A coding-plugin skill that confirms the goal and a completion check, then runs discovery rounds. Each - round tries the change, records new prerequisites in a committed markdown graph, and restores the code to the last - commit. It stops for the person to review the new prerequisites, then works leaves one at a time, committing each - only when the tests pass. It starts only from a clean tree with a passing suite. -- **Trade-offs:** It matches the method as described, and it gives the person the root-cause grouping the sources say an - agent should not own. It costs a stop after every discovery round. It also adds a skill whose sequencing overlaps - `plan-a-change`. It must commit as it goes, where `refactor` commits only when asked. -- **Rests on:** (A1), (A3), (A5), (A10), (A11), (A18), (A20), (A21) -- **Evidence status:** loop corroborated. The human gate rests on two independent practitioner sources. The safety of - the undo is drawn from the codebase and the commit-per-leaf practice. +- **What it is:** A coding-plugin skill that confirms the goal, runs discovery rounds, keeps a committed markdown graph, + and makes each leaf change itself under passing tests, committing each one. +- **Trade-offs:** It matches the method as described and keeps the whole loop in one place. But it re-implements + `refactor`'s change, test, and undo loop, so the suite gains a third place that carries out a restructure step. Every + undo hazard in the section above falls on this skill alone. +- **Rests on:** (A1), (A3), (A5), (A11), (A18) +- **Evidence status:** loop corroborated. The duplication cost is codebase-corroborated. -### O2: A discovery-only skill that builds the graph and hands leaves to `refactor` or `tdd` +### O2: A discovery-only skill that ends with a graph for the person to work through - **What it is:** The skill runs only the discovery half: try, record, undo. It ends with a graph file. The person then runs each leaf through `refactor` (or `tdd` for leaves that change behavior). -- **Trade-offs:** Execution reuses existing, tested skills, and the new skill stays small. But a leaf can reveal new - prerequisites while it is being built (A3), and `refactor` has no way to send them back into the graph. The person - becomes the go-between for every leaf. +- **Trade-offs:** The new skill stays small and execution reuses tested skills. But a leaf can turn up new + prerequisites while it is built (A3), and nothing carries them back into the graph. The person becomes the go-between + for every leaf. - **Rests on:** (A3), (A17), (A18), (A20) - **Evidence status:** corroborated for the fit. No source runs the method split this way. -### O3: One autonomous skill for the full loop, with a time or attempt budget and no human gate +### O3: A skill that owns the graph and discovery, and hands each leaf to `refactor` or `tdd` + +- **What it is:** The new skill owns the goal, the graph, and the discovery rounds. For each leaf it invokes `refactor` + (or `tdd` when the leaf changes behavior) with that one leaf as the whole plan. When `refactor` stops because the step + spread or failed twice, the new skill records the blockers as new nodes and goes back to discovery. +- **Trade-offs:** It reuses `refactor`'s tested undo and `tdd`'s test-first gate rather than duplicating them, and it + carries new prerequisites back into the graph, which O2 cannot. It depends on `refactor` stopping cleanly with the + offending step undone and the blockers named; the earlier report found the scope stop does not undo the step today + (A25), so that has to change or the new skill has to undo it. `tdd`'s refactor step says "revert it" with no + mechanism (A25), which matters for behavior-changing leaves. The overlap with `plan-a-change` for ordering work remains. +- **Rests on:** (A3), (A14), (A17), (A18), (A20), (A24), (A25) +- **Evidence status:** the fit is codebase-corroborated. The one outside example of joining Mikado to a refactor loop is + single-source (A14). + +### O4: One autonomous skill with a time budget and no human gate - **What it is:** O1's loop with no stops. A budget per attempt (10 minutes in the source) bounds each round, and fixed commit prefixes record discoveries. -- **Trade-offs:** It is the simplest to run and the least work to review. The budget comes from one source and was - designed for people. Nothing in it guards against an agent editing tests, and no source caps the number of rounds. +- **Trade-offs:** It is the simplest to run and the least work to review. Included for contrast: the budget comes from + one source and was designed for people, nothing guards against an agent editing tests, and no source caps the number + of rounds. - **Rests on:** (A4), (A9), (A13) - **Evidence status:** single-source for the specifics. -### O4: Add Mikado to `refactor` instead of building a new skill +### O5: Add Mikado to `refactor` instead of building a new skill - **What it is:** The earlier report's recommendation. When `refactor` stops on a scope or repeated-failure rule, it - records what blocked the step as prerequisites in its stop report (A25). One community skill does the same, using - Mikado as a fallback inside a refactor loop (A14). -- **Trade-offs:** It is the smallest change, and it adds no overlapping skill. But it never runs discovery on purpose, - so a deep chain of blockers takes several runs. It also does not deliver the new skill that was asked for. + records what blocked the step as prerequisites in its stop report (A25). +- **Trade-offs:** It is the smallest change and adds no overlapping skill, and the earlier report recommended it on its + merits. It never runs discovery on purpose, so a deep chain of blockers takes several runs. It is ruled out here by + the decision to build a new skill, not by the evidence. - **Rests on:** (A14), (A18), (A25) - **Evidence status:** codebase-corroborated for the fit. A14 is single-source. ## Recommendation -- **Recommendation:** O1, built with these specific choices. - 1. **Place it in `han-coding`**, beside `refactor` and `tdd`. Route between it and its neighbors in the description: - `plan-a-change` predicts a restructure by reading code, and this skill discovers one by trying it. - 2. **Make the undo safe by construction.** Require a clean tree and a passing suite before the first attempt. Commit - each finished leaf, and commit each graph update separately from the code. Undo an attempt by restoring the code to - the last commit, which then holds every passing step. Never undo across uncommitted work the person made. - 3. **Define "broken" up front** as the resolved test command plus the type-check command where one exists, reusing - the detection script `refactor` uses. - 4. **Keep the graph in a committed markdown file**, a nested checklist where each node carries an ID and what it - requires. Mark a node done only after its green commit. - 5. **Stop for the person at two points:** to confirm the goal and its completion check, and after each discovery round - to review how failures were grouped into prerequisites. Present each stop in the shape the collaborative-stop rule - sets, and add the skill to `pairing`'s list. - 6. **Guard against patching forward.** A red attempt is always undone, never patched. A leaf commit that restructures - code changes no tests. - 7. **Bound discovery with a round count, not a clock.** Treat the exact limit as open, because the only stated budget - (10 minutes) was designed for people. +- **Recommendation:** O3, built with these specific choices. + 1. **Place it in `han-coding`**, beside `refactor` and `tdd`. Discovery is planning-like, since its edits are thrown + away, but the skill edits code, runs tests, and commits, and those are what the coding plugin holds. + 2. **Hand each leaf to `refactor`, or to `tdd` when the leaf changes behavior.** Treat a `refactor` scope stop or + double failure as a discovery: record the blockers as new nodes and return to discovery. Make `refactor`'s scope + stop undo the offending step, or have the new skill undo it. + 3. **Get commit consent at the first stop.** Mikado's safety depends on committing each leaf and each graph update, so + the skill says so when it confirms the goal and runs on a dedicated branch. It refuses a dirty tree, which is + stricter than `refactor` on purpose, because its undo is only safe from a clean one. + 4. **Choose the discovery undo deliberately.** Either restore to the last commit under every condition in "The undo + problem," or run each attempt in a throwaway worktree. No source settles this; the deciding criteria are the cost + of reinstalling dependencies per attempt against the risk of touching the person's working tree. + 5. **Define "broken" up front** as build, test, and lint failures. Reuse `refactor`'s detection script for those + commands, ask for the type-check command as `refactor` does, and have the person confirm the commands at the first + stop. + 6. **Keep the graph in a committed markdown file**, a nested checklist where each node carries an ID and what it + requires. Name its path, and decide whether Han's output-directory setting applies to it. Mark a node done only + after its green commit. + 7. **Stop for the person to confirm the goal, its completion check, and the commands.** A stop after each discovery + round to review how failures were grouped is a reasonable default but rests on one source (A10); under `pairing`, + add a stop after each leaf commit, as the worked example did (A11). + 8. **Guard against patching forward.** A red attempt is always undone, never patched. Test changes happen only in + `tdd` leaves; a restructuring leaf changes no tests. + 9. **Cap discovery rounds** with a configurable count and a stop when exceeded. The right number is an open + assumption; the only stated budget (10 minutes) was designed for people. - **Evidence basis:** The loop, the graph as the lasting artifact, and commit-per-leaf are corroborated across several - independent sources (A1, A2, A3, A4, A5, A11). The plugin placement, the test-detection reuse, and the undo hazard come - from the codebase (A18, A19, A21). The human gate on root-cause grouping rests on two independent practitioner posts - (A10, A11). The no-test-edits rule rests on one source each for the risk and the guard (A9, A14) [single-source]. The - attempt budget in choice 7 is the one part with no evidence behind it, so it is left open rather than fixed. + sources (A1, A2, A3, A4, A5, A11). Handing leaves to `refactor`, the meaning of its stops, the undo hazard, and the + plugin placement come from the codebase (A17, A18, A19, A24). The precondition list for a safe restore is drawn from + git's behavior and the codebase, not from any source. The grouping-review stop rests on one source (A10) + [single-source], and the no-test-edits rule on one source for the risk (A9) [single-source]. The undo choice and the + round cap are left open because no evidence settles them. Removing any single web source leaves the recommendation + standing except the grouping-review stop, which falls back to a design choice. ## Validation -Validation has not run yet; this section is filled in after the adversarial pass. +### V1: The codebase citations match the files + +- **Strategy:** Challenge the Evidence +- **Investigation:** Checked every codebase location (A17 to A26) against the current files and git history. +- **Result:** Confirmed +- **Impact:** All locations hold. Two content problems surfaced elsewhere (V2, V6). + +### V2: The detection script was over-credited + +- **Strategy:** Challenge the Evidence +- **Investigation:** Searched the detection script for a type-check command. +- **Result:** Partially Refuted +- **Impact:** The script infers test, lint, and build commands only, and its guesses need confirming. The recommendation + now asks for the type-check command and adds build failure to "broken," since compile breaks are the method's main + signal. + +### V3: Several citations did not support their claims + +- **Strategy:** Challenge the Evidence +- **Investigation:** Compared each cited claim against its registry entry. +- **Result:** Partially Refuted +- **Impact:** Corrected: "four independent sources" became the authors' talk, a report on it, and two practitioners; + commit-on-green moved to the sources that say it; "at least four community skills" became three; absence claims now + read "the search found none"; several registry entries were widened to carry what the sources said. + +### V4: The human-gate evidence was overstated + +- **Strategy:** Challenge the Evidence +- **Investigation:** Compared the gate claim in the Recommendation with the two sources cited for it. +- **Result:** Refuted +- **Impact:** Only one source supports a person reviewing how failures are grouped (A10). The other shows a different + gate, approving each commit (A11). The recommendation now labels the grouping stop single-source. + +### V5: "Safe by construction" does not hold for the undo + +- **Strategy:** Challenge the Recommendation +- **Investigation:** Traced a restore to the last commit against created files, ignored and generated files, installed + packages, the graph file, a person editing during the run, an interrupted leaf, and a repository without git. +- **Result:** Refuted as stated +- **Impact:** Replaced the claim with an explicit list of conditions, added the throwaway-worktree alternative, and left + the choice between them open. + +### V6: Committing as it goes conflicts with Han's convention + +- **Strategy:** Challenge the Recommendation +- **Investigation:** Compared the design with `refactor`, which commits only on request, and with Han's output-directory + setting. +- **Result:** Partially Refuted +- **Impact:** The recommendation now gets commit consent at the first stop, runs on a dedicated branch, explains the + stricter clean-tree rule, and names the graph path as a decision to make. + +### V7: Options were missing + +- **Strategy:** Challenge the Options Framing +- **Investigation:** Looked for alternatives between the listed options, including a throwaway copy for attempts, a + hybrid that delegates leaves, and an agent for grouping. +- **Result:** Partially Refuted +- **Impact:** Added the hybrid as O3, which became the recommendation because it reuses `refactor` instead of + duplicating it. Added the worktree undo. O4 and O5 are now marked as included for contrast, with their real grounds + for rejection. A grouping agent was not added: the only source on grouping says it belongs to a person. + +### V8: The earlier report's argument was handled thinly + +- **Strategy:** Challenge the Recommendation +- **Investigation:** Read the earlier report's recommendation and its rejection of a separate skill. +- **Result:** Partially Refuted +- **Impact:** Added a section on how this report relates to it, what has changed since, and the routing edits the + overlap requires. + +### V9: Plugin placement holds, with a gap + +- **Strategy:** Challenge the Recommendation +- **Investigation:** Checked placement against how the coding and planning plugins split their skills. +- **Result:** Confirmed +- **Impact:** Added a sentence on why discovery's planning-like nature does not change placement, and listed the work a + new skill must ship with. + +### V10: What `pairing` adds was unstated + +- **Strategy:** Challenge the Recommendation +- **Investigation:** Compared the always-on stops with the collaborative-stop rule. +- **Result:** Partially Refuted +- **Impact:** The recommendation now says `pairing` adds a stop after each leaf commit on top of the default stops. + +### V11: The web evidence holds up, with one load-bearing single source + +- **Strategy:** Challenge the Evidence-Gathering Integrity +- **Investigation:** Reviewed authorship and interest for each web source, and removed each in turn to test the + recommendation. +- **Result:** Partially Refuted +- **Impact:** No directive text was found in any summary. A7 and A12 share an author who builds Mikado tooling, A9 and + A11 share an author, and A4, A12, A13, and A14 are interested parties; the registry now says so. The recommendation + survives removing any one source except the grouping stop, which rests on A10 alone. + +### V12: Smaller gaps + +- **Strategy:** Challenge the Recommendation +- **Investigation:** Checked the test rule against behavior-changing leaves and the round cap against a graph that + never converges. +- **Result:** Confirmed +- **Impact:** Test changes now happen only in `tdd` leaves. The round cap is now a configurable count with a stop, + labeled as an assumption. + +### Adjustments Made + +Validation changed the recommendation from O1 (one skill that carries out every leaf itself) to O3 (a skill that hands +each leaf to `refactor` or `tdd`). It also replaced the undo safety claim with a list of conditions, left the undo +mechanism open between restore and a throwaway worktree, and downgraded the grouping-review stop to single-source. + +### Confidence Assessment + +- **Confidence:** Medium +- **Remaining Risks:** + - The validator had no web access, so it judged the web sources from their registry summaries only. + - No source measures whether the method, or an agent running it, improves outcomes. + - The grouping-review stop rests on one source (A10). + - O3 depends on changes to `refactor`'s scope stop and on `tdd`'s revert having a mechanism. + - The undo mechanism and the round cap are open decisions, untested in a real repository. + - The earlier report (A25) lives only on an unmerged branch. ## Sources -| ID | Source | Link / location | Retrieved | Trust class | Summary (one line) | Evidence status | -| --- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------- | -| A1 | Øredev 2010 speaker page, Ola Ellnestam | https://archive.oredev.org/oredev2010/2010/speakers/ola-ellnestam | 2026-10-27 | web | Co-author's 7-step "Naive Approach": goal, naive attempt, find breaks, record prerequisites, revert, recurse, leaves first. | corroborated by A2, A3, A5 | -| A2 | InfoQ, "Large scale refactoring" (2010) | https://www.infoq.com/news/2010/08/large-scale-refactoring | 2026-10-27 | web | Graph built from the goal down; leaves have no prerequisites and go first; do not fear reverting. | corroborated by A1, A3 | -| A3 | heise, "Update legacy code step by step with the Mikado method" | https://www.heise.de/en/background/Update-legacy-code-step-by-step-with-the-Mikado-method-11119651.html?seite=all | 2026-10-27 | web | Six-step loop, flexible graph tooling, and limits: no natural end, needs tests and fast builds, unwinding finds new obstacles. | loop corroborated by A1, A2, A5; limits single source | -| A4 | Vinta Software, "The Mikado Method" (2025) | https://www.vintasoftware.com/blog/the-mikado-method | 2026-10-27 | web | 10-minute timeboxed rounds, hard reset on failure, commit per green node, completion check fixed up front. | commit-per-node corroborated by A5, A11; timebox single source | -| A5 | Matthias Noback, "Successful refactoring projects: the Mikado Method" (2021) | https://matthiasnoback.nl/2021/02/refactoring-the-mikado-method/ | 2026-10-27 | web | Worked dependency-removal example; finished prerequisites committed one at a time so every step leaves a working app. | corroborated by A1, A3, A4 | -| A6 | Manning / O'Reilly book pages, *The Mikado Method* (2014) | https://livebook.manning.com/book/the-mikado-method/chapter-1 | 2026-10-27 | web | Confirms authors, publisher, and year; body text was not readable. | single source | -| A7 | mikado.nvie.com | https://mikado.nvie.com/ | 2026-10-27 | web | Graph is the main artifact, usually drawn on paper; tool shares graphs, for example on pull requests. | corroborated by A3, A4 | -| A8 | Martin Fowler, "Parallel Change" | https://martinfowler.com/bliki/ParallelChange.html | 2026-10-27 | web | Expand, migrate, contract keeps code shippable through a change that cannot land in one step. | single source; not a Mikado source | -| A9 | Chaabani, "Taming Agentic Refactoring with the Mikado Method" | https://anischaabani.com/en/blog/mikado-method-ai-agents/ | 2026-10-27 | web | Agent failure modes: sweeping edits, scattered context, tests edited to pass; reverts with a hard reset; versioned graph file. | partly corroborated by A10; same author as A11 | -| A10 | WellAged.dev, "The Mikado Method in the Age of AI Agents" | https://wellaged.dev/posts/mikado-method-ai-agents/ | 2026-10-27 | web | Graph is what survives each step; commit leaves only on green; grouping failures by root cause cannot be delegated to the agent. | corroborated by A9, A11 on revert and graph; root-cause claim single source | -| A11 | Chaabani, "Mikado Method in Action" | https://anischaabani.com/en/blog/mikado-method-example/ | 2026-10-27 | web | Worked agent example: committed checklist graph with IDs and `requires:`, graph commit then code revert, one commit per leaf, human approves each. | single source for format (same author as A9) | -| A12 | nvie/skills "mikado" (skills.sh listing) | https://skills.sh/nvie/skills/mikado | 2026-10-27 | web | Community skill keeps one graph per goal under an uncommitted `.mikado/` folder. | single source; full skill not visible | -| A13 | nWave "nw-mikado-method" (OpenSkillIndex listing) | https://openskillindex.com/skills/nwave-ai-nwave-nw-mikado-method-474589 | 2026-10-27 | web | Community skill: committed checklist graph, revert after every attempt, 10-minute attempts, one leaf at a time, no human gate. | loop corroborated by A9, A11; specifics single source | -| A14 | Oma Refactor skill (TypingMind listing) | https://www.typingmind.com/skills/first-fluke-oma-refactor | 2026-10-27 | web | Mikado as a fallback inside a test-gated refactor loop; refactor commits change no tests; graph held in memory. | single source | -| A15 | Pre-agent Mikado tooling (clokado, mikado_graph_generator, mikado-app) | https://github.com/ahitrin/clokado | 2026-10-27 | web | Pre-agent tooling is graph drawers and small web apps; no IDE plugin or CLI found. | single search pass (snippets only) | -| A16 | Kent Beck, "make the change easy, then make the easy change" | https://tidyfirst.substack.com/p/hinge | 2026-10-27 | web | States the enabling-change-first rule; no source ties it to Mikado directly. | corroborated across two Beck posts | -| A17 | `refactor` skill, plan step | `han-coding/skills/refactor/SKILL.md:110-124` | n/a | codebase | Plans every refactoring, with evidence and a file list, before the first edit. | codebase anchor | -| A18 | `refactor` skill, execute, undo, and stop rules | `han-coding/skills/refactor/SKILL.md:128-155` | n/a | codebase | One change then the full suite; undo only the step's own edits, never restore from git; stop on scope spread or two failures in a row. | codebase anchor | -| A19 | `refactor` skill description | `han-coding/skills/refactor/SKILL.md:3-12` | n/a | codebase | Test-gated loop in the coding plugin; routes multi-module restructure planning to `plan-a-change`. | codebase anchor | -| A20 | `plan-a-change` skill | `han-planning/skills/plan-a-change/SKILL.md:3-10`, `:312-315` | n/a | codebase | Sequences change units so each leaves the code working, by reading code, never by trying a change. | codebase anchor | -| A21 | Test-command detection script | `han-coding/skills/refactor/scripts/detect-refactor-context.sh:26-94` | n/a | codebase | Infers the project's test command from its manifest (npm, pytest, go, cargo, and others). | codebase anchor | -| A22 | Collaborative-stop rule | `han-core/references/collaborative-stop-rule.md` | n/a | codebase | Shared contract for how a skill detects the collaborative flag and what a stop presents. | codebase anchor | -| A23 | `pairing` skill, flagged skills | `han-core/skills/pairing/SKILL.md:87-89` | n/a | codebase | Lists the skills `pairing` can drive collaboratively: tdd, refactor, design-an-api, iterative-plan-review, plan-implementation. | codebase anchor | -| A24 | Entity taxonomy | `han-plugin-builder/skills/guidance/references/plugin-entity-taxonomy.md` | n/a | codebase | A flowchartable, repeatable process is a skill; contextual judgment is an agent. | codebase anchor | -| A25 | Earlier Han research on Mikado in `refactor` | `docs/research/mikado-method-refactor.md` on branch `research/mikado-method-refactor` | n/a | codebase | Advised against a Mikado mode in `refactor` and a separate skill; recommended fixing the undo, then recording prerequisites at stops. | codebase anchor (prior research) | -| A26 | Coverage rule | `docs/templates/coverage-rule.md` | n/a | codebase | Every new skill needs a long-form doc, a plugin README line, and an index entry in the same change. | codebase anchor | +| ID | Source | Link / location | Retrieved | Trust class | Summary (one line) | Evidence status | +| --- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| A1 | Øredev 2010 speaker page, Ola Ellnestam (co-author) | https://archive.oredev.org/oredev2010/2010/speakers/ola-ellnestam | 2026-10-27 | web (interested party) | Co-author's 7-step "Naive Approach," called a depth-first recursion: goal, naive attempt, find breaks via compiler and tests, record, revert, recurse, leaves first. | corroborated by A3, A5 | +| A2 | InfoQ, "Large scale refactoring" (2010) | https://www.infoq.com/news/2010/08/large-scale-refactoring | 2026-10-27 | web | Report on the authors' talk: graph built from the goal down; leaves have no prerequisites and go first; do not fear reverting. | corroborated by A3; not independent of A1 | +| A3 | heise, "Update legacy code step by step with the Mikado method" | https://www.heise.de/en/background/Update-legacy-code-step-by-step-with-the-Mikado-method-11119651.html?seite=all | 2026-10-27 | web | Six-step loop, flexible graph tooling, reset or stash to undo; limits: no natural end, needs tests and fast builds, undoing feels wasteful, unwinding finds new obstacles. | loop corroborated by A1, A5; limits single source | +| A4 | Vinta Software, "The Mikado Method" (2025) | https://www.vintasoftware.com/blog/the-mikado-method | 2026-10-27 | web (consultancy) | 10-minute rounds, hard reset on failure, commit per green node, graph attachable to pull requests, completion check fixed up front, early rounds commit nothing. | commit-per-node corroborated by A5, A11; timebox single source | +| A5 | Matthias Noback, "Successful refactoring projects: the Mikado Method" (2021) | https://matthiasnoback.nl/2021/02/refactoring-the-mikado-method/ | 2026-10-27 | web | Dependency-removal example; each prerequisite committed only when green; reverting feels wasteful; hidden dependencies are hard to find by trying. | corroborated by A1, A3, A4 | +| A6 | Manning / O'Reilly book pages, *The Mikado Method* (2014) | https://livebook.manning.com/book/the-mikado-method/chapter-1 | 2026-10-27 | web | Confirms authors, publisher, and year; body text was not readable. | single source | +| A7 | mikado.nvie.com (Vincent Driessen) | https://mikado.nvie.com/ | 2026-10-27 | web (interested party) | Graph is the main artifact, usually drawn on paper; the tool shares graphs, for example on pull requests. | corroborated by A3, A4; same author as A12 | +| A8 | Martin Fowler, "Parallel Change" | https://martinfowler.com/bliki/ParallelChange.html | 2026-10-27 | web | Expand, migrate, contract keeps code shippable through a change that cannot land in one step. | single source; not a Mikado source | +| A9 | Anis Chaabani, "Taming Agentic Refactoring with the Mikado Method" (2026) | https://anischaabani.com/en/blog/mikado-method-ai-agents/ | 2026-10-27 | web | Agent failure modes (sweeping edits, scattered context, tests edited to pass); compiler and tests as the signal; hard reset to undo; versioned graph file. | partly corroborated by A10; same author as A11 | +| A10 | WellAged.dev, "The Mikado Method in the Age of AI Agents" (2026) | https://wellaged.dev/posts/mikado-method-ai-agents/ | 2026-10-27 | web | Graph is what survives each step; commit leaves only on green; grouping failures by root cause cannot be delegated to the agent. | revert and graph corroborated by A9; root-cause claim single source | +| A11 | Anis Chaabani, "Mikado Method in Action" (2026) | https://anischaabani.com/en/blog/mikado-method-example/ | 2026-10-27 | web | Agent example: committed checklist graph with IDs and `requires:`, a loop-check script, graph commit then code revert, one commit per leaf, person approves each. | single source for format; same author as A9 | +| A12 | nvie/skills "mikado" (skills.sh listing) | https://skills.sh/nvie/skills/mikado | 2026-10-27 | web (interested party) | Community skill keeps one graph per goal in an uncommitted `.mikado/` folder. | single source; full skill not visible; same author as A7 | +| A13 | nWave "nw-mikado-method" (OpenSkillIndex listing) | https://openskillindex.com/skills/nwave-ai-nwave-nw-mikado-method-474589 | 2026-10-27 | web (interested party) | Community skill: committed checklist graph, compile and test failures as the signal, revert after every attempt, 10-minute attempts, no human gate. | loop corroborated by A9, A11; specifics single source | +| A14 | Oma Refactor skill (TypingMind listing) | https://www.typingmind.com/skills/first-fluke-oma-refactor | 2026-10-27 | web (interested party) | Mikado as a fallback inside a test-gated refactor loop after repeated failure; refactor commits change no tests; graph held in memory. | single source | +| A15 | Pre-agent Mikado tooling (clokado, mikado_graph_generator, mikado-app) | https://github.com/ahitrin/clokado | 2026-10-27 | web | Pre-agent tooling is graph drawers and small web apps; no IDE plugin or CLI found. | single search pass (snippets only) | +| A16 | Kent Beck, "make the change easy, then make the easy change" | https://tidyfirst.substack.com/p/hinge | 2026-10-27 | web | States the enabling-change-first rule; no source ties it to Mikado directly. | corroborated across two Beck posts | +| A17 | `refactor` skill, plan step | `han-coding/skills/refactor/SKILL.md:110-124` | n/a | codebase | Plans every refactoring, with evidence and a file list, before the first edit. | codebase anchor | +| A18 | `refactor` skill, execute, undo, and stop rules | `han-coding/skills/refactor/SKILL.md:128-155` | n/a | codebase | One change then the full suite; undo only the step's own edits, never restore from git; stop on scope spread or two failures in a row; commit only on request. | codebase anchor | +| A19 | `refactor` skill description | `han-coding/skills/refactor/SKILL.md:3-12` | n/a | codebase | Test-gated loop in the coding plugin; routes multi-module restructure planning to `plan-a-change`. | codebase anchor | +| A20 | `plan-a-change` skill | `han-planning/skills/plan-a-change/SKILL.md:3-10`, `:312-315` | n/a | codebase | Sequences change units so each leaves the code working, by reading code, never by trying a change. | codebase anchor | +| A21 | Command detection script | `han-coding/skills/refactor/scripts/detect-refactor-context.sh:26-94` | n/a | codebase | Infers test, lint, and build commands from the project's manifest as suggestions to confirm; no type-check detection. | codebase anchor | +| A22 | Collaborative-stop rule | `han-core/references/collaborative-stop-rule.md` | n/a | codebase | Shared contract for how a skill detects the collaborative flag and what a stop presents. | codebase anchor | +| A23 | `pairing` skill, flagged skills | `han-core/skills/pairing/SKILL.md:87-89` | n/a | codebase | Lists the skills `pairing` can drive: tdd, refactor, design-an-api, iterative-plan-review, plan-implementation. | codebase anchor | +| A24 | Entity taxonomy | `han-plugin-builder/skills/guidance/references/plugin-entity-taxonomy.md` | n/a | codebase | A flowchartable process is a skill and may invoke other skills for fixed sub-steps; contextual judgment is an agent. | codebase anchor | +| A25 | Earlier Han research on Mikado in `refactor` | `docs/research/mikado-method-refactor.md` on branch `research/mikado-method-refactor` | n/a | codebase (prior research) | Advised against a separate skill on overlap grounds; recommended the undo fix, then recording blockers at stops; found the scope stop does not undo and `tdd`'s revert has no mechanism. | codebase anchor; unmerged branch | +| A26 | Coverage rule | `docs/templates/coverage-rule.md` | n/a | codebase | Every new skill needs a long-form doc, a plugin README line, and an index entry in the same change. | codebase anchor | From 277b69894db90f63a96a7722e32bfea7099982f5 Mon Sep 17 00:00:00 2001 From: River Bailey Date: Tue, 27 Oct 2026 08:38:06 -0600 Subject: [PATCH 3/7] docs(research): readability pass on Mikado skill research --- docs/research/mikado-method-skill.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/research/mikado-method-skill.md b/docs/research/mikado-method-skill.md index 4400c660..a874db94 100644 --- a/docs/research/mikado-method-skill.md +++ b/docs/research/mikado-method-skill.md @@ -6,16 +6,17 @@ should share work with the skills Han already has, and where it should sit. Evid ## Summary -Build a new skill that owns the Mikado graph and the discovery rounds, and hands each finished-out step to the -`refactor` or `tdd` skill to carry out. The method is well described and stable: try the change the simple way, write +Build a new skill that owns the Mikado graph and the discovery rounds, and hands each leaf (a step with no prerequisites +of its own) to the `refactor` or `tdd` skill to carry out. The method is well described and stable: try the change the simple way, write down what breaks, undo the attempt, fix the blockers first, and commit each one only when the tests pass. Han already has skills that make one small change safely under passing tests, so the new skill should reuse them rather than build a third way to do that. -The hardest part is undoing a deliberately wide attempt without losing anyone's work. Restoring files from git, the -method practitioners use, is only safe under a short list of conditions the skill has to check, and nothing settles -whether a throwaway copy of the code is the better choice. The loop itself is well-corroborated. The agent-specific -design advice comes from a handful of 2026 blog posts and skill listings, and nothing measures whether any of it works. +The hardest part is undoing a deliberately wide attempt without losing anyone's work. Restoring files from git is the +undo practitioners use. It is only safe under a short list of conditions the skill has to check, and nothing settles +whether a throwaway copy of the code is the better choice. + +The loop itself is well-corroborated. The agent-specific design advice comes from a handful of 2026 blog posts and skill listings, and nothing measures whether any of it works. - **Confidence:** Medium - **Web search:** used @@ -190,7 +191,7 @@ Han's conventions add required work to any new skill (A22, A23, A26): spread or failed twice, the new skill records the blockers as new nodes and goes back to discovery. - **Trade-offs:** It reuses `refactor`'s tested undo and `tdd`'s test-first gate rather than duplicating them, and it carries new prerequisites back into the graph, which O2 cannot. It depends on `refactor` stopping cleanly with the - offending step undone and the blockers named; the earlier report found the scope stop does not undo the step today + offending step undone and the blockers named. The earlier report found the scope stop does not undo the step today (A25), so that has to change or the new skill has to undo it. `tdd`'s refactor step says "revert it" with no mechanism (A25), which matters for behavior-changing leaves. The overlap with `plan-a-change` for ordering work remains. - **Rests on:** (A3), (A14), (A17), (A18), (A20), (A24), (A25) From dab9ba0b506e98f0f48a1116f66bf582bf199f9a Mon Sep 17 00:00:00 2001 From: River Bailey Date: Tue, 27 Oct 2026 08:51:36 -0600 Subject: [PATCH 4/7] feat(restructure): add the restructure skill with Mikado discovery for stalled units Coordinates architectural-analysis, plan-a-change (or its own plan when han-planning is absent), and refactor or tdd per unit, after one start gate. A unit that stalls becomes the goal of a Mikado graph: attempt, record prerequisites, undo with undo-attempt.sh, and work leaves first. Co-Authored-By: Claude Opus 5.5 --- han-coding/skills/restructure/SKILL.md | 254 ++++++++++++++++++ .../references/change-log-format.md | 116 ++++++++ .../restructure/references/mikado-method.md | 152 +++++++++++ .../restructure/scripts/undo-attempt.bats | 100 +++++++ .../restructure/scripts/undo-attempt.sh | 61 +++++ 5 files changed, 683 insertions(+) create mode 100644 han-coding/skills/restructure/SKILL.md create mode 100644 han-coding/skills/restructure/references/change-log-format.md create mode 100644 han-coding/skills/restructure/references/mikado-method.md create mode 100644 han-coding/skills/restructure/scripts/undo-attempt.bats create mode 100755 han-coding/skills/restructure/scripts/undo-attempt.sh diff --git a/han-coding/skills/restructure/SKILL.md b/han-coding/skills/restructure/SKILL.md new file mode 100644 index 00000000..ca9713a5 --- /dev/null +++ b/han-coding/skills/restructure/SKILL.md @@ -0,0 +1,254 @@ +--- +name: restructure +description: > + Restructures a codebase or a large area of it toward a target layout or set of boundaries without changing behavior. + After one start gate it runs unattended: it analyzes the area, plans ordered units, carries out each unit through + refactor or tdd, and commits each one on the current branch with a change log that justifies every decision. When a + unit stalls because its code is too tangled to move in one step, it uses the Mikado Method to tease it apart: try the + change, record what breaks as prerequisites in a committed graph, undo the attempt, and do the prerequisites first. + Use when the user wants to reorganize, restructure, split up, untangle, or re-apply a layout across many files or + modules, or to enforce the documented structure. Does not restructure one named spot — use refactor. Does + not plan without executing — use plan-a-change. Does not stop at findings — use architectural-analysis. Does not + change behavior. Runs to completion after the start gate; to review each unit as it lands, use pairing. +argument-hint: "[the target structure or goal, optional: the area to restructure]" +allowed-tools: + Read, Write, Edit, Glob, Grep, Skill, Bash(git *), Bash(find *), Bash(mkdir *), Bash(date *), Bash(npm *), + Bash(npx *), Bash(pnpm *), Bash(yarn *), Bash(bun *), Bash(pytest *), Bash(python3 *), Bash(go *), Bash(cargo *), + Bash(make *), Bash(bundle *), Bash(rake *), Bash(bash "${CLAUDE_SKILL_DIR}/scripts/undo-attempt.sh" *), + Bash(bash "${CLAUDE_PLUGIN_ROOT}/skills/refactor/scripts/detect-refactor-context.sh"), + Bash(bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh") +--- + +## Project Context + +- git installed: !`which git 2>/dev/null || echo "not installed"` +- current branch: !`git branch --show-current 2>/dev/null || echo unknown` +- working tree: !`git status --porcelain 2>/dev/null | head -5` +- CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` +- AGENTS.md: !`find . -maxdepth 1 -name "AGENTS.md" -type f` +- project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` +- personal config directory: !`bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"` +- project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` + +As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read +that returns no file is no personal configuration: continue silently. When that file or the `project .han/config.md` +probe supplies content, apply it per [config-rule.md](../../references/config-rule.md), which governs precedence +between the two files, relative-path resolution, and what to do with a file that reads but cannot be used. + +## Constraints (read before anything else) + +The steps below are the whole skill. This skill is a coordinator. `architectural-analysis`, `plan-a-change`, `refactor`, +and `tdd` do the analysis, the planning, and the code changes. This skill discovers the project, validates, forwards, +captures what each one produced, commits, and logs. The one piece of work it does itself is the Mikado discovery loop +for a unit that stalls, and every edit that loop makes is thrown away. + +- **One start gate, then unattended.** Step 3 is the one stop where the person confirms the goal and the run's settings. + After it, never ask the person a question and never wait for approval, BECAUSE they have stepped away, and a question + left pending stops the whole run. Decide from evidence (the code, the project's documented structure rules, earlier + change sets, the analysis) and record every decision as a D-N entry. The only other stops are the hard failures Steps + 2, 7, and 8 name, and the collaborative stop in Step 7. Report a hard failure and end the run. +- **Everything about the project is discovered at runtime.** Never assume a language, a directory layout, a set of + packages or modules, a test runner, or an entry point. Find them in the project's own files in Step 1, BECAUSE this + skill runs on any codebase, and a guessed layout moves the wrong files. +- **Commits go to the current branch and no further.** Commit each step to the branch checked out at the start gate. + Never create or switch branches, push, or open a pull request, BECAUSE the person decides where this work lands and + who sees it. +- **The tree must start clean, untracked files included.** This is stricter than `refactor` on purpose. Failed units + and discovery attempts are undone by restoring to the last commit, which is only safe when the last commit holds + everything worth keeping. +- **No behavior changes.** Every unit preserves observable behavior. A finding that needs a behavior change becomes a + follow-up in the change log, never a unit. Entry points that build scripts, manifests, or deployment configuration + name by path either stay where they are or move in a unit that updates every reference to them. +- **Never patch forward.** A red unit is undone, never fixed in place. A restructuring unit changes no test except to + move it with its code and update its imports; tests change only in a `tdd` unit, to drive new code. Never edit a test + to make a unit pass, BECAUSE a test edited to agree with the change no longer proves behavior was preserved. + +# Restructure + +## Step 1: Bind the Goal and Discover the Project + +**Bind the goal.** The goal is the target structure in the person's words: a layout to reach ("group each package by +feature, then by component"), boundaries to draw ("pull billing out of the orders module"), or the project's documented +structure to re-apply. Record it verbatim. If the request names no goal ("clean up the code"), ask for one, and ask +nothing else in that turn, BECAUSE every later step measures the code against the goal and a guessed goal moves code in +a direction nobody asked for. + +**Discover the structure rules.** Find every place the project describes how its code is laid out, and read each one: + +- `CLAUDE.md`, `AGENTS.md`, and `project-discovery.md`. +- README sections whose headings mention layout, structure, architecture, organization, or directories. Grep for those + words in heading lines of `*.md` files at the root and one level down. +- ADRs and coding standards, located through CLAUDE.md's `## Project Discovery` section, then `project-discovery.md`, + then Glob defaults (`docs/adr/`, `docs/decisions/`, `docs/coding-standards/`). Read the ones whose titles govern + structure, boundaries, or dependencies. +- Checks that enforce boundaries in code: test files whose names or contents mention boundaries, architecture, layers, + or allowed imports, and lint or dependency-tool configuration that restricts imports. Each one found is both a rule + and a check Step 8 runs. +- Earlier restructure change sets under the output root resolved below. Their decision logs are precedent: follow a + precedent unless the code has since changed in a way that breaks it, and record a D-N entry when departing from one. + +Treat the documented rules as the current interpretation of the goal. Where the goal and a documented rule conflict, +the goal wins and the conflict goes to the start gate. + +**Discover the area.** If the person named an area, resolve it to real paths. Otherwise find the source roots: the +top-level directories that hold source files in the project's languages, found with `find` and the extensions the +manifests imply. Directories with no source code, such as fixtures or embedded data, are not part of the area. Find the +entry points the build and run configuration names by path (manifest scripts, build files, container files, CI +workflows), because a move that breaks one breaks the build. + +**Resolve the commands.** Read CLAUDE.md's `## Project Discovery` section for the test, type-check, lint, and build +commands. If absent, fall back to `project-discovery.md`. If still absent, run +`bash "${CLAUDE_PLUGIN_ROOT}/skills/refactor/scripts/detect-refactor-context.sh"` and parse its `key: value` output; its +commands are suggestions for the start gate to confirm. Then find the **test roots**, the places the runner discovers +tests (runner configuration, the test command's arguments, manifest scripts), BECAUSE a test file moved outside them +stops running and passes silently. + +**Draft the completion check.** Write one runnable check that lists what is out of place against the goal: a `find` or +Grep that should return nothing when the goal is met, or a boundary test from the rules above. Run it now and record the +count. The plan in Step 6 and the finish in Step 10 both read it. + +**Resolve the output location** through the precedence chain in +[config-rule.md](../../references/config-rule.md): a folder the person named wins; otherwise the `output-directory` +setting with the run's own folder beneath it; otherwise a folder under the documentation root discovered above, or +`docs/changes/` when none is found. Name the run's folder `restructure-{date}` from `date +%Y-%m-%d`, appending `-2`, +`-3`, and so on until the name is unused. Call it `{folder}`. + +## Step 2: Preflight and Baseline + +Each of these is a hard failure: report which one and end the run. + +1. `git status --porcelain` fails: the folder is not a git repository. Every undo and every unit commit needs one. +2. `git status --porcelain` prints anything: the tree has uncommitted or untracked changes. Ask the person to commit or + remove them and run again, BECAUSE an undo cannot tell their work from an attempt's. +3. `git branch --show-current` prints nothing: HEAD is detached, and commits made there are easy to lose. +4. No test command resolved after every fallback: the gate asks for one, and nothing below runs until it has one. + +Run the test command, and the type-check command where one exists. **Paste the runner's summary line** and record the +counts as the baseline. If anything is red, report the output and end the run, BECAUSE a restructure can only be proven +behavior-preserving against a suite that was green to begin with. + +## Step 3: The Start Gate + +Present everything the run will act on, then end the turn: + +- The goal, verbatim, and the area it covers. +- The structure rules found, each with its source path, and any conflict between them and the goal. +- The completion check and how many items it lists today. +- The test, type-check, lint, and build commands, and the test roots. +- The branch. If it is the repository's default branch, say so and recommend the person create a dedicated branch first. +- The output folder. +- The discovery round cap, five per stalled unit unless the person sets another. +- What the run will do once confirmed: commit the analysis, the plan, every unit, and every Mikado graph update to this + branch, one commit each, with no further questions. + +Ask the person to confirm or amend any of it. When they answer, record each amendment and the confirmation itself as +the first D-N entries. From here on, the run asks nothing more. + +## Step 4: Start the Change Set + +1. Run `mkdir -p {folder}/artifacts`. +2. Write `{folder}/change-log.md` from the skeleton and `{folder}/artifacts/change-decision-log.md` from the decision + format in [references/change-log-format.md](references/change-log-format.md), filled with what Steps 1 to 3 + recorded. +3. Run `git add {folder}` and commit with the message `Start the restructure change set`. + +## Step 5: Run the Architectural Analysis + +Invoke `han-coding:architectural-analysis` through the Skill tool on the area. Pass the goal verbatim and these +overrides: + +- Run unattended. Choose the analysis size from evidence, and do not ask the person anything. +- Write the report to `{folder}/artifacts/architectural-analysis.md`. +- Focus on what would make moving code unsafe: paths computed from a file's own location, imports that cross the + boundaries the goal draws, code loaded by name or path at runtime, shared mutable state, and code duplicated across + the boundaries. + +When it returns, confirm the report file exists, add a change-log entry, run `git add {folder}`, and commit with the +message `Add the architectural analysis for the restructure`. Then continue to Step 6. The analysis is an input to this +skill, not its result. + +## Step 6: Plan the Units, or Stop if Nothing Is Out of Place + +1. Run the completion check, and compare the area against the structure rules. List every file that sits in the wrong + place and every analysis finding that blocks a move. +2. If the list is empty, add a `## No changes needed` section to the change log with the evidence, commit it with the + message `Record that the structure needs no changes`, report it, and end the run. +3. If `han-planning:plan-a-change` is among the available skills, invoke it through the Skill tool. Pass the goal + verbatim, the list from item 1, and the analysis report path, with these overrides: + - Run unattended. Resolve every interview question from evidence and record each as the next D-N entry in + `{folder}/artifacts/change-decision-log.md`, using the decision format in + [references/change-log-format.md](references/change-log-format.md). + - Write the plan to `{folder}/change-plan.md` and its companion files to `{folder}/artifacts/`. + - Keep the change a pure restructure. Record behavior-changing findings as follow-ups, not units. + - Split the work into ordered units with the fields in the unit format of + [references/change-log-format.md](references/change-log-format.md): kind (`refactor` or `tdd`), the files each may + touch, the units it depends on, and why. Put the units that make moving safe first. +4. If `plan-a-change` is not available, or the Skill call reports it unknown, write `{folder}/change-plan.md` yourself + from the list in item 1 and the analysis, using the unit format and ordering rule in + [references/change-log-format.md](references/change-log-format.md). Record a D-N entry saying the plan was written + without `plan-a-change`, and why each unit is ordered where it is. +5. Confirm the plan and the decision log exist, add a change-log entry, run `git add {folder}`, and commit with the + message `Plan the restructure`. Then continue to Step 7. + +## Step 7: Carry Out Each Unit + +Work through the plan's units in order, skipping any unit marked not started. For each unit: + +1. Confirm `git status --porcelain` is empty, and record `git rev-parse HEAD` as the unit's base. +2. Invoke `han-coding:refactor` for a `refactor` unit, or `han-coding:tdd` for a `tdd` unit, through the Skill tool. + Pass the unit text verbatim. Tell it to run unattended, to treat the unit's file list as its declared scope, to stop + and report rather than ask when it would otherwise ask the person, to record any new decision as the next D-N entry + in the decision log, and not to commit, BECAUSE this skill makes exactly one commit per unit so a unit can be undone + as a whole. +3. When it returns, run the test command and the type-check command. **Paste the summary lines.** The suite must be + green and must still include every baseline test. A count lower than the baseline, other than a count the plan says + it moves or merges, is a failure. +4. **Green:** add a change-log entry in the entry format, run `git add -A`, and commit with a message that names the + unit. If the unit is a node in the Mikado graph, check it off and include the graph in the same commit. + + **Running collaboratively.** When the request asks to review each unit as it lands, which is what `pairing` does + when it hands work here, stop at this point and hand control back instead of continuing. Present the stop in the + shape [collaborative-stop-rule.md](../../references/collaborative-stop-rule.md) specifies, with the commit as the + thing to check. Absent such a request, continue as below; an ordinary invocation is unchanged. + +5. **Stalled:** the sub-skill stopped because the unit needed files outside its list or two steps in a row failed, + `tdd` could not reach green, or the suite is red after it returned. Run + `bash "${CLAUDE_SKILL_DIR}/scripts/undo-attempt.sh" {base}` to return to the unit's base, re-run the suite, and + paste its summary line. Then go to Step 8 with this unit as the goal, and come back here when Step 8 returns. +6. **Not covered:** if `refactor` stopped because the unit's code has no meaningful test coverage, that is not a stall + and the Mikado Method cannot fix it. Undo to the base as in item 5, log the unit under "Units not done" with the + uncovered behaviors as a follow-up, and mark every unit that depends on it as not started. +7. **Hard failure:** if `undo-attempt.sh` exits non-zero, or the suite is not green after the undo, report the output + and end the run, BECAUSE nothing after this point can be trusted on an unknown tree. + +If two units in a row end up in "Units not done," skip to Step 10, BECAUSE repeated failures mean the plan no longer +matches the code. After the last unit, continue to Step 9. + +## Step 8: Tease Apart a Stalled Unit with the Mikado Method + +Read [references/mikado-method.md](references/mikado-method.md) and follow it with the stalled unit as the goal node. +It holds the discovery loop, what counts as broken, how to group failures into prerequisites, the graph file at +`{folder}/artifacts/mikado-graph.md`, the conditions that make each undo safe, and the round cap. + +- Add a change-log entry for each discovery round, in the discovery-round format. +- Carry out each leaf through items 1 to 4 of Step 7, as a unit of its own, then attempt its parent again. +- When the goal node is carried out and committed, return to Step 7 for the next unit. +- When the round cap is reached, commit the graph, log the unit under "Units not done" with its graph section, mark + every unit that depends on it as not started, and return to Step 7 for the next unit. + +## Step 9: Update the Structure Docs and Check the Build + +1. Rewrite each documentation section Step 1 found that describes the layout of the area, so it describes the tree as + it now stands and follows the goal. Commit with the message `Describe the restructured layout`. +2. Run the test, type-check, lint, and build commands. **Paste the summary line from each.** If one fails because a + path moved, fix that path reference, log the fix, re-run, and commit it. If it fails for any other reason, log the + output under "Units not done" rather than changing behavior to make it pass. + +## Step 10: Finish the Log and Report + +1. Run the completion check and record its result. +2. Finish `{folder}/change-log.md` with the closing sections from + [references/change-log-format.md](references/change-log-format.md), then commit with the message + `Finish the restructure change log`. +3. Report the branch, the change-log path, the units done and not done, the completion check's count before and after, + the final test counts compared with the baseline, and the decisions to look at first. diff --git a/han-coding/skills/restructure/references/change-log-format.md b/han-coding/skills/restructure/references/change-log-format.md new file mode 100644 index 00000000..b45bea7e --- /dev/null +++ b/han-coding/skills/restructure/references/change-log-format.md @@ -0,0 +1,116 @@ +# Change Set Formats + +## Contents + +- Change-log skeleton +- Entry format +- Decision format +- Unit format +- Closing sections + +Use these formats so every restructure change set reads the same way, and so a later run can read an earlier one as +precedent. `{folder}` is the change-set folder Step 1 resolved. + +## Change-log skeleton (`{folder}/change-log.md`) + +```markdown +# Change Log: {the goal, in the person's words} + +This is the running log of every change made in this change set, in the order it was made. After the start gate the run +continued without the person, so every decision is made and justified here. Each entry says what changed and why, and +links the decision (D-N) behind it. + +**Where to read more:** + +- [change-plan.md](change-plan.md): the plan these changes carry out. +- [artifacts/change-decision-log.md](artifacts/change-decision-log.md): every decision, with its reasoning and the + alternatives rejected. +- [artifacts/architectural-analysis.md](artifacts/architectural-analysis.md): the analysis that found the risks. +- [artifacts/mikado-graph.md](artifacts/mikado-graph.md): the prerequisites discovered for units that stalled. Present + only when a unit stalled. + +**Branch:** `{branch}`. Every step below is one commit on it. + +**Structure rules:** {each source of the rules the run applied, as a path, plus the goal itself}. + +**Commands:** test `{command}`, type-check `{command or none}`, lint `{command or none}`, build `{command or none}`. + +**Completion check:** `{the check}`, which listed {N} items out of place before any change. + +**Discovery round cap:** {N} per stalled unit. + +**Baseline before any change:** {the test runner's summary line, with counts}. +``` + +## Entry format + +Add one numbered section per step, in order: the analysis, the plan, each unit, each discovery round, and the +documentation update. + +```markdown +## {n}. Unit {k}: {what the unit does} (`refactor` or `tdd`) + +- **Commit:** the commit message. The short hash is not known until after the commit, so fill it in with the next + entry's commit, or at the finish for the last one. +- **What:** the files moved, created, or edited, as `old path` → `new path` where files moved. +- **Why:** the structure rule or the analysis finding this unit serves. +- **Decisions:** D-{n}, D-{n}, each with one line on what it settled. +- **Tests:** the suite's counts after the unit, compared with the baseline. +``` + +A discovery round gets a shorter entry: + +```markdown +## {n}. Discovery round {r} for G-{g}: {the node attempted} + +- **Attempt:** what was tried. +- **Broke:** the failing checks, one line each. +- **Prerequisites added:** G-{id}, G-{id}, with D-{n} for how the failures were grouped. +- **Undo:** the files `undo-attempt.sh` removed, and the suite's counts after the undo. +``` + +## Decision format (`{folder}/artifacts/change-decision-log.md`) + +Number decisions D-1, D-2, and so on in the order they were made. Never renumber, BECAUSE the change log, the plan, and +the graph link to them by number. Answers the person gave at the start gate are decisions too; record them first, with +the person as the rationale. + +```markdown +### D-{n}: {the decision, stated as a sentence} + +- **Question:** what had to be decided. +- **Decision:** what was chosen. +- **Rationale:** the evidence behind it: a file path, a rule, a finding, an earlier change set's precedent, or the + person's answer at the start gate. +- **Alternatives rejected:** each alternative and why it lost. +``` + +## Unit format + +Use this when the skill writes `{folder}/change-plan.md` itself because `plan-a-change` is not available. When +`plan-a-change` writes the plan, ask it for the same fields on each unit. + +```markdown +### Unit {k}: {what the unit does, stated as a change} + +- **Kind:** `refactor` (moves or renames existing code) or `tdd` (adds new code a move needs, such as a shared module + or a path anchor, driven by a test). +- **Files:** every file the unit may touch. This is the declared scope `refactor` holds the unit to. +- **Depends on:** the earlier units that must be done first, or "none". +- **Why:** the structure rule or analysis finding it serves, with the misplaced items it fixes. +- **Done when:** the observable result, such as the completion check no longer listing these items. +``` + +Order units so the ones that make moving safe come first, and every unit comes after the units it depends on. + +## Closing sections + +Add these to the end of the change log at the finish, in this order: + +- `## Where things ended up`: the top-level layout of the area after the change, the completion check's result, and + the final test counts compared with the baseline. +- `## Decisions to look at first`: the D-N entries that were closest calls, departed from precedent, overrode an + analysis recommendation, or grouped discovery failures, each with one line on why it matters. +- `## Units not done`: each unit that failed, stalled past the round cap, or was not started, with the failing output, + the graph section, or the unit it depended on. Write "None" if every unit finished. +- `## Follow-ups not done here (behavior changes)`: the behavior-changing findings the run deferred. diff --git a/han-coding/skills/restructure/references/mikado-method.md b/han-coding/skills/restructure/references/mikado-method.md new file mode 100644 index 00000000..000e8fb4 --- /dev/null +++ b/han-coding/skills/restructure/references/mikado-method.md @@ -0,0 +1,152 @@ +# The Mikado Method, as This Skill Runs It + +## Contents + +- When the method takes over +- The discovery loop +- What counts as broken +- Grouping failures into prerequisites +- The graph file +- The undo, and the conditions that make it safe +- Working the leaves back up +- The round cap +- Never patch forward + +The Mikado Method is a loop for a change too big or too tangled to make in one step. Ola Ellnestam and Daniel Brolund +described it in _The Mikado Method_ (Manning, 2014): try the change the simple way, write down what breaks, undo the +attempt, fix the blockers first, and work back up to the goal. This skill does not run it on every unit. It runs it on a +unit that stalled, because a stall is the signal that the unit has prerequisites the plan did not find by reading the +code. + +## When the method takes over + +A unit stalls when any of these happens: + +- `refactor` stopped because a step needed files outside the unit's declared file list. The files it reached for are + the first clue to the prerequisites. +- `refactor` stopped because two steps in a row failed. +- `tdd` could not bring the unit's behavior to green. +- The full suite is red after the unit returns, or a baseline test stopped being discovered. + +Each of these means the same thing: the unit depends on a change nobody has made yet. The stalled unit becomes the goal +node of a new graph. + +## The discovery loop + +Work one node at a time, depth first, starting from the goal node: + +1. **Check the tree is clean** with `git status --porcelain`, and record `git rev-parse HEAD` as the attempt's base. + Never start an attempt on a dirty tree, BECAUSE the undo cannot tell an attempt's edit from anything else. +2. **Try the node the simple, direct way.** Make the change as if nothing stood in the way: move the files, update the + imports, split the module. Go wide on purpose. This attempt is thrown away, so its job is to surface breaks, not to + be clean. +3. **Run every check** named in "What counts as broken" and capture the failures. +4. **Group the failures into prerequisites** and add each one to the graph under the node, as the next section + describes. +5. **Commit the graph file alone**, with `git add` on the graph path and `git commit` naming that path, so the attempt's + code edits stay out of the commit. Then confirm HEAD moved by exactly that one commit, and record the new HEAD as the + undo base. +6. **Undo the attempt** with `bash "${CLAUDE_SKILL_DIR}/scripts/undo-attempt.sh" {base}`, then run the full suite and + confirm it is green with the baseline count. +7. **Descend.** Take the first new prerequisite that is not done and repeat from 1 with it as the node. A node whose + attempt surfaces no failures is a **leaf**. + +When an attempt is green, it is still undone. The leaf is then carried out through `refactor` or `tdd` like any planned +unit, BECAUSE their gates (a green suite before the first edit, one named step at a time, the observed failing test) are +what make the committed change trustworthy, and the attempt had none of them. + +## What counts as broken + +Broken means any of these, run in this order so a cheap failure is found before an expensive one: + +1. The build or compile command fails. +2. The type-check command fails, where the project has one. +3. The test command fails, or reports fewer tests than the baseline. A moved test that stops being discovered fails + silently otherwise. +4. The lint command fails on a file the attempt touched. +5. A check the project uses to enforce its own boundaries fails, such as an architecture test or an import-restriction + rule, when Step 1 found one. + +Nothing else counts. A hunch that something "looks wrong" is not a failure. Record it in the decision log instead, +BECAUSE the graph must hold only what an attempt proved. + +## Grouping failures into prerequisites + +One root cause usually produces many failures. Group the failures by the change that would remove them, not by the file +they appear in: + +- Failures that name the same symbol, module, or path, and would all go away with one change, are one prerequisite. +- A failure that would go away only after another prerequisite is done is a child of that prerequisite, not a sibling. +- State each prerequisite as a change to make ("Move the shared formatting helpers out of the reporting module"), never + as the failure ("Import error in three files"). + +Record how each group was formed as a D-N entry in the decision log. Grouping is the judgment call in this loop, and the +person reviews it when they return. + +## The graph file + +The graph is the method's one lasting artifact. It survives every undo because it is committed before the undo runs. +Keep it at `{folder}/artifacts/mikado-graph.md`, one section per stalled unit, as a nested checklist: + +```markdown +## Goal G-{n}: {the stalled unit, stated as a change} + +- [ ] G-{n}: {the stalled unit} + - [ ] G-{n}.1: {prerequisite, stated as a change}. Found by attempt {k}: {one-line summary of the failures}. + - [ ] G-{n}.1.1: {its prerequisite}. Found by attempt {k}: {summary}. + - [x] G-{n}.2: {prerequisite}. Done in commit `{short sha}`. +``` + +- Each node carries an ID that encodes its parent, so the order is readable without a drawing. +- A node is checked only after its change is committed with a green suite. Never check a node that is merely attempted. +- A node with no unchecked children is ready. Leaves go first. +- When two branches need the same prerequisite, list it once and refer to its ID from the other branch, BECAUSE a + duplicated node gets done twice or marked done in only one place. + +## The undo, and the conditions that make it safe + +Restoring to the last commit is safe here only because every one of these holds. Check each before every undo: + +- The project is a git repository and the run is on the branch the start gate confirmed. +- The tree was clean, untracked files included, when the attempt started. +- The graph update is committed before the code is restored, or the restore discards the prerequisites just found. +- Nothing was committed since the attempt started except the graph. `undo-attempt.sh` refuses to run when HEAD has + moved from the base it is given. +- The full suite runs after every undo. A restore does not revert ignored or generated state such as build output, + installed packages, or caches, and that state can make the next run pass or fail for the wrong reason. If the suite is + not green after the undo, clear the project's build output with its own clean command if it has one, and run again. + If it is still not green, that is a hard failure: report it and end the run. + +## Working the leaves back up + +Once a node is a leaf, carry it out the way Step 7 of the skill carries out any unit: one invocation of `refactor` (or +`tdd`, when the leaf adds new code the move needs), the full suite, one commit. Then check the node in the graph and +commit the graph with it. + +Then return to the node's parent and attempt it again from step 1 of the loop. With its prerequisites done, it either +goes green (and becomes a leaf) or surfaces new prerequisites, which become new branches. New obstacles turning up on the +way back is normal, not a sign the loop failed. + +The loop ends when the goal node itself is carried out and committed. + +## The round cap + +Every attempt counts as one round. Stop discovery for a goal after five rounds, unless the start gate set a different +cap, BECAUSE the method has no natural end and a graph that keeps growing means the unit is larger than the plan +assumed. When the cap is reached: + +- Commit the graph as it stands. +- Log the unit under "Units not done" with the graph section's link and the last attempt's failures. +- Mark every unit that depends on it as not started. + +The right cap is a judgment, not an evidenced number. Record the cap in effect in the change log so the person can +adjust it next time. + +## Never patch forward + +An attempt that breaks is always undone, never fixed in place. Patching forward turns a discovery into an unplanned +change with no test gate, which is the failure this method exists to prevent. + +A restructuring leaf changes no test, except to move a test file along with the code it tests and update its imports. +Tests change only in a `tdd` leaf, and only to drive new code. Never edit a test to make an attempt or a leaf pass, +BECAUSE a test edited to agree with the change no longer proves the change preserved behavior. diff --git a/han-coding/skills/restructure/scripts/undo-attempt.bats b/han-coding/skills/restructure/scripts/undo-attempt.bats new file mode 100644 index 00000000..c158f8a4 --- /dev/null +++ b/han-coding/skills/restructure/scripts/undo-attempt.bats @@ -0,0 +1,100 @@ +#!/usr/bin/env bats +# +# Tests for undo-attempt.sh: the undo restructure runs after every Mikado +# discovery attempt and after a failed unit. Each test builds a throwaway git +# repository under BATS_TEST_TMPDIR, so nothing touches this checkout. + +setup() { + SCRIPT="$BATS_TEST_DIRNAME/undo-attempt.sh" + REPO="$BATS_TEST_TMPDIR/repo" + mkdir -p "$REPO" + cd "$REPO" || return 1 + git init -q + git config user.email "test@example.com" + git config user.name "Test" + git config commit.gpgsign false + printf 'build/\n' >.gitignore + printf 'original\n' >tracked.txt + mkdir -p src + printf 'original\n' >src/module.txt + git add -A + git commit -qm "base" + BASE=$(git rev-parse HEAD) +} + +@test "restores edited tracked files to the base commit" { + printf 'changed\n' >tracked.txt + run bash "$SCRIPT" "$BASE" + [ "$status" -eq 0 ] + [ "$(cat tracked.txt)" = "original" ] +} + +@test "restores a staged move back to its original path" { + mkdir -p moved + git mv src/module.txt moved/module.txt + run bash "$SCRIPT" "$BASE" + [ "$status" -eq 0 ] + [ -f src/module.txt ] + [ ! -e moved/module.txt ] +} + +@test "removes files the attempt created and reports each one" { + mkdir -p newdir + printf 'new\n' >newdir/created.txt + run bash "$SCRIPT" "$BASE" + [ "$status" -eq 0 ] + [ ! -e newdir/created.txt ] + [[ "$output" == *"removed: newdir/created.txt"* ]] +} + +@test "leaves ignored files in place" { + mkdir -p build + printf 'artifact\n' >build/output.txt + printf 'changed\n' >tracked.txt + run bash "$SCRIPT" "$BASE" + [ "$status" -eq 0 ] + [ -f build/output.txt ] +} + +@test "leaves the tree clean" { + printf 'changed\n' >tracked.txt + printf 'new\n' >created.txt + run bash "$SCRIPT" "$BASE" + [ "$status" -eq 0 ] + [ -z "$(git status --porcelain)" ] +} + +@test "works when run from a subdirectory" { + printf 'changed\n' >tracked.txt + printf 'new\n' >src/created.txt + run bash -c 'cd src && bash "$1" "$2"' _ "$SCRIPT" "$BASE" + [ "$status" -eq 0 ] + [ "$(cat tracked.txt)" = "original" ] + [ ! -e src/created.txt ] +} + +@test "refuses and changes nothing when HEAD has moved" { + printf 'committed\n' >tracked.txt + git commit -qam "moved on" + printf 'pending\n' >tracked.txt + run bash "$SCRIPT" "$BASE" + [ "$status" -eq 2 ] + [ "$(cat tracked.txt)" = "pending" ] +} + +@test "fails with a usage error when no commit is given" { + run bash "$SCRIPT" + [ "$status" -eq 1 ] +} + +@test "fails when the argument is not a commit" { + run bash "$SCRIPT" not-a-commit + [ "$status" -eq 1 ] +} + +@test "fails outside a git repository" { + mkdir -p "$BATS_TEST_TMPDIR/plain" + cd "$BATS_TEST_TMPDIR/plain" + run bash "$SCRIPT" "$BASE" + [ "$status" -eq 1 ] +} diff --git a/han-coding/skills/restructure/scripts/undo-attempt.sh b/han-coding/skills/restructure/scripts/undo-attempt.sh new file mode 100755 index 00000000..0af5c9dc --- /dev/null +++ b/han-coding/skills/restructure/scripts/undo-attempt.sh @@ -0,0 +1,61 @@ +#!/usr/bin/env bash +# Undo a Mikado discovery attempt, or a failed unit, back to the last commit. +# +# Usage: undo-attempt.sh BASE_SHA +# +# BASE_SHA is the commit HEAD pointed at when the attempt started. The undo is +# only safe when nothing was committed since, so the script refuses to touch +# the tree if HEAD has moved. It then restores every tracked file to HEAD and +# removes every untracked, non-ignored file. Ignored files (build output, +# installed packages, caches) are left alone, which is why the caller re-runs +# the full suite afterward. +# +# The caller guarantees the tree was clean, untracked files included, when the +# attempt started, so every untracked file present now was created by the +# attempt. Each removed file is printed as "removed: PATH". +# +# Exit codes: 0 undone and the tree is clean; 1 usage error or not a git +# repository; 2 HEAD moved since BASE_SHA; 3 the tree is still dirty after the +# undo. + +set -u + +if [ "$#" -ne 1 ] || [ -z "$1" ]; then + echo "usage: undo-attempt.sh BASE_SHA" >&2 + exit 1 +fi + +if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then + echo "error: not inside a git repository" >&2 + exit 1 +fi + +BASE=$(git rev-parse --verify --quiet "$1^{commit}") +if [ -z "$BASE" ]; then + echo "error: $1 is not a commit" >&2 + exit 1 +fi + +HEAD_SHA=$(git rev-parse HEAD) +if [ "$HEAD_SHA" != "$BASE" ]; then + echo "error: HEAD moved from $BASE to $HEAD_SHA since the attempt started; nothing was undone" >&2 + exit 2 +fi + +ROOT=$(git rev-parse --show-toplevel) +cd "$ROOT" || exit 1 + +git ls-files --others --exclude-standard | while IFS= read -r path; do + echo "removed: $path" +done + +git restore --source=HEAD --staged --worktree -- . 2>/dev/null || true +git clean -fdq -- . + +if [ -n "$(git status --porcelain)" ]; then + echo "error: the tree is still dirty after the undo:" >&2 + git status --porcelain >&2 + exit 3 +fi + +echo "undone: tree matches $BASE" From 66df591bed90907c0242c4cef23a3a35688883dd Mon Sep 17 00:00:00 2001 From: River Bailey Date: Tue, 27 Oct 2026 08:53:10 -0600 Subject: [PATCH 5/7] docs(restructure): long-form doc, README scent line, skills index, and workflow map Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 4 +- CONTRIBUTING.md | 2 +- docs/concepts.md | 2 +- docs/skills/README.md | 3 + docs/workflows.md | 19 ++- han-coding/.claude-plugin/plugin.json | 2 +- han-coding/README.md | 5 +- han-coding/docs/skills/restructure.md | 188 ++++++++++++++++++++++++++ 8 files changed, 215 insertions(+), 10 deletions(-) create mode 100644 han-coding/docs/skills/restructure.md diff --git a/CLAUDE.md b/CLAUDE.md index 92fc49c0..c1ff600c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,7 +20,7 @@ planning the build with `plan-implementation`, sequencing it with `plan-a-phased `iterative-plan-review`, plus the `discussion-facilitator` agent that audits a planning discussion in progress; depends on `han-communication` and `han-core` and is bundled by the `han` meta-plugin), `han-coding` (the coding skills -you reach for while working in code: writing it with `tdd` and `refactor`, designing an interface contract with +you reach for while working in code: writing it with `tdd` and `refactor`, restructuring whole areas of it with `restructure`, designing an interface contract with `design-an-api`, plus reviewing, overviewing, analyzing, testing, investigating, and standardizing it with `code-review`, `code-overview`, `code-walkthrough`, `architectural-analysis`, @@ -118,7 +118,7 @@ han-plugin-builder skill: │ ├── skills/ # Planning skill directories, each with SKILL.md + references/ + scripts/ │ ├── docs/ # In-plugin long-form docs: docs/skills/{name}.md + docs/agents/discussion-facilitator.md │ └── references/ # Both kinds: han-planning-owned canonical files (planning-boundary-rule.md, scope-justification-rule.md, operator-escalation-rule.md, contract-pinning-rule.md, synthesis-failure-rule.md) beside vendored copies (yagni-rule.md, evidence-rule.md, config-rule.md, collaborative-stop-rule.md). Each owned file opens by saying so; do not overwrite one in a re-sync sweep -├── han-coding/ # Coding plugin: tdd, refactor, design-an-api, code-review, code-overview, code-walkthrough, architectural-analysis, automated-test-planning, manual-test-planning, investigate, coding-standard (the skills for working in code; depends on han-communication and han-core; bundled by the han meta-plugin) +├── han-coding/ # Coding plugin: tdd, refactor, restructure, design-an-api, code-review, code-overview, code-walkthrough, architectural-analysis, automated-test-planning, manual-test-planning, investigate, coding-standard (the skills for working in code; depends on han-communication and han-core; bundled by the han meta-plugin) │ ├── README.md # Light front door + scent-line skills list │ ├── .claude-plugin/ │ │ └── plugin.json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fc64b956..ef77259a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -115,7 +115,7 @@ change goes before you scaffold anything. (For the user-facing version of this m `plan-work-items`, `iterative-plan-review`). A skill goes here when its job is specifying what a feature does, planning how to build it, sequencing the build, breaking it into work, or stress-testing a plan before implementation. It depends on `han-communication` and `han-core` and is bundled by the `han` meta-plugin. -- **`han-coding`** carries the coding skills (`tdd`, `refactor`, `code-review`, `code-overview`, +- **`han-coding`** carries the coding skills (`tdd`, `refactor`, `restructure`, `code-review`, `code-overview`, `architectural-analysis`, `automated-test-planning`, `manual-test-planning`, `investigate`, `coding-standard`). A skill goes here when its job is working directly in code: writing it, reviewing it, analyzing it, testing it, investigating it, or standardizing it. It depends on `han-communication` and `han-core` and is bundled by the `han` meta-plugin. diff --git a/docs/concepts.md b/docs/concepts.md index 1ca8687e..5d1113af 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -243,7 +243,7 @@ plugins dispatch, the project-discovery skill, the `/pairing` collaborative work `/issue-triage`) plus the research-analyst agent. `han-planning` adds the planning skills you reach for before implementation (`/plan-a-feature`, `/plan-a-change`, `/plan-implementation`, `/plan-a-phased-build`, `/plan-work-items`, and `/iterative-plan-review`). `han-coding` adds the coding skills you reach for while working in code (`/tdd`, `/refactor`, -`/design-an-api`, `/code-review`, `/code-overview`, `/code-walkthrough`, `/architectural-analysis`, +`/restructure`, `/design-an-api`, `/code-review`, `/code-overview`, `/code-walkthrough`, `/architectural-analysis`, `/automated-test-planning`, `/manual-test-planning`, `/investigate`, and `/coding-standard`). `han-github` adds the GitHub skills, and `han-reporting` adds the reporting skills. All of these except `han-reporting` depend on `han-core`, so installing any of them brings the shared agents along; `han-reporting` depends only on `han-communication`. diff --git a/docs/skills/README.md b/docs/skills/README.md index 5638eac9..07777d06 100644 --- a/docs/skills/README.md +++ b/docs/skills/README.md @@ -93,6 +93,9 @@ skill-and-agent split is fuzzy, read [Concepts](../concepts.md) first. through a test-gated loop that re-runs the full suite after every small step. - [`/research`](../../han-research/docs/skills/research.md) — Research an open-ended question across the codebase and the open web and end at an adversarially-validated recommendation, without committing the team to any artifact. +- [`/restructure`](../../han-coding/docs/skills/restructure.md) — Restructure a codebase or a large area of it toward a + target layout, unit by unit through `/refactor` and `/tdd` with a commit and a logged decision for each, using the + Mikado Method to tease apart any unit too tangled to move in one step. - [`/runbook`](../../han-documentation/docs/skills/runbook.md) — Create or update a runbook for a single operational scenario, with a symptom-first template and a YAGNI preflight that requires real evidence before writing. - [`/skill-builder`](../../han-plugin-builder/docs/skills/skill-builder.md) — Build a new skill from scratch through an diff --git a/docs/workflows.md b/docs/workflows.md index 30700406..bc64de21 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -95,6 +95,10 @@ flowchart TD design --> tdd["/tdd"] review --> pr["/post-code-review-to-pr"] refactor --> tdd + restructure["/restructure"] -.runs.-> arch + restructure -.runs.-> change + restructure -.runs.-> refactor + restructure -.runs.-> tdd tdd --> prdesc["/update-pr-description"] investigate["/investigate"] --> iterate["/iterative-plan-review"] ddd["/ddd-analysis"] --> arch @@ -102,6 +106,7 @@ flowchart TD pairing["/pairing"] -.drives.-> refactor pairing -.drives.-> tdd pairing -.drives.-> design + pairing -.drives.-> restructure ``` - **[`/code-review`](../han-coding/docs/skills/code-review.md) → @@ -118,6 +123,12 @@ flowchart TD refactor would mean deciding the target structure while editing, plan the change first. The report becomes the current-state record, and the plan's sequenced change units convert to work items or feed a refactor one at a time. `/plan-a-change` runs its own discovery round when you have no report, so the analysis step is optional. +- **[`/restructure`](../han-coding/docs/skills/restructure.md) runs + [`/architectural-analysis`](../han-coding/docs/skills/architectural-analysis.md), + [`/plan-a-change`](../han-planning/docs/skills/plan-a-change.md), and then + [`/refactor`](../han-coding/docs/skills/refactor.md) or [`/tdd`](../han-coding/docs/skills/tdd.md) per unit.** When a + restructure spans many files or modules and you want to step away, it chains the whole sequence after one start gate, + commits each unit, and uses the Mikado Method on any unit `/refactor` cannot finish in one step. - **[`/refactor`](../han-coding/docs/skills/refactor.md) → [`/tdd`](../han-coding/docs/skills/tdd.md).** Preparatory refactoring makes the change easy, then `/tdd` makes the easy change. - **[`/architectural-analysis`](../han-coding/docs/skills/architectural-analysis.md) → @@ -137,10 +148,10 @@ flowchart TD turn its commits into the PR body. This is the description half of the PR; `/post-code-review-to-pr` is the review half, and the two are independent. - **[`/pairing`](../han-core/docs/skills/pairing.md) drives - [`/refactor`](../han-coding/docs/skills/refactor.md), [`/tdd`](../han-coding/docs/skills/tdd.md), and - [`/design-an-api`](../han-coding/docs/skills/design-an-api.md).** This is not a chain but a wrapper: `/pairing` runs one - of them and takes control back at each unit boundary, so you review as the work lands rather than at the end. Invoking - any of the three directly runs it straight through, unchanged. + [`/refactor`](../han-coding/docs/skills/refactor.md), [`/restructure`](../han-coding/docs/skills/restructure.md), + [`/tdd`](../han-coding/docs/skills/tdd.md), and [`/design-an-api`](../han-coding/docs/skills/design-an-api.md).** This + is not a chain but a wrapper: `/pairing` runs one of them and takes control back at each unit boundary, so you review + as the work lands rather than at the end. Invoking any of the four directly runs it straight through, unchanged. ## Planning the tests diff --git a/han-coding/.claude-plugin/plugin.json b/han-coding/.claude-plugin/plugin.json index 09594bf0..ff24f469 100644 --- a/han-coding/.claude-plugin/plugin.json +++ b/han-coding/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "han-coding", - "description": "Coding-facing skills for the Han suite: writing, reviewing, testing, investigating, and standardizing code. Home of the tdd skill, which drives a feature or behavior through a BDD-framed red-green-refactor loop with an enforced observed-failure gate, and the refactor skill, which restructures existing code without changing its behavior through a test-gated refactoring loop, plus design-an-api (designing an interface contract for one stated goal through an options round, a question round, and an adversarial validation round), code-review (comprehensive review of local changes), code-overview (a progressive-disclosure, understand-now overview of unfamiliar code or a PR's changes), code-walkthrough (a paced, one-step-at-a-time walk through a branch's changes in conversation), architectural-analysis (module-level coupling, data flow, concurrency, risk, and SOLID assessment), automated-test-planning (coverage-gap and edge-case test plans), manual-test-planning (plain-language manual test plans a person runs by hand), investigate (evidence-based root-cause debugging), and coding-standard (creating and updating coding standards). Depends on han-core and han-communication; bundled by the han meta-plugin.", + "description": "Coding-facing skills for the Han suite: writing, reviewing, testing, investigating, and standardizing code. Home of the tdd skill, which drives a feature or behavior through a BDD-framed red-green-refactor loop with an enforced observed-failure gate, and the refactor skill, which restructures existing code without changing its behavior through a test-gated refactoring loop, and the restructure skill, which restructures a codebase or large area toward a target layout unit by unit through refactor and tdd, using the Mikado Method to tease apart units too tangled to move in one step, plus design-an-api (designing an interface contract for one stated goal through an options round, a question round, and an adversarial validation round), code-review (comprehensive review of local changes), code-overview (a progressive-disclosure, understand-now overview of unfamiliar code or a PR's changes), code-walkthrough (a paced, one-step-at-a-time walk through a branch's changes in conversation), architectural-analysis (module-level coupling, data flow, concurrency, risk, and SOLID assessment), automated-test-planning (coverage-gap and edge-case test plans), manual-test-planning (plain-language manual test plans a person runs by hand), investigate (evidence-based root-cause debugging), and coding-standard (creating and updating coding standards). Depends on han-core and han-communication; bundled by the han meta-plugin.", "version": "3.4.0", "dependencies": ["han-communication", "han-core"] } diff --git a/han-coding/README.md b/han-coding/README.md index f2a2f782..6712106e 100644 --- a/han-coding/README.md +++ b/han-coding/README.md @@ -1,7 +1,7 @@ # han-coding The coding layer of the Han suite: the skills you reach for while working in code. It writes code test-first, refactors -it under a green suite, and reviews, overviews, walks someone through, analyzes, tests, investigates, and standardizes +it under a green suite, restructures whole areas of it unit by unit, and reviews, overviews, walks someone through, analyzes, tests, investigates, and standardizes it, dispatching specialist agents to cover each dimension in parallel. Reach for it once there is code to write, change, or judge. **Bundled.** Installed with the `han` meta-plugin. Depends on `han-communication` and `han-core`. @@ -12,6 +12,9 @@ it, dispatching specialist agents to cover each dimension in parallel. Reach for enforced observed-failure gate; it writes code, not a document. - [`/refactor`](docs/skills/refactor.md) — Restructure existing code without changing its behavior through a test-gated loop that re-runs the full suite after every small step. +- [`/restructure`](docs/skills/restructure.md) — Restructure a codebase or a large area of it toward a target layout, + unit by unit through `/refactor` and `/tdd` with a commit and a logged decision for each, using the Mikado Method to + tease apart any unit too tangled to move in one step. - [`/design-an-api`](docs/skills/design-an-api.md) — Design the contract for an API change inside one codebase, with every element justified from one stated goal and the design run past a question round and an adversarial validation round. diff --git a/han-coding/docs/skills/restructure.md b/han-coding/docs/skills/restructure.md new file mode 100644 index 00000000..c0308f46 --- /dev/null +++ b/han-coding/docs/skills/restructure.md @@ -0,0 +1,188 @@ +# /restructure + +Operator documentation for the `/restructure` skill in the han plugin. This document helps you decide _when_ and _how_ +to use the skill. For what the skill does internally, read the skill definition at +[`han-coding/skills/restructure/SKILL.md`](../../skills/restructure/SKILL.md). + +> See also: [Plugin README](../../README.md) · [Repo root](../../../README.md) · +> [All skills](../../../docs/skills/README.md) · [All agents](../../../docs/agents/README.md) · +> [YAGNI](../../../docs/yagni.md) + +## TL;DR + +- **What it does.** Restructures a codebase, or a large area of it, toward a target layout or set of boundaries without + changing behavior. It analyzes the area, plans ordered units, and carries out each unit through `/refactor` or + `/tdd`, committing each one. When a unit is too tangled to move in one step, it uses the Mikado Method to tease it + apart. +- **When to use it.** You want code reorganized across many files or modules, such as a new folder layout, a module + split along a boundary, or the project's documented structure re-applied, and you want to step away while it runs. +- **What you get back.** A series of commits on your current branch, one per step, plus a change-set folder holding a + change log that justifies every decision, the analysis, the plan, and a Mikado graph for any unit that stalled. + +## Key concepts + +- **One start gate, then unattended.** The skill stops once, before any code moves, so you can confirm the goal, the + structure rules it found, the completion check, the commands, the branch, and the output folder. After you confirm, + it asks nothing more. Every decision it makes from then on is written down as a numbered `D-N` entry for you to review + when you come back. +- **A coordinator, not a fourth way to edit code.** [`/architectural-analysis`](./architectural-analysis.md) finds what + makes moving code unsafe, [`/plan-a-change`](../../../han-planning/docs/skills/plan-a-change.md) splits the work into + ordered units, and [`/refactor`](./refactor.md) or [`/tdd`](./tdd.md) carries out each unit under their own test + gates. This skill discovers the project, forwards the goal, commits, and logs. +- **Mikado only when needed.** Most units go straight through `/refactor`. A unit _stalls_ when `/refactor` stops + because the unit reached outside its files or failed twice, when `/tdd` cannot reach green, or when the suite is red + afterward. A stall means the unit has prerequisites the plan could not see by reading the code. The skill then tries + the change the simple way, records what breaks as prerequisites in a graph, undoes the attempt, and works the + prerequisites first. Each finished prerequisite is its own unit and its own commit. +- **Nothing about your project is assumed.** The skill finds your source roots, entry points, test runner, test roots, + and structure rules in your own files when it runs. It works on any language and any layout. +- **A clean tree, and commits on the current branch only.** Failed units and discovery attempts are undone by restoring + to the last commit, which is only safe when the tree started clean. The skill never creates or switches branches, + pushes, or opens a pull request. + +## When to use it + +**Invoke when:** + +- You want to reorganize code across a whole package, service, or repository: by feature, by layer, by component. +- You want a module split along a boundary, and the code is tangled enough that the split will take many steps. +- Your project documents how its code should be laid out, and the code has drifted from it. +- A `/plan-a-change` plan already exists for a restructure and you want it carried out unit by unit with a record of + every decision. + +**Do not invoke for:** + +- **One named spot.** Extracting a function, removing duplication in one module, or a refactoring you can name in a + sentence belongs to [`/refactor`](./refactor.md), which is faster and stops for you when its scope spreads. +- **Planning without executing.** Use [`/plan-a-change`](../../../han-planning/docs/skills/plan-a-change.md) to settle + the target structure and sequence the units, then decide whether to run them. +- **Finding out what is wrong.** Use [`/architectural-analysis`](./architectural-analysis.md) when you want findings and + no code changes. +- **Changing behavior.** Fixes and features are follow-ups in the change log, never units. Use + [`/investigate`](./investigate.md) and [`/tdd`](./tdd.md) for those. +- **A tree with uncommitted work, or no tests.** The skill refuses a dirty tree and a red suite. A unit whose code has + no test coverage is logged as not done rather than moved blind. + +## How to invoke it + +Run `/restructure` in Claude Code on the branch where the commits should land. A dedicated branch is best; the skill +warns you at the start gate when you are on the default branch. + +Give it: + +1. **The goal.** The structure you want, in your own words: _"group each package by feature, then by component"_, + _"pull the billing code out of the orders module"_, or _"re-apply the layout in our README"_. The skill asks for a + goal if you give none, and asks nothing else in that turn. +2. **Optionally, the area.** A directory or set of modules. Without one, the skill finds the source roots itself. +3. **Nothing about the test framework.** The skill resolves the test, type-check, lint, and build commands from your + project and shows them at the start gate for you to confirm. + +At the start gate you can also change the discovery round cap (five attempts per stalled unit by default) and the +output folder. + +Example prompts: + +- `/restructure`. _"Reorganize `services/` so every service is grouped by feature, with shared code in a `shared/` + folder at the lowest level that covers every user."_ +- `/restructure`. _"Split the reporting code out of the accounts module into its own module."_ +- `/restructure`. _"Bring the code back in line with the layout section of the README."_ + +## What you get back + +Commits on your branch, in this order: the change-set start, the architectural analysis, the plan, one commit per unit, +one commit per Mikado graph update, the updated layout docs, and the finished change log. + +The change-set folder (under your configured `output-directory`, or `docs/changes/restructure-{date}/` by default) +holds: + +- **`change-log.md`.** Every step in order, with what changed, why, the decisions behind it, and the test counts + against the baseline. It closes with where things ended up, the decisions to look at first, the units not done, and + the behavior changes deferred as follow-ups. +- **`change-plan.md`.** The ordered units, each tagged `refactor` or `tdd`, with the files it may touch and the units it + depends on. +- **`artifacts/change-decision-log.md`.** Every decision as a `D-N` entry with its rationale and the alternatives + rejected. +- **`artifacts/architectural-analysis.md`.** The analysis that found the risks to moving code. +- **`artifacts/mikado-graph.md`.** Present only when a unit stalled: a nested checklist of each stalled unit's + prerequisites, with which attempt found each one and which commit finished it. + +## How to get the most out of it + +- **Write your structure rules down first.** The skill reads your README, CLAUDE.md, ADRs, coding standards, and any + boundary tests to learn the rules. The clearer they are, the fewer judgment calls end up in the decision log. +- **Read "Decisions to look at first" before anything else.** That section names the closest calls, any departure from + an earlier change set, and how the skill grouped failures into prerequisites. Grouping is the judgment call the Mikado + research says a person should check. +- **Review the commits, not the final diff.** Each commit is one unit or one graph update, so a wrong turn can be + reverted without losing the rest. +- **Watch the round cap.** A unit that hits it is logged as not done with its graph. A graph that keeps growing means + the unit is bigger than the plan assumed; the graph is a good starting point for a smaller follow-up run. +- **Pair with it when the stakes are high.** Run it through [`/pairing`](../../../han-core/docs/skills/pairing.md) to + stop after every unit lands. + +## YAGNI + +`/restructure` does not add structure of its own: every unit must serve the goal or a documented structure rule, and +the planning and refactoring skills it runs apply the [YAGNI](../../../docs/yagni.md) evidence gate to each unit and +each refactoring. A unit with no evidence behind it is not planned. Behavior changes the analysis turns up are recorded +as follow-ups rather than folded in. + +## Cost and latency + +This is the most expensive skill in `han-coding` to run. It runs `/architectural-analysis` (which dispatches a team of +analyst agents), `/plan-a-change` (which runs its own discovery and review rounds), and then one `/refactor` or `/tdd` +run per unit. Every unit and every Mikado attempt re-runs your full test suite at least once, so your suite's runtime +multiplied by the number of units and attempts dominates the total. Narrowing the area is the main cost lever. + +When `han-planning` is not installed, the skill writes the unit plan itself from the analysis, which is cheaper but +skips `/plan-a-change`'s review rounds. The decision log records when that happened. + +## In more detail + +`/refactor` holds each step to a declared list of files and stops when a step spreads beyond it or two steps fail in a +row. Those rules are what make it safe, and they are exactly what a tangled restructure trips over. A stop there is a +discovery, not a dead end: the step has prerequisites nobody has found yet. This skill reads the stop that way. It +keeps `/refactor`'s rules intact for every committed change, and runs the Mikado Method's discovery loop around them. + +The undo is the hardest part of running the method on a real tree. Discovery attempts are deliberately wide and always +thrown away. The skill restores to the last commit with a bundled script that refuses to run if anything was committed +since the attempt began, removes only untracked files (ignored build output and installed packages stay), and leaves +the tree clean. That is safe only because the tree started clean, the graph is committed before each undo, and the full +suite runs after each one. The skill checks all three every time. + +The honest limits: the method needs a test suite to tell it what broke, and dependencies that never show up as a build, +type, test, lint, or boundary-check failure cannot be discovered by trying. The default round cap of five is a judgment, +not a measured number. No published study measures whether an agent running the Mikado Method improves outcomes; the +design rests on the method's well-corroborated loop and on Han's existing test-gated skills. + +## Sources + +### Ola Ellnestam and Daniel Brolund, _The Mikado Method_ (Manning, 2014) + +The discovery loop: try the goal the simple way, record what breaks as prerequisites, undo, and work the leaves first. +The graph as the method's one lasting artifact. + +URL: https://livebook.manning.com/book/the-mikado-method/chapter-1 + +### Practitioner write-ups of the method + +Commit each finished prerequisite only with the tests green, keep the graph in a file alongside the code, and expect +new obstacles while working back up. Drawn from Matthias Noback's and heise's write-ups of the method. + +URL: https://matthiasnoback.nl/2021/02/refactoring-the-mikado-method/ + +## Related documentation + +- [Plugin README](../../README.md). The plugin's front door: its skills, agents, and how they fit together. +- [Repo root README](../../../README.md). The Han suite landing page. Start here if you arrived from outside the docs + tree. +- [`/pairing`](../../../han-core/docs/skills/pairing.md). Run this skill collaboratively, stopping after each unit so you + review it as it lands. Invoking `/restructure` directly runs to completion after the start gate. +- [Skills Index](../../../docs/skills/README.md). All skills, grouped by purpose. +- [`/refactor`](./refactor.md). Carries out each `refactor` unit. Use it directly for one named spot. +- [`/tdd`](./tdd.md). Carries out each `tdd` unit, such as a new shared module a move needs. +- [`/architectural-analysis`](./architectural-analysis.md). The analysis this skill runs first. Use it directly for + findings without changes. +- [`/plan-a-change`](../../../han-planning/docs/skills/plan-a-change.md). The planning skill this skill runs to split + the work into units. Use it directly to plan without executing. +- [YAGNI](../../../docs/yagni.md). The evidence gate the planning and refactoring skills apply to each unit. From ff0064d2bf82a409dcce89b7d02abe8c2f124c42 Mon Sep 17 00:00:00 2001 From: River Bailey Date: Tue, 27 Oct 2026 08:55:45 -0600 Subject: [PATCH 6/7] feat(pairing): drive restructure collaboratively, and route refactor and plan-a-change to it Adds restructure to pairing's flagged skills and to the collaborative-stop rule (canonical and both vendored copies, still byte-identical), and gives refactor and plan-a-change routing lines toward restructure. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 4 ++-- han-coding/docs/skills/refactor.md | 3 +++ han-coding/references/collaborative-stop-rule.md | 7 ++++--- han-coding/skills/refactor/SKILL.md | 9 +++++---- han-coding/skills/restructure/scripts/undo-attempt.bats | 0 han-core/README.md | 4 ++-- han-core/docs/skills/pairing.md | 6 +++--- han-core/references/collaborative-stop-rule.md | 7 ++++--- han-core/skills/pairing/SKILL.md | 5 +++-- han-planning/docs/skills/plan-a-change.md | 6 +++++- han-planning/references/collaborative-stop-rule.md | 7 ++++--- han-planning/skills/plan-a-change/SKILL.md | 3 ++- 12 files changed, 37 insertions(+), 24 deletions(-) mode change 100644 => 100755 han-coding/skills/restructure/scripts/undo-attempt.bats diff --git a/CLAUDE.md b/CLAUDE.md index c1ff600c..9a7df068 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -262,8 +262,8 @@ such as Claude, should be referenced here. - **[han-core/references/collaborative-stop-rule.md](./han-core/references/collaborative-stop-rule.md).** The shared contract behind `/pairing`: how a skill detects the collaborative flag, what a stop presents and in what order, when the pre-build ask fires and what makes a choice expensive to walk back, and what to do with the answer. Consumed by - `pairing` and by the skills that hand control back at their own boundaries — `tdd`, `refactor`, `design-an-api`, - `iterative-plan-review`, and `plan-implementation`. Vendored byte-identical into `han-coding/references/` and + `pairing` and by the skills that hand control back at their own boundaries — `tdd`, `refactor`, `restructure`, + `design-an-api`, `iterative-plan-review`, and `plan-implementation`. Vendored byte-identical into `han-coding/references/` and `han-planning/references/`; edit the canonical copy and re-sync the others. ### Writing voice diff --git a/han-coding/docs/skills/refactor.md b/han-coding/docs/skills/refactor.md index e9b25abd..8cdab3b0 100644 --- a/han-coding/docs/skills/refactor.md +++ b/han-coding/docs/skills/refactor.md @@ -57,6 +57,9 @@ use the skill. For what the skill does internally, read the skill definition at [`/plan-a-change`](../../../han-planning/docs/skills/plan-a-change.md) when the change spans several modules and the target structure is still open. This skill applies a named refactoring to a named target; that one settles what the target structure should be. +- **Restructuring a whole area.** Use [`/restructure`](./restructure.md) when the change spans many files or modules + and you want it carried out unit by unit with a commit and a logged decision for each. It runs this skill for each + unit and uses the Mikado Method when a unit stops here because its scope spread. - **Fixing a bug.** A fix changes behavior, which this skill never does. Use [`/investigate`](./investigate.md) and then drive the fix in with [`/tdd`](./tdd.md). - **Mapping domain boundaries before restructuring along them.** Use diff --git a/han-coding/references/collaborative-stop-rule.md b/han-coding/references/collaborative-stop-rule.md index 48086b9c..61cef938 100644 --- a/han-coding/references/collaborative-stop-rule.md +++ b/han-coding/references/collaborative-stop-rule.md @@ -14,9 +14,10 @@ This rule defines what happens when a skill running collaboratively reaches a un it presents when it stops, and what it does with the answer. It exists so a stop means the same thing whichever skill performed it. -Six places need to agree on that answer. `pairing` drives the loop, and `tdd`, `refactor`, `design-an-api`, -`iterative-plan-review`, and `plan-implementation` each stop at a boundary they already have. Without one shared -definition, each would describe stopping in its own words and a person would meet six slightly different experiences. +Seven places need to agree on that answer. `pairing` drives the loop, and `tdd`, `refactor`, `restructure`, +`design-an-api`, `iterative-plan-review`, and `plan-implementation` each stop at a boundary they already have. Without +one shared definition, each would describe stopping in its own words and a person would meet seven slightly different +experiences. Every vendored copy of this file is byte-identical to the canonical `han-core/references/collaborative-stop-rule.md`. ## Who reads this diff --git a/han-coding/skills/refactor/SKILL.md b/han-coding/skills/refactor/SKILL.md index 2a5270f7..8631c5e3 100644 --- a/han-coding/skills/refactor/SKILL.md +++ b/han-coding/skills/refactor/SKILL.md @@ -4,11 +4,12 @@ description: > Restructure existing code without changing its behavior, through a test-gated refactoring loop: a named target, a green suite over that target before any edit, a planned sequence of small named refactorings, and the full suite re-run after every step. Use when the user wants to refactor, restructure, clean up, simplify, or improve the design - of existing code, or to apply refactoring recommendations from a code-review or architectural-analysis report. This + of existing code, or to apply refactoring findings from a code-review or architectural-analysis report. This skill changes code; it does not review code (use code-review), assess architecture (use architectural-analysis), plan - a multi-module restructure before executing it (use plan-a-change), map domain boundaries before restructuring along - them (use ddd-analysis), or build new behavior test-first (use tdd). Do not use it on code inside an active tdd loop; - the refactor step of tdd owns that cleanup. Runs its planned sequence to completion without pausing for review; to review each named + a multi-module restructure before executing it (use plan-a-change), restructure a whole area unit by unit (use + restructure), map domain boundaries before restructuring along + them (use ddd-analysis), or build new behavior test-first (use tdd). Not for code inside an active tdd loop; tdd's + refactor step owns that cleanup. Runs its planned sequence to completion without pausing for review; to review each named refactoring as it lands, use pairing. argument-hint: "[file, module, named smell, or a path to review findings]" allowed-tools: diff --git a/han-coding/skills/restructure/scripts/undo-attempt.bats b/han-coding/skills/restructure/scripts/undo-attempt.bats old mode 100644 new mode 100755 diff --git a/han-core/README.md b/han-core/README.md index 726e017e..e352981f 100644 --- a/han-core/README.md +++ b/han-core/README.md @@ -13,8 +13,8 @@ kind of work rather than belonging to any one plugin's subject matter. The documentation skills live in `han-documentation`, the pre-planning research skills in `han-research`, the planning skills in `han-planning`, and the coding skills in `han-coding`; each depends on han-core. Install only this and you -have the specialists, project discovery, and the pairing mode. `/pairing` gains its test-driven, refactoring, interface, -and plan-review paths when the plugins carrying those skills are installed alongside it, and names the missing skill +have the specialists, project discovery, and the pairing mode. `/pairing` gains its test-driven, refactoring, restructuring, +interface, and plan-review paths when the plugins carrying those skills are installed alongside it, and names the missing skill rather than substituting when they are not. **Bundled.** Installed with the `han` meta-plugin. Depends on no other Han plugin. diff --git a/han-core/docs/skills/pairing.md b/han-core/docs/skills/pairing.md index 392d1c9e..f81a2672 100644 --- a/han-core/docs/skills/pairing.md +++ b/han-core/docs/skills/pairing.md @@ -50,7 +50,7 @@ use the skill. For what the skill does internally, read the skill definition at - **Understanding something rather than producing it.** Use [`/code-overview`](../../../han-coding/docs/skills/code-overview.md) for a written overview, or [`/research`](../../../han-research/docs/skills/research.md) for an open question. -- **Running a skill straight through.** Invoke `tdd`, `refactor`, `design-an-api`, `iterative-plan-review`, or +- **Running a skill straight through.** Invoke `tdd`, `refactor`, `restructure`, `design-an-api`, `iterative-plan-review`, or `plan-implementation` directly. Each runs to completion without pausing unless this skill is driving. ## How to invoke it @@ -170,8 +170,8 @@ Treat both as provisional. - [YAGNI](../../../docs/yagni.md). The evidence-based "You Aren't Gonna Need It" rule. - [`collaborative-stop-rule.md`](../../references/collaborative-stop-rule.md). The shared contract this skill and its backing skills follow, defining what a stop presents and what returning control means. -- [`/tdd`](../../../han-coding/docs/skills/tdd.md), [`/refactor`](../../../han-coding/docs/skills/refactor.md), and - [`/design-an-api`](../../../han-coding/docs/skills/design-an-api.md). The coding skills this one can drive. +- [`/tdd`](../../../han-coding/docs/skills/tdd.md), [`/refactor`](../../../han-coding/docs/skills/refactor.md), + [`/restructure`](../../../han-coding/docs/skills/restructure.md), and [`/design-an-api`](../../../han-coding/docs/skills/design-an-api.md). The coding skills this one can drive. - [`/iterative-plan-review`](../../../han-planning/docs/skills/iterative-plan-review.md) and [`/plan-implementation`](../../../han-planning/docs/skills/plan-implementation.md). The planning skills this one can drive. diff --git a/han-core/references/collaborative-stop-rule.md b/han-core/references/collaborative-stop-rule.md index 48086b9c..61cef938 100644 --- a/han-core/references/collaborative-stop-rule.md +++ b/han-core/references/collaborative-stop-rule.md @@ -14,9 +14,10 @@ This rule defines what happens when a skill running collaboratively reaches a un it presents when it stops, and what it does with the answer. It exists so a stop means the same thing whichever skill performed it. -Six places need to agree on that answer. `pairing` drives the loop, and `tdd`, `refactor`, `design-an-api`, -`iterative-plan-review`, and `plan-implementation` each stop at a boundary they already have. Without one shared -definition, each would describe stopping in its own words and a person would meet six slightly different experiences. +Seven places need to agree on that answer. `pairing` drives the loop, and `tdd`, `refactor`, `restructure`, +`design-an-api`, `iterative-plan-review`, and `plan-implementation` each stop at a boundary they already have. Without +one shared definition, each would describe stopping in its own words and a person would meet seven slightly different +experiences. Every vendored copy of this file is byte-identical to the canonical `han-core/references/collaborative-stop-rule.md`. ## Who reads this diff --git a/han-core/skills/pairing/SKILL.md b/han-core/skills/pairing/SKILL.md index 95dc6f32..fa14fa4d 100644 --- a/han-core/skills/pairing/SKILL.md +++ b/han-core/skills/pairing/SKILL.md @@ -5,7 +5,7 @@ description: > person stays in the lead and steers while the work happens instead of reviewing a finished result. Use when someone says to pair with them on something, asks to collaborate rather than direct, wants to review as it goes, or wants to guide the work piece by piece — on code, on a design decision, or on writing. For a test-first build it runs tdd, for - restructuring it runs refactor, for an interface contract it runs design-an-api, and for plan work it runs + restructuring it runs refactor, for reorganizing a whole area it runs restructure, for an interface contract it runs design-an-api, and for plan work it runs iterative-plan-review or plan-implementation, each collaboratively; invoke any of those directly instead to run it straight through without pausing. Does not pace someone through code that already exists and builds nothing — use code-walkthrough. Does not explain, summarize, or research something instead of producing it — use code-overview or @@ -85,7 +85,8 @@ person can merge them back. An extra stop costs one turn. A missing one costs th Apply this test to each concern separately, in order, and stop at the first match: 1. Does a skill carrying the collaborative flag cover this work? Then it is **skill-backed**. The flagged skills are - `tdd` for a test-first build, `refactor` for restructuring, `design-an-api` for an interface contract, + `tdd` for a test-first build, `refactor` for restructuring, `restructure` for reorganizing a whole area unit by + unit, `design-an-api` for an interface contract, `iterative-plan-review` for sharpening a plan, and `plan-implementation` for planning a build. 2. Does the work produce a choice among options that commits the person to something? Then it is **decision work**. 3. Does the work produce prose someone will read? Then it is **prose work**. diff --git a/han-planning/docs/skills/plan-a-change.md b/han-planning/docs/skills/plan-a-change.md index 911d479f..f5dd8da4 100644 --- a/han-planning/docs/skills/plan-a-change.md +++ b/han-planning/docs/skills/plan-a-change.md @@ -52,7 +52,9 @@ and _how_ to use the skill. For what the skill does internally, read the skill d - **Designing a new interface that does not exist yet.** Use [`/design-an-api`](../../../han-coding/docs/skills/design-an-api.md). - **Carrying out the change.** Use [`/refactor`](../../../han-coding/docs/skills/refactor.md) for a - behavior-preserving unit, or [`/tdd`](../../../han-coding/docs/skills/tdd.md) to build one test-first. + behavior-preserving unit, or [`/tdd`](../../../han-coding/docs/skills/tdd.md) to build one test-first. To plan and + carry out a whole-area restructure in one unattended run, use + [`/restructure`](../../../han-coding/docs/skills/restructure.md), which runs this skill for its plan. ## How to invoke it @@ -211,6 +213,8 @@ safe. - [`/refactor`](../../../han-coding/docs/skills/refactor.md). Carries out a behavior-preserving change unit once the plan names its target and its refactoring. - [`/tdd`](../../../han-coding/docs/skills/tdd.md). Builds a behavior-changing change unit test-first. +- [`/restructure`](../../../han-coding/docs/skills/restructure.md). Runs this skill to plan a whole-area restructure, + then carries out every unit through `/refactor` or `/tdd`, using the Mikado Method on any unit that stalls. - [`software-architect`](../../../han-core/docs/agents/software-architect.md). Proposes the target structure at Step 4, under the YAGNI and contract-pinning directives. - [`junior-developer`](../../../han-core/docs/agents/junior-developer.md). Reframes a question in plain terms before the diff --git a/han-planning/references/collaborative-stop-rule.md b/han-planning/references/collaborative-stop-rule.md index 48086b9c..61cef938 100644 --- a/han-planning/references/collaborative-stop-rule.md +++ b/han-planning/references/collaborative-stop-rule.md @@ -14,9 +14,10 @@ This rule defines what happens when a skill running collaboratively reaches a un it presents when it stops, and what it does with the answer. It exists so a stop means the same thing whichever skill performed it. -Six places need to agree on that answer. `pairing` drives the loop, and `tdd`, `refactor`, `design-an-api`, -`iterative-plan-review`, and `plan-implementation` each stop at a boundary they already have. Without one shared -definition, each would describe stopping in its own words and a person would meet six slightly different experiences. +Seven places need to agree on that answer. `pairing` drives the loop, and `tdd`, `refactor`, `restructure`, +`design-an-api`, `iterative-plan-review`, and `plan-implementation` each stop at a boundary they already have. Without +one shared definition, each would describe stopping in its own words and a person would meet seven slightly different +experiences. Every vendored copy of this file is byte-identical to the canonical `han-core/references/collaborative-stop-rule.md`. ## Who reads this diff --git a/han-planning/skills/plan-a-change/SKILL.md b/han-planning/skills/plan-a-change/SKILL.md index 179944ba..f35fbbbd 100644 --- a/han-planning/skills/plan-a-change/SKILL.md +++ b/han-planning/skills/plan-a-change/SKILL.md @@ -7,7 +7,8 @@ description: > a restructure, extraction, split, consolidation, responsibility shift, or API revision of existing code, including "these responsibilities are wrong, plan the fix". Does not assess an area and stop at findings — use architectural-analysis. Does not specify new behavior — use plan-a-feature. Does not diagnose a bug — use investigate. - Does not write the code — use refactor to restructure it or tdd to build it. + Does not write the code — use refactor for one named spot, restructure to carry out a + restructure across a whole area, or tdd to build it. arguments: size argument-hint: "[size: small | medium | large | dynamic] [what needs to change, optional: source findings path]" allowed-tools: From 7f5a5151608dec020f7f27c7d98e92fa62f87191 Mon Sep 17 00:00:00 2001 From: River Bailey Date: Tue, 27 Oct 2026 08:56:35 -0600 Subject: [PATCH 7/7] fix(restructure): apply guidance-review fixes Moves the missing-test-command case out of the hard-failure list and into the start gate, says what happens when a Mikado leaf stalls, and renames the test fixture's folder so no conventional source path appears. Co-Authored-By: Claude Opus 5.5 --- han-coding/skills/restructure/SKILL.md | 10 ++++++---- .../skills/restructure/scripts/undo-attempt.bats | 14 +++++++------- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/han-coding/skills/restructure/SKILL.md b/han-coding/skills/restructure/SKILL.md index ca9713a5..93e7646c 100644 --- a/han-coding/skills/restructure/SKILL.md +++ b/han-coding/skills/restructure/SKILL.md @@ -121,9 +121,9 @@ Each of these is a hard failure: report which one and end the run. 2. `git status --porcelain` prints anything: the tree has uncommitted or untracked changes. Ask the person to commit or remove them and run again, BECAUSE an undo cannot tell their work from an attempt's. 3. `git branch --show-current` prints nothing: HEAD is detached, and commits made there are easy to lose. -4. No test command resolved after every fallback: the gate asks for one, and nothing below runs until it has one. -Run the test command, and the type-check command where one exists. **Paste the runner's summary line** and record the +If no test command resolved after every fallback, skip the baseline below: Step 3 asks for the command, and the +baseline runs as soon as the person supplies it, before Step 4. Otherwise, run the test command, and the type-check command where one exists. **Paste the runner's summary line** and record the counts as the baseline. If anything is red, report the output and end the run, BECAUSE a restructure can only be proven behavior-preserving against a suite that was green to begin with. @@ -134,7 +134,7 @@ Present everything the run will act on, then end the turn: - The goal, verbatim, and the area it covers. - The structure rules found, each with its source path, and any conflict between them and the goal. - The completion check and how many items it lists today. -- The test, type-check, lint, and build commands, and the test roots. +- The test, type-check, lint, and build commands, and the test roots. When no test command resolved, ask for one here. - The branch. If it is the repository's default branch, say so and recommend the person create a dedicated branch first. - The output folder. - The discovery round cap, five per stalled unit unless the person sets another. @@ -231,7 +231,9 @@ It holds the discovery loop, what counts as broken, how to group failures into p `{folder}/artifacts/mikado-graph.md`, the conditions that make each undo safe, and the round cap. - Add a change-log entry for each discovery round, in the discovery-round format. -- Carry out each leaf through items 1 to 4 of Step 7, as a unit of its own, then attempt its parent again. +- Carry out each leaf through items 1 to 4 of Step 7, as a unit of its own, then attempt its parent again. A leaf that + stalls when carried out is not a leaf: undo it with `undo-attempt.sh`, and continue discovery with it as the node. + The rounds it takes count toward the same cap. - When the goal node is carried out and committed, return to Step 7 for the next unit. - When the round cap is reached, commit the graph, log the unit under "Units not done" with its graph section, mark every unit that depends on it as not started, and return to Step 7 for the next unit. diff --git a/han-coding/skills/restructure/scripts/undo-attempt.bats b/han-coding/skills/restructure/scripts/undo-attempt.bats index c158f8a4..80496534 100755 --- a/han-coding/skills/restructure/scripts/undo-attempt.bats +++ b/han-coding/skills/restructure/scripts/undo-attempt.bats @@ -15,8 +15,8 @@ setup() { git config commit.gpgsign false printf 'build/\n' >.gitignore printf 'original\n' >tracked.txt - mkdir -p src - printf 'original\n' >src/module.txt + mkdir -p nested + printf 'original\n' >nested/module.txt git add -A git commit -qm "base" BASE=$(git rev-parse HEAD) @@ -31,10 +31,10 @@ setup() { @test "restores a staged move back to its original path" { mkdir -p moved - git mv src/module.txt moved/module.txt + git mv nested/module.txt moved/module.txt run bash "$SCRIPT" "$BASE" [ "$status" -eq 0 ] - [ -f src/module.txt ] + [ -f nested/module.txt ] [ ! -e moved/module.txt ] } @@ -66,11 +66,11 @@ setup() { @test "works when run from a subdirectory" { printf 'changed\n' >tracked.txt - printf 'new\n' >src/created.txt - run bash -c 'cd src && bash "$1" "$2"' _ "$SCRIPT" "$BASE" + printf 'new\n' >nested/created.txt + run bash -c 'cd nested && bash "$1" "$2"' _ "$SCRIPT" "$BASE" [ "$status" -eq 0 ] [ "$(cat tracked.txt)" = "original" ] - [ ! -e src/created.txt ] + [ ! -e nested/created.txt ] } @test "refuses and changes nothing when HEAD has moved" {