SPEC.md

SPEC — conductor

Spec viva do conductor: descreve o comportamento atual da skill (o que já está implementado e validado), não o que está planejado. É a fonte de verdade do que a skill faz; o SKILL.md é a implementação dela.

• Mudanças entram como spec de rodada publicada no tracker (issue, via /to-spec) — ver "Histórico de rodadas" no fim. Ao fechar a rodada, o delta é incorporado aqui.
• Visão de longo prazo e o princípio que não muda ficam em ROADMAP.md; plano de tarefas em tasks/plan.md.

Estado consolidado: v1.0 → v1.8.

Problem Statement

O usuário mantém vários projetos em estágios muito diferentes de maturidade (do zero; maduro com processo formalizado; legado maduro sem processo de IA formalizado) e usa um pipeline de skills de spec development (descoberta → sharpen/modelo de domínio → spec formal → quebra em tarefas → implementação → revisão) que é poderoso mas fragmentado: nenhuma skill sabe dizer "você está aqui, o próximo passo é ali". É fácil pular uma etapa (ex: escrever tarefas sem spec formal) sem perceber.

Além do pipeline de spec, o projeto acumula artefatos vivos (board de fases, diagrama de arquitetura, fluxo de tela, artefatos de QA) que ficam desatualizados em silêncio quando a decisão que eles registram muda — e nem todo artefato faz sentido pra todo tipo de projeto.

E um estágio pode estar "feito" sem nada checando a qualidade do que ele produziu: diagrama registrado que ninguém valida, lint que só roda quando alguém lembra, gate vermelho há semanas — e a recomendação de avançar sai como se estivesse tudo bem.

Solution

Uma skill global (conductor) que lê o estado real de um projeto e sua convenção específica, diz exatamente qual skill do pipeline chamar agora, e mantém os artefatos vivos do processo rastreados contra sua fonte de verdade, e reconhece os gates de qualidade que cada estágio/artefato deveria ter — verificando o estado real deles e avisando, sem travar, antes de recomendar avançar. Ela identifica o que falta ou ficou pra trás e conduz o usuário até a peça certa — nunca é ela quem cria, mantém ou melhora a pipeline por conta própria. Nunca dispara as skills sensíveis (marcadas como manuais), e nunca decide sozinha entre alternativas: recomenda, o usuário decide.

Objetivos e critérios de sucesso

Objetivo	Critério verificável (via eval)
O usuário sabe o próximo passo sem reler o pipeline	Resposta nomeia estágio atual + próxima skill + motivo amarrado ao estado do repo
Nenhum trabalho pronto é refeito	Em projeto maduro, não recomenda spec/planejamento que já existe (mature-feature)
Projeto legado não é tratado como ideia nova	Não recomenda wayfinder/grilling de descoberta em legado (legacy-project)
Controle do usuário sobre ações caras	Nunca invoca skill manual; devolve o comando exato (todos os casos)
Artefato vivo não fica desatualizado em silêncio	Avisa divergência e aponta a skill certa, sem regenerar (non-board-artifact-staleness)
Recomendação proporcional ao projeto	Não oferece artefato de UI a projeto headless (headless-project-no-ui-recommendation)
Pergunta só uma vez	Recusa de tipo de artefato registrada no projeto não é perguntada de novo (board-tool-refusal-remembered)
Qualidade do estágio não passa em silêncio	Sinaliza gate esperado ausente citando fonte e confiança (quality-gate-expected-missing)
Estado de gate nunca é presumido	Roda o gate ou reporta "não verificado" (quality-gate-failing, quality-gate-ci-unverifiable)
Aviso, não trava	Gate vermelho é avisado antes de recomendar avançar, e a decisão continua do usuário (quality-gate-failing)
Skill agrega sobre o baseline	with_skill ≥ baseline em todos os casos de evals/evals.json
Custo de contexto proporcional ao caso	Instrução condicional só é lida quando o gatilho dispara; tokens por run caem sem nenhum caso piorar (regressão da v1.5)

Estado atual desse último critério (regressão completa da v1.4, 16 casos em fixtures isoladas, formato oficial): with_skill 100%, baseline 77,9%; nenhuma regressão. Empate com o baseline em mature-feature, legacy-project, board-tool-precedent-non-notion, board-tool-first-ask, board-tool-refusal-remembered, headless-project-no-ui-recommendation e quality-gate-not-triggered — o modelo com as skills de SDD instaladas já faz isso sozinho. Detalhes e limites em evals/results-v1.4.md.

