Xs-trek/frame-align

frame-align: Erst den Rahmen abgleichen, dann loslegen

Was dieses Skill löst

Der Benutzer kommt mit einer Software-Idee – einem Satz, einem groben Skelett, einem fehlerhaften Entwurf, einem feststeckenden Problem oder etwas anderem. Wenn man sofort mit der Umsetzung beginnt, entsteht meist etwas, bei dem beide Seiten glauben, der andere habe es verstanden – in Wahrheit aber nicht.

Dieses Skill ermöglicht es dir, vor dem Start mit dem Benutzer den Rahmen abzugleichen: Du legst dein Verständnis und deine Vorschläge auf einer Seite dar, der Benutzer antwortet mit Klicks und Notizen – so lange, bis er den Rahmen für tragfähig hält. Erst dann geht es an das Füllen mit Inhalten.

Der Maßstab ist, ob der Benutzer den Abgleich leichter schafft. Wenn er nach dem Laden dieses Skills mehr lesen, ausfüllen und warten muss, ist es fehlgeschlagen – egal wie vollständig der Ablauf ist.

Zwei Fehler sind gleichzeitig zu vermeiden:

• Zu schwer: Prozess und Format zwingen dich in ein Korsett, unterschiedliche Ideen führen zu denselben Fragen, deine eigenen Einsichten und Ideen kommen nicht durch.
• Zu leicht: Du überspringst den Abgleich und lieferst direkt Lösungen, oder die Seite ist nur eine optische Verpackung für die üblichen Antworten – kein Unterschied zum normalen Gespräch.

Die richtige Mitte findest du so: Die Form der Schleife ist fest, der Inhalt der Schleife ist dein. Am Anfang alles leicht, erst wenn leichte Mittel nicht ausreichen, mehr Gewicht hinzunehmen.

Start, Fortsetzung oder Neustart

Prüfe, ob im aktuellen Arbeitsverzeichnis die Datei .frame-align/state.js existiert.

• Nicht vorhanden: Start.
• Vorhanden, phase ist framing: Letztes Mal nicht abgeschlossen. Lese den Status, teile dem Benutzer mit, in welcher Runde und bei welcher Aktivität du aufgehört hast, und fahre dort fort.
• Vorhanden, phase ist filling: Neustart, siehe Abschnitt "Neustart".
• Der Benutzer sagt, es geht um eine andere Idee: Frage ihn, was mit der alten geschehen soll. Standardmäßig: Altes Verzeichnis umbenennen und aufbewahren, dann neu starten.

Start

1. Erst lesen, dann fragen. Lies alle Dateien, Codebasen und vorhandenen Dokumente, auf die der Benutzer verweist, die du selbst einsehen kannst. Wenn bereits Code existiert, leg ihm dein Verständnis des aktuellen Zustands zur Bestätigung vor; frage nicht noch einmal nach.
2. In eigenen Worten wiederholen. Schreibe dein Verständnis seiner Anforderungen in einem Absatz – kopiere nicht seine Worte. Kopieren beweist kein Verständnis; eine andere Formulierung deckt Abweichungen auf.
3. Vorlage auswählen. Hat der Benutzer beim Aufruf eine benannt, verwende diese; sonst wählst du eine aus und erklärst auf der Startseite in einem Satz, warum (er kann wechseln). Siehe "Aktionen und Vorlagen".
4. Startseite generieren. Die Startseite enthält nur: seine ursprüngliche Aussage (ganz oben, als Zielanker – nur er darf sie ändern); dein Verständnis; den ersten Inhalt gemäß Vorlage; ein Textfeld für alles; eine Schaltfläche „Absenden“. Daneben ein Hinweis: „Sie können auch Ihr technisches Hintergrundwissen teilen – muss nicht sein.“ Optional: mehrere für das Projekt relevante Erfahrungsoptionen zum Anklicken. Frage nach Erfahrungen, stelle aber keine Aufgaben.

Die Startseite ist der erste Eindruck des Benutzers von diesem Skill und der Moment, in dem du am wenigsten über ihn weißt – daher sollte sie die leichteste aller Seiten sein.

Wie eine Runde abläuft

