chrislacey89/compound

Was macht compound?

Dokumentieren Sie ein kürzlich gelöstes Problem oder eine ausgelieferte Funktion, um das Wissen Ihres Projekts zu verdichten. Jede dokumentierte Lösung macht zukünftige Planung und Implementierung schneller – der Agent konsultiert docs/solutions/ während /research und /write-a-prd, sodass heute gelernte Lektionen Morgen Fehler vermeiden.

Wenn die Arbeit Überraschungen bei der Planung oder Schätzung zutage gefördert hat, erfassen Sie auch diese. McConnell-artige Kalibrierung funktioniert nur, wenn die tatsächliche Arbeit in die zukünftige Modellierung zurückfließt.

Aufrufposition

Dies ist ein primäres Pipeline-Skill, das den Compoundierungs-Kreislauf schließt. Es läuft nahe dem Ende des standardmäßigen Auslieferungspfads, nachdem /pre-merge den PR erstellt hat.

Standard – Lektion im PR vor dem Merge erfassen. Wenn eine dauerhafte Lektion zum Zeitpunkt des PR bereits bekannt ist, führen Sie /compound auf dem offenen PR-Zweig aus, sodass der docs/solutions/-Eintrag denselben PR wie der Code begleitet, der die Lektion hervorgebracht hat – vor demselben Merge geprüft und atomar mit diesem gemergt. Dies platziert /compound zwischen /pre-merge und /closeout und kehrt einmal über /pre-merge zurück:

… → /pre-merge → /compound (in-PR, wenn eine Lektion existiert) → /pre-merge (erneut ausführen: der Compound-Commit ist das Post-Stamp-Delta; stampelt neu) → /closeout (Merge + Teardown) → cleanup

Das Rückbeinschritt ist nicht dekorativ. Das Committen auf den Branch verschiebt den HEAD über den Stamp, den /pre-merge Phase 4 geschrieben hat, und /pre-merge ist der einzige Schreiber des Stamps – ohne den erneuten Lauf wird der Eintrag mit dem Code gemergt und von niemandem gelesen, genau das, was der In-PR-Standard vermeiden sollte. Phase 5 beschreibt die Übergabe; deshalb existiert sie.

Fallback – nach dem Merge erfassen. Manche Lektionen werden erst während oder nach dem Merge sichtbar: Integrationsüberraschungen, QA-Erkenntnisse, Verhalten, das erst nach der Auslieferung sichtbar wird. Für diese führen Sie /compound nach /closeout aus, nachdem gemergt wurde. Dies ist der Fallback-Pfad, nicht der Standard.

In beiden Fällen führt /compound niemals den Merge oder Worktree-Teardown selbst durch – das ist /closeout – und schreibt niemals den Review-Currency-Stamp, der /pre-merge allein gehört. Das Erfassen im PR bedeutet, auf den offenen PR-Zweig zu committen und zur Prüfung zurückzugeben; es bedeutet nicht, zu mergen.

Verwenden Sie es nicht für triviale Änderungen oder für Lektionen, die vollständig in einem höherwertigen Artefakt wie einem Test, einer Linter-Regel oder einem Code-Kommentar ohne dauerhaften Projekterkenntnisgewinn erfasst werden können. Ob im PR oder nach dem Merge, die „Wann NICHT verwenden“-Regel unten gilt weiterhin – die meisten PRs enthalten keine dauerhafte Lektion, und es gibt keinen festen docs/solutions/-Platz pro PR.

Warum dies existiert

Ohne diesen Schritt haben Sie traditionelles Engineering mit KI-Unterstützung durchgeführt. Die ersten drei Schritte des Workflows (Planen, Arbeiten, Prüfen) produzieren eine Funktion. Dieser vierte Schritt produziert ein System, das Funktionen jedes Mal besser baut.

Wann verwenden

