av/facts

Qu'est-ce que facts ?

av/facts est un workflow et un format de spécification pour gérer un projet sous forme de liste de revendications atomiques dans un fichier .facts. Chaque ligne est une affirmation courte et structurée sur ce qui doit être vrai, et elle peut optionnellement inclure une commande shell que la machine exécute pour vérifier la revendication.

L'objectif principal est de permettre à un agent et à votre équipe de maintenir les exigences du projet lisible et vérifiable : vous écrivez des vérités approximatives, les affinez en spécifications précises, puis les implémentez et les vérifiez. Vous pouvez exécuter facts check pour voir quelles revendications passent, échouent ou nécessitent une attention manuelle.

Fonctionnalités clés

• Format de spécification “fact” atomique (.facts) : Écrivez une revendication par ligne sous forme de chaînes simples, organisées avec des titres Markdown par domaine.
• Étiquetage de cycle de vie pour le suivi des progrès : Utilisez @draft, @spec et @implemented (plus des étiquettes personnalisées) pour indiquer où en est chaque revendication dans son pipeline.
• Vérification basée sur des commandes : Pour les faits incluant une command, facts check exécute la commande et considère la revendication vraie si elle se termine par 0.
• Vérification automatisée et regroupement des statuts : facts check vérifie les fichiers, exécute toutes les commandes, regroupe les résultats (ex. : vert passé, rouge échoué, jaune manuel) ; il se termine avec un code non nul si quoi que ce soit échoue.
• Codes de sortie et filtrage adaptés à la CI : Filtrez les vérifications par expressions d'étiquettes (ex. : --tags "mvp and not blocked") pour vérifier des sous-ensembles de votre spécification.
• Transitions gérées par l'agent et implémentation contre la spec : Un agent lit la fiche des faits, prend les faits @spec, les construit, exécute facts check, et étiquette les faits passés comme @implemented tandis que la spec se met à jour elle-même.

Comment utiliser facts

1. Installez l'outil CLI/agent (le projet propose plusieurs options d'installation, y compris un binaire Rust et une commande npx comme décrit ci-dessous).
   • Exemple : npx skills add av/facts
   • Puis demandez à l'agent d'exécuter Init facts (ex. : “Init facts”) pour détecter votre stack et créer un fichier .facts initial.
2. Créez ou modifiez votre fichier .facts en utilisant le format documenté :
   • Ajoutez des titres pour organiser par domaine (ex. : # auth, # data).
   • Ajoutez une revendication par ligne.
   • Étiquetez chaque fait avec des labels de stade de cycle de vie comme @draft, @spec ou @implemented.
   • Pour les revendications vérifiables, incluez une command qui se termine par 0 quand la revendication est vraie.
3. Exécutez la vérification : utilisez facts check pour vérifier et linter tous les faits (ou utilisez --tags pour limiter les vérifications). Passez en revue ceux qui ont passé, échoué ou nécessitent un travail manuel.
4. Itérez avec l'agent : écrivez des idées approximatives comme @draft, affinez-les en @spec, puis laissez l'agent implémenter les faits @spec et les étiqueter comme @implemented après passage de facts check.

Cas d'usage

• Validation de spec de projet après changements : Maintenez une checklist vivante de ce qui doit être vrai et exécutez facts check après les modifications pour voir rapidement ce qui tient encore.
• Transformation des exigences en vérifications exécutables : Convertissez des affirmations “doit être vrai” (comme le comportement d'authentification ou les règles de gestion de données) en faits avec vérification basée sur commande.
• Gestion du travail en cours avec un cycle de vie des faits : Utilisez @draft → @spec → @implemented pour communiquer les progrès et assurer que chaque revendication est soit implémentée et vérifiée, soit clairement marquée pour affinage.
• Découverte et classification automatisée du codebase : Utilisez la compétence facts-discover pour scanner le codebase et classer les faits par stade de cycle de vie, y compris ajouter des vérités manquantes.
• Implémentation contre une spec : Utilisez le flux facts-implement où l'agent lit les faits @spec, construit le code, le vérifie avec facts check, et met à jour les étiquettes.

FAQ

facts est-il seulement un format de documentation, ou vérifie-t-il vraiment les revendications ? Il peut faire les deux : les faits sans commande peuvent être vérifiés par l'agent contre le codebase, tandis que les faits avec une command sont vérifiés en exécutant la commande et en vérifiant le code de sortie 0.

Que fait facts check ? Il linter les fichiers, exécute toutes les commandes fournies, regroupe les résultats par statut (passé/échoué/manuel), et se termine avec un code non nul si quoi que ce soit échoue.

Comment les faits sont-ils organisés et suivis ? Les faits vivent dans un fichier .facts écrit en structure compatible Markdown/YAML, avec des titres pour l'organisation par domaine et des étiquettes (y compris @draft, @spec, @implemented) pour suivre le statut du cycle de vie.

Puis-je vérifier seulement une partie de mon projet ? Oui. facts check supporte le filtrage par étiquettes via --tags avec des expressions booléennes.

Alternatives

• Suites de tests (tests unitaires/intégration) : Les tests traditionnels peuvent vérifier le comportement, mais une checklist .facts met l'accent sur des revendications atomiques lisibles par l'humain et un pipeline de cycle de vie/statut, pas seulement un passé/échoué automatisé.
• Documentation statique + revue de code : Les docs peuvent capturer les exigences, mais elles ne sont généralement pas directement exécutables ; facts lie les revendications à la vérification via facts check.
• Outils de spécification supportant la traçabilité des exigences : Les outils qui lient exigences et implémentation peuvent fournir de la traçabilité, mais facts utilise spécifiquement un format de revendications ligne par ligne avec exécution de commande optionnelle et transitions de cycle de vie basées sur étiquettes.