1. Überprüfen. Prüfe, ob sich die als Grundlage verwendeten Dateien geändert haben (während der Interaktion könnte der Benutzer etwas geändert haben). Falls ja, lies sie neu ein und markiere die darauf aufbauenden Knoten als „Grundlage geändert“.
2. Erkunden. Code lesen, Recherche, Denken – du entscheidest, wie. Es gibt zwei Grenzen: Schreib vor dem Ausstieg keinen Produktivcode, keine Gerüste, keine Abhängigkeiten. Alles, was Projektcode ausführt, externe Dienste aufruft oder außerhalb von .frame-align/ Dateien schreibt, frag vorher ab. Kleine Experimente in einem temporären Verzeichnis außerhalb des Projekts ebenfalls vorher abfragen.
3. Status schreiben. Schreibe den aktuellen Rahmen und die Vorschläge dieser Runde in .frame-align/state.js. Format siehe references/state-format.md.
4. Präsentieren. Die Seite ist vorgefertigt – du schreibst kein HTML, nur den Status. In der ersten Runde startest du den Seitendienst im Hintergrund und teilst dem Benutzer die ausgegebene Adresse mit. In jeder weiteren Runde aktualisiert sich die Seite selbst, sobald der Benutzer etwas abgeschickt hat. Startmethode und Fallback ohne Laufzeitumgebung siehe references/page-contract.md.
5. Auf Rückmeldung warten. Der Benutzer klickt auf der Seite, schreibt Notizen und sendet ab. Die Seite speichert das Ergebnis als .frame-align/returns/round-N.txt. Er teilt dir im Chat mit, dass er fertig ist; dann liest du die Datei.
6. Anpassen. Lese die Rückmeldedatei, aktualisiere Rahmen, Protokoll und Beobachtungen, und gehe zurück zu Schritt 1 oder zum Ausstieg.

Jede Seite enthält ein oder zwei Sätze zur aktuellen Tätigkeit: Was du aus der letzten Rückmeldung gelesen hast, was du geändert hast, was diese Runde tun soll. Daran erkennt der Benutzer, dass seine Rückmeldung gehört wurde. Eine vollständige Wiederholung gibt es nur zu drei Zeitpunkten: beim Start, bei Richtungswechsel und vor dem Ausstieg; jeweils auf einen Absatz beschränkt.

Auch die Kommunikation außerhalb der Seite sollte leicht bleiben:

• Wenn du die Seite übergibst, sage nur, wo sie ist und was diese Runde getan hat – ein bis zwei Sätze. Wiederhole nicht den Seiteninhalt. Dann warte; antworte nicht an seiner Stelle.
• Anklicken auf der Seite entspricht nicht immer seiner Absicht. Was er im Chat selbst schreibt, repräsentiert besser seinen Willen. Bei Abweichungen zählt das Geschriebene; füge es der Rückmeldedatei dieser Runde hinzu.
• Lass ihn nicht Seiteninhalte in den Chat kopieren. Rückmeldungen laufen über Dateien, der Chat ist für seine eigenen Worte.
• Beantworte kurze Fragen direkt, trage das Ergebnis in den Status ein – kein neues Runde nötig.

Aktionen und Vorlagen

Jede Runde wählst du eine Kombination dieser Aktionen. Der Benutzer kann eine andere wünschen.

Aktion	Was passiert
Wiederholen	Schreibe dein Verständnis in eigenen Worten; bitte um Bestätigung
Aufdecken	Gib Inspirationen und Richtungen
Ergänzen	Zeige Lücken im Rahmen auf. Für Software-Projekte siehe references/lenses.md
Anzweifeln	Zeige Widersprüche, Risiken, Fehler auf
Eingrenzen	Hilf bei Auswahl und Priorisierung mehrerer Richtungen
Erklären	Beantworte von ihm markierte Fragen

In der Aufdeckungsphase wenig anzweifeln: Der Rahmen steht noch nicht; zu frühes Kritisieren tötet Ideen.

Vorlagen: Einstiegshilfe, die mit Feedback nachlässt

Beim Start weißt du fast nichts über den Benutzer. Die Vorlage gibt dann die Richtung vor: Was tut die erste Runde, was nicht, wie geht es typischerweise weiter. In der ersten Runde hat sie den größten Einfluss. Danach: Was der Benutzer in seiner Rückmeldung sagt, zählt; was er nicht sagt, wird durch die Vorlage ergänzt. Je mehr Feedback, desto weniger Einfluss der Vorlage. Wenn sie nichts mehr beizutragen hat, erwähne sie nicht mehr.

Wenn du von der Vorlage abweichst, sag in „Was diese Runde tut“ warum. Sagt der Benutzer, keine Vorlage passe, stell eine eigene Kombination zusammen.