• Wenn der PR einer Funktion bereit ist und er eine dauerhafte Lektion gelehrt hat – erfassen Sie sie auf dem PR vor dem Merge (der glückliche Pfad)
• Nach der Auslieferung, wenn eine Lektion erst während oder nach dem Merge klar wurde (der Post-Merge-Fallback)
• Nach der Behebung eines kniffligen Bugs, bei dem die Ursache nicht offensichtlich war
• Nach einem QA-Zyklus, der Probleme aufgedeckt hat, die früher hätten erkannt werden können
• Nach einer Architekturentscheidung mit signifikanten Kompromissen
• Wenn Sie ein Muster entdeckt haben, das wiederverwendet werden sollte

Wann NICHT verwenden

• Für triviale Korrekturen (Tippfehler-Korrekturen, einfache Konfigurationsänderungen)
• Wenn die Lösung bereits gut in offiziellen Bibliotheksdokumentationen dokumentiert ist
• Wenn die Lektion projektspezifisch ist, aber Sie im Begriff sind, diesen Code zu deprecated
• Wenn die Arbeit eine saubere Ausführung eines vorgeformten Plans war – keine Überraschungen, keine Nacharbeit, keine nicht offensichtlichen Entscheidungen. Der Issue-Text und die PR-Beschreibung enthalten diese Aufzeichnung bereits; ein docs/solutions/-Eintrag ohne wiederverwendbare Lektion trainiert zukünftige Leser, zu überfliegen
• Im Zweifelsfall – das Überspringen kostet nichts, da der Issue und der PR in GitHub bestehen bleiben. Das Erfassen einer minderwertigen Lektion kostet die Aufmerksamkeit zukünftiger Planer jedes Mal, wenn sie docs/solutions/ konsultieren

Ausführungsablauf

Phase 1: Identifizieren, was zu erfassen ist

Auf dem In-PR-Standardpfad ist die zu prüfende Arbeit der offene PR-Zweig, daher lesen die folgenden Befehle ihn direkt – ein git log und ein git diff des Zweigs gegen die Basis, in die er gemergt wird, während er noch ungemergt ist. Auf dem Post-Merge-Fallback-Pfad führen Sie sie in einer Sitzung aus, die noch die Historie der gemergten Funktion sehen kann – sobald /closeout den Branch entfernt und die Basis gezogen hat, ist dieser Diff leer, und Sie müssen stattdessen den PR-Diff über gh pr diff <n> lesen. Prüfen Sie in beiden Fällen die aktuelle Arbeit.

Lösen Sie zuerst die Basis auf. Harten Sie main nicht fest – dieses Repository selbst verwendet prod, und ein Name ist kein Ref: in einem Worktree-Workflow checkt niemand den Basis-Zweig aus, daher ist der lokale Branch bei dem Stand eingefroren, als der Checkout erstellt wurde, während origin/<base> sich weiterbewegt. Fragen Sie sidecar.sh base-ref; leiten Sie die Basis nicht ab.

SC="<this skill's directory>/references/sidecar.sh"
BASE_REF="$(bash "$SC" base-ref)" || { echo "base-ref failed: not guessing a base" >&2; exit 1; }
git log --oneline "$BASE_REF..HEAD"
git diff --stat "$BASE_REF...HEAD"

Prüfen Sie:

1. Git-Log – Welche Commits wurden gemacht? Was hat sich geändert? Basis-relativ, nicht -20: eine feste Anzahl liest die eigene Historie der Basis als „die zu prüfende Arbeit“ auf jedem kürzeren Branch. Zwei Punkte sind hier korrekt – dies sind die Commits auf diesem Branch und nicht auf der Basis. (Das git diff hat drei Punkte aus dem spiegelbildlichen Grund: es diffed vom Merge-Basis aus, anstatt Basis-seitige Arbeit zu subtrahieren.) Auf dem Post-Merge-Fallback-Pfad ist der Branch verschwunden, verwenden Sie daher gh pr diff <n> wie oben.

2. Issue-Thread – Was war das ursprüngliche Problem? Was wurde diskutiert?

