grill-with-docs

name	grill-with-docs
description	Sessão rigorosa para confrontar plano/proposta com documentação do domínio (CONTEXT, ADRs, regras), alinhar terminologia antes de codar e atualizar docs com decisões aprovadas.
reference	["https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/SKILL.md"]
tools	["Read","Bash"]
activation_hints	["use grill-with-docs","grill with docs","alinhar com contexto","revisar contra ADR","validar plano com docs"]

Skill: Grill With Docs

Mission

Validar a robustez de uma proposta contra o modelo documental do projeto, eliminar ambiguidade de termos e registrar decisões de forma rastreável antes ou durante a especificação.

When to use

• Antes de implementação relevante (mudança de arquitetura, fluxo crítico, API).
• Quando há risco de desalinhamento entre proposta e decisões já documentadas.
• Quando o humano pede validação rigorosa de plano, linguagem e premissas.

Inputs mínimos

• Plano/proposta atual (pode ser PRD, SPEC, plano técnico ou tasks).
• Fontes de referência do domínio:
  • CONTEXT.md (quando existir)
  • ADRs e docs arquiteturais
  • regras RN/RA/RG aprovadas
  • knowledge packs do projeto (quando aplicável)
• Limites de escopo e critérios de sucesso definidos.

Execution protocol

1. Collect doc baseline

• Listar e ler somente os documentos necessários para a proposta.
• Identificar versão/estado de cada fonte (atual, legado, substituído).

1. Extract domain assertions

• Extrair afirmações normativas das fontes:
  • invariantes
  • termos canônicos
  • restrições operacionais
  • decisões arquiteturais ativas
• Marcar conflitos explícitos entre fontes.

1. Stress the proposal

• Confrontar proposta item a item com as afirmações extraídas.
• Classificar cada item como:
  • adherent
  • divergent
  • unknown
• Para divergência, gerar trade-off e impacto por dimensão:
  • negócio
  • arquitetura
  • governança

1. Human decision gate (mandatory)

• Apresentar divergências e opções de decisão ao humano.
• Não avançar para execução enquanto divergências críticas estiverem abertas.
• Se necessário, propor evolução de regra/documento antes do avanço.

1. Update docs from approved decisions

• Aplicar apenas decisões formalmente aprovadas.
• Atualizar:
  • CONTEXT.md (quando aplicável)
  • ADR(s) afetadas
  • referência cruzada no artefato SDD atual
• Garantir rastreabilidade (o que mudou, por que mudou, qual decisão aprovou).

1. Closeout

• Emitir resumo final com:
  • aderências
  • divergências resolvidas
  • pendências remanescentes
• Declarar prontidão para seguir ao próximo gate (Refiner/Executor).

Davi governance gates

• Divergência com RN/RA/RG aprovadas exige decisão humana formal.
• Mudança de escopo deve retornar ao fluxo de refinamento SDD.
• Sem decisão formal, status deve permanecer blocked.

Output obrigatório

• Status: ready | blocked
• Docs analisados e versão/estado
• Mapa de aderência (adherent, divergent, unknown)
• Decisões humanas registradas
• Atualizações documentais aplicadas
• Riscos residuais e próximo passo recomendado

Quality rules

• Sem implementação de código nesta skill.
• Sem alteração silenciosa de regras/documentos.
• Toda mudança documental deve apontar para decisão aprovada.
• Terminologia deve permanecer consistente com contexto canônico.