Custo (regressão da v1.5, 18 casos, só with_skill): nenhum caso piorou; média por run 70,7k → 66,7k tokens; o custo próprio da skill (run com skill − run sem skill) caiu ≈ 20%. Detalhes em evals/results-v1.5.md; números por run em evals/benchmarks/.

User Stories

Orientação no pipeline

1. Como desenvolvedor solo com vários projetos ativos, quero perguntar "onde estamos"/"o que eu faço agora" em qualquer repositório, para não precisar lembrar em que estágio do processo de spec cada projeto está.
2. Como desenvolvedor começando um projeto do zero, quero que a skill reconheça a ausência total de convenção/spec e recomende a descoberta certa (wayfinder para escopo grande/multi-sessão, grilling para escopo menor), para não pular direto para tarefas.
3. Como desenvolvedor num projeto maduro com pipeline formalizado, quero que a skill leia o estado real (specs, tarefas, milestones, issues — conteúdo, não só existência de arquivo) antes de recomendar, para não ser mandado a refazer planejamento pronto.
4. Como desenvolvedor num projeto legado sem processo formalizado, quero que a skill reconheça sinais de maturidade (histórico de commits, volume de código, estrutura de solução) e recomende mapear o sistema existente, não descobrir uma ideia nova.
5. Como desenvolvedor num projeto legado, quero que a skill encontre convenções em formatos de outras ferramentas de IA (.cursor/rules, .github/copilot-instructions.md, .windsurfrules), inclusive exigências de artefato de planejamento obrigatório.
6. Como desenvolvedor num projeto legado, quero que a skill minere ~3 commits de mudanças parecidas e compare os arquivos tocados, para derivar a convenção praticada — e diga quando os três divergem, em vez de inventar um padrão.
7. Como desenvolvedor, quero que a convenção do projeto (CLAUDE.md ou equivalente) tenha precedência sobre a ordem genérica do pipeline.
8. Como desenvolvedor, quero ser avisado proativamente quando estiver pulando uma etapa (ex: tarefas sem spec), só com a recomendação — sem a skill disparar nada sozinha.

Controle sobre invocação

9. Como desenvolvedor, quero que a skill nunca dispare as skills manuais (disable-model-invocation: true), apenas devolva o comando exato.
10. Como desenvolvedor, quero que a skill ofereça chamar diretamente as skills não manuais do pipeline quando fizer sentido.
11. Como desenvolvedor, quero que a skill nunca edite o frontmatter de outra skill.

Catálogo e avaliação de skill nova

12. Como desenvolvedor, quero ver as skills do pipeline ordenadas por estágio, com uma frase curta de cada.
13. Como desenvolvedor, quero que o catálogo seja lido dinamicamente das skills instaladas, para que uma skill nova apareça sem editar o conductor.
14. Como desenvolvedor, quero propor uma skill nova e receber uma avaliação (complementa / substitui / redundante) contra o que já existe no mesmo estágio, sem a skill decidir qual fica.
15. Como desenvolvedor, quero que essa avaliação considere precedente já registrado no projeto (skill parecida já aceita/rejeitada).
16. Como desenvolvedor, quero poder pedir — ou receber a oferta, quando a leitura ficar ambígua — uma avaliação quantitativa via skill-creator, nunca disparada automaticamente.
17. Como desenvolvedor, quero que um roteador estático já instalado (ex: ask-matt) seja tratado como vocabulário do pipeline, com a recomendação final vindo da leitura de estado.

Artefatos vivos

18. Como desenvolvedor, quero que a ferramenta de cada tipo de artefato siga o precedente do projeto; sem precedente, a disponível na sessão; com mais de uma, que a skill pergunte — nenhuma ferramenta é padrão por definição.
19. Como desenvolvedor, quando o precedente registrado não bater com o que o conector encontra, quero ver o que foi encontrado e escolher, em vez de só uma confirmação de identidade.
20. Como desenvolvedor sem ferramenta disponível, quero ser perguntado uma única vez por projeto e por tipo de artefato; se recusar, que a recusa fique registrada no projeto alvo e nunca mais seja perguntada ali — e que recusar um tipo não se estenda aos outros.
21. Como desenvolvedor, quero um board de fases com página-hub do projeto e uma subpágina por fase contendo o grafo de dependência das tarefas (Mermaid ou formato nativo), com tarefas como nós — nunca páginas próprias.
22. Como desenvolvedor, quero que a skill nunca crie página esporádica sem perguntar, recomendando nota na fase atual (pontual) ou subpágina dedicada (grande).
23. Como desenvolvedor, quero que qualquer artefato vivo registrado (board, diagrama de arquitetura, fluxo de tela, QA — lista aberta) seja checado contra sua fonte de verdade, e que a skill avise e aponte a skill de regeneração quando divergir, sem regenerar sozinha.
24. Como desenvolvedor, quero que conector indisponível nunca bloqueie o resto da orientação — só avise que aquela parte ficou pendente.

Tipo de projeto

25. Como desenvolvedor, quero que a skill reconheça se o projeto tem UI (web, mobile, desktop) ou é headless, e não ofereça fluxo de tela/design de UI a projeto headless.
26. Como desenvolvedor com projeto ambíguo (ex: backend com painel admin), quero ser perguntado em vez de a skill presumir.
27. Como desenvolvedor, quero poder pedir um artefato fora do perfil detectado e ser atendido — a detecção filtra recomendação, não trava pedido.

Gates de qualidade

28. Como desenvolvedor, quero saber, ao perguntar "onde estamos", se os gates de qualidade esperados do estágio atual existem e estão passando — não só se o estágio está "feito".
29. Como desenvolvedor, quero que "qual gate é esperado onde" seja uma régua fixa da skill (lista aberta), filtrada pelo tipo e pela stack do projeto.
30. Como desenvolvedor, quero que a expectativa de um gate venha de uma fonte explícita — convenção, artefato registrado, projeto irmão, ou só sugestão de baixa confiança — e que a resposta diga a fonte e a confiança.
31. Como desenvolvedor, quero que o estado do gate seja verificado de verdade (rodando o gate, ou lendo a última run de CI com data) e reportado como "não verificado" quando não der para checar.
32. Como desenvolvedor, quero ser avisado quando um gate existe mas não roda no momento em que deveria (ex: convenção pede pre-commit e não há hook).
33. Como desenvolvedor, quero ser avisado de gate vermelho antes de qualquer recomendação de avançar, podendo seguir mesmo assim — aviso, não trava.
34. Como desenvolvedor, quero que a skill nunca crie nem configure gate sozinha; com precedente claro e risco baixo, que só ofereça o setup, e pergunte quando houver mais de uma ferramenta possível.

Custo de contexto

35. Como desenvolvedor que usa a skill em toda tarefa, quero que cada execução ocupe pouco da janela de contexto, carregando instrução condicional só quando o caso se aplica.
36. Como desenvolvedor, quero que os fatos mecânicos do projeto (convenção, maturidade, tipo, artefatos do pipeline, git, onde cada gate roda, última run de CI, precedente dos irmãos) venham de um script só leitura, com resultado igual para o mesmo estado e "indisponível" com motivo quando uma fonte falha.
37. Como desenvolvedor, quero que a saída do script seja mapa do que abrir, nunca conclusão de que uma etapa está completa.
38. Como desenvolvedor, quero que a orientação continue se o script falhar, com a mesma leitura feita à mão.

Reconsulta e catálogo completo

39. Como desenvolvedor, quero ser lembrado de voltar a consultar o conductor a cada checkpoint da pipeline (fim da skill recomendada, antes do próximo estágio, PR aberta/mergeada, mudança de foco) — não só no início da tarefa.
40. Como desenvolvedor, quero que o catálogo enxergue também as skills instaladas via plugin de marketplace, não só as globais/do projeto.
41. Como desenvolvedor, quero que a skill some ao catálogo do script as skills que a própria sessão já sabe estarem disponíveis, pra cobrir o que o script nunca vai conseguir ler em disco (skill embutida no host).
42. Como desenvolvedor, quero que a skill diga explicitamente quando nenhuma skill cobre o estágio recomendado (apontando find-skills quando instalada), em vez de inventar um passo ou ficar em silêncio — e quero poder registrar esse estágio na tabela de referência mesmo sem skill ainda, informando se ele tem gate.

