Cada ambiguidade na sua especificação
é um token que seu agente queima.

O que dá errado sem ele.

• 🌀 As especificações divergem.

  A especificação no documento, a thread no Slack e o código no PR discordam silenciosamente por semanas. Ninguém consegue achar qual versão da conversa é a canônica.

  A solução

  Uma especificação canônica, no repositório, versionada com o código.specscore lint roda no CI a cada push; o histórico do git é a trilha de auditoria. A especificação, a thread e o PR não podem mais discordar em silêncio — eles compartilham o mesmo arquivo em revisão.

• 🌫️ Os critérios ficam vagos.

  "Lida com erros graciosamente" era para significar"mostrar um toast e fazer rollback." Ou era"logar e tentar de novo?" O agente tem que adivinhar.

  A solução

  O linter pega critérios ambíguos antes de qualquer linha de código ser escrita. O verbo falha no lint porque não tem objeto ou condição concretos. Corrigir o aviso obriga você a escrever o que "lida" realmente significa.

• 🤖 Agentes entregam a coisa errada.

  Humanos interpolam, perguntam, esclarecem. Agentes de IA não — eles implementam o padrão mais comum nos dados de treinamento. O código passa no review porque fazalguma coisa sensata. Só não é o que você queria dizer.

  A solução

  Entrada estruturada. Agentes de IA parseiam REQ IDs, AC IDs e cenáriosGIVEN / WHEN / THENde forma determinística — não há nada para interpolar. Planos precisam citar os AC IDs que cada tarefa satisfaz, então o que foi construído é sempre verificável contra o que foi especificado.

• 🔁 Você paga em dobro por uma especificação vaga.

  O agente constrói algo a partir de um brief ambíguo, você percebe que está errado e pede de novo — de quatro formas diferentes. Cada funcionalidade pela metade e cada nova tentativa são cobradas em tokens. Quanto mais vaga a especificação, mais rodadas até acertar.

  A solução

  Faça lint da especificação antes de o agente rodar.specscore lint rejeita verbos vagos e critérios de aceitação ausentes logo de início, então o agente implementa um brief concreto de uma vez em vez de adivinhar entre tentativas. A execução mais barata é a que você não precisa repetir.

• 💸 Agentes pagam para reler suas especificações.

  Um agente de IA respondendo "o que depende dessa feature?"lê o README inteiro da feature. Depois cada índice pai. Depois features irmãs por garantia. Toda consulta é um re-parse. Tokens evaporam; a latência sobe; a conta sobe junto.

  A solução

  Consultas estruturadas em vez de leituras de arquivo.specscore feature tree devolve a hierarquia em YAML; feature deps percorre a cadeia transitiva de dependências; feature info expõe status, dono e perguntas em aberto — cada uma em uma única chamada. O agente navega o grafo, não a prosa.

• 🔗 O código esquece sua especificação.

  Seis meses depois, você está debugando uma função e ninguém lembra qual feature ela implementa. A ligação entre código e especificação vivia na cabeça de alguém, e essa pessoa saiu. O PR que a introduziu está no arquivo morto.

  A solução

  Anotações no código-fonte. Comentários como// specscore: features/checkout/apply-discount/R1.AC-2tornam a ligação legível por máquinas e sobrevivem a qualquer refatoração.specscore code deps responde"qual especificação este arquivo implementa?" em uma única chamada; o linter sinaliza referências que apontam para especificações deletadas.

• 🏷️ Mudanças de status vazam.

  Você move uma feature de Draft para Approvedno README dela, mas o features-index pai ainda a lista como Draft. Três semanas depois, um agente lendo o índice acha que ela ainda está em definição. O status agora vive em dois lugares, e eles discordam.

  A solução

  specscore feature change-status reescreve o campo Status da feature e ressincroniza a linha no features-index num único passo atômico — se o lint falhar, a reescrita é revertida. O status existe em um único lugar canônico; o índice é uma visão gerada dele.

• 📋 As especificações esquecem o que não sabem.

  Uma especificação parece acabada — até você lembrar que a pergunta"e quanto aos fusos horários?" se perdeu numa thread do Slack há dois meses e nunca chegou ao documento. Agora vocês estão na implementação, e ninguém sabe dizer qual era a resposta.

  A solução

  Toda feature SpecScore tem uma seçãoOutstanding Questions obrigatória. O linter rejeita features que a omitem — vazio tudo bem ("None at this time."), mas faltar não pode. Perguntas em aberto ficam visíveis no documento, consultáveis pela CLI, e impossíveis de esquecer.