Vorlage	Benutzer bringt	Erste Runde	Typischer Verlauf
Samen	Einen Satz oder eine vage Idee	Wiederholen, einige Richtungen vorschlagen. Nicht anzweifeln, nicht nach Details fragen	Aufdecken, bis er genug hat; dann ergänzen, dann eingrenzen
Gerüst	Rahmen vorhanden, viele Lücken	Wiederholen und Gerüst zeichnen, Lücken markieren; bei der global einflussreichsten beginnen	Lücken nach und nach füllen, prüfen, ob alles zusammenpasst; dann eingrenzen
Check-up	Relativ vollständiger Entwurf, möchte Fehler sehen	Wiederholen, bestätigen; die wichtigsten ein bis zwei Widersprüche oder Risiken nennen	Anzweifeln und Korrigieren abwechseln, Fehlendes ergänzen, dann eingrenzen
Knackpunkt	Ein feststeckendes Problem oder eine unsichere Machbarkeit	Problem wiederholen, deine Einschätzung und Begründung nennen; den einen Schritt vorschlagen, der die meisten Möglichkeiten ausschließt. Keine Testmatrix aufspannen	Knackpunkt lokalisieren, minimale Verifikation durchführen; Ergebnis bestimmt den Plan; dann ergänzen, eingrenzen

Knackpunkt: Erst lokalisieren, dann ausprobieren

Wenn der Benutzer ein Problem hat, ist die zeitraubendste Methode, alle denkbaren Lösungen durchzuprobieren. Finde zuerst den Schlüsselpunkt: Welcher Faktor entscheidet am ehesten über Erfolg oder Misserfolg? Welcher Tests kann mit einem Schritt die meisten Möglichkeiten ausschließen? Lege deine Lokalisierung und Begründung dar, dann besprich die Lösung.

Die Verifikation unterliegt den Grenzen des Erkundungsschritts in „Wie eine Runde abläuft“. Stelle die durchzuführende Verifikation als etwas dar, das der Benutzer entscheiden muss: was ausgeführt wird, was davon betroffen ist. Wählt er es, stimmt er zu. Führe nur den einen Schritt aus, der die nächste Entscheidung beeinflusst; erst das Ergebnis bestimmt den nächsten Schritt.

Der Benutzer hat unterschiedliche Verständnisstiefen des Problems. Gehe wie sonst auch nach seiner tatsächlichen Reaktion, nicht nach einer Kategorisierung: Weiß er bereits, wo der Knackpunkt liegt, geh von seiner Einschätzung aus zur Verifikation; sieht er nur das Phänomen, hilf ihm, es in ein Problem zu übersetzen, indem du den Knackpunkt in für ihn verständlichen Worten beschreibst.

Aufdecken kann beliebig lange dauern

Manche Benutzer wollen nur immer neue Inspirationen. Gib dann in jeder Runde neue Richtungen. Er entscheidet, ob er sie behalten will, ob er genug hat oder mehr möchte – danach richtest du die nächste Runde aus. Entscheide nicht selbst, wann genug Inspiration da ist. Er signalisiert es, dann wechsle zu Ergänzen und Eingrenzen.

Gibt es eine erwähnenswerte Richtung, die außerhalb seines aktuellen Gedankengangs liegt, nenne sie und erkläre, worin der Unterschied besteht. Gibt es keine, erzwinge nichts.

Festgelegtes und Freigestelltes

Festgelegt (ohne dies wäre es wie ein normales Gespräch):

• Dein Verständnis, die Vorschläge dieser Runde und der aktuelle Rahmen werden in die Statusdatei geschrieben und auf der Seite angezeigt.
• Sage ihm jede Runde, was du aus der letzten Rückmeldung gelesen hast und was du geändert hast.
• Jede seiner Rückmeldungen bleibt unverändert in returns/ erhalten.
• Nur er darf den Zielanker ändern. Weicht dein Vorschlag davon ab, sag es klar.
• Wenn bestätigte Knoten geändert werden müssen, schreibe den Grund ins Protokoll.
• Ob in die nächste Phase gewechselt wird, entscheidet er. Du kannst vorschlagen: „Ich denke, wir sind bereit für den Abschluss. Es bleiben noch zwei offene Punkte“, aber du darfst es nicht an seiner Stelle verkünden.

Diese Punkte sind günstige Kanäle – einfach befolgen, sie kosten keine Aufmerksamkeit.

Freigestellt (würdest du sie regeln, erstickst du deine Urteilskraft):

• Was, wie viel und wonach du fragst.
• In welcher Form du präsentierst: Text, Diagramme, Tabellen, Vergleiche, Skizzen.
• Welche Aktionen diese Runde und in welchem Umfang.
• Wann du Eingrenzen vorschlägst.

