av/facts

¿Qué es facts?

av/facts es un workflow y formato de especificación para gestionar un proyecto como una lista de afirmaciones atómicas en un archivo .facts. Cada línea es una afirmación corta y estructurada sobre lo que debe ser verdadero, y opcionalmente puede incluir un comando de shell que la máquina ejecuta para verificar la afirmación.

El propósito principal es permitir que un agente y tu equipo mantengan los requisitos del proyecto legibles y verificables: escribes verdades aproximadas, las refinas en especificaciones precisas y luego las implementas y verificas. Puedes ejecutar facts check para ver qué afirmaciones pasan, fallan o necesitan atención manual.

Características clave

• Formato de especificación de “hechos” atómicos (.facts): Escribe una afirmación por línea como cadenas simples, organizadas con encabezados Markdown por dominio.
• Etiquetas de ciclo de vida para seguimiento del progreso: Usa @draft, @spec y @implemented (más etiquetas personalizadas) para mostrar en qué etapa del pipeline está cada afirmación.
• Verificación respaldada por comandos: Para hechos que incluyen un command, facts check ejecuta el comando y considera la afirmación verdadera si sale con 0.
• Verificación automatizada y agrupación de estados: facts check analiza los archivos, ejecuta cada comando y agrupa resultados (p. ej., verde: pasa, rojo: falla, amarillo: manual); sale con código no cero si algo falla.
• Códigos de salida y filtrado aptos para CI: Filtra verificaciones por expresiones de etiquetas (p. ej., --tags "mvp and not blocked") para verificar subconjuntos de tu especificación.
• Transiciones gestionadas por agente e implementación contra la spec: Un agente lee la hoja de hechos, toma hechos @spec, los construye, ejecuta facts check y etiqueta los que pasan como @implemented mientras la spec se actualiza.

Cómo usar facts

1. Instala la CLI/herramientas del agente (el proyecto ofrece múltiples opciones de instalación, incluyendo un binario Rust y un comando npx como se describe a continuación).
   • Ejemplo: npx skills add av/facts
   • Luego pide al agente que ejecute Init facts (p. ej., “Init facts”) para detectar tu stack y crear un archivo .facts inicial.
2. Crea o edita tu archivo .facts usando el formato documentado:
   • Agrega encabezados para organizar por dominio (p. ej., # auth, # data).
   • Agrega una afirmación por línea.
   • Etiqueta cada hecho con etapas del ciclo de vida como @draft, @spec o @implemented.
   • Para afirmaciones verificables, incluye un command que salga con 0 cuando la afirmación sea válida.
3. Ejecuta verificación: usa facts check para analizar y verificar todos los hechos (o usa --tags para limitar las verificaciones). Revisa cuáles pasaron, fallaron o requieren trabajo manual.
4. Itera con el agente: escribe ideas aproximadas como @draft, refínalas en @spec, luego deja que el agente implemente hechos @spec y los etiquete como @implemented después de que pasen facts check.

Casos de uso

• Validación de spec del proyecto tras cambios: Mantén una lista de verificación viva de lo que debe ser verdadero y ejecuta facts check después de ediciones para ver rápidamente qué sigue vigente.
• Convertir requisitos en verificaciones ejecutables: Transforma afirmaciones “debe ser verdadero” (como comportamiento de autenticación o reglas de manejo de datos) en hechos con verificación basada en comandos.
• Gestionar trabajo en progreso con ciclo de vida de hechos: Usa @draft → @spec → @implemented para comunicar progreso y asegurar que cada afirmación esté implementada y verificada o marcada claramente para refinamiento.
• Descubrimiento y clasificación automatizada del codebase: Usa la skill facts-discover para escanear el codebase y clasificar hechos por etapa del ciclo de vida, incluyendo agregar verdades faltantes.
• Implementar contra una spec: Usa el flow facts-implement donde el agente lee hechos @spec, construye código, lo verifica con facts check y actualiza etiquetas.

Preguntas frecuentes

¿Es facts solo un formato de documentación, o realmente verifica afirmaciones? Puede hacer ambas: los hechos sin comandos pueden ser verificados por el agente contra el codebase, mientras que los hechos con un command se verifican ejecutando el comando y comprobando el código de salida 0.

¿Qué hace facts check? Analiza los archivos, ejecuta cada comando proporcionado, agrupa resultados por estado (pasa/falla/manual) y sale con código no cero si algo falla.

¿Cómo se organizan y rastrean los hechos? Los hechos viven en un archivo .facts escrito en estructura compatible con Markdown/YAML, con encabezados para organización por dominio y etiquetas (incluyendo @draft, @spec, @implemented) para rastrear el estado del ciclo de vida.

¿Puedo verificar solo parte de mi proyecto? Sí. facts check soporta filtrado por etiquetas vía --tags con expresiones booleanas.

Alternativas

• Suites de pruebas (tests unitarios/integración): Las pruebas tradicionales pueden verificar comportamiento, pero una lista de verificación .facts enfatiza afirmaciones atómicas legibles por humanos y un pipeline de ciclo de vida/estado, no solo pasa/falla automatizado.
• Documentación estática + revisión de código: Los docs pueden capturar requisitos, pero usualmente no son directamente ejecutables; facts vincula afirmaciones a verificación vía facts check.
• Herramientas de especificación con trazabilidad de requisitos: Herramientas que vinculan requisitos a implementación pueden ofrecer trazabilidad, pero facts usa específicamente un formato de afirmaciones línea por línea con ejecución de comandos opcional y transiciones de ciclo de vida basadas en etiquetas.