ajitta/know-your-unknowns

Unknowns Loop — Arbeitsablauf für den Umgang mit leistungsstarken Modellen

Kernprinzip: Der Engpass bei leistungsstarken Modellen ist nicht das Modell – es ist die Fähigkeit des Benutzers, die Karte (Plan) mit dem Territorium (Realität) abzugleichen. Diese Lücke sind die Unbekannten. Das Design des Erkunden → Fragen → Planen → Implementieren → Protokollieren von Abweichungen → Verifizieren-Loops ist wichtiger als ein einzelner guter Prompt. Ursprung: Die 11 „Know your unknowns“-Beispiele; der Loop selbst ist eine Plugin-Erweiterung – siehe skills/loop/references/talk-source.md.

Ausgabe: Artifact-Tool → .unknowns/<YYYY-MM-DD>-loop-<slug>.html → Markdown. Jedes Stufen-Artefakt behält seine eigene Skill-Reaktionskontrolle; die Kontrolle des Loops selbst ist der Pro-Stufen-Checkpoint, der in den .unknowns/loop.json-Tracker einfließt. Details: skills/loop/references/output-routing.md

Schritte (10 – je nach Größe skalieren)

1. Wert & Erfolgskriterien definieren

Vor dem Start mit dem Benutzer abstimmen: Zweck / Wert für den Benutzer / Erfolgskriterien / vorhandenes Verhalten, das nie gebrochen werden darf / erlaubte Kosten & Änderungsumfang. Ohne Erfolgskriterien wird der Implementierungsumfang leicht mit Fortschritt verwechselt.

2. Blind-Spot-Investigation → /unknowns:blindspot (bzw. /blindspot für kopierte Installationen)

Nur untersuchen, keine Implementierung. Unbekannte Unbekannte, Konfliktpunkte, Regressionsrisiken finden; verbesserten Prompt erstellen. Wenn die Domäne selbst unvertraut ist (Anfragen vage, weil Begriffe unbekannt), zusätzlich /unknowns:teach-me ausführen.

3. Interview → /unknowns:interview

Architekturverändernde Fragen zuerst, maximal 4 pro Runde.

4. Lösungen erkunden & formen (bei Bedarf)

• Was zu tun ist unentschieden → /unknowns:brainstorm (Lösungsraumkarte)
• Kann nicht in Worten beschreiben, wie es aussehen soll → /unknowns:prototypes (divergente Mockups)
• Hat ein Beispiel zum Nachahmen → /unknowns:reference (Referenzanalyse)

5. Risikobehafteter Annahmen-Prototyp (bei Bedarf)

Vor der vollständigen Implementierung einen minimalen Prototypen bauen, der nur die unsicherste technische Annahme verifiziert. Zuerst die Annahme sowie die Erfolgs-/Fehlerkriterien angeben.

6. Plan → /unknowns:plan

Anpassbarer Plan, sortiert nach Revisionswahrscheinlichkeit, nicht nach Ausführungsreihenfolge. Entscheidungen, die Benutzereingaben erfordern (Schema, Schnittstellen, UX-Verträge), stehen oben.

7. Implementieren + Abweichungsprotokoll → Regeln von /unknowns:notes anwenden

Alles protokollieren, was nicht im Plan steht; bei Entscheidungen, die Architektur, benutzersichtbares Verhalten, Daten oder Sicherheit betreffen, anhalten und nachfragen. Wenn das Gespräch komprimiert wurde, vor der Fortsetzung der Implementierung erneut /unknowns:notes (und dieses Skill für die Schrittliste) aufrufen.

8. Unabhängige Verifizierung → Agent unknowns:independent-reviewer

Mit dem Agent-Tool (subagent_type: unknowns:independent-reviewer) starten. Nie einen Fork oder /subtask – diese erben den Kontext des Implementierers, was dieser Schritt gerade ausschließen soll. Dem Agenten übergeben: Erfolgskriterien (Schritt 1), den genehmigten Plan (Schritt 6), den Pfad zu IMPLEMENTATION_NOTES.md, den Diff-Bereich / die betroffenen Dateien und die Anleitung zum Ausführen der Tests. Nie die eigene Zusammenfassung des Implementierers übergeben.

9. Verständnis-Check & Übergabe → /unknowns:quiz

Prüfen, ob der Benutzer diese Arbeit in einem PR oder einer Übergabe erklären kann. Wenn die Arbeit die Zustimmung eines Reviewers oder Stakeholders benötigt, zusätzlich ein /unknowns:buy-in-Dokument erstellen.

10. Wertermittlung

Beurteilung anhand des echten Werts, nicht der Code-Qualität: Wessen Problem ist geschrumpft und um wie viel / schneller / Gründe, warum es ungenutzt bleiben könnte / Metriken / Entfernungskriterium. Bauen ist einfach, Werte zu generieren ist immer noch schwer. Abschließend eine Scoreboard-Zeile erfassen – den Benutzer fragen, ob dies etwas zu Tage gefördert hat, das er nicht wusste, und ob es eine Entscheidung geändert hat; dann die Zeile an .unknowns/scorecard.md anhängen. Nie diese beiden Fragen für den Benutzer beantworten, und die Zeile auch dann schreiben, wenn beide Antworten „Nein“ sind. Details: skills/loop/references/scorecard.md

Skalierungskriterien

• Kleine Korrektur (1–2 Dateien, klare Spezifikation): nur Schritt-7-Regeln (Notizen) – kein Loop nötig.
• Mittlere Arbeit: 1 (ein Austausch) → 2 → 3 → 6 → 7 → 9.
• Große oder unvertraute Arbeit: alle Schritte, wobei 4 und 5 nur bei Bedarf ausgeführt werden.
• Schritt 1 läuft in jeder Stufe. Unsicher, welche Stufe → Benutzer fragen, dann die Wahl dokumentieren.

Loop-Status (überlebt Kompression, /resume, neue Sitzungen)

.unknowns/loop.json behalten – {task, tier, stage, decisions[], artifacts[]} – und bei jedem Stufenwechsel neu schreiben. Jede Stufe mit einem AskUserQuestion-Checkpoint (fortsetzen / überspringen / anhalten) abschließen und die Antwort dort dokumentieren.

• Argument status: Datei lesen; Stufe, aktuelle Phase, verbleibende Schritte melden.
• Argument resume: Datei lesen; ab der gespeicherten Phase fortsetzen.
• Jeder andere Argumenttext ist die Aufgabenbeschreibung.
• Kein Argument: .unknowns/loop.json fortsetzen, falls vorhanden; andernfalls zuerst nach der Aufgabe fragen.

Arbeitsprinzipien (komprimiert)

1. Zweck definieren. 2. Blind Spots vor der Implementierung finden. 3. Das Modell Fragen stellen lassen.
2. Referenzen und Prototypen statt Worte geben. 5. Pläne nach Revisionswahrscheinlichkeit sortieren.
3. Unbekannte und Planabweichungen protokollieren. 7. Mit Tests und unabhängiger Überprüfung verifizieren.
4. Sicherstellen, dass der Benutzer das Ergebnis erklären kann. 9. Ergebnisse in reaktionsfähiger Form.
5. Den echten Wert messen, nicht die Code-Menge.