zby/commonplace

JETZT AUSFÜHREN

Ziel: $ARGUMENTS

Alle Dokumente in der Wissensbasis (KB) leben in einer Sammlung: einem Verzeichnis unter kb/ mit einer lokalen COLLECTION.md, wie z. B. kb/notes/, kb/reference/, kb/instructions/ oder einer installierten Bibliothekssammlung wie kb/commonplace/notes/. Jede Sammlung, die Schreibvorgänge akzeptiert, hat eine COLLECTION.md mit ihrem Register, Qualitätsziel, Typangeboten und Verlinkungskonventionen.

Dokumente mit Frontmatter tragen einen pfadbasierten type:, der auf ein Typspezifikationsdokument verweist, z. B. type: kb/types/note.md oder type: kb/reference/types/adr.md. Dateien ohne Frontmatter sind implizit text.

Schritt 1 - Argumente parsen

Bearbeitungsmodus: Das erste Argument ist ein Pfad zu einer vorhandenen .md-Datei. Lesen Sie sie, leiten Sie die Sammlung aus dem Pfad ab und lesen Sie ihren type:-Pfad aus dem Frontmatter. Wenn sie Frontmatter, aber keinen type: hat, stoppen Sie und beheben Sie dieses strukturelle Problem, bevor Sie bearbeiten. Wenn sie kein Frontmatter hat, behandeln Sie sie als implizites text. Öffnen Sie das vom type: benannte Typspezifikationsdokument, bevor Sie strukturelle Änderungen vornehmen.

Neuschreibmodus: Alles andere. Extrahieren Sie Sammlung, Typ und Thema aus den Argumenten. Standardwerte: Sammlung notes, Typ kb/types/note.md. Wenn der angeforderte Typ eine Anweisung ist und keine Sammlung explizit angegeben wurde, verwenden Sie die Sammlung instructions.

Auflösen der Zielsammlung in ein Verzeichnis unter kb/ mit einer lokalen COLLECTION.md; Kurznamen wie notes bedeuten kb/notes/. Lesen Sie den Abschnitt ## Types dieser Sammlung und wählen Sie einen der aufgeführten Typpfade aus. Wenn der angeforderte Typ nicht aufgeführt ist und der Benutzer keinen expliziten Pfad angegeben hat, stoppen Sie und listen Sie die verfügbaren Typen auf. Wenn der Benutzer einen expliziten kb/.../*.md-Typpfad angibt, öffnen Sie diese Datei und überprüfen Sie, ob es sich um ein Typspezifikationsdokument handelt, bevor Sie es verwenden.

Schritt 2 - Sammlungskonventionen laden

Lesen Sie die COLLECTION.md der Zielsammlung für die Schreibkonventionen der Sammlung, einschließlich der Regeln für ausgehende Verknüpfungen. Finden Sie den Abschnitt für ausgehende Verknüpfungen (die Überschrift variiert – suchen Sie nach der, die Ziele und Bezeichnungen nennt) und behandeln Sie ihn als maßgeblich. Er sagt Ihnen, mit welchen Zielsammlungen diese Quelle verknüpfen darf, welche Ziele ausgeschlossen sind, welche Bezeichnungen für welche Quell-Ziel-Paare autorisiert sind und welches Leserbedürfnis jede Bezeichnung erfüllt. Das interne Format variiert (pro-Ziel-Blöcke, eine einzelne Bezeichnungstabelle mit einer Zielspalte, Prosa) – lesen Sie es nach Inhalt, nicht nach Form. Es gibt kein separates Verknüpfungsdokument, das konsultiert werden muss.

Harter Fehler, wenn die Zielsammlung keine COLLECTION.md hat. Jede Sammlung, die Schreibvorgänge akzeptiert, muss eine COLLECTION.md haben; ihr Register, Qualitätsziel und Verlinkungsregeln unterscheiden die Sammlungen. Fahren Sie nicht mit Standardkonventionen fort.

Schritt 3 - Das Typspezifikationsdokument laden

Lesen Sie das ausgewählte Typspezifikationsdokument. Sein Frontmatter muss type: kb/types/type-spec.md, name, description und schema enthalten. Sein Körper liefert die Artefaktform und kann einen Vorlagenblock enthalten. Befolgen Sie diesen Körper als strukturellen Autorenvertrag.

Fallen Sie nicht von einem fehlenden Typpfad auf note zurück.

Verwenden Sie für text rohes Markdown ohne Frontmatter nur, wenn der Benutzer explizit unstrukturierte Erfassung wünscht. Verwenden Sie andernfalls kb/types/note.md.

Schritt 4 - Vor dem Schreiben suchen

Schreiben führt keine aktive Erkundung durch – das ist die Aufgabe von cp-skill-connect. Schreiben verfasst eine Notiz und übernimmt nur Verknüpfungen, die der Autor bereits zur Hand hat, plus eine kostengünstige Duplikatsprüfung:

1. Fast-Duplikat-Prüfung. Durchsuchen Sie die Zielsammlung nach den charakteristischen Titelbegriffen der neuen Notiz mit rg (z. B. rg -i "Schlüsselbegriff" kb/notes/ --glob "*.md"). Dies ist eine gezielte Begriffssuche – zählen Sie nicht die gesamte Sammlung auf; eine vollständige Auflistung kostet linearen Kontext und ist das falsche Werkzeug für die Duplikatsprüfung einer einzelnen Notiz. Wenn ein Fast-Duplikat bereits vorhanden ist, ziehen Sie es vor, dieses zu bearbeiten, anstatt eine zweite Notiz zu erstellen.
2. Bereits geladener Kontext. Notizen, Quellen und Importe, die für diesen Schreibvorgang in die Sitzung gezogen wurden, sind erstklassige Verknüpfungskandidaten. Wenn es wert war, gelesen zu werden, ist es wert, als Verknüpfung in Betracht gezogen zu werden.
3. Vom Benutzer benannte Ziele. Verknüpfungsziele, die der Benutzer in der Eingabeaufforderung erwähnt.

