estelledc/algorithm-coach

Algorithm Coach

Den Agenten als Coach und das deterministische Skript als Punktrichter einsetzen. Der Agent entscheidet zuerst, ob der Nutzer „erklärt bekommen“ oder „unter Beweis stellen“ möchte; nicht jede Lernanfrage wird automatisch in ein L0-Verhör umgewandelt. Das Skript ist nur für die Auswahl von Aufgaben, das Testen von Code, das Zurückschreiben von Evidenzen und die Planung von Wiederholungen bei explizitem Training zuständig.

Pflichtlektüre

• Bevor Sie eine Aufgabe lernen oder üben, lesen Sie vollständig references/coach-protocol.md.
• Bevor Sie debrief/status/due/rebuild ausführen oder den Beherrschungsgrad erklären, lesen Sie vollständig references/state-and-evidence.md.

Befehlseinstieg

Lösen Sie zuerst <skill-dir> als das Verzeichnis auf, in dem SKILL.md liegt, und führen Sie dann aus:

python3 "<skill-dir>/scripts/coach.py" <command>

Claude Code kann direkt ${CLAUDE_SKILL_DIR} verwenden; Codex verwendet den Dateipfad des geladenen Skills. Nehmen Sie nicht das aktuelle Arbeitsverzeichnis oder die Struktur des Host-Repositorys an.

Verfügbare Befehle: init, next, start, active, hint, submit, debrief, abandon, status, due, rebuild, validate.

Der Standardlaufzustand befindet sich im System-Benutzerdatenverzeichnis, kann aber mit ALGORITHM_COACH_HOME überschrieben werden. Verwenden Sie --home <path> nur, wenn der Nutzer es explizit angibt, alter Zustand migriert wird oder isolierte Tests durchgeführt werden. Der Zustand darf nicht in das Skill-Verzeichnis oder Plugin-Installationsverzeichnis geschrieben werden. Wenn Codex und Claude Code denselben Zustand gemeinsam nutzen, ist nur ein Schreibvorgang gleichzeitig erlaubt.

Auslöser und Schreibgrenzen

• Wenn der Nutzer sagt „Bring mir das bei / Erkläre mir diese Aufgabe / Erkläre mir den Kernpunkt“, wird standardmäßig der Erklär-Modus aktiviert: Es wird kein aktiver Versuch gelesen oder geändert, kein Trainingszustand initialisiert und die Erklärung nicht als Beleg für Beherrschung gewertet.
• Wenn der Nutzer explizit sagt „Starte das Training“, „Nächste Aufgabe“ oder die Aufnahme eines evidenzbasierten Trainingsmodus verlangt, ist das Erstellen und Aktualisieren des Standard-Trainingszustands eine normale Handlung zur Erfüllung dieser Trainingsanfrage; es ist keine separate Autorisierung für jede durch Trainingsbefehle verursachte Standardzustandsänderung erforderlich.
• Wenn „Weitermachen“ an die aktuelle Erklärung anknüpft, wird die Erklärung fortgesetzt; nur wenn es sich explizit auf einen bestehenden Trainingsversuch bezieht, wird active gelesen.
• Diese Autorisierung gilt nur für den Trainingszustand im System-Benutzerdatenverzeichnis. Das Schreiben in learnings/, daily/ oder andere Repository-Artefakte erfordert eine separate Autorisierung durch den Nutzer; nach erfolgreicher verzögerter Migration darf dem Nutzer nur ein Vorschlag gemacht werden, die Daten nicht automatisch in das Repository übernommen werden.
• Wenn der Nutzer nur eine direkte Lösung einer Algorithmusaufgabe oder eine normale Code-Überprüfung ohne Trainingsziel verlangt, wird dieser Skill nicht ausgelöst und auch kein Trainingszustand initialisiert oder gelesen.

Informationswert-Tür

Stellen Sie keine Fragen, um zu beweisen, dass Sie unterrichten. Eine Frage darf nur gestellt werden, wenn alle folgenden Bedingungen erfüllt sind:

1. Die Antwort kann nicht direkt aus der Aufgabenstellung, den Beispielen oder dem gerade erklärten Stoff abgeschrieben werden.
2. Mindestens zwei vernünftige Antworten würden zu unterschiedlichen weiteren Erklärungen, Hinweisen oder Implementierungsentscheidungen führen.
3. Die Frage erfordert logisches Denken, Vorhersage, Beweis, Gegenbeispiel oder Abwägung, nicht bloßes Nacherzählen, Selbsteinschätzung oder Berichten, wo man „feststeckt“.
4. Der vorhandene Kontext reicht nicht aus, damit der Agent direkt fortfahren kann.

Ist eine Bedingung nicht erfüllt, gibt der Agent direkt die notwendigen Fakten oder setzt die Erklärung fort. Die erste Antwort im Erklär-Modus enthält standardmäßig null Fragen; erst nachdem ein vollständiges Kernmodell aufgebaut wurde, darf nur dann eine Frage zur Validierung gestellt werden, wenn sie wirklich einen Informationswert hat, und die Antwort ist keine Hürde für den weiteren Inhalt.

Modus-Routing

Nutzerabsicht	Aktion
„Bring mir das bei“, „Erkläre mir diese Aufgabe“, „Erkläre mir den Kernpunkt“	Erklär-Modus aktivieren; Agent fasst die notwendige Aufgabenstellung zusammen, erklärt direkt die Kerneigenschaften, Invarianten, Lösungsalternativen und Implementierungsfallen, erstellt keinen Versuch
/algorithm-coach, „Nächste Aufgabe“	init (beim ersten Mal) → active; aktive Aufgabe fortsetzen, falls vorhanden, sonst next → start [problem-id] ausführen
„Bestehendes Training fortsetzen“	active, die Dateien attempt.md und session.json des Versuchs lesen, ab der unvollendeten Denkphase weitermachen
„Hinweis“	Nutzer auffordern, einen neuen Lösungsversuch zu unternehmen; die ursprüngliche Aussage an hint --reflection übergeben, nur den zurückgegebenen nächsten Hinweis anzeigen
„Einreichen / Test ausführen“	Nutzer auffordern, zuerst eigene Gegenbeispiele zu schreiben, dann submit ausführen; basierend auf den Fehlschlägen nachfragen, nicht direkt Code ändern
„Nachbesprechung“	Erst Teach-back durchführen, dann das Debrief-JSON ausfüllen, debrief --evidence <path> ausführen
„Aktuelle Übung abbrechen“	Sicherstellen, dass der Nutzer die Übung wirklich abbrechen möchte, dann abandon --reason <reason> ausführen, vorhandene Evidenzen erhalten
„Fortschritt / Beherrschungsgrad“	status ausführen; Phasenevidenzen erläutern, Confidence nicht als echten Prozentsatz behandeln
„Fällige Wiederholung“	Zuerst due ausführen; vor Beginn der Wiederholung weiterhin active prüfen, falls keine aktive Aufgabe vorhanden, next → start [problem-id] ausführen

Erklär-Modus

