Knowledge Capture
Utilisation automatique
Avant la réponse finale pour toute tâche liée au dépôt, si des fichiers ont été modifiés, des tests exécutés, ou une décision / découverte / suivi a été effectué, créer ou mettre à jour exactement une capture de session active pour la session / le workflow en cours. Faire cela après la vérification et avant de demander le nettoyage du backlog ou l'approbation.
Ne pas créer une nouvelle capture simplement parce que la compétence est invoquée à nouveau. Si le chemin d'une capture active est connu pour ce workflow, mettre à jour ce fichier. Sinon, lire .ai/raw/active-session.json comme pointeur actif candidat. S'il n'existe pas de capture active fiable ou si le workflow a clairement changé, créer une nouvelle capture brute et remplacer le pointeur.
Capturer suffisamment de détails sur la tâche en cours pour une utilisation ultérieure. Lire/mettre à jour uniquement la capture active pour le workflow en cours ; ne pas lire, mettre à jour, dédupliquer, fusionner, synchroniser, valider, publier ou promouvoir des captures non liées dans v0.2.
Une capture n'est pas complète simplement parce que l'assistant a écrit un fichier. Ne pas laisser « Non capturé. » dans les sections dont les faits sont connus, en particulier Demande de l'utilisateur, Modifications et preuves, Décisions et découvertes, et Questions ouvertes et prochaines étapes.
Lors de la mise à jour d'une capture active, écrire l'intégralité de la capture telle qu'elle devrait se présenter après l'étape actuelle du workflow. Ne pas ajouter une note de delta uniquement. Utiliser le contexte de la tâche en cours, les fichiers visibles, les diffs, les tests, les résultats de commandes et le texte de passation comme preuves ; si la continuité n'est pas claire, créer une nouvelle capture plutôt que d'inventer un contexte manquant.
Maintenir la capture alignée sur la réalité actuelle, et non sur chaque pensée intermédiaire. Si une décision antérieure a changé et que le travail a changé en conséquence, capturer la décision finale / actuelle et les preuves. Conserver la décision remplacée uniquement si elle explique du code implémenté, un rollback, un risque non résolu ou une question ouverte ; omettre les options abandonnées purement théoriques.
Stocker les captures sous .ai/raw/<dossier-type>/YYYY-MM-DDTHH-mm-ssZ--<type>--<slug-sujet>.md. Si le nom de fichier exact existe, ajouter --2, --3, etc. avant .md.
Types : session -> sessions, discussion -> discussions, investigation -> investigations, decision -> decisions, handoff -> handoffs.
Pour les captures de session, maintenir .ai/raw/active-session.json comme un pointeur local vers la capture du workflow actif. Ne pas le vider après chaque réponse finale ; il prend en charge la reprise, la compaction et la passation. Le remplacer quand une nouvelle capture de workflow commence.
Capture
Traiter /capture comme créer/mettre à jour la capture de la session en cours. Traiter /capture <type> comme ce type de capture lorsque <type> est session, discussion, investigation, decision ou handoff.
Avant la compression de contexte, la compaction ou la passation, capturer d'abord si un travail ou des décisions significatifs n'ont pas déjà été capturés.
Si Node est disponible, l'assistant sans dépendances peut créer la première capture, remplacer la capture active connue avec --update <chemin>, ou remplacer la capture pointée avec --update-active. Passer des détails riches et structurés via --stdin ou écrire du Markdown directement. L'assistant bloque par défaut les captures avec uniquement titre/résumé car elles perdent des connaissances utiles de la session.
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "correction token refresh auth" --summary "Comportement corrigé du token refresh expiré" --stdin
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "correction token refresh auth" --update .ai/raw/sessions/2026-07-04T18-22-10Z--session--auth-refresh-token-fix.md --stdin
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "correction token refresh auth" --update-active --stdin
Fournir les titres Markdown depuis references/raw-capture-schema.md sur stdin. Si Node ou l'exécution shell n'est pas disponible, créer ou mettre à jour le Markdown directement.
Utiliser cet ordre pour les captures de session actives :
- Si le chemin actif est connu dans le contexte actuel, mettre à jour ce chemin.
- Sinon lire
.ai/raw/active-session.jsoncomme pointeur candidat. - Si le pointeur et l'exécution exposent un
agent_session_idet qu'ils correspondent, le mettre à jour. - Si l'ID de session diffère, est manquant, ou indisponible mais que la demande de l'utilisateur ou la passation continue clairement le même workflow, le mettre à jour et rafraîchir le pointeur.
- Sinon créer une nouvelle capture et remplacer le pointeur. Ne jamais choisir par devinette du nom de fichier le plus récent.
Garde-fous
- Capturer des détails bruts utiles, mais éviter les transcriptions, les grands logs et les fichiers entiers.
- Placer les fichiers modifiés, tests, commandes et preuves sous
Modifications et preuves; regrouper les fichiers par objectif lorsque plusieurs fichiers ont été modifiés. - Inclure uniquement les commandes / résultats rares, non évidents ou pertinents pour la décision ; omettre les commandes de routine qui n'auront pas d'importance plus tard.
- Réorganiser une capture active uniquement pour la rendre précise et utile ; ne pas inventer des faits ou conserver silencieusement une théorie obsolète comme si elle était toujours vraie.
- Traiter
agent_session_idcomme un garde-fou utile, pas la définition d'un workflow. Une nouvelle session d'agent peut continuer le même workflow. - Utiliser
--agent-session-iduniquement lorsque l'exécution expose clairement un ID de session, conversation, fil d'exécution ou d'exécution stable. S'il n'est pas disponible, l'omettre. Ne jamais en inventer un. - Exclure les secrets, identifiants, clés API, clés privées, données privées des clients et les souvenirs personnels non liés.
- Si un contenu sensible est présent, ne pas créer la capture ; résumer d'abord de manière abstraite.
- L'état brut/local uniquement provient du chemin
.ai/raw/et de la politique de la compétence, pas des champs de workflow par capture. - Considérer l'assistant Node comme optionnel. La création directe de fichier reste valide.
Après l'enregistrement, signaler le chemin, le type et s'il a été créé ou mis à jour. Si l'assistant bloque la capture, signaler l'avertissement et ne pas enregistrer le contenu brut.
Références
- Lire
references/raw-capture-schema.mduniquement lors de l'écriture manuelle ou du changement du schéma. - Lire
references/active-session-example.mden cas de doute sur l'apparence d'une capture de workflow mise à jour. - Lire
references/agent-portability.mduniquement lors de l'adaptation de cette compétence à un autre agent.