Gates de transição

43. Como desenvolvedor, quero ver numa tabela única todos os portões que o conductor aplica entre etapas do pipeline (gatilho, sinal, tipo do sinal, consequência, ação), em vez de ter que ler o SKILL.md inteiro pra saber o que ele vai exigir.
44. Como desenvolvedor, quero que os portões hoje implícitos nos Passos 2, 4 e 6 (etapa sem a anterior completa, skill manual, reconsulta a cada checkpoint, artefato vivo desatualizado) e o aviso de gate de qualidade vermelho (v1.4) virem linhas dessa tabela, numa única fonte da regra.
45. Como desenvolvedor, quero que um sinal checável por comando seja avaliado por um script determinístico (mesmo estado → mesmo resultado), e que um sinal de julgamento nunca seja apresentado como se fosse mecânico.
46. Como desenvolvedor, quando um gatilho afeta mais de uma consequência, quero cada uma reportada separadamente, nunca resumida num único veredito.
47. Como desenvolvedor com um artefato vivo registrado, quero ser avisado quando a área que ele acompanha muda depois da última atualização dele, com o vínculo vindo sempre do registro do Passo 6 — nunca inventado; sem registro, o gate é "não avaliado", nunca presumido.
48. Como desenvolvedor, quero que uma spec sem user stories não siga para a quebra em tarefas, e que uma rodada não feche com story sem nenhum caso de verificação vinculado — um caso pode cobrir várias stories, e uma story estrutural (não comportamento) pode ser marcada não-verificável com justificativa, conferida ao fechar a rodada. Esses gates valem a partir de quando entram em produção, sem reabrir rodada já fechada.
49. Como desenvolvedor, quero que um gate disparado resulte em aviso e em não recomendar avanço, nunca em bloqueio mecânico — a decisão de seguir mesmo assim é minha; se eu quiser um portão que feche de verdade, quero que o conductor aponte o caminho (hook via update-config, ou check de CI) sem instalar nada sozinho, e sem nunca sobrepor o disable-model-invocation de skill de terceiro.
50. Como desenvolvedor de projeto headless, quero que gates ligados a artefato de UI não sejam avaliados, coerente com o filtro de tipo de projeto.
51. Como mantenedor do conductor, quero que a tabela de gates só mude por rodada neste repositório (spec + eval); em runtime, uma skill nova sem gate conhecido só gera proposta e pergunta, nunca edição direta da tabela.

Lembrete de reconsulta via TodoWrite

52. Como usuário, quero que o lembrete de reconsulta (G3/G4/G5) fique visível entre turnos, para não perder de vista a recomendação porque a conversa seguiu para outro assunto.
53. Como usuário, quero que esse lembrete seja marcado como concluído automaticamente quando eu de fato reconsultar a skill, para não acumular item obsoleto na minha lista de tarefas.
54. Como usuário, quero que o mesmo gatilho não crie um lembrete duplicado se eu ainda não resolvi o anterior.
55. Como usuário, quero que o texto do lembrete diga qual gatilho o disparou (skill terminou, PR aberta/mergeada, ou foco mudou).
56. Como usuário, quero que esse mecanismo nunca bloqueie nem falhe nenhuma ação, continuando consistente com "avisa, nunca trava" (ADR 0001), e que funcione sem nenhuma configuração extra.
57. Como usuário que trabalha em mais de um projeto ao mesmo tempo, quero que o lembrete não se confunda entre sessões/projetos diferentes.
58. Como mantenedor, quero que a distinção sinal mecânico/julgamento de G3/G4/G5 continue intacta (TodoWrite é consequência adicional, não gate novo), sem exigir mudança em scripts/check-gates.sh.
59. Como mantenedor, quero documentação explícita no SKILL.md e um caso de eval cobrindo o comportamento, para que mudanças futuras no Passo 8 não regridam essa regra silenciosamente.
60. Como mantenedor, quero que os gates de sinal mecânico (G1, G2, G6-G10) continuem sem esse comportamento, restrito ao problema real (reconsulta esquecida).

Gráficos de custo × ganho no README