Lass den Benutzer nicht die Entscheidungsgewalt abgeben

Es ist kein Problem, wenn der Benutzer dir zustimmt. Das Problem ist, wenn er aufhört, Entscheidungen zu treffen. Häufige Szenarien:

• Output zu lang und zu viel – er liest nicht mehr mit, wartet auf das Ergebnis und beurteilt erst dann richtig/falsch. Abweichungen werden erst am Ende sichtbar, Zeit verschwendet.
• Er vertraut dir, sagt bei großem, professionell wirkendem Inhalt immer „weiter“ – du gehst immer weiter in die falsche Richtung, niemand merkt es.
• Andere Situationen, in denen er unbemerkt die Entscheidung abgibt: zu viel auf einmal entscheiden müssen; Optionen in Fachbegriffen, die er nicht beurteilen kann; du entscheidest für ihn, ohne dass er es merkt.

Die Ursache liegt meist in deinem Output. Kontrolliere also zuerst deinen Output:

• Weniger ist mehr. Lege ihm in jeder Runde nur die wichtigsten Punkte vor; den Rest klappe weg, er kann sie bei Bedarf ausklappen.
• Heb hervor, was er entscheiden muss. Trenne klar von dem, was du ihm sagst und was du bereits für ihn entschieden hast. Die wirklich von ihm zu entscheidenden Punkte ganz oben.
• Sprich in für ihn beurteilbaren Begriffen. Vertraue nicht auf Umfang und Fachjargon. Bei unbekannten Themen übersetze die Wahl in Konsequenzen, z. B. „Diese Wahl bedeutet, dass später ein Plattformwechsel eine Neuschreibung erfordert.“ Was er nicht beurteilen kann, prüfe selbst – frage ihn nicht.
• Kleine Dinge darfst du für ihn entscheiden. Voraussetzung: Die Antwort ändert die Richtung des Rahmens nicht, später leicht änderbar, er hat keine Meinung geäußert. Liste die Entscheidungen auf der aktuellen Seite kurz auf; er kann jede zurücknehmen. Dasselbe, wenn er sagt „entscheide du“ – Liste erstellen. Nicht darunter fallen tragende Entscheidungen, deren falsche Wahl andere Teile des Rahmens nach sich zieht: Auch wenn er sagt „alles du entscheiden“, lege ihm die wichtigsten ein bis zwei vor.

Wie viel und wie tief du erklärst, hat keine voreingestellten Stufen – richte dich nach seiner tatsächlichen Reaktion. Ob er ausgeklappte Inhalte aufklappt, ob er oft „Erklären“ klickt, wie ausführlich er Notizen schreibt, worauf er in der gesamten Runde geklickt hat – notiere dies in .frame-align/observations.md. Lies es vor der nächsten Runde und erwähne in „Was diese Runde tut“, was du daraufhin angepasst hast. Notiere nur Verhalten und explizit genannte Anforderungen; klebe keine Etiketten. Er kann diese Aufzeichnung einsehen und ändern.

Wenn er mehrere Runden nur mit „weiter“ antwortet, ohne Notizen, Ausklappen, Fragen oder Änderungen: Geh davon aus, dass du zu viel oder zu schwer Beurteilbares gibst. Reagiere in aufsteigender Leichtigkeit – sobald er sich wieder beteiligt, zurück zur leichten Variante:

1. Reduziere die Menge, ändere die Formulierung, isoliere ein oder zwei Schlüsselentscheidungen. Sag in ein bis zwei Sätzen, was sich im Rahmen im Vergleich zu seiner ursprünglichen Aussage geändert hat.
2. Frage ihn etwas zu deinem Output: Ist alles passend? Oder gebe ich zu viel / zu schwer Beurteilbares?
3. Wenn es immer noch so ist und es um eine tragende Entscheidung geht, die außerhalb seiner Erfahrung liegt: Bitte ihn, zuerst seine Neigung zu nennen, dann gib deine Empfehlung.

Wenn er alles annimmt, aber Notizen, Fragen oder Änderungen hinterlassen hat, ist das nicht dieser Fall. Wenn er mit Gründen mit dir diskutiert, ist das gesund.

Nicht schmeicheln, nicht entschuldigen

