/continuous-refactoring.de

0.7.0: ein Run, deine Entscheidungen, kein eigener Zustand

· Release · geschrieben für 0.7.0

0.7.0 ist die bisher größte Änderung an der Suite. Das Release ist nicht abwärtskompatibel und ändert, wie du im Alltag mit der Suite arbeitest. Dieser Beitrag erklärt, was sich geändert hat, warum, und was ein Projekt tun muss, das mit 0.6 eingerichtet wurde. Wer nur die Schritte braucht, springt zu Umstieg von 0.6.

Wie 0.6 funktioniert hat

Bis 0.6 war die Suite ein Loop. Jeder Aufruf von /continuous-refactoring machte einen Durchgang: Er wählte den am längsten überfälligen der vier Tracks (Safety Net, Guardrails, Housekeeping, Investigation), jeder mit eigenem Rhythmus, und übergab ihn an den Skill dieses Tracks. Der lief Scan → Priorisieren → Entwurf → Umsetzung → Lernen ab, jeder Schritt ein eigener Skill. Insgesamt elf Skills, und nur refactor-learn durfte die Aufzeichnungen der Suite schreiben.

Diese Aufzeichnungen lagen in Dateien unter .scratch/refactor/:

  • config.md, pro Person und Rechner: wo die Buchführung liegt und ob Tickets und Merge Requests automatisch oder nach Rückfrage angelegt werden (Ticket-create-mode, MR-create-mode)
  • bookkeeping.md, oder stattdessen ein Tracker-Ticket: Rhythmus, letzter Scan und offene Punkte jedes Tracks
  • merge-requests.md und out-of-scope/ für gemerkte Merge Requests und Ablehnungen

Als Sicherung von Anfang an hielt die Suite bei zwei offenen Merge Requests und fünf offenen Kandidaten an: Ein Durchgang an dieser Grenze endete ohne neue Arbeit.

Was im Weg stand

Bis 0.6 standen zwei Dinge im Weg:

  • Die Autonomie war pro Rechner festgelegt. Eine Config-Datei entschied einmal, ob die Suite Tickets und Merge Requests selbst anlegt oder vorher fragt. Beim einen Aufruf „zeig mal“ und beim nächsten „mach einfach“ zu sagen, ging nicht.
  • Sie führte eigene Aufzeichnungen. Ein Buchführungsdokument, lokal oder in einem Tracker-Ticket, hielt fest, was gescannt und angelegt war. Es konnte von dem abweichen, was der Tracker tatsächlich zeigte, und welcher Track als Nächstes dran war, ergab sich aus einem Veraltungsquotienten, den niemand vorhersagen konnte.

Ein Run, eine Kette von Entscheidungspunkten

/continuous-refactoring macht jetzt einen Run: von deinen offenen Refactoring-Tickets bis zu einem geöffneten Merge Request. Unterwegs durchläuft er eine feste Kette von Entscheidungspunkten: Abgleich, Track-Wahl, Scan, Tickets anlegen, Ticket auswählen, Entwurf, Umsetzung, Merge Request.

Jeder Entscheidungspunkt zeigt dieselben drei Dinge: was er gefunden hat, die Optionen und eine Empfehlung mit kurzer Begründung. In deinen Tracker, deine Forge oder deine Dateien wird nur geschrieben, was aus einem Entscheidungspunkt folgt.

Ohne weitere Angabe ist der Run interaktiv: Du beantwortest jeden Entscheidungspunkt. Im Aufruf kannst du mehr sagen, in deinen eigenen Worten:

/continuous-refactoring
/continuous-refactoring do it yourself
/continuous-refactoring diy
/continuous-refactoring Safety Net, ohne zu fragen
/continuous-refactoring bearbeite Ticket #42
/continuous-refactoring nur die Rector-Tools

„do it yourself“, oder einfach „diy“, macht den Run autonom: Er nimmt an jedem Entscheidungspunkt seine eigene Empfehlung. Die Befunde, die er dir gezeigt hätte, schreibt er trotzdem, dazu die gewählte Empfehlung. So kannst du hinterher nachlesen, warum der Run so gelaufen ist. Wenn du interaktiv startest und es dir anders überlegst, sag „mach ab hier selbst weiter“, und der Run läuft ab dem nächsten Entscheidungspunkt autonom.

Kein eigener Zustand

Die Suite führt keine eigenen Aufzeichnungen mehr. Bei jedem Run sucht sie in deinem Tracker und deiner Forge nach ihren Tickets, Merge Requests und Ablehnungen. Deshalb fällt weg:

  • die Config-Datei und das Buchführungsdokument, lokal und remote
  • Ticket-create-mode und MR-create-mode
  • die Rhythmen der Tracks

Tickets werden an ihrem Gegenstand erkannt, nicht an einem festen Label oder Titel. Ein Ticket, das du selbst geschrieben hast, wird aufgegriffen, wenn es deine Candidate-Markierung trägt (sofern dein Tracker eine hat) oder wenn du es im Aufruf nennst. Ein Track wird einmal gescannt; danach sind seine Tickets die Aufzeichnung.

All das findet die Suite über die Refactoring operations in docs/agents/issue-tracker.md. Auch dieser Abschnitt ändert sich:

  • Search ist neu und Pflicht: wie Tickets nach Wörtern gesucht werden, offene und geschlossene zusammen.
  • Rejected, Blocked by und Housekeeping sind neu und optional. Ohne Rejected schlägt der Run einen Ort vor, wenn er zum ersten Mal eine Ablehnung festhält.
  • Bookkeeping, Filed date und Comment author and time entfallen.

Die Grenzen fallen weg

Die Grenzen von zwei offenen Merge Requests und fünf offenen Kandidaten waren eine Sicherung von Anfang an, kein Fehler. Mit der Zeit hat sich gezeigt, dass sie nicht nötig sind, solange zwei Dinge gelten:

  • Die Merge Requests bauen nicht aufeinander auf (keine Stacked MRs), und
  • der Agent erkennt, wann ein offener Merge Request mit der geplanten Änderung in Konflikt geraten wird, und berücksichtigt das bei der Planung.

Deshalb fallen beide Grenzen in 0.7.0 weg. Wer in seinem Projekt trotzdem eine Grenze haben will, kann sie dort weiterhin setzen.

Ohne die Grenze von zwei Merge Requests wird noch etwas möglich: Ein Ticket kann jetzt in mehreren kleineren Merge Requests umgesetzt werden statt in einem großen. Jeder zweigt für sich vom Default-Branch ab, und jeder ist für Menschen leichter zu reviewen.

Zwei Skills statt elf

Die Suite besteht jetzt aus continuous-refactoring und continuous-housekeeping. Die neun anderen sind weg.

Die Aufteilung hatte zwei Zwecke: Der ganze Loop sollte nicht in einer einzigen Skill-Datei stehen, und man sollte in einzelne Schritte des Loops springen können. Die Nutzung hat gezeigt, dass beides keine eigenen Skills braucht:

  • Das Routing zwischen Skills war unzuverlässig, je nach Agent. Referenzdateien, die nur bei Bedarf gelesen werden, funktionieren mit allen Agenten zuverlässiger.
  • In einen Schritt springen geht auch ohne eigenen Skill. Im Aufruf den Schritt zu nennen, bei dem der Agent einsteigen soll, hat damals funktioniert und funktioniert auch heute.

Hat dein Projekt eigene Skills fürs Planen und Umsetzen, empfiehlt ein Run jetzt diese und nutzt die Abläufe der Suite nur als Rückfall. Vorher wurden die eigenen Skills eines Projekts bei Refactoring-Arbeit ignoriert.

Housekeeping als stehendes Ticket

Housekeeping ist jetzt ein stehendes Ticket, erzeugt aus einer Vorlage in deinem Repository, mit einem Rhythmus, den du wählst. Refactoring-Ideen, die für ein eigenes Ticket zu klein sind, kommen als Kommentare daran. Es hat einen eigenen Befehl, /continuous-housekeeping, den du planen kannst und den ein Agent auch selbst starten darf, wenn das Ticket fällig ist. Siehe Housekeeping.

Umstieg von 0.6

Ein Projekt, das mit 0.6.0 eingerichtet wurde, braucht drei Schritte.

  1. Onboarding erneut ausführen. Ruf /continuous-refactoring auf. Es ergänzt Search in deinem Abschnitt ## Refactoring operations und entfernt die Einträge, die es nicht mehr gibt. Danach endet der Run; committe die geänderte Tracker-Datei und ruf ihn erneut auf.
  2. Alte Dateien löschen unter .scratch/refactor/: config.md, bookkeeping.md, merge-requests.md und den Ordner out-of-scope/. Sie werden nicht mehr gelesen. Tickets, die als Markdown-Dateien in .scratch/refactor/issues/ liegen, bleiben. Wenn du deine alten Ablehnungen behalten willst, nenne ihren Ordner unter Rejected, statt ihn zu löschen. Eine Ablehnung, die wiederkommen soll, sobald dein Projekt eine PHP-Version erreicht, braucht eine Zeile Blocker: PHP >= X.Y. Lag deine Buchführung in einem Tracker-Ticket, schließ dieses Ticket.
  3. Symlinks entfernen, die auf die entfernten Skills zeigen: refactor-loop, refactor-scan, refactor-prioritize, refactor-design, refactor-implement, refactor-learn, continuous-safety-net, continuous-guardrails, continuous-investigation.

Migriert wird nichts. Der erste Scan jedes Tracks baut die Arbeitsliste als Tickets neu auf.

