Merge pull request #202 from JThoennes/main

feat: refine Mikado Method documentation with enhanced clarity

Author: rdmueller

docs/anchors/mikado-method.adoc

@@ -12,17 +12,21 @@ Also known as:: Mikado Graph Method
 [discrete]
 == *Core Concepts*:
 
-Mikado Goal:: The final desired state of the code after refactoring; the root of the dependency graph
+Mikado Goal:: The clear desired future state of the code after refactoring; the root of the dependency graph and success criterion of the change
 
 Prerequisite discovery:: Reveal blocking dependencies by attempting the change and noting what breaks
 
-Revert and repeat:: After discovering a prerequisite, revert to a working state before addressing it
+Use experiments:: Prefer quick or time-boxed empirical attempts over long upfront analysis
 
-Mikado Graph:: A directed acyclic graph where nodes are prerequisites and edges show dependencies between them
+Always revert:: *IMPORTANT*: After discovering a prerequisite, *always* revert to the last known working state before addressing it
+
+Mikado Graph:: A directed acyclic graph where goals and prerequisites are nodes and arrows show dependencies
 
 Leaf-first resolution:: Resolve the leaf nodes (no further prerequisites) first, working back to the root goal
 
-Small reversible steps:: Each step leaves the codebase in a working state, eliminating the risk of long-running broken branches
+Small reversible steps:: Revert failed experiments immediately; keep or commit only coherent healthy changes
+
+Meaningful commits:: Commit only when the code compiles, tests run, the product is in a good state, and the change makes sense on its own
 
 Key Proponents:: Ola Ellnestam, Daniel Brolund ("The Mikado Method", 2012)
 
@@ -33,6 +37,33 @@ Key Proponents:: Ola Ellnestam, Daniel Brolund ("The Mikado Method", 2012)
 * When a direct change breaks too many things to fix at once
 * Coordinating multi-developer refactoring efforts safely
 * Making incremental improvements without blocking the team
+* Brownfield development with hidden dependencies
+
+[[mikado-method-recipe-canonical-form]]
+[discrete]
+== *Mikado Method Recipe (Canonical Form)*
+
+1. Start here: Draw the Mikado Goal.
+2. Implement the goal or prerequisite naively.
+3. Are there any errors?
+* Examples: compiler errors, failing tests, runtime errors, broken builds.
+* If *Yes*, go to step 4.
+* If *No*, go to step 9.
+4. Come up with immediate solutions to the errors.
+5. Draw the solutions as new prerequisites in the Mikado Graph.
+6. Revert all changes and return to the last known good state.
+7. Select the next prerequisite to work with.
+8. Go to step 2.
+9. Does the change make sense?
+* Examples: understandable, internally consistent, safe to keep, useful on its own.
+* If *Yes*, go to step 10.
+* If *No*, go to step 7.
+10. Commit the change.
+11. Is the Mikado Goal met?
+* If *Yes*, go to step 12.
+* If *No*, go to step 7.
+12. DONE!
+
 
 [discrete]
 == *Related Anchors*:

docs/anchors/mikado-method.de.adoc

@@ -12,17 +12,21 @@ Auch bekannt als:: Mikado-Graph-Methode
 [discrete]
 == *Kernkonzepte*:
 
-Mikado-Ziel:: Der angestrebte Endzustand des Codes nach dem Refactoring; die Wurzel des Abhängigkeitsgraphen
+Mikado-Ziel:: Der klare, angestrebte zukünftige Zustand des Codes nach dem Refactoring; die Wurzel des Abhängigkeitsgraphen und das Erfolgskriterium der Änderung
 
 Voraussetzungsermittlung:: Blockierende Abhängigkeiten aufdecken, indem die Änderung versucht und notiert wird, was dabei bricht
 
-Rückgängig machen und wiederholen:: Nach dem Entdecken einer Voraussetzung den Code auf einen funktionierenden Zustand zurücksetzen, bevor diese angegangen wird
+Experimente nutzen:: Bevorzuge schnelle oder zeitlich begrenzte empirische Versuche gegenüber langen Vorab-Analysen
 
-Mikado-Graph:: Ein gerichteter azyklischer Graph, bei dem Knoten Voraussetzungen und Kanten die Abhängigkeiten zwischen ihnen darstellen
+Immer rückgängig machen:: *WICHTIG*: Nach dem Entdecken einer Voraussetzung *immer* zum letzten bekannten funktionierenden Zustand zurückkehren, bevor diese angegangen wird
+
+Mikado-Graph:: Ein gerichteter azyklischer Graph, bei dem Ziele und Voraussetzungen Knoten sind und Pfeile die Abhängigkeiten anzeigen
 
 Blatt-zuerst-Auflösung:: Zuerst die Blattknoten (ohne weitere Voraussetzungen) auflösen und von dort zurück zum Wurzelziel arbeiten
 
-Kleine reversible Schritte:: Jeder Schritt hinterlässt die Codebasis in einem funktionierenden Zustand und vermeidet das Risiko langer kaputt-Branches
+Kleine reversible Schritte:: Mache fehlgeschlagene Experimente sofort rückgängig; behalte oder committe nur zusammenhängende, gesunde Änderungen
+
+Aussagekräftige Commits:: Committe nur, wenn der Code kompiliert, Tests laufen, das Produkt in einem guten Zustand ist und die Änderung für sich genommen sinnvoll ist
 
 Schlüsselvertreter:: Ola Ellnestam, Daniel Brolund ("The Mikado Method", 2012)
 
@@ -33,6 +37,33 @@ Schlüsselvertreter:: Ola Ellnestam, Daniel Brolund ("The Mikado Method", 2012)
 * Wenn eine direkte Änderung zu viele Dinge bricht, um sie auf einmal zu beheben
 * Koordination von Refactoring-Arbeiten mehrerer Entwickler auf sichere Weise
 * Inkrementelle Verbesserungen vornehmen, ohne das Team zu blockieren
+* Brownfield-Entwicklung mit versteckten Abhängigkeiten
+
+[[mikado-methode-rezept-kanonische-form]]
+[discrete]
+== *Mikado-Methode-Rezept (kanonische Form)*
+
+1. Hier beginnen: Das Mikado-Ziel aufschreiben.
+2. Das Ziel oder die Voraussetzung naiv implementieren.
+3. Treten Fehler auf?
+* Beispiele: Compilerfehler, fehlschlagende Tests, Laufzeitfehler, kaputte Builds.
+* Wenn *Ja*, gehe zu Schritt 4.
+* Wenn *Nein*, gehe zu Schritt 9.
+4. Unmittelbare Lösungen für die Fehler finden.
+5. Die Lösungen als neue Voraussetzungen in den Mikado-Graphen einzeichnen.
+6. Alle Änderungen rückgängig machen und zum letzten bekannten guten Zustand zurückkehren.
+7. Die nächste zu bearbeitende Voraussetzung auswählen.
+8. Gehe zu Schritt 2.
+9. Ist die Änderung sinnvoll?
+* Beispiele: verständlich, intern konsistent, sicher beizubehalten, für sich allein nützlich.
+* Wenn *Ja*, gehe zu Schritt 10.
+* Wenn *Nein*, gehe zu Schritt 7.
+10. Die Änderung committen.
+11. Ist das Mikado-Ziel erreicht?
+* Wenn *Ja*, gehe zu Schritt 12.
+* Wenn *Nein*, gehe zu Schritt 7.
+12. FERTIG!
+
 
 [discrete]
 == *Verwandte Anchors*: