jhincapie/egm-cursor

EGM Drift Report: Was das Dokument sagte vs. was gebaut wurde

/egm-implement baut aus dem Designdokument und protokolliert Abweichungen in IMPLEMENT.md, während es passiert. Manche Abweichungen schlüpfen dennoch durch: eine Änderung, die die Sitzung als zu klein zum Protokollieren ansah, eine spätere Korrektur, eine Schnittstelle, die sich mit echten Aufrufern anders eingependelt hat. Dieses Skill misst die Lücke im Nachhinein und schreibt sie auf, sodass der Benutzer später sagen kann "Aktualisiere das Designdokument entsprechend" und das Dokument wieder zur Quelle der Wahrheit wird.

Aufruf als /egm-drift-report [pfad-zum-designdokument].

EGM-Operationsreflexe (gemeinsame Präambel)

Jedes Skill dieser Suite trägt diese vier Reflexe in sich, da nicht jede Oberfläche eine globale CLAUDE.md lädt. Sie stammen aus dem Elephant-Goldfish-Artikel und gelten für die gesamte Sitzung, nicht nur während dieses Skills läuft.

1. Design ist der neue Code. Für jede nicht-triviale Funktion oder Änderung ein Designdokument erstellen, bevor Code geschrieben wird. Wenn das Design nicht klar genug ist, dass der Code sich selbst schreiben sollte, zuerst designen (/egm-design).
2. Speichelleckerei verweigern. Ihre Aufgabe ist es, das Denken des Benutzers herauszufordern; Zustimmung allein hilft ihm nicht. Wenn Sie im Begriff sind "guter Punkt" oder "Sie haben völlig recht" zu sagen, halten Sie inne und suchen Sie stattdessen nach dem, was falsch ist. Wenn der Benutzer sagt "Sie sind nicht hilfreich" (der EGM-Reset), behandeln Sie es als Zeichen, dass Sie zu viel zugestimmt haben, und gehen Sie zurück zum Finden von Lücken.
3. KI schlägt zuerst vor. Lassen Sie den Benutzer niemals ein Design, Framework oder Bewertungsschema mit seinem eigenen ersten Entwurf säen. Sie schlagen zuerst vor, in Prosa und Blockdiagrammen; der Benutzer reagiert und argumentiert.
4. Artefakte speichern. Das Triple aus Beschreibung + Kriterien + Ausgabe dauerhaft speichern: docs/designs/<slug>.md, die Journale in docs/egm/<slug>/, PEANUTS.md im Quellverzeichnis und das /egm-decide-Triple an seinem oberflächenzugeordneten Ort, wo dieses Skill installiert ist. Das Chat-Transkript ist nicht das Artefakt.

Harte Regeln: Diese nicht brechen

1. Schreibgeschützt. Die einzige Datei, die dieses Skill schreibt, ist docs/egm/<slug>/DRIFT-REPORT.md. Bearbeiten Sie niemals das Designdokument, den Code, Tests oder andere Journale (IMPLEMENT.md, GOLDFISH.md, ELEPHANT.md). Das Anwenden der vorgeschlagenen Aktualisierungen ist eine separate Anfrage, die der Benutzer später stellt.
2. Beweis oder es ist keine Abweichung. Jeder Punkt zitiert, was das Dokument sagt (Abschnitt und kurzes Zitat) und was gebaut wurde (Pfad:Zeile, oder ein Commit, oder "keine solche Datei"). Ein Punkt ohne Beweise auf beiden Seiten ist eine offene Frage und wird als solche aufgeführt.
3. Der Code ist die beobachtete Tatsache; das Dokument ist die Behauptung. Melden Sie die Differenz neutral. Entscheiden Sie nicht, welche richtig ist, es sei denn, ein Journal dokumentiert die Entscheidung; der vorgeschlagene Aktualisierung ist ein Vorschlag, kein Urteil.
4. Frische Augen führen den Vergleich durch. Die Sitzung, die das Feature implementiert hat, ist voreingenommen, ihre eigene Absicht in den Code hineinzulesen. Übergeben Sie den Vergleich einem frischen, schreibgeschützten Subagenten (Schritt 3), wann immer einer verfügbar ist.

Arbeitsablauf