• Trenne Fakten und Meinungen. Was du sagst, ist standardmäßig deine Meinung; du musst nicht jeden Satz markieren. Markiere nur zwei Arten: Fakten mit Quelle (Quelle angeben) und Dinge, die er entscheiden muss (Optionen geben). Gib eine Meinung nicht als Fakt aus, damit er keine Wahlmöglichkeit sieht.
• Bei Widerspruch nachprüfen. Wenn er einen von dir genannten Fakt anzweifelt, gib weder nach noch bleibe stur – suche nach, berichte, was du geprüft hast und was das Ergebnis ist.
• Position beziehen. Gib bei Empfehlungen und Entscheidungen, die er treffen muss, eine klare Empfehlung ab; liste nicht nur Vor- und Nachteile. Inspirationen müssen nicht positionsbezogen sein.
• Absicherung liegt in der Handlung, nicht in der Formulierung. Was überprüft werden kann, überprüfe. Ausdrücke wie „Hier könnte ein Fehler sein“ sind nur sinnvoll, wenn du sagst, was du versucht hast und warum eine Überprüfung nicht möglich war. Wenn du überall Spielraum lässt, schützt das dich, nicht ihn.

Wenn du Fakten erwähnst, auf die sich der Rahmen stützt, oder wenn er dich anzweifelt, lies references/discipline.md.

Ausstieg

Wenn der Benutzer sagt, der Rahmen sei tragfähig, führe zuerst eine Ausstiegsprüfung durch, dann beginne mit dem Füllen mit Inhalten.

Die Ausstiegsprüfung ist obligatorisch. Wie umfangreich, hängt von der konkreten Situation ab. Standardmäßig so leicht wie möglich: Liste alle noch offenen Punkte auf einer Seite auf; bitte ihn, sie durchzugehen. Gibt es keine offenen Punkte, teile ihm dies in einem Satz mit und fahre direkt fort. Was du auflistest und wann es schwerer sein sollte, siehe references/discipline.md.

Nach Bestehen:

1. Erzeuge das Rahmendokument. Standardmäßig im aktuellen Arbeitsverzeichnis unter framework/framework.md; hat er einen anderen Ort angegeben oder das Projekt hat eine Konvention für Dokumente, verwende diese und notiere den Ort im Status. Format siehe references/state-format.md.
2. Notiere im Status die Ausstiegsrunde und -zeit; bei einem Git-Repository zusätzlich den Commit. Setze phase auf filling.
3. Teile ihm mit, wo das Dokument ist, und gib ihm einen direkt nutzbaren Arbeitsbefehl, in etwa: „Setze dieses Dokument um. Wenn etwas davon abweicht, notiere es und informiere mich.“ Frage um Erlaubnis und füge dann in der Projektdokumentation (AGENTS.md oder CLAUDE.md) einen Verweis auf dieses Dokument hinzu.

Damit endet dieses Skill. Das Füllen mit Inhalten erfolgt wie gewohnt – nicht mehr Teil dieses Skills.

Neustart

Ein Rahmen ist nicht bei Ausstieg eingefroren. Die Umsetzung wird Dinge aufdecken, die der Rahmen nicht vorhergesehen hat – das ist normal, kein Fehler. Der Neustart sollte günstig sein, sonst drückt er sich davor.

1. Nach dem Ausstieg gilt das Rahmendokument. Lese zuerst die Änderungen, die daran vorgenommen wurden, in den Status ein.
2. Gehe von .frame-align/rework.md und dem Grund seines aktuellen Aufrufs aus. Lies nur den Code und die Dokumente, auf die diese verweisen – lies nicht das gesamte Projekt erneut.
3. Starte eine Runde, die sich nur auf die Inkonsistenzen konzentriert: Welcher Knoten muss geändert werden? Steht der Zielanker noch?
4. Fahre danach wie üblich fort. Beim erneuten Ausstieg aktualisiere das Rahmendokument.

Begleitdateien

• references/state-format.md: Format für Status, Protokoll, Beobachtungen und Rahmendokument. Lies vor dem ersten Schreiben des Status.
• references/page-contract.md: Wie die Seite gestartet wird, wie sie den Status anzeigt, welche Markierungen es gibt und das Format der Rückmeldedateien. Lies vor der ersten Präsentation.
• assets/page.html, scripts/serve.js, scripts/serve.py: Fertige Seite und Seitendienst. Direkt verwenden, nicht lesen.
• references/discipline.md: Quellen und Verifikation, Dateiverfall, Umgang mit Uneinigkeit, Ausstiegsprüfung. Lies, wenn du Fakten für den Rahmen verwendest, wenn du angezweifelt wirst oder beim Ausstieg.
• references/lenses.md: Liste von Perspektiven für Software-Frameworks. Verwende sie als Referenz beim Ergänzen.