zby/commonplace

EXÉCUTEZ MAINTENANT

Cible : $ARGUMENTS

Tous les documents de la KB vivent dans une collection : un répertoire sous kb/ avec un COLLECTION.md local, comme kb/notes/, kb/reference/, kb/instructions/, ou une collection de bibliothèque installée comme kb/commonplace/notes/. Chaque collection qui accepte des écritures possède un COLLECTION.md avec son registre, son objectif de qualité, ses offres de types et ses conventions de liaison.

Les documents avec un frontmatter portent un type: à valeur de chemin qui pointe vers un doc de spécification de type, par exemple type: kb/types/note.md ou type: kb/reference/types/adr.md. Les fichiers sans frontmatter sont implicitement text.

Étape 1 - Analyser les arguments

Mode édition : le premier argument est un chemin vers un fichier .md existant. Lisez-le, déduisez la collection du chemin et lisez son chemin type: dans le frontmatter. S'il a un frontmatter mais pas de type:, arrêtez-vous et corrigez ce problème structurel avant d'éditer. S'il n'a pas de frontmatter, traitez-le comme text implicite. Ouvrez le doc de spécification de type nommé par type: avant de faire des modifications structurelles.

Mode nouvelle écriture : tout le reste. Extrayez la collection, le type et le sujet des arguments. Valeurs par défaut : collection notes, type kb/types/note.md. Si le type demandé est une instruction et qu'aucune collection n'est explicite, utilisez la collection instructions.

Pour les nouvelles écritures, résolvez la collection cible en un répertoire sous kb/ avec un COLLECTION.md local ; les noms raccourcis comme notes signifient kb/notes/. Lisez la section ## Types de cette collection et choisissez un chemin de type listé. Si le type demandé n'est pas listé et que l'utilisateur n'a pas donné de chemin explicite, arrêtez-vous et listez les types disponibles. Si l'utilisateur donne un chemin de type explicite kb/.../*.md, ouvrez ce fichier et vérifiez qu'il s'agit d'un doc de spécification de type avant de l'utiliser.

Étape 2 - Charger les conventions de la collection

Lisez le COLLECTION.md de la collection cible pour les conventions d'écriture de la collection, y compris les règles de liaison sortante. Trouvez la section de liaison sortante (le titre varie — cherchez celui qui nomme les destinations et les étiquettes) et traitez-la comme faisant autorité. Elle vous indique à quelles collections de destination cette source peut lier, quelles destinations sont exclues, quelles étiquettes sont autorisées pour quelles paires source->destination, et le besoin du lecteur que chaque étiquette sert. Le format interne varie (blocs par destination, un seul tableau d'étiquettes avec une colonne de destinations, prose) — lisez-le pour le contenu, pas pour la forme. Il n'y a pas de document de liaison séparé à consulter.

Échec dur si la collection cible n'a pas de COLLECTION.md. Chaque collection qui accepte des écritures doit avoir un COLLECTION.md ; son registre, son objectif de qualité et ses règles de liaison sont ce qui distingue les collections. Ne continuez pas avec des conventions par défaut.

Étape 3 - Charger la spécification de type

Lisez le doc de spécification de type sélectionné. Son frontmatter doit inclure type: kb/types/type-spec.md, name, description, et schema. Son corps fournit la forme de l'artefact et peut inclure un bloc de modèle. Suivez ce corps comme contrat d'écriture structurelle.

Ne revenez pas d'un chemin de type manquant à note.

Pour text, écrivez du markdown brut sans frontmatter uniquement lorsque l'utilisateur souhaite explicitement une capture non structurée. Sinon, utilisez kb/types/note.md.

Étape 4 - Chercher avant d'écrire

L'écriture n'exécute pas de découverte active — c'est le travail de cp-skill-connect. L'écriture rédige une note et ne valide que les liens que l'auteur a déjà en main, plus une garde de doublon bon marché :

1. Vérification des quasi-doublons. Recherchez dans la collection cible les termes distinctifs du titre de la nouvelle note avec rg (par exemple rg -i "terme clé" kb/notes/ --glob "*.md"). Il s'agit d'une recherche de terme ciblée — n'énumérez pas toute la collection ; un listing complet coûte un contexte linéaire et est le mauvais outil pour une vérification de doublon d'une seule note. Si un quasi-doublon existe déjà, privilégiez la modification de cette note plutôt que la création d'une deuxième.
2. Contexte déjà chargé. Les notes, sources et imports tirés dans la session pour cette écriture sont des candidats de premier ordre pour les liens. Si cela valait la peine d'être lu, cela vaut la peine d'être considéré comme un lien.
3. Cibles nommées par l'utilisateur. Cibles de lien que l'utilisateur mentionne dans l'invite.