Kleinere Änderungen

  • Das Onboarding probiert seine Such- und Merge-Request-Befehle jetzt aus, bevor es dir die Zusammenfassung zeigt. Schlägt einer fehl, etwa mit einem älteren glab oder gh, fragt es gleich nach einer funktionierenden Variante. Du bestätigst also nur einmal.
  • Das Onboarding beendet jetzt den Run, statt im selben Aufruf weiterzumachen.
  • Die Suite setzt und liest die Triage-Labels needs-info und ready-for-agent nicht mehr. Ob ein Ticket auf eine Antwort wartet, liest sie aus seinen Kommentaren. Sie bleibt mit anderen Engineering-Skills wie mattpocock/skills kompatibel und braucht keinen davon.
  • Datumszeile, Vorlagenzeile und Titel des Housekeeping-Tickets dürfen frei formuliert sein. Runs lesen sie an ihrem Inhalt.

Die Run-Seite beschreibt den Run, wie er heute ist. Fragen zum Umbau gern in den GitHub Discussions.

Changelog 0.7.0

Die Einträge aus dem Upstream-Changelog zu 0.7.0, unverändert auf Englisch. Auch auf GitHub: Release 0.7.0.

Changelog-Einträge anzeigen

  • Breaking, for 0.7.0: the suite is rebuilt around one run of decision points, with all state in your tracker and forge. /continuous-refactoring now leads from your open refactoring tickets to one opened merge request and, at every step — reconcile, Track choice, scan, filing tickets, selecting, design, implementation, merge request — shows what it found, the options and one recommendation. By default you decide each time; say in the call that it should do the run itself ("do it yourself"), or mid-run "carry on yourself from here", and it takes its own recommendations. The call also takes a Track, a ticket or a restriction ("only the Rector tools") in your own words. The suite keeps no state of its own any more: the config file, the bookkeeping document (local and remote), Ticket-create-mode, MR-create-mode and the Track cadences are gone, and so are the limits of two open merge requests and five open candidates. Tickets are found by their subject instead of a fixed label or title, a ticket you wrote yourself is picked up through a Candidate mark or by naming it, and a Track is scanned once — afterwards its tickets are the record. Where your project has its own skills for planning and implementing, a run recommends those and uses the suite's procedures as a fallback. Housekeeping is now one standing ticket made from a template in your repository, with a rhythm you choose, refactoring ideas left on it as comments, and its own command /continuous-housekeeping that can be scheduled and that an agent may start by itself. The suite is two skills, continuous-refactoring and continuous-housekeeping; the nine others are removed. The operations in docs/agents/issue-tracker.md change their cut: Search is new and required; Rejected, Blocked by and Housekeeping are new and optional; Bookkeeping, Filed date and Comment author and time are removed.

    A project onboarded on 0.6.0 needs three steps. (1) Run the onboarding again: call /continuous-refactoring, which adds Search to your ## Refactoring operations section and removes the bullets that no longer exist. (2) Delete the suite's old files under .scratch/refactor/ — config.md, bookkeeping.md, merge-requests.md and the folder out-of-scope/; they are no longer read. Tickets kept as local Markdown files under .scratch/refactor/issues/ stay. To keep your old rejections where they are instead of deleting them, name that folder under Rejected in the section (a rejection that should come back by itself once a PHP version is reached needs a line Blocker: PHP >= X.Y). Where the bookkeeping lived in a tracker issue, close that issue. (3) Remove the symlinks of the removed skills from your skills folder: refactor-loop, refactor-scan, refactor-prioritize, refactor-design, refactor-implement, refactor-learn, continuous-safety-net, continuous-guardrails, continuous-investigation. Nothing is migrated; the first scan of each Track rebuilds the worklist as tickets.

  • The Housekeeping ticket's date line, template line and title are described by what they hold, not by a fixed wording: the onboarding words the Housekeeping bullet itself, and later runs read the due date and the template from the ticket in whatever words it states them.

  • The suite no longer sets or reads the triage labels needs-info and ready-for-agent. Whether a ticket waits for an answer or is ready to work is read from its comments, so it works in a tracker without them. It stays compatible with other engineering skills, such as those of mattpocock/skills, and needs none of them.

  • The onboarding now ends the run. Instead of offering to go on in the same call, /continuous-refactoring reports the onboarding as complete, points out the changes it left in the working tree (the tracker file) and recommends committing them and calling the skill again.

  • The onboarding now tries its search and merge-request commands before it shows you the summary, not after writing the tracker file. When one fails, for example because your installed glab or gh is older, the onboarding asks about a working variant at that point, so the summary you confirm already contains commands that work and no second confirmation follows after writing. A run on its own takes a working variant it found itself; without one, it writes nothing and names the open question.

Fragen oder Anmerkungen zu diesem Beitrag? Gern in den GitHub Discussions (Q&A).