av/facts

O que é facts?

av/facts é um fluxo de trabalho e formato de especificação para gerenciar um projeto como uma lista de atomic claims em um arquivo .facts. Cada linha é uma declaração curta e estruturada sobre o que deve ser verdadeiro, e pode opcionalmente incluir um shell command que a máquina executa para verificar a claim.

O propósito principal é permitir que um agente e sua equipe mantenham os requisitos do projeto legíveis e verificáveis: você escreve verdades aproximadas, refina-as em specs precisas e depois implementa e verifica. Você pode executar facts check para ver quais claims passam, falham ou precisam de atenção manual.

Principais Recursos

• Formato de especificação de “fact” atômico (.facts): Escreva uma claim por linha como strings simples, organizadas com cabeçalhos Markdown por domínio.
• Marcação de ciclo de vida para rastreamento de progresso: Use @draft, @spec e @implemented (mais tags personalizadas) para mostrar onde cada claim está em seu pipeline.
• Verificação baseada em comando: Para facts que incluem um command, facts check executa o comando e considera a claim verdadeira quando o comando sai com 0.
• Verificação automatizada e agrupamento de status: facts check faz lint nos arquivos, executa todos os comandos e agrupa resultados (ex.: verde passou, vermelho falhou, amarelo manual); sai com código não-zero se algo falhar.
• Códigos de saída e filtragem amigáveis para CI: Filtre verificações por expressões de tags (ex.: --tags "mvp and not blocked") para verificar subconjuntos da spec.
• Transições gerenciadas por agente e implementação contra a spec: Um agente lê a planilha de facts, pega facts @spec, constrói-os, executa facts check e marca facts aprovados como @implemented enquanto a spec se atualiza.

Como Usar facts

1. Instale a CLI/ferramenta de agente (o projeto oferece várias opções de instalação, incluindo um binário Rust e um comando npx como descrito abaixo).
   • Exemplo: npx skills add av/facts
   • Depois, peça ao agente para executar Init facts (ex.: “Init facts”) para detectar sua stack e criar um arquivo .facts inicial.
2. Crie ou edite seu arquivo .facts usando o formato documentado:
   • Adicione cabeçalhos para organizar por domínio (ex.: # auth, # data).
   • Adicione uma claim por linha.
   • Marque cada fact com rótulos de estágio de ciclo de vida como @draft, @spec ou @implemented.
   • Para claims verificáveis, inclua um command que sai com 0 quando a claim é válida.
3. Execute verificação: use facts check para fazer lint e verificar todos os facts (ou use --tags para limitar verificações). Revise quais passaram, falharam ou precisam de trabalho manual.
4. Itere com o agente: escreva ideias aproximadas como @draft, refine-as em @spec, depois deixe o agente implementar facts @spec e marcá-los como @implemented após passarem em facts check.

Casos de Uso

• Validação de spec do projeto após mudanças: Mantenha uma checklist viva do que deve ser verdadeiro e execute facts check após edições para ver rapidamente o que ainda vale.
• Transformar requisitos em verificações executáveis: Converta declarações “deve ser verdadeiro” (como comportamento de autenticação ou regras de manipulação de dados) em facts com verificação baseada em comando.
• Gerenciar trabalho em progresso com ciclo de vida de facts: Use @draft → @spec → @implemented para comunicar progresso e garantir que cada claim esteja implementada e verificada ou claramente marcada para refinamento.
• Descoberta e classificação automatizada do codebase: Use a skill facts-discover para escanear o codebase e classificar facts por estágio de ciclo de vida, incluindo adicionar verdades ausentes.
• Implementar contra uma spec: Use o flow facts-implement onde o agente lê facts @spec, constrói código, verifica com facts check e atualiza tags.

FAQ

facts é apenas um formato de documentação, ou realmente verifica claims? Pode fazer ambos: facts sem comandos podem ser verificados pelo agente contra o codebase, enquanto facts com command são verificados executando o comando e checando o código de saída 0.

O que facts check faz? Faz lint nos arquivos, executa todos os comandos fornecidos, agrupa resultados por status (passou/falhou/manual) e sai com código não-zero se algo falhar.

Como os facts são organizados e rastreados? Facts vivem em um arquivo .facts escrito em estrutura compatível com Markdown/YAML, com cabeçalhos para organização por domínio e tags (incluindo @draft, @spec, @implemented) para rastrear status de ciclo de vida.

Posso verificar apenas parte do meu projeto? Sim. facts check suporta filtragem por tags via --tags com expressões booleanas.

Alternativas

• Suítes de testes (unit/integration tests): Testes tradicionais verificam comportamento, mas uma checklist .facts enfatiza claims atômicas legíveis por humanos e um pipeline de ciclo de vida/status, não só passou/falhou automatizado.
• Documentação estática + code review: Docs capturam requisitos, mas geralmente não são diretamente executáveis; facts vincula claims à verificação via facts check.
• Ferramentas de especificação que suportam rastreabilidade de requisitos: Ferramentas que ligam requisitos à implementação podem fornecer rastreabilidade, mas facts usa especificamente um formato claim por linha com execução de comando opcional e transições de ciclo de vida baseadas em tags.