En mode édition, exécutez également une recherche de rétroliens sur la note cible — une requête, pas de recherche de corps — afin que les modifications n'orphelinent pas les dépendants.

Toute découverte au-delà — analyses de description à l'échelle de la collection, prospection inter-destination, recherche de corps, parcours de balises, suivi de liens, raisonnement par arêtes inverses — appartient à cp-skill-connect, pas ici. L'écriture reste concentrée sur la rédaction d'une note.

Étape 5 - Rédiger et enregistrer

Suivez le doc de spécification de type et les conventions de la collection. Déduisez un nom de fichier en minuscules avec traits d'union à partir de # Titre sauf si vous éditez un fichier existant. Pour les artefacts typés, définissez type: sur le chemin exact de la spécification de type relatif au dépôt, pas sur le nom du type.

Définissez les traits uniquement lorsqu'ils sont clairement justifiés. Les traits disponibles et leurs significations sont définis dans la spécification du type cible (par exemple le tableau des traits dans kb/types/note.md) — prenez le vocabulaire de là, pas d'une liste mémorisée.

Préservez le frontmatter et les liens existants lors des modifications, sauf si la modification demandée nécessite de les changer.

Étape 6 - Valider

Validez la note que vous avez écrite ou modifiée :

commonplace-validate chemin/vers/fichier.md

Corrigez les échecs structurels avant de vous arrêter.

Suggérez ensuite cp-skill-connect comme prochaine étape. L'étape 4 ne valide que les liens que l'auteur avait déjà en main (contexte chargé, nommé par l'utilisateur) plus une garde de doublon ; le reste de la part du graphe de la note — analyses de description à l'échelle de la collection, candidats inter-destination, résultats de recherche de corps, parcours de balises, suivi de liens, candidats par arêtes inverses — n'apparaît que sous le skill de connexion. La suggestion n'est pas une finition facultative.

Mécanismes universels

Ceux-ci s'appliquent à tous les artefacts typés, quelle que soit la collection.

Le frontmatter rend les notes interrogeables. Pas de frontmatter signifie text implicite ; tout fichier avec un frontmatter doit inclure un type: à valeur de chemin. La plupart des notes de bibliothèque ont également besoin d'une description (entre guillemets doubles, 50-200 caractères), plus des traits, tags et status optionnels.

Les descriptions sont des filtres de récupération, pas des résumés. Le test : si un agent recherchait le concept de cette note et obtenait 5 résultats, cette description l'aiderait-elle à choisir celle-ci ? Paraphraser le titre n'ajoute aucune valeur de récupération.

Vocabulaire. Utilisez le vocabulaire actif déclaré dans la racine AGENTS.md. Lorsque vous écrivez ou modifiez substantiellement de la prose, glosez et liez le vocabulaire actif à la première mention significative lorsque le lecteur ne connaît peut-être pas le terme. Ne remaniez pas les passages intacts uniquement pour ajouter des liens de vocabulaire.

Liens. Utilisez des chemins markdown relatifs à partir du fichier source. Chaque lien doit pointer vers un fichier réel.

La position encode l'engagement. Les connecteurs en ligne dans la prose (depuis [X](./x.md), parce que [X](./x.md), mais [X](./x.md)) sont les plus forts — la cible est une prémisse de l'argument en cours. Les liens en pied de page portent une étiquette explicite et une phrase de contexte : - [titre](./chemin.md) — étiquette : phrase de contexte.

Le COLLECTION.md de la collection autorise les étiquettes par destination et nomme le besoin du lecteur que chaque étiquette sert. Choisissez une étiquette dont le besoin du lecteur correspond à l'objectif du lien ; rédigez la phrase de contexte pour répondre à "[source] se connecte à [cible] parce que [raison spécifique]." Si aucune étiquette autorisée ne correspond, le candidat est hors de portée pour cette collection — supprimez le lien ou signalez-le à l'auteur de la collection pour étendre l'autorisation.

Noms de fichiers sont en minuscules, avec traits d'union, .md, dérivés de # Titre, 70 caractères max.

Suivi de distillation : lors de la distillation de notes vers un artefact ciblé, ajoutez Distillé dans: dans le pied de page de chaque note source. L'artefact distillé ne renvoie pas de lien en retour.

Renommages : ne renommez jamais manuellement. Utilisez commonplace-relocate-note pour mettre à jour les rétroliens.