Skill Reviewer

A skill reviewer é a etapa VALIDATE do fluxo de desenvolvimento do Archgate. Ela verifica cada alteração de código em relação aos Architecture Decision Records (ADRs) do projeto e bloqueia qualquer coisa que se desvie de uma decisão documentada. Ela é executada após o código ser escrito e antes do commit.

O que ela faz

O reviewer reúne todos os dados de que precisa em uma única chamada archgate review-context e então delega a verificação a sub-agentes focados — um por domínio afetado, mais um sub-agente Geral/Processo sempre ativo. Cada sub-agente é executado em sua própria janela de contexto, de modo que ler todos os arquivos alterados nunca esgota o contexto do agente pai; apenas o relatório conciso de conformidade retorna.

Ela impõe quatro coisas em cada alteração:

• Os ADRs relevantes ao domínio foram lidos antes da implementação
• O código cumpre todos os ADRs aplicáveis (os Do’s e Don’ts)
• Não há desvio arquitetural das decisões documentadas
• A estrutura de arquivos, as convenções de nomenclatura e os limites de dependência são respeitados

Requisito de pré-validação

O reviewer pressupõe o fluxo do agente desenvolvedor, que exige que os ADRs sejam lidos antes de escrever código. Ele valida o resultado desse fluxo — não é um substituto para ler os ADRs de antemão.

Como funciona

1. Reúne o contexto. Ela executa archgate review-context --run-checks, que retorna todos os arquivos alterados, esses arquivos agrupados por domínio com os briefings dos ADRs aplicáveis (Decisão mais Do’s e Don’ts) e o resumo das verificações automatizadas — tudo em uma única resposta JSON. Por padrão, ela inspeciona as alterações não preparadas (unstaged) em relação ao branch principal; --staged é usado somente quando os arquivos foram explicitamente preparados.

2. Interrompe em caso de falhas automatizadas. Se o resumo das verificações automatizadas reportar uma falha, o reviewer bloqueia imediatamente e reporta as falhas — ele não avança para a revisão manual até que sejam corrigidas. Se não houver arquivos alterados, ele reporta como aprovado, sem necessidade de revisão.

3. Lança sub-agentes de domínio em paralelo. Para cada domínio afetado, ele cria um sub-agente (sempre incluindo um sub-agente Geral/Processo). Cada um recebe sua lista de arquivos alterados e os briefings de ADR relevantes inline, lê cada arquivo e o verifica em relação aos Do’s e Don’ts. Os sub-agentes rodam em um modelo leve, porque isso é uma verificação de checklist, não raciocínio aberto.

4. Agrega os resultados. Assim que cada sub-agente retorna, o reviewer produz um único relatório compacto de conformidade.

Formato de saída

A skill retorna um veredito conciso e estruturado — APPROVED ou BLOCKED — com um detalhamento por domínio e a contagem de violações e avisos:

## Reviewer: APPROVED
- Automated checks: PASS (3/3)
- General/Process: PASS
- Backend: PASS_WITH_WARNINGS
- Violations: 0 | Warnings: 1
⚠ BE-002 src/api/handler.ts — Error responses use string messages instead of
  the error code enum. Not a violation but drifts from the recommended pattern.

As regras de decisão são rígidas:

• APPROVED — todas as verificações automatizadas passam e todo domínio retorna PASS ou PASS_WITH_WARNINGS. Todo aviso é listado para que você possa tomar uma decisão informada; avisos nunca bloqueiam.
• BLOCKED — qualquer verificação automatizada falha ou qualquer domínio retorna FAIL. Cada violação é reportada com seu ID de ADR, caminho do arquivo, número da linha quando possível, o que está errado e como corrigir.
• ESCALATE — a alteração expõe uma lacuna que as regras existentes não cobrem bem. O reviewer a sinaliza para que a skill lessons-learned possa capturá-la.

O relatório é deliberadamente mínimo. Violações de ADR são bloqueios definitivos: o reviewer se recusa a aprovar código não conforme, referencia o ADR violado e fornece orientação de correção.

Como se encaixa no fluxo

O reviewer é a etapa 4 do fluxo do desenvolvedor:

UNDERSTAND → PLAN → WRITE → VALIDATE → CAPTURE
                            (reviewer)

O agente desenvolvedor executa primeiro archgate check para uma validação automatizada rápida e depois invoca o reviewer para a passagem completa e ciente de domínio. Após a aprovação do reviewer, o controle passa para a skill lessons-learned na etapa CAPTURE. Para pequenos ajustes de acompanhamento, o agente pula o reviewer e executa apenas archgate check.

skill lessons-learned A etapa CAPTURE que roda após a aprovação do reviewer.

Nota

Para a sintaxe e a saída exatas de archgate review-context e archgate check, veja a referência autoritativa em cli.archgate.dev.