3. Der Diff – Welche Dateien haben sich geändert? Welche Muster sind aufgetaucht?

Fragen Sie den Benutzer: „Was war das Wichtigste, das Sie gelernt haben, oder der kniffligste Teil dieser Funktion?“ Ihre Antwort enthüllt oft die wertvollste Lektion, die es zu erfassen gilt.

Klassifizieren Sie vor dem Schreiben die Lektion auf der richtigen Ebene:

• Ereignis – ein einmaliger Vorfall oder sichtbarer Fehler
• Muster – etwas, das wiederholt über Funktionen, Bugs oder Übergaben hinweg aufgetreten ist
• Struktur – eine wiederkehrende Bedingung im Codebase, Workflow, Anreizen oder Entscheidungsprozess, die das Muster immer wieder produziert

Bevorzugen Sie die Erfassung der höchsten Ebene, die Sie mit Beweisen unterstützen können. Wenn die Lektion strukturell ist, benennen Sie die Rückkopplungsschleife, die fehlende Rückkopplung oder den verzögerten Effekt, der das Ergebnis wahrscheinlich gemacht hat.

Beantworten Sie vor dem Fortfahren vier Fragen:

1. Ist dies wirklich neuartig? Überprüfen Sie offizielle Bibliotheksdokumentationen und die Stores, die Phase 4s Überlappungssuche abdeckt. Wenn die Lektion bereits anderweitig gut dokumentiert ist, überspringen Sie sie oder verlinken Sie zur bestehenden Quelle.
2. Wird dies in 3 Monaten noch korrekt sein? Wenn die Lektion eng an eine Abhängigkeitsversion oder einen temporären Workaround gekoppelt ist, notieren Sie das – es beeinflusst die volatility-Klassifizierung unten.
3. Könnte dies näher an der Quelle erfasst werden? Eine Verhaltensinvariante ist besser als Test. Eine Konvention ist besser als Linter-Regel. Eine „Warum“-Erklärung ist besser als Code-Kommentar, kollokalisiert mit der Entscheidung – begrenzt auf das aktuelle Warum, der Grund, den ein Leser braucht, um den Code zu verstehen, wie er jetzt ist. Der Vorfall, der es entdeckt hat, gehört in die Commit-Nachricht und den PR-Text, wo ein Leser, der die Historie rekonstruiert, bereits sucht; /execute Schritt 3 gibt dieses Routing zum Zeitpunkt des Schreibens des Kommentars an, und diese Frage ist die retrospektive Prüfung darauf. Wenn die Lektion in einem höherwertigen Artefakt erfasst werden kann, tun Sie das, anstatt Prosa zu schreiben. Es geht darum, die Lektion zu tragen – Phase 4s Clustering-Prüfung stellt eine andere Frage, ob ein Mechanismus die nächste Instanz fangen sollte, und eine Wiederholung kann eine solche erfordern, selbst wenn die Lektion selbst Prosa benötigte.
4. Wurde der Prozess gefixt? (Nur Bug-Fix-Compounds.) War der Fix eine Korrektur (hat den Defekt entfernt) oder ein Workaround (hat den Fehler unterdrückt)? Wurden strukturell ähnliche Muster anderswo im Codebase gefunden und adressiert? Welche Prozessänderung würde verhindern, dass diese Defektklasse erneut in den Codebase gelangt – ein strengerer Test, eine Linter-Regel, eine Assertion, ein Planungs-Checklistenelement oder ein eingereichter Issue in chrislacey89/skills (siehe Einreichen gegen das Paket unten)? Wenn die Antwort „nichts“ ist, ist der Mechanismus, der diesen Defekt produziert hat, noch aktiv.

Einreichen gegen das Paket – der fünfte Mechanismus