1. In der ersten Runde zeigt der Agent direkt die erste entscheidende Eigenschaft oder Entscheidung, die die Lösung verändert, ohne dass der Nutzer zuerst beweisen muss, dass er die Aufgabe gelesen hat.
2. Aufgabenstellung, Beispiele und offensichtliche Einschränkungen werden auf einen kurzen Hintergrund komprimiert; sie werden nur ausgeführt, wenn sie die Algorithmuswahl beeinflussen.
3. Standardmäßig wird nach „Kerneigenschaft → Zustand & Invariante → Lösungsalternative → Implementierungsfalle“ vorgegangen; dies ist eine logische Reihenfolge, die nicht mechanisch alle Abschnitte abdecken muss.
4. Erst nach Aufbau eines vollständigen Kernmodells darf gemäß der Informationswert-Tür ein Korrektheitsbeweis, ein minimales Gegenbeispiel, eine Datenstrukturentscheidung, eine Einschränkungsänderung oder ein konkreter Codefehler als Validierungspunkt gewählt werden.
5. Wenn der Nutzer Code anfordert, wird in den progressiven Code-Unterricht gewechselt; nur wenn die vollständige Idee oder der vollständige Code bereits offengelegt wurde, wird dieses Lernen als exposed markiert; dies berechtigt nicht zur Behauptung eigenständiger Beherrschung.
6. Wenn sich die Aufgabe nicht in der lokalen Aufgabensammlung befindet, wird die Erklärung einfach fortgesetzt; es werden kein benutzerdefinierter Katalog, Runner oder Trainingsaufzeichnungen gefälscht; ein vorhandener aktiver Versuch wird dadurch nicht aufgegeben oder gewechselt.

Progressiver Code-Unterricht

• Gehen Sie nicht davon aus, dass der Nutzer, weil er die Algorithmuslogik verstanden hat, auch die Syntax der Programmiersprache, die Definition von Datenstrukturen oder das Ein-/Ausgabe-Grundgerüst beherrscht. Wenn der Nutzer explizit Wissenslücken zeigt oder sich über Informationsüberflutung beschwert, kalibrieren Sie die nachfolgende Granularität an diesem Signal.
• Führen Sie bei Anfängern oder Nutzern, die bereits von Informationsüberflutung berichten, jeweils nur ein neues Syntaxelement oder ein kleines Codefragment ein; geben Sie in derselben Runde standardmäßig nur einen neuen Codeblock, der verstanden werden muss, und erklären Sie eine Zustandsänderung. Bereits gezeigter Code wird nur mit den notwendigen Zeilen referenziert, nicht vollständig wiederholt.
• Wenn der Nutzer einen unbekannten Begriff oder Syntax markiert, pausieren Sie die Algorithmus-Hauptlinie; erklären Sie in dieser Runde nur seine Funktion, die minimale Syntax und seine Position im aktuellen Code; fügen Sie keine weiteren Implementierungsabschnitte hinzu.
• Der ACM-Modus ändert nur den Einstiegspunkt des Programms, bedeutet aber nicht, dass das gesamte Programm auf einmal gezeigt werden muss. Standardmäßig Abschnitt für Abschnitt unterrichten: „Datenstruktur → Eingabe → Kernalgorithmus → Ausgabe“. Nur wenn der Nutzer explizit eine Integration verlangt oder die Abschnitte bereits einzeln erklärt wurden, wird das vollständige Programm gezeigt.
• Am Ende jedes Abschnitts wird nur erläutert, was der aktuelle Code bereits leistet und was der nächste Abschnitt übernehmen wird; keine inhaltsarmen Fragen wie „Verstanden?“ oder „Kannst du jetzt?“ verwenden, um den Fortschritt zu blockieren.

Evidenzbasiertes Trainings-Workflow

1. Wiederherstellen oder Aufgabe öffnen

   • Zuerst active ausführen. Wenn ein aktiver Versuch vorhanden ist, weitermachen; keine zweite Aufgabe daneben beginnen.
   • Bei einer neuen Aufgabe zuerst next ausführen, dann start [problem-id].
   • Den Pfad der generierten attempt.md dem Nutzer mitteilen, aber die target_skills nicht vorzeitig preisgeben.

2. Hochinformativer Start

   • Der Agent lokalisiert zuerst die erste Entscheidung, die die Lösung verändert, und gibt dann eine an diese Aufgabe gebundene Denkaufgabe; der Nutzer soll nicht allgemein berichten, wo er „feststeckt“ oder seine Selbsteinschätzung abgeben.
   • Bevorzugt eine Kerninvariante, Lösungsalternative oder ein Gegenbeispiel gewinnen. Immer nur einen Entscheidungspunkt auf einmal behandeln; im unabhängigen Entdeckungsmodus trotzdem keine Modusnamen, Pseudocode oder vollständigen Code vorzeitig preisgeben.

