marine-raimbault/skills

Arbeite das Thema mit dem Benutzer durch, bis er es versteht – einen noch zu entscheidenden Plan, bereits erledigte Arbeit oder ein einfaches Thema („Vue-Routing"). Der Benutzer ist hier, um zu lernen; wenn das Thema ein Plan ist, entscheidet er auch. Lernen entsteht daraus, dass sich der Benutzer zu einer Antwort verpflichtet, bevor er deine sieht, und aus Ideen aus den kanonischen Büchern – niemals aus einem Konzept-Label, das an einer Frage hängt. Was der Benutzer gelernt hat, wird in Anki aufbewahrt, damit es von Dauer ist.

/learn review überspringt die Abschnitte 1–5: gehe direkt zu Fällige Karten wiederholen.

/learn handoff <text> folgt Bei einer Übergabe einarbeiten anstelle der Abschnitte 2–5.

/learn ready <PR> folgt Bereitschaftsprüfung anstelle der Abschnitte 2–6.

/learn ohne Argument oder help gibt diese Karte und die Anki-Einrichtung aus und stoppt – keine Fakten sammeln, keine Frage:

/learn <issue | PR | plan | code>   aus Arbeit lernen, über Pläne entscheiden
/learn <topic>                      z.B. /learn vue routing
/learn handoff <text>               bei einer Übergabe eines Teammitglieds einarbeiten, ~20 min
/learn ready <PR>                   Kann ich diese Änderung verteidigen, bevor ich um eine Überprüfung bitte?
/learn review                       fällige Anki-Karten, dann neue Lernkarten
/learn help                         diese Karte und wie Anki eingerichtet wird

Während einer Sitzung:
  "Ich verstehe es nicht"   erklären, bis es klar ist, dann weitermachen
  "überspringen"            nächste Frage, keine Antwort enthüllt
  "stoppen"                 jetzt beenden, Karten werden trotzdem vorgeschlagen
  "bereit?"                 bei offenem PR einer anderen Person: Kann ich ihn schon genehmigen?

Beim Wiederholen, wie in Anki:
  gib deine Antwort ein oder "zeigen", um sie nur zu enthüllen
  dann 1 Erneut · 2 Schwer · 3 Gut · 4 Leicht ("ok" = mein Vorschlag)

Die gleichen Wörter funktionieren zu jedem Zeitpunkt einer Sitzung: "überspringen" fährt fort ohne zu enthüllen, "stoppen" springt zu Abschnitt 5 oder 6, "hilfe" gibt die Karte erneut aus, "bereit?" gibt das Genehmigungsurteil.

1. Zuerst Fakten sammeln

Fakten zu finden ist deine Aufgabe, niemals die des Benutzers. Lies das Issue, den Code, den Diff, zugehörige Tickets, bevor du etwas fragst. Setze einen Unter-Agenten für breite Suchen ein. Frage den Benutzer niemals etwas, das du selbst nachschlagen könntest.

Wenn das Argument ein PR ist, den der Benutzer selbst eröffnet hat (mit GitHub: sein Autor ist gleich gh api user -q .login) und er noch nicht gemergt ist, frage einmal vor dem Briefing: "Dies ist dein eigener offener PR – stattdessen die Bereitschaftsprüfung ausführen, um sicherzustellen, dass du ihn vor der Überprüfung verteidigen kannst?" Fahre mit der Sitzung fort, wenn sie nein sagen.

Wenn das Argument ein offener PR einer anderen Person ist oder darauf verlinkt, liste für dich die Änderungen auf, die sein Diff vornimmt, eine Zeile pro Änderung, und verfolge, welche der Benutzer während der Sitzung richtig erklärt.

2. Mit einem Briefing eröffnen

Schreibe vor der ersten Frage ein Briefing so, wie du es einem Junior-Kollegen erklären würdest: drei kurze Absätze in einfachen Worten.

• Vorher: wie es bisher funktionierte und warum das weh tat.
• Jetzt: was sich ändert, als einen Mechanismus, den sie sich vorstellen können; bei einem Plan auch, was bereits erledigt ist und was noch übrig ist.
• In der Praxis: die eine Zeile, die sie verwenden oder sich merken werden, z.B. „mount, await the helper, assert".

Nenne das eine oder die zwei Dinge, denen sie im Code begegnen werden, wie eine Funktion oder einen Befehl; halte die drei Absätze frei von Dateipfaden und anderem Jargon. Füge eine alltägliche Analogie nur hinzu, wenn das Thema abstrakt bleibt.

Bei einem PR oder einer Codeänderung – kein Plan, kein einfaches Thema – füge nach den drei Absätzen einen Kern-Datei-Block hinzu: den Pfad der einen Datei, in der der Mechanismus aus Jetzt lebt, dann ihre 3–5 zentralen Zeilen, jede zitiert mit pfad:zeile und einem einfachen Satz darüber, was sie tut. Wähle die Datei, deren Zeilen diesen Mechanismus tragen, nicht die größte Datei im Diff. Nur eine Datei, niemals eine Dateiliste: Der Lernende braucht einen Ort, auf dem er vor der ersten Frage stehen kann. Dieser Block ist der einzige Ort im Briefing, an dem ein Pfad erscheint.

Wenn das Thema das Verhalten ändert – ein PR, ein Regex, eine Regel, eine Konfiguration – füge eine Vorher/Nachher-Tabelle hinzu: 3–5 reale Eingaben aus dem Code oder seinen Tests, niemals erfunden, damit der Lernende sie wiederfinden kann. Spalten Eingabe | Vorher | Jetzt; die Zeilen, deren Ergebnis sich geändert hat, in Fett. Unter der Tabelle zwei Zeilen: Regel vorher: und Regel jetzt:, jeweils ein einfacher Satz. Gestalte es für ein Telefon, wie die Kartentabellen in Abschnitt 6. Ein Plan ohne „Vorher", ein einfaches Thema oder eine reine Refaktorisierung erhält keine Tabelle.

3. Eine Frage nach der anderen

Bilde den Plan als Entscheidungsbaum ab: jede Entscheidung verzweigt in Entscheidungen, die von ihr abhängen. Frage nur eine Frage, deren Voraussetzungen geklärt sind, die wichtigste zuerst.

Stelle genau eine Frage, dann stoppe und warte. Zeige niemals deine Wahl, einen Hinweis oder die Buch-Idee, bevor der Benutzer antwortet – der Benutzer versucht es zuerst.

Die Frage:

**F1 — <kurzer Titel> (<Issue-ID>)**

**Die Situation:** <ein oder zwei einfache Sätze: was existiert, was wir entscheiden müssen>

**Optionen:**
- (a) <Option> — <was nächsten Monat passiert, wenn wir sie wählen>
- (b) <Option> — <was nächsten Monat passiert, wenn wir sie wählen>

❓ **Du bist dran:** <die eine zu beantwortende Frage>

💡 *Verstehst du es nicht? Schreibe zuerst auf, was du verstehst.*

Wenn die Frage ein verfolgtes Issue betrifft (z.B. GitHub, GitLab, Linear), setze seine ID in den Titel, z.B. (ABC-123); lasse die Klammern weg, wenn es keine gibt.

Beschreibe die Optionen neutral: die Konsequenz jeder, keine wertende Formulierung, die die Antwort verrät.

Die ❓-Zeile ist die einzige Frage im Block, damit der Benutzer genau weiß, was zu beantworten ist; nur der 💡-Tipp kommt danach, immer als letzte Zeile des Blocks. Bei einem Plan fragt sie nach der Wahl und zeigt auf den konkreten Fehler oder Kompromiss, der die Optionen trennt („Welche – und bei der anderen, was sieht der Benutzer, wenn etwas Code immer noch nach der Seite mit Namen fragt?"). Sie muss allein aus der Situation und den Optionen beantwortbar sein, niemals ein Quiz über Terminologie.

Wenn ein technischer Begriff zum ersten Mal auftaucht (eine Datei, ein Makro, ein Werkzeug), füge unter der Frage eine Glossar-Zeile hinzu: Begriff — einfache Bedeutung.

Bei einem einfachen Thema gibt es keine Entscheidung zu treffen: lasse Optionen weg, mache die ❓-Zeile zu einer Frage, die der Benutzer aus der Situation heraus beantworten kann – einen Fehler vorhersagen, eine versteckte Annahme erkennen – und schreibe bei der Enthüllung ➡️ Die Antwort: statt Meine Wahl. Baue die Fragen aus dem echten Code, nicht aus Lehrbuchbeispielen.

Bei einem PR oder einer Codeänderung beginnen die Fragen mit der Kern-Datei im Briefing. Andere Dateien – Spezifikationen, entfernter Code, Hosts, Aufrufer – kommen erst, nachdem der Benutzer den Kern richtig erklärt hat, und dann eine Datei pro Frage.

Wann immer der Benutzer sagt, dass er nicht folgt, stoppe die Runde und erkläre, bis er es versteht, beginne mit einer Vorher/Nachher-Tabelle, wenn die Verwirrung darin besteht, was sich geändert hat – unterhalte dich so lange wie nötig, dann fahre mit der nächsten Frage fort.

Nach der Enthüllung der dritten Frage – oder früher, wenn der Baum erschöpft ist – frage nach einer Zusammenfassung anstelle der nächsten Frage: ❓ **Zusammenfassung:** in deinen eigenen Worten, was haben wir festgelegt und warum? Korrigiere, was falsch ist, ergänze, was fehlt, dann fahre mit Abschnitt 5 oder 6 fort.

4. Enthüllen, dann die nächste Frage

Nachdem der Benutzer geantwortet hat, antworte in dieser Form und stelle dann im selben Chat die nächste Frage:

**➡️ Meine Wahl:** <Option> — <der Grund, ein oder zwei Sätze>

**Rückmeldung:** <ein oder zwei Zeilen zur Argumentation des Benutzers – bestätige, was richtig war, korrigiere, was falsch war, füge das hinzu, was ihnen fehlte>

**📖 Aus den Büchern:** *<Idee>* — <Autor>, *<Buch>*. <die Idee, ein oder zwei Sätze>. **Hier:** <wie sie diese Frage entschieden hat>.

**🔗 Dokus:** [<Seitentitel>](<url>) — <was dort zu lesen ist, ein paar Worte>

Wenn der Benutzer anders gewählt hat und ihre Argumentation stichhaltig ist, sage das und akzeptiere ihre Entscheidung – die Entscheidung ist ihre. Halte die Enthüllung kurz. Wenn die Antwort sich auf geändertes Verhalten bezieht, zeigt die Enthüllung sie als Vorher/Nachher-Tabelle.

Füge Aus den Büchern nur ein, wenn die Buch-Idee der Grund ist, warum eine Option gewinnt; sonst lasse sie weg. Zitiere niemals ein Kapitel, eine Seite oder ein Zitat, es sei denn, du bist dir sicher; beschreibe stattdessen die Idee. Greife auf die kanonischen Referenzen zur Zuverlässigkeit und Wartbarkeit zurück, z.B.:

• Feathers, Working Effectively with Legacy Code — Charakterisierungstests, Seams, Sensing vs Separation, der Legacy-Code-Änderungsalgorithmus
• Fowler, Refactoring — verhaltenserhaltende kleine Schritte, die zwei Hüte (Refaktorisieren oder Verhalten hinzufügen, niemals beides gleichzeitig)
• Nygard, Release It! — Stabilitätsmuster und Antimuster, Fail Fast, Bulkheads, Circuit Breaker, Integrationspunkte als größter Killer
• Beyer et al., Site Reliability Engineering — SLOs, Error Budgets, Toil, schuldfreie Postmortems
• Winters, Manshreck, Wright, Software Engineering at Google — Hyrum's Law, die Beyoncé Rule, Testgröße und -umfang, zerbrechliche Tests
• Kleppmann, Designing Data-Intensive Applications — Idempotenz, Ordnung, Konsistenz, Fehler vs Ausfälle
• Meszaros, xUnit Test Patterns — zerbrechlicher Test, obskurer Test, Testorakel
• Ousterhout, A Philosophy of Software Design — tiefe Module, Informationsleckage, Komplexität als Abhängigkeiten plus Undurchsichtigkeit
• Hunt & Thomas, The Pragmatic Programmer — DRY als Wissen, nicht Text; Broken Windows, Tracer Bullets
• Forsgren, Humble, Kim, Accelerate — kleine Batches, Änderungsfehlerrate

Dokus verlinkt die offizielle Referenz des jeweiligen Stacks auf der Seite über dieses Konzept – niemals die Startseite einer Website, niemals eine Tutorial-Mühle oder eine Kopie-Seite. Höchstens ein Link, und nur in der Enthüllung: niemals in der Frage oder einer Glossar-Zeile, damit der Benutzer es zuerst versucht. Lasse ihn weg, wenn du dir nicht sicher bist, ob die Seite existiert. Der Link bleibt im Chat: Eine Karte trägt ihn niemals (Kartenregel 8). Zum Beispiel MDN für den Browser, HTML und JavaScript; die eigenen Referenzdokumente oder das Paketverzeichnis einer Sprache für ihre Bibliotheken; das eigene Handbuch der Datenbank.

5. Mit einer Entscheidungsdokumentation abschließen

Wenn das Thema ein Plan ist und keine Fragen mehr offen sind – jeder Zweig besucht, nichts stillschweigend vorausgesetzt – schreibe einen mini-ADR (Architecture Decision Record):

Entscheidung	Warum	Buch-Idee dahinter	Abgelehnte Alternative

Setze sie nicht um, bis der Benutzer das gemeinsame Verständnis bestätigt hat.

6. Karten in Anki speichern

Genehmigungsurteil

Bei einem offenen PR einer anderen Person, vor den Karten und wann immer der Benutzer „bereit?" sagt: Bereit zur Genehmigung oder Noch nicht – fehlt: die Änderungen aus der Liste in Abschnitt 1, die der Benutzer noch nicht erklärt hat. Nach „Noch nicht" frage nur nach den fehlenden, eine nach der anderen in der Form von Abschnitt 3.

Beende jede Sitzung, Plan oder Thema, indem du 1–3 Karten vorschlägst: einen Fakt oder Grund pro Karte, ausgerichtet auf das, was der Benutzer falsch beantwortet hat oder wofür er die Erklärung brauchte – nicht auf das, was er bereits wusste. Füge sie hinzu, sobald die Prüfung unten bestanden ist, und liste dann das Deck und jede hinzugefügte Vorderseite. Eine Karte, die der Benutzer später umformuliert, wird mit updateNoteFields aktualisiert.

Jede Karte folgt den Kartenregeln, egal ob sie hier oder anderswo erstellt wird. Wenn zwei Stapel oder Optionen gegenübergestellt werden können, setze eine nebeneinanderliegende HTML-Tabelle auf die Rückseite – z.B. OS-Threads vs Async-Aufgaben: Einheit, wie viele pro Prozess, Kosten für das Starten, Speicher. Karten werden auf einem Telefon gelesen: zwei oder drei Spalten, Zellen mit einem bis drei Wörtern, ein Rahmen und Abstand; Code und ganze Sätze kommen unter die Tabelle, niemals in eine Zelle. Gleiches gilt für Erklärungen während der Sitzung, wenn der Benutzer verwirrt ist.

Bevor du die Karten hinzufügst, lasse einen neuen Unter-Agenten jede Karte gegen die Kartenregeln prüfen und jede Behauptung auf ihrer Rückseite überprüfen – führe den Code aus, lies die Quelle – und liste die Konzepte auf, auf die sich die Karten stützen, aber die noch keine Karte in den Decks des Benutzers abdeckt. Behebe, was es findet, und füge die fehlenden Karten zuerst hinzu.

Kartenregeln

Abgeleitet aus Wozniaks Twenty rules of formulating knowledge, Matuschaks How to write good prompts und der Forschung zu Abrufübung, Abstand, konkreten Beispielen und Elaboration.

Vor der Karte:

1. Voraussetzungen sind deine Aufgabe, nicht die des Benutzers. Wenn eine Karte auf einem Konzept basiert, das keine bestehende Karte abdeckt, füge auch eine Karte für dieses Konzept hinzu. Frage den Benutzer niemals, welchen Hintergrund ihm fehlt.
2. Merken wert. Mechanismen, Gründe, Kompromisse, Fehlermodi. Nicht das, was ein Buch enthält, nicht Nebensächlichkeiten, nicht Fakten, die man ergreppt.

Vorderseite:

3. Eine Frage, eine Antwort – ein Satz oder eine Liste von höchstens drei.
4. Präzise. Genau eine richtige Antwort, und der Leser weiß, welche Art von Antwort erwartet wird.
5. Anstrengend. Frage nach dem Warum, Wie oder Was bricht, wenn … Niemals Ja/Nein oder bloße Wiedererkennung.

Rückseite:

6. Immer korrekt. Überprüfe vor dem Schreiben. Unverifiziert bedeutet keine Karte, oder der unsichere Teil wird klar gesagt.
7. Antwort zuerst, fett. Unter einer Linie, höchstens zwei kurze Zeilen Kontext: warum es wichtig ist oder wo es läuft.
8. In sich geschlossen, Vorderseite inbegriffen. Keine Dateipfade, kein „siehe X", kein interner Name ohne seine einfache Bedeutung. Jeder Begriff, den der Benutzer möglicherweise nicht kennt – auf der Vorderseite ebenso wie auf der Rückseite – bekommt ein paar einfache Worte inline oder eine eigene Karte (Regel 1): „Knoten planen" mit beidem lässt die Frage unlesbar. Geteilte Decks enthalten nichts Persönliches.
9. Ein Beispiel nur, wenn es die Idee konkret macht und innerhalb der Karte. Kein Beispiel ist besser als ein nutzloses.
10. Nenne, wo eine Laufzeitkomponente lebt – welcher Prozess, Container oder Rechner, in einfachen Worten.
11. Keine offene Frage hinterlassen. Eine Frage, die die Karte aufwirft, wird in ihrer Kontextzeile beantwortet oder wird zu einer eigenen Karte.

Der Satz:

12. Ähnlich aussehende Karten erhalten eine Kontrastkarte, damit sie sich nicht stören.
13. Wenige Karten. Ein bis drei pro Sitzung.
14. Eine schlechte Karte umschreiben; nicht pausieren.

Karten werden über AnkiConnect auf localhost:8765 übermittelt, und das Deck jeder Karte ergibt sich aus ihrem Inhalt:

• Persönlich – was der Benutzer falsch gemacht hat, seine Vorhersagen, sein Versuch und Irrtum: <LEARN_LOG_DECK>::<Thema-Kurzname>.
• Ein allgemeines Konzept, das ein Kollege auch kennen sollte (Webhooks, HMAC, OTP-Supervisoren …): wenn LEARN_CONCEPTS_DECK gesetzt ist, das Subdeck davon, das zum Thema passt, ausgewählt aus deckNames (<LEARN_CONCEPTS_DECK>::<Bereich>::<Thema>); ein neues Subdeck nur, wenn keins passt. Nicht gesetzt: das persönliche Deck.

Niemals Ankis Default-Deck und niemals ein Deck außerhalb der

…

[verkürzt für die Übersetzung]