Dieser Unterabschnitt ist nicht auf Bug-Fixes beschränkt. Q4 oben ist es (seine Überschrift sagt das), aber sowohl Q4 als auch Phase 4s Regel zum Hochstufen zu einem Mechanismus zitieren die folgenden Regeln, und Phase 4 ist nicht auf Bug-Fixes beschränkt. Der Vorfall, für den dieser Mechanismus existiert, war ein Feature-Compound. Ein Prozedur, die nur über den Pfad erreichbar ist, den ihr eigener Vorfall nicht genommen hat, ist der Defekt, der eine Ebene tiefer behoben wird – daher werden die Regeln hier einmal deklariert, und beide Phasen verweisen darauf.

Der fünfte Name ist durch Eigentümerschaft begrenzt, nicht durch Schwierigkeit. Die ersten vier sind Artefakte dieses Codebase; der fünfte existiert, weil einige verhindernde Änderungen nicht in diesem Codebase sind – sie sind Änderungen an Prosatexten, Toren, Übergaben oder Vertragstests eines Skills in chrislacey89/skills, die kein nachgelagertes Artefakt überhaupt tragen kann. Das, und nur das, ist der Fall, in dem der fünfte Name qualifiziert. Er qualifiziert nicht weil die ersten vier hier schwer, teuer oder unklar sind: das ist der Compliance-Exit, den chrislacey89/skills#257 bewusst offen gelassen hat, und „Ich konnte keinen bauen“ löst immer noch so auf wie immer – durch Benennung im Eintrag, welcher der vier am nächsten kam und was ihn blockiert hat.

Einreichungs-Eigentümer-Tor (DO-CONFIRM – vor dem Schreiben von etwas Ausgehendem prüfen)

Einreichen bewegt Wörter aus dem Repository, in dem Sie sich befinden, in ein öffentliches. Das ist ein anderer Akt als jeder andere Mechanismus in der Liste – ein Test, eine Linter-Regel, eine Assertion und ein Checklisten-Element bleiben alle dort, wo sie sind. Prüfen Sie daher vor dem Verfassen eines Textes, ob der Eigentümer des aktuellen Repositorys einer ist, von dem aus Sie einreichen dürfen:

git remote get-url origin | sed -E 's#(git@[^:]+:|https://[^/]+/)([^/]+)/.*#\2#'

Vergleichen Sie es mit der Erlaubnisliste unten. Die Erlaubnisliste ist das gesamte Tor – ein Eigentümer, der nicht darauf steht, ist nicht erlaubt, einschließlich eines Eigentümers, den Sie nicht erkennen. Kehren Sie dies nicht in „Blockieren Sie die Eigentümer, von denen ich weiß, dass sie Arbeit sind“ um: eine Client-Organisation, die letzte Woche angebunden wurde, steht auf niemandes Liste, daher würde eine Blockierliste genau das Repository mit der am wenigsten bekannten Vertraulichkeitshaltung zulassen. Schließen Sie bei Unbekanntem geschlossen aus.

chrislacey89

Die Marker um diesen Zaun sind tragend: dieser Unterabschnitt enthält mehrere umzäunte Blöcke, daher ist „die Liste ist der Code-Block unten“ für alles, das mechanisch liest, mehrdeutig – ein Leser, der falsch rät, extrahiert Prosa, und dann schlägt jeder Eigentümer die Prüfung fehl. Gleichen Sie die Marker ab, nicht die Position.

Fügen Sie einen Eigentümer nur als bewusste, überprüfte Änderung zu dieser Liste hinzu – eine Zeile, offline, durchsuchbar. Ein öffentliches Repository, zu dem Sie beitragen, qualifiziert sich, sobald Sie es benennen; es qualifiziert sich nicht nur durch seine Öffentlichkeit. Sichtbarkeit ist eine veränderbare Remote-Eigenschaft, ein öffentlicher Fork kann einen privaten Elternteil maskieren, und – der Grund, warum das hier wichtig ist – was eingereicht wird, ist eine Erzählung über die Arbeit, nicht der Code des Repositorys. Öffentlicher Quellcode und eine vertrauliche Zusammenarbeit darum herum ist eine gewöhnliche Kombination, und „wir sind darauf gestoßen, während wir X für Y gebaut haben“ gibt die Beziehung preis, selbst wenn jede Zeile weltweit lesbar ist.