Führen Sie im Bearbeitungsmodus auch eine Rückwärtsverknüpfungssuche für die Zielnotiz durch – eine Abfrage, keine Körpersuche –, damit Änderungen keine abhängigen Elemente verwaist lassen.

Jede Erkundung, die darüber hinausgeht – sammlungsweite Beschreibungsscans, abteilungsübergreifende Suche, Körpersuche, Tag-Traversal, Verfolgen von Verknüpfungen, Umkehrkanten-Schlussfolgerungen – gehört zu cp-skill-connect, nicht hierher. Das Schreiben konzentriert sich auf die Erstellung einer Notiz.

Schritt 5 - Entwurf und Speicherung

Befolgen Sie das Typspezifikationsdokument und die Sammlungskonventionen. Leiten Sie einen Dateinamen in Kleinschreibung mit Bindestrich von # Titel ab, es sei denn, Sie bearbeiten eine vorhandene Datei. Setzen Sie für getippte Artefakte type: auf den genauen, repository-relativen Pfad des Typspezifikationsdokuments, nicht auf den Typnamen.

Setzen Sie Merkmale nur, wenn klar begründet. Die verfügbaren Merkmale und ihre Bedeutungen sind in der Spezifikation des Zieltyps definiert (z. B. die Merkmalstabelle in kb/types/note.md) – nehmen Sie das Vokabular von dort, nicht aus einer gespeicherten Liste.

Frontmatter und Links während der Bearbeitung beibehalten, es sei denn, die angeforderte Änderung erfordert deren Änderung.

Schritt 6 - Validieren

Validieren Sie die von Ihnen geschriebene oder bearbeitete Notiz:

commonplace-validate path/to/file.md

Beheben Sie strukturelle Fehler, bevor Sie aufhören.

Schlagen Sie dann cp-skill-connect als nächsten Schritt vor. Schritt 4 verpflichtet sich nur zu Verknüpfungen, die der Autor bereits zur Hand hatte (geladener Kontext, benutzerdefiniert) plus eine Duplikatsperre; der Rest des Graphen, der auf diese Notiz entfällt – sammlungsweite Beschreibungsscans, abteilungsübergreifende Kandidaten, Körpersuche-Treffer, Tag-Traversal, Verfolgen von Verknüpfungen, Umkehrkanten-Kandidaten – wird nur unter der Connect-Fähigkeit sichtbar. Der Vorschlag ist keine optionale Verzierung.

Universelle Mechaniken

Diese gelten für alle getippten Artefakte unabhängig von der Sammlung.

Frontmatter macht Notizen abfragbar. Kein Frontmatter bedeutet implizites text; jede Datei mit Frontmatter muss einen pfadbasierten type: enthalten. Die meisten Bibliotheksnotizen benötigen auch description (doppelt angeführt, 50-200 Zeichen), plus optional traits, tags und status.

Beschreibungen sind Abruffilter, keine Zusammenfassungen. Der Test: Wenn ein Agent nach dem Konzept dieser Notiz suchte und 5 Ergebnisse erhielte, würde diese Beschreibung helfen, diese auszuwählen? Eine Paraphrasierung des Titels bringt keinen zusätzlichen Abrufwert.

Vokabular. Verwenden Sie das aktive Vokabular, das in der Wurzel AGENTS.md deklariert ist. Wenn Sie Prosa schreiben oder wesentlich bearbeiten, glossieren und verknüpfen Sie aktives Vokabular bei der ersten sinnvollen Erwähnung, wenn der Leser den Begriff möglicherweise nicht kennt. Wechseln Sie nicht unberührte Passagen nur, um Vokabellinks hinzuzufügen.

Verknüpfungen. Verwenden Sie relative Markdown-Pfade von der Quelldatei. Jede Verknüpfung muss auf eine reale Datei verweisen.

Position codiert Verbindlichkeit. Inline-Prosakonjunktionen (da [X](./x.md), weil [X](./x.md), aber [X](./x.md)) sind am stärksten – das Ziel ist eine Prämisse des aktuellen Arguments. Fußzeilen-Links tragen eine explizite Bezeichnung und einen Kontextausdruck: - [title](./path.md) — Bezeichnung: Kontextausdruck.

Die COLLECTION.md der Sammlung autorisiert Bezeichnungen pro Ziel und benennt das Leserbedürfnis, das jede Bezeichnung erfüllt. Wählen Sie eine Bezeichnung, deren Leserbedürfnis dem Zweck der Verknüpfung entspricht; schreiben Sie den Kontextausdruck so, dass er die Frage beantwortet: "[Quelle] verbindet sich mit [Ziel] weil [spezifischer Grund]." Wenn keine autorisierte Bezeichnung passt, liegt der Kandidat außerhalb des Rahmens dieser Sammlung – lassen Sie die Verknüpfung fallen oder heben Sie sie an den Sammlungsautor, um die Autorisierung zu erweitern.

Dateinamen sind kleingeschrieben, mit Bindestrich, .md, abgeleitet von # Titel, maximal 70 Zeichen.

Destillationsverfolgung: Wenn aus Notizen in ein fokussiertes Artefakt destilliert wird, fügen Sie Destilliert in: in der Fußzeile jeder Quellnotiz hinzu. Das destillierte Artefakt verlinkt nicht zurück.

Umbenennungen: Niemals manuell umbenennen. Verwenden Sie commonplace-relocate-note, um Rückwärtsverknüpfungen zu aktualisieren.