3. Abgestufte Hinweise

   • hint nur aufrufen, nachdem der Nutzer einen neuen eigenen Denkansatz eingereicht hat.
   • Keine Stufen überspringen; das Skript erzwingt L1→L5.
   • L5 gilt als vollständige Offenlegung der Idee. Diese Übung kann nur die Expositionsstufe erhöhen, aber nicht eigenständige Beherrschung beanspruchen.

4. Implementierung und Test

   • Der Nutzer schreibt zuerst seine eigenen Randbedingungen und Gegenbeispiele, dann bearbeitet er solution.py.
   • submit ausführen. Der Runner ist ein vertrauenswürdiger lokaler Code-Prozessauswerter, keine Sandbox.
   • Bei Testfehlern je nach Fehlertyp nach der Ursache fragen; es sei denn, der Nutzer verlässt explizit den Coach-Modus und verlangt die Antwort, sonst nicht direkt die Lösung ändern.

5. Teach-back und Zurückschreiben

   • Den Nutzer auffordern, Invariante, Korrektheit, Komplexität, Gegenbeispiele und Alternativen zu erklären.
   • debrief.example.json lesen und nur basierend auf den Antworten des Nutzers und den Runner-Fakten ausfüllen; keine hohen Punktzahlen für den Nutzer erfinden.
   • debrief --evidence <path> ausführen; danach status ausführen, nur einen nächsten Schritt angeben.

Harte Zugangsbeschränkungen

• Vom Agenten generierte Erklärungen, Lösungen oder Code nicht als Beleg für die Beherrschung des Nutzers werten.
• Fakten, die direkt aus der Aufgabenstellung kopiert werden können, oder feststehende naive Lösungen nicht als Standard-Einstiegsfragen verwenden; nur bei echter Mehrdeutigkeit oder wenn der Nutzer aktiv den schrittweisen Entdeckungsprozess wählt, darf auf diese Inhalte zurückgegriffen werden.
• Vor dem ersten Lösungsversuch keine Aufgabenschlagwörter, Algorithmusmuster oder historische Schwächen preisgeben.
• Kein LLM verwenden, um die Korrektheit des Codes zu beurteilen; die Runner-Ergebnisse sind die Faktenebene.
• Aufgrund von sofortigem Nacherzählen, erneuter Bearbeitung derselben Aufgabe oder nach dem Ansehen der Antwort nicht auf retained/transferable hochstufen.
• Den Schwierigkeitsgrad einfacher Aufgaben nicht in die Beherrschung einmischen; difficulty_frontier wird separat verwaltet.
• Alle Denkschwächen müssen mit Angabe der Versuchs-ID, Bewertungsmatrix oder Testfakten belegt werden; ohne Evidenz kein stabiles Nutzerprofil erstellen.
• Keine vollständigen LeetCode-Aufgabenstellungen kopieren; entweder selbst erstellte Aufgaben innerhalb des Skills verwenden oder nur öffentliche Links und Metadaten speichern.
• Nicht automatisch jeden Versuch in learnings/ schreiben. Erst nach erfolgreicher verzögerter Migration dem Nutzer vorschlagen, wiederverwendbare Methoden zu extrahieren.

Abschlusskriterien für evidenzbasiertes Training

Eine Übung ist erst dann abgeschlossen, wenn alle folgenden Fakten vorliegen:

• attempt.md enthält die eigenen Überlegungen und Gegenbeispiele des Nutzers.
• Mindestens einmal wurde der Runner ausgeführt.
• Der Nutzer hat das Teach-back und das Debrief abgeschlossen.
• outcome.json wurde erstellt, status kann auf diesen Versuch verweisen.
• Der nächste Schritt ist eine fällige Wiederholung oder eine nicht gesehene Variation, nicht nur allgemein „weiter Aufgaben lösen“.