Wenn der Eigentümer nicht auf der Erlaubnisliste steht, ist der fünfte Name nicht verfügbar. Fallen Sie auf das Verhalten zurück, das vor diesem Mechanismus bestand: notieren Sie das Rezept im Feld Prävention → Prozessebene des Eintrags, empfehlen Sie /improve-pipeline, und lassen Sie es von einem Menschen transportieren. Die Lektion ist nicht verloren; sie reist nur nicht automatisch.

Verfassen und Einreichen

Wenn sowohl die Eigentümerschutzsperre als auch das Einreichungs-Eigentümer-Tor bestanden sind, ist das Einreichen der Mechanismus, und /compound reicht es ein – das Rezept, das dieses Repository erreicht, ist das Artefakt, nicht ein Satz, der empfiehlt, dass jemand es dort hin bringt. Überprüfen Sie zuerst auf Überlappung und kommentieren Sie den bestehenden Issue, anstatt einen neuen einzureichen; ein neuer ausgehender Kanal in ein Backlog ist nur wertvoll, wenn er sich nicht mit Wiederholungen füllt.

gh issue list -R chrislacey89/skills --state all --search "<pipeline area> <failure-mode keywords>"
gh issue create -R chrislacey89/skills --title "[improve-pipeline] <pipeline area> — <prescription>" --body-file <file>

--title und --body* sind erforderlich, nicht stilistisch: gh issue create ohne beide führt unter jedem nicht-interaktiven Runner zu einem Fehler, und das ist jeder AFK-Pfad, den dieser Mechanismus überleben soll.

Schreiben Sie den Text anonymisiert und behandeln Sie dies als Teil des Vertrags, nicht als gute Manieren. Das Tor oben entscheidet, ob Sie einreichen dürfen; dies entscheidet, was die Grenze überquert. Beschreiben Sie die Form des Vorfalls, nicht sein Subjekt:

• Benennen Sie die Paketdatei, die die Änderung betrifft, den Pipeline-Schritt, der es übersehen hat, und was er stattdessen hätte tun sollen.
• Benennen Sie nicht das nachgelagerte Repository, seinen Eigentümer, seinen Client, seine Pfade, seine Bezeichner oder seine Issue- und PR-Nummern. Charakterisieren Sie es – „ein nachgelagertes TypeScript-Web/Page-Analyse-Repo“ – so wie chrislacey89/skills#266 es tat, das das ausgearbeitete Beispiel ist: es öffnet Triggering repo: anonymized und vermerkt, dass die Quelle absichtlich von Kennungen befreit wurde.
• Zitieren Sie nicht den Pfad dieses Eintrags als Beleg. Ein docs/solutions/…-Pfad ist ein Dateiname aus einem Repository, auf das der Leser möglicherweise keinen Zugriff hat, daher beweist er ihnen nichts und identifiziert die Arbeit für alle anderen. Tragen Sie stattdessen die Begründung über die Grenze; der Eintrag bleibt zu Hause.

Die Paketdatei und die Fehlerform sind das, was einen Vorschlag hier umsetzbar macht. Alles, was die Anonymisierungsregel entfernt, ist Detail, das nur in dem Repository, aus dem es stammt, lesbar war.

Halten Sie es kurz. Dies ist ein Vorschlagsentwurf, kein ausgearbeiteter Vorschlag – /improve-pipeline ist das, was einen entwickelt, und die /improve-pipeline-Empfehlung später in dieser Phase besteht weiterhin: empfehlen Sie es, rufen Sie es nicht auf. Zitieren Sie die Issue-Nummer im Eintrag. Ein nicht zitierter Vorschlag ist wieder Prosa: der Eintrag nennt #N, oder der fünfte Name wurde nicht verwendet.

**Kaninchenloch-Überprüfung.

…

[für die Übersetzung gekürzt]