61. Como alguém avaliando se instala o conductor, quero ver no README quanto a skill custa em tokens por execução, para estimar o impacto no orçamento de contexto antes de instalar.
62. Como alguém avaliando se instala o conductor, quero ver no README quanto a skill custa em tempo por execução, para saber se o ganho compensa a latência.
63. Como alguém avaliando se instala o conductor, quero ver o ganho de qualidade (nota com a skill vs. sem ela) ao lado do custo, para decidir com os dois lados da troca visíveis juntos.
64. Como alguém avaliando se instala o conductor, quero ver esses números por versão, para entender se o custo ou o ganho mudou ao longo do tempo.
65. Como mantenedor, quero que o gráfico seja gerado por um script a partir de evals/benchmarks/<versão>.json, nunca desenhado à mão, para que ele nunca desalinhe dos números reais.
66. Como mantenedor, quero rodar esse script de novo a qualquer momento e obter o mesmo resultado a partir dos mesmos arquivos de entrada, para confiar que o gráfico no README reflete os dados versionados.
67. Como mantenedor, quero que o script leia todos os evals/benchmarks/*.json existentes automaticamente, para não ter que listar versões à mão quando uma rodada nova registrar benchmark.
68. Como mantenedor, quero que uma versão sem comparação with_skill vs. without_skill (ex: v1.5) apareça só com a barra que tem, sem forçar uma barra de ganho inexistente.
69. Como mantenedor, quero que o modelo e a data de cada rodada apareçam junto do gráfico, para que a leitura não presuma que todas as rodadas usaram o mesmo modelo.
70. Como mantenedor, quero que o script nunca leia nem exponha response.md/evidência de eval, usando só os números já presentes em evals/benchmarks/, para manter a mesma regra de privacidade já aplicada a esses arquivos.
71. Como mantenedor, quero que os arquivos gerados sejam versionados no repositório, para que o README renderize o gráfico sem depender de geração em tempo real no GitHub.
72. Como mantenedor, quero que a linha do README sobre "estrutura de acompanhamento no Notion" seja corrigida para descrever o Passo 6 atual, para o README não contradizer o que a skill faz desde a v1.1.
73. Como mantenedor, quero que a tabela antiga da seção "Qualidade" seja substituída pelo gráfico multi-versão, sem duplicar a mesma informação em dois formatos divergentes.
74. Como mantenedor, ao fechar uma rodada futura com benchmark novo, quero só rodar o script de novo e commitar o resultado, sem editar nenhuma tabela ou imagem do README à mão.
75. Como mantenedor, quero um teste determinístico do script de gráfico, para pegar regressão na geração sem depender de inspeção visual a cada rodada.

Implementation Decisions

• Skill global, não por projeto: funciona em qualquer repositório sem configuração.
• Módulos: SKILL.md (frontmatter + processo em 7 passos + gatilhos), script de estado (sinais mecânicos do projeto alvo em JSON), script de catálogo (name / description / manual de cada skill instalada, lido do frontmatter na hora) e referências. Sempre lidas: estágios do pipeline e tabela de tipos de gate (artefato/estágio → gate → ferramenta → comando → quando deveria rodar, e o que conta como gate existente). Lidas só por gatilho: projeto sem convenção, tipo de projeto, avaliação de skill nova, artefatos vivos, detalhe dos gates e leitura de estado manual (plano B).
• Carga sob demanda (ADR 0002): o SKILL.md tem só o fluxo que roda sempre, as regras de proteção e os gatilhos; o corte é por caso, não por passo. Gatilhos são condições sobre campos da saída do script, exceto "o usuário propôs uma skill" (julgamento). Regras de proteção nunca ficam atrás de gatilho.
• Script de estado (bash, sem dependência nova, JSON sem jq): grupos convencao, maturidade, tipo_projeto, pipeline, artefatos, git e gates (ferramentas da tabela de gates, pontos de execução, última run de CI, irmãos). Só lê: nunca roda comando do projeto nem escreve. Fonte que falha vira indisponivel com motivo. A lista de ferramentas vem da tabela de tipos de gate (fonte única).
• Auto-invocável (sem disable-model-invocation): só informa/recomenda, sem efeito colateral irreversível. Reabrir isso exige decisão explícita.
• Skills manuais nunca invocadas: bloqueio mecânico da ferramenta de skill, reforçado como regra explícita. Qual skill é manual vem sempre do catálogo, não da lista de exemplo.
• Nomes de skill são exemplo: a referência de estágios não hardcoda nomes como universais; o catálogo é a fonte de verdade do que está instalado.
• Processo em 7 passos:
  1. Script de estado como mapa; convenção do projeto (CLAUDE.md/AGENTS.md); por gatilho: convenção de outra ferramenta, legado (maturidade sem convenção, mineração de ~3 commits), projeto novo e detalhe do tipo de projeto (UI / headless / ambíguo). Script falhou → leitura manual.
  2. Estado do projeto em ordem (modelo de domínio/ADR → spec formal → tarefas com critério de aceite → implementação em andamento → PR em revisão); o primeiro "não" indica o próximo passo; ler conteúdo e índice, nunca concluir por grep solto.
  3. Catálogo dinâmico (script + plugins de marketplace + skills da própria sessão) cruzado com a referência de estágios; skill fora da tabela vira candidata a entrar nela (pergunta ao usuário o estágio); estágio sem skill nenhuma é dito explicitamente (aponta find-skills) e pode ser registrado na tabela com gate sim/não/não verificado.
  4. Recomendação no formato "Você está em X. O próximo passo é Y — motivo"; manual → devolve comando e para; não manual → oferece invocar. Reconsulta a cada checkpoint da pipeline, não só no início da tarefa.
  5. Por gatilho (usuário propõe skill): avaliação por leitura + precedente do projeto, com escalada opt-in para avaliação quantitativa via skill-creator.
  6. Artefatos vivos: sem nada registrado, pergunta única; com artefato ou recusa registrados (ou ao registrar), por gatilho: escolha de ferramenta (precedente → disponível → pergunta única), estrutura do board, detecção de desatualização por artefato, degradação.
  7. Gates de qualidade: esperados pela referência (filtrados por tipo e stack), confiança pela fonte, existência (script, CI ou hook), estado real ou "não verificado", acionamento no momento esperado; lacuna sempre com fonte e confiança. Parte mecânica vem do script; o detalhe, por gatilho (há gate configurado, irmão, artefato ou convenção que exige gate). O Passo 4 avisa gate vermelho antes de recomendar avançar. Setup só oferecido, executado com aprovação.
• Decisões persistidas no projeto alvo, nunca no conductor (recusa de artefato, registro de artefato: onde vive + fonte de verdade que acompanha).
• Tipo de projeto é filtro de recomendação, nunca trava.
• Avisa, nunca bloqueia (ADR 0001): a ação mais forte diante de um gate é avisar e deixar de recomendar avanço.
• Gates de transição (references/transition-gates.md): tabela declarativa gatilho → consequência (id, sinal verificável, tipo — mecânico | julgamento —, consequência, ação). Consolida os portões que antes viviam em prosa nos Passos 2/4/6 e o aviso de gate de qualidade vermelho (v1.4), mais os gates de rastreabilidade SDD (spec sem stories; story sem caso de verificação, com cobertura n:1 e marcação de não-verificável). Passo 8 do SKILL.md roda scripts/check-gates.sh (sinais mecânicos, saída determinística) e soma a interpretação dos sinais de julgamento, reportando toda linha disparada antes de fechar a recomendação do Passo 4. Binding de artefato vivo vem só do registro do Passo 6; sem registro, "não avaliado", nunca inventado. Evolução da tabela só por rodada neste repositório — em runtime, skill sem gate conhecido (G10) só gera proposta + pergunta, gravada no registro local do usuário (nunca nas tabelas embutidas da skill).
• Lembrete de reconsulta via TodoWrite: quando G3, G4 ou G5 dispara, o Passo 8 chama TodoWrite registrando um item pendente de "reconsultar o conductor", citando o motivo do gatilho, além do aviso em prosa já existente. Dedup: não duplica item pendente — só atualiza o motivo. O Passo 1 marca esse item como concluído ao rodar de fato numa consulta nova. Não muda scripts/check-gates.sh nem a classificação de sinal/ação de G3/G4/G5 (continuam julgamento/avisar). Hosts sem a tool TodoWrite (ex: extensões fora do Claude Code CLI) não têm onde executar essa instrução hoje — lacuna registrada no ROADMAP.md.
• Gráficos de custo × ganho no README: scripts/generate_benchmark_charts.py lê todos os evals/benchmarks/*.json (sem argumento de versão) e gera docs/benchmarks/custo.svg (tokens e duração medianos por execução) e ganho.svg (taxa de acerto with_skill vs. without_skill), versionados no repositório; SVG construído por código puro (stdlib Python, sem lib de plotting), nunca editado à mão. Versão sem uma das duas configs (ex: v1.5, que reaproveita o baseline sem skill da v1.4) desenha só a barra que tem. Modelo e data de cada versão aparecem como legenda, lidos dos mesmos campos já presentes em evals/benchmarks/<versão>.json. README (seção "Qualidade") embute os dois SVGs em vez da tabela fixa anterior (só cobria a v1.4); item 6 de "Como funciona" corrigido para não descrever Notion como estrutura fixa de acompanhamento. Rodada de infraestrutura de documentação do próprio repositório — nenhuma mudança de comportamento do SKILL.md.

Testing Decisions

• Seam 1, eval: framework de eval do skill-creator — subagente com a skill (with_skill) vs. subagente baseline, mesmos prompts, sempre em paralelo; avaliação por comparação contra expected_output em prosa, não assertion determinística de string.
• Testa comportamento externo do SKILL.md inteiro (a recomendação que o usuário recebe), não passos isolados.
• Casos cobertos (evals/evals.json): fresh-project, mature-feature, skill-evaluation, legacy-project, board-tool-precedent-non-notion, board-tool-first-ask, board-tool-refusal-remembered, board-tool-precedent-mismatch, non-board-artifact-staleness, headless-project-no-ui-recommendation, quality-gate-expected-missing, quality-gate-low-confidence, quality-gate-failing, quality-gate-ci-unverifiable, quality-gate-not-triggered, quality-gate-setup-offered-not-executed, tasks-without-acceptance-criteria (#27; não reproduziu o bug, fica como proteção da regra do Passo 2), combined-legacy-with-live-artifact (vários gatilhos juntos: legado sem convenção + diagrama registrado desatualizado + sinal de UI). Resultados em evals/results-*.md.
• Fixtures isoladas: todo caso com estado roda numa cópia de evals/files/<fixture> com git próprio, uma por run (scripts/prepare_fixture.sh); estado que não cabe em arquivo (histórico longo, pasta sem git) vem de um gancho de setup. A comparação com o baseline só é válida a partir da v1.4: antes disso os casos citavam projetos reais e descreviam o estado no próprio prompt.
• Seam 2, teste do script de estado: scripts/test_state.sh roda o script contra cada fixture (preparada como no eval) e compara com evals/state-expected/, com datas, branch padrão e tamanhos normalizados; job state-script no CI.
• Seam 3, teste do script de gates: scripts/test_check_gates.sh roda scripts/check-gates.sh contra fixtures (spec-sem-stories, spec-com-stories, pasta-vazia, story-sem-verificacao, story-justificada) e compara com evals/check-gates-expected/; campo DISPARADO/MOTIVO de G10 normalizado (depende do catálogo da máquina que roda); inclui caso de saída estável entre execuções. Casos de eval novos desta rodada: two-gates-triggered-separately, spec-without-user-stories (nome interno spec-sem-stories no fixture), story-without-verification-case. Cobertura das 26 user stories da spec #25 registrada no campo stories de cada caso de evals/evals.json (incluindo retag retroativo de casos anteriores à #25 que já exercitavam o mesmo comportamento, ex.: non-board-artifact-staleness → stories 9 e 10) e no array stories_nao_verificaveis para as estruturais/de processo (ex: existência e schema da própria tabela, estilo de saída do script, regra de não retroatividade) — conferido ao fechar a rodada.
• Custo controlado: toda execução de eval só com aprovação explícita do usuário. Rodada de refatoração compara with_skill contra a rodada anterior (sem refazer baseline sem skill); 1 run por caso, 3 no gatilho de julgamento; smoke test de poucos casos durante o desenvolvimento. Números por run versionados em evals/benchmarks/<versão>.json (scripts/benchmark_summary.py), nunca as respostas brutas.
• Formato oficial do skill-creator (run-N + grading.json), com assertions tiradas do expected_output e fixadas antes das runs.
• Validações em execução real (fora do eval): Passo 6 com Notion num projeto piloto; seam rodado pelos scripts oficiais do skill-creator (aggregate_benchmark, generate_review.py); escalada quantitativa do Passo 5 com par sintético propositalmente ambíguo.
• Regra: passo/comportamento novo no SKILL.md exige caso novo em evals/evals.json antes de a rodada fechar.
• Prior art: a iteração 1 de mature-feature expôs que a skill (e a assertion) presumiam falta de spec sem ler tasks/plan.md a fundo — origem da regra "ler conteúdo, não só existência".
• Seam 4, teste do gerador de gráficos: scripts/test_generate_benchmark_charts.sh roda scripts/generate_benchmark_charts.py contra os evals/benchmarks/*.json já versionados e compara a saída entre duas execuções (determinismo) e contra o SVG comitado (drift); job benchmark-chart-script no CI. Não é caso de eval: a rodada v1.8 não muda o comportamento do SKILL.md recomendado a um projeto alvo — é infraestrutura do próprio repositório, por isso todas as stories 61–75 ficam em stories_nao_verificaveis, cobertas por este seam de script e checagem manual do README renderizado.

Out of Scope

• Criar, configurar ou implementar qualquer parte da pipeline (spec, artefato, gate) — isso é da skill/ferramenta que o conductor aponta.
• Invocar skills manuais, mesmo que fosse possível.
• Plataforma de orquestração de terceiro para gerenciar projetos — avaliada e rejeitada (resolve outro problema; proveniência de código não confiável).
• Kernel de pontuação determinístico sempre ligado para avaliar skills — overhead desproporcional; avaliação quantitativa fica opt-in.
• Padronização de código (formatação, nomenclatura) — resolvida por ferramenta determinística do projeto (ESLint/Prettier), não por orientação.

Histórico de rodadas

Cada rodada é uma spec de delta no tracker; depois de implementada e validada, foi incorporada acima.

Rodada	Spec	O que mudou	Validação
v1.0	#1	Orientação no pipeline, catálogo, avaliação de skill nova, board no Notion	4 casos de eval + validações reais (#3, #4, #5)
v1.1	#6	Passo 6 agnóstico de ferramenta (Notion deixa de ser obrigatório)	evals/results-v1.1-passo6-agnostico.md
v1.2	#9	Desatualização checada para qualquer artefato vivo, não só board	evals/results-v1.2-v1.3.md
v1.3	#12	Detecção de tipo de projeto filtra recomendação de artefato de UI	evals/results-v1.2-v1.3.md
v1.4	#24	Gates de qualidade: esperados, fonte e confiança, estado real, acionamento, aviso sem trava; casos antigos migrados para fixtures	evals/results-v1.4.md
v1.5	#50	Enxugar o contexto: script de estado, carga sob demanda (ADR 0002), SKILL.md −52%; nenhum comportamento novo	evals/results-v1.5.md
v1.6.1	sem spec formal — #79, #80, #81 (decisão explícita do usuário, 2026-09-29)	Reconsulta a cada checkpoint (Passo 4); catálogo soma plugins de marketplace e skills da sessão (Passo 3); estágio sem skill é dito explicitamente; estágio novo sem skill pode ser registrado com gate	pendente (ver evals/evals.json)
v1.6	#25	Gates de transição como tabela declarativa (references/transition-gates.md + scripts/check-gates.sh, Passo 8), consolidando os portões implícitos dos Passos 2/4/6 e o gate de qualidade vermelho (v1.4); gates de rastreabilidade SDD (spec sem user stories; story sem caso de verificação)	evals/evals.json (26 stories da #25: 13 por caso de eval/retag, 13 por stories_nao_verificaveis) + scripts/test_check_gates.sh
v1.7	#93	Lembrete de reconsulta via TodoWrite nos gates G3/G4/G5 (dedup + conclusão automática no Passo 1); achado em dogfooding real: TodoWrite pode não existir no host (registrado no ROADMAP.md)	evals/evals.json (12 stories da #93: 5 por caso de eval, 7 por stories_nao_verificaveis)
v1.8	#109	Gráficos de custo × ganho no README (scripts/generate_benchmark_charts.py, a partir de evals/benchmarks/*.json); README corrigido (linha do Notion); infraestrutura do próprio repositório, sem mudança de comportamento do SKILL.md	scripts/test_generate_benchmark_charts.sh (Seam 4) + checagem manual do README; 15 stories da #109, todas em stories_nao_verificaveis