EGM Drift Report Fortschritt:
- [ ] Schritt 1: Designdokument und Slug aufgelöst; docs/egm/<slug>/ gefunden
- [ ] Schritt 2: Basis-Commit gewählt; Beweispaket-Pfade aufgelistet
- [ ] Schritt 3: Vergleich von einem frischen, schreibgeschützten Subagenten durchgeführt (oder inline, vermerkt)
- [ ] Schritt 4: Ergebnisse geprüft, klassifiziert und in DRIFT-REPORT.md geschrieben
- [ ] Schritt 5: Benutzer informiert, wo der Bericht ist und dass er bitten kann, die Aktualisierungen anzuwenden

Schritt 1: Designdokument auflösen

Bevorzugen Sie das Argument des Benutzers. Suchen Sie andernfalls in dem Ordner, der durch design_doc_path: in der AGENTS.md oder CLAUDE.md des Projekts benannt ist, und andernfalls in docs/designs/*.md. Wenn genau ein Dokument existiert, verwenden Sie es; wenn mehrere, listen Sie sie auf und fragen Sie, welches. Der Slug ist der Dateiname des Dokuments ohne .md, und das Statusverzeichnis ist docs/egm/<slug>/. Wenn dieses Verzeichnis nicht existiert, durchlief das Feature nie /egm-design; sagen Sie das und bieten Sie an, den Bericht trotzdem dort zu schreiben (nur docs/egm/<slug>/DRIFT-REPORT.md erstellend).

Schritt 2: Basis wählen und Beweispaket sammeln

Die Basis ist der Punkt, an dem das Dokument genehmigt wurde. Wählen Sie die erste zutreffende Option und notieren Sie, welche Sie verwendet haben:

1. Der Commit, der human_review_gate: passed (oder skipped-solo) in docs/egm/<slug>/GOLDFISH.md gesetzt hat: git log --format='%H %ad %s' --date=short -- docs/egm/<slug>/GOLDFISH.md.
2. Der letzte Commit, der das Designdokument am oder vor dem start_date in IMPLEMENT.md berührt hat: git log --format='%H %ad %s' --date=short -- <doc>.
3. Fragen Sie den Benutzer nach einem Commit oder Datum.

Listen Sie dann, ohne zusammenzufassen, die Beweise auf, die der Vergleich lesen wird:

• das Designdokument (bei HEAD und bei der Basis, falls es sich seitdem geändert hat: git show <base>:<doc>);
• docs/egm/<slug>/IMPLEMENT.md, insbesondere ## Berührte Dateien, jeden ## Abweichung-Eintrag (offen und gelöst) und ## Verifikation;
• GOLDFISH.md-Verfügungsnotizen, wo sie eine Dokumentenänderung festhalten;
• git log --stat <base>..HEAD und git diff --stat <base>..HEAD, plus unbestätigte Änderungen von git status und git diff;
• die Dateien, die die detaillierte Implementierung des Dokuments auflistet, und die Dateien, die der Diff berührt hat, die das Dokument nicht nennt.

Nicht im Paket: dieser Chat, ELEPHANT.md-Designbegründungen oder Ihre eigene Erinnerung, warum etwas getan wurde. Diese gehören nur dann in die Spalte "wahrscheinlicher Grund", wenn ein Journal es sagt.

Schritt 3: Vergleich in einer frischen, schreibgeschützten Sitzung durchführen

Starten Sie in Cursor einen Task-Subagenten vom Typ drift-auditor (installiert unter ~/.cursor/agents/drift-auditor.md, readonly: true). Wenn er nicht installiert ist, verwenden Sie einen generischen Task-Subagenten und teilen Sie ihm mit, dass er schreibgeschützt ist. Senden Sie die Eingabeaufforderung in assets/drift-auditor-prompt.md mit ausgefülltem Dokumentpfad, Slug, Basis und Beweisliste. Fügen Sie nichts hinzu: keine Zusammenfassung der Implementierung, keine Erklärung, warum sich Dinge geändert haben.

Wenn keine Subagenten-Laufzeitumgebung existiert, führen Sie den Vergleich inline durch, indem Sie derselben Eingabeaufforderung selbst folgen, und notieren Sie comparison: inline (no fresh subagent available) im Berichtskopf, damit der Leser weiß, dass er nicht unabhängig war.

Schritt 4: Prüfen, klassifizieren und Bericht schreiben

Prüfen Sie jeden zurückgegebenen Punkt, bevor Sie ihn schreiben: Öffnen Sie das zitierte Pfad:Zeile und den zitierten Dokumentabschnitt, und entfernen oder korrigieren Sie alles, was die Beweise nicht stützen. Verwenden Sie die Kategorien aus der Vorlage: changed-approach, added, not-built, renamed-or-moved, interface-change, data-model-change, behavior-change, new-dependency, constraint-discovered, alternative-switched. Schweregrad ist major (das Dokument würde einen Leser darüber irreführen, wie das System funktioniert), minor (ein Detail ist falsch) oder cosmetic (Benennung, Wortlaut).

Querverweis mit IMPLEMENT.md: Markieren Sie jeden Punkt als logged (ein Abweichungseintrag existiert, mit seinem Status) oder unlogged. Nicht protokollierte Hauptpunkte sind die Schlagzeile.

Schreiben Sie docs/egm/<slug>/DRIFT-REPORT.md aus assets/drift-report-template.md. Wenn die Datei bereits existiert, setzen Sie den neuen datierten Bericht oben unter dem Dateikopf und verschieben Sie die vorherigen Berichte unverändert unter ## Frühere Berichte. Überschreiben Sie niemals einen früheren Bericht.

Wenn es keine Abweichung gibt, schreiben Sie den Bericht dennoch mit drift_items: 0, der verwendeten Basis und dem, was verglichen wurde, sodass "keine Abweichung" ein dokumentiertes Ergebnis und keine Abwesenheit ist.

Schritt 5: Rückgabe an den Benutzer

Teilen Sie dem Benutzer in dieser Form mit:

Abweichungsbericht geschrieben nach docs/egm/<slug>/DRIFT-REPORT.md: Punkte ( major, nicht in IMPLEMENT.md protokolliert). Ich habe das Designdokument oder den Code nicht geändert. Wenn Sie möchten, dass das Dokument dem entspricht, was gebaut wurde, bitten Sie mich, die vorgeschlagenen Dokumentenaktualisierungen aus dem Bericht anzuwenden; Punkte, die den Technischen Plan ändern, sollten zurück zu /egm-design, und eine große Umschreibung zu /egm-review.

Wenden Sie die Aktualisierungen in dieser Sitzung nicht an, es sei denn, der Benutzer bittet darum, nachdem er den Bericht gesehen hat.

Anti-Patterns

• Das Dokument während der Berichterstattung korrigieren. Der Bericht ist das Ergebnis. Das Bearbeiten des Dokuments vermischt Messung mit Änderung und verbirgt, was die Abweichung war.
• Den Code korrigieren, um dem Dokument zu entsprechen. Gleiches Problem in die andere Richtung. Der Benutzer entscheidet, welche Seite sich bewegt.
• Abweichung aus dem Gedächtnis erklären. "Wir haben das geändert wegen X" ohne eine Journalzeile ist eine Vermutung; schreiben Sie reason: unknown und lassen Sie den Benutzer es ausfüllen.
• Den Diff zusammenfassen statt vergleichen. Eine Liste geänderter Dateien ist kein Abweichungsbericht. Jeder Punkt verbindet eine Dokumentbehauptung mit einer beobachteten Tatsache.
• Die frische Sitzung überspringen, um Zeit zu sparen. Die implementierende Sitzung glaubt bereits, dass der Code dem Dokument entspricht. Dieser Glaube ist es, den dieses Skill zu testen existiert.

Wo dieses Skill in EGM sitzt

/egm-learn (nur Legacy-Code) → /egm-design → /egm-review → /egm-implement → /egm-code-review, mit /egm-drift-report jederzeit nach /egm-implement (vor oder nach dem Code-Review).

• Liest: das Designdokument, IMPLEMENT.md, GOLDFISH.md, Git-Verlauf seit der Basis und den Code.
• Schreibt: ausschließlich docs/egm/<slug>/DRIFT-REPORT.md.
• Speist: eine spätere "Aktualisiere das Designdokument aus dem Abweichungsbericht"-Anfrage; /egm-design für Änderungen des Technischen Plans; /egm-review, wenn das aktualisierte Dokument erneut validiert werden muss.