revisão-de-código

Skill de Revisão de Código

Revise um PR gerando e respondendo TODAS as perguntas derivadas dos princípios de revisão. Produz um documento final com comentários específicos para o PR e referências aos artefatos de raciocínio.

Como Funciona

Revisão de código é interrogatório: gere perguntas, responda a todas elas, destaque o que não está claro ou é preocupante.

O que esta skill produz:

• Perguntas derivadas dos princípios de revisão
• Respostas para cada pergunta (ou "precisa do autor" explícito)
• Implicações extraídas das respostas
• Preocupações levantadas, organizadas por categoria

O que esta skill NÃO produz:

• Classificações de gravidade (crítico/maior/menor)
• Classificações de bloqueio vs. não bloqueio
• Recomendações de aprovação

Processo: 0. Configuração - Fazer checkout do branch do PR localmente

1. Exploração - Mapeia o território do PR, gera perguntas iniciais (podem ser superficiais)
2. Refinar Perguntas - Preenche lacunas de conhecimento, gera o backlog REAL de perguntas, classifica por tipo
3. Responder Perguntas - Roteia cada pergunta para o manipulador adequado, produz documento de Q&A
4. Pré-Avaliação Holística - Avalia a abordagem usando Q&A (em paralelo com a etapa 5)
5. Revisão por Commit - Revisa cada commit usando Q&A (em paralelo) 5.5. Filtrar Implicações - Decisão binária de exposição + categorização
6. Pós-Avaliação Holística - Reavalia, verifica atendimento a requisitos
7. Sintetizar - Combina em preocupações organizadas por categoria

Tipos de pergunta e manipuladores:

• FATO → skill fact-find (respostas citadas)
• PESQUISA → skill deep-research (documentos educacionais)
• DESIGN → avaliação de design (propor alternativas, avaliar contra princípios)
• CORRETUDE → análise de corretude (rastrear código, verificar comportamento)
• INTENÇÃO → marcado como precisa-do-autor (não pode ser auto-respondido)

Insight chave: Cada pergunta recebe uma resposta explícita e documentada (ou "precisa do autor" explícito). Isso cria artefatos verificáveis.

Entrada

• Referência do PR (URL, número ou branch)
• Opcional: problemas críticos ou documentação identificados pelo usuário

Configuração

Antes de começar, o orquestrador faz checkout do PR:

# No diretório do repositório alvo
gh pr checkout <PR-number>

Pré-requisitos:

• O diretório de trabalho deve ser o repositório que contém o PR
• Sem alterações não commitadas (falhe cedo se estiver sujo)
• GitHub CLI autenticado

Após o checkout, todos os subagentes leem o código do sistema de arquivos local em vez de usar a CLI gh para diffs.

Espaço de Trabalho

Crie planning/<pr-slug>/ para todos os artefatos. Não faça commit destes artefatos — são documentos de trabalho, não entregáveis.

planning/<pr-slug>/
├── 00-scout.md           # Mapa de território inicial
├── 01-questions.md       # Backlog de perguntas refinado e classificado
├── 02-answers.md         # Documento consolidado de Q&A
├── answers/              # Artefatos de resposta individuais
│   ├── fact-Q1.md
│   ├── design-Q2.md
│   └── ...
├── 03-commit-NN.md       # Revisões por commit
├── 04-holistic-pre.md
├── filtered-implications.md  # Implicações categorizadas a serem expostas
├── 05-holistic-post.md
└── REVIEW.md             # Saída final

Protocolo de Subagente

Arquivos a passar: PRINCIPLES.md, o arquivo de instrução do agente, artefatos de fases anteriores

Dados a passar: caminho do workspace, dados específicos da fase

Respostas:

OUTPUT: <filename>
STATUS: ok | problems
NOTES: <if problems>

Confie em STATUS: ok. Em caso de problems, leia as notas e decida.

Acesso ao Repositório

O PR é verificado localmente antes do início da revisão. Os subagentes recebem:

• repo_path: Caminho para o repositório com o PR verificado
• base_ref: O branch base (ex.: main)
• head_ref: O branch do PR (verificado)

Os subagentes leem os arquivos diretamente de repo_path. Use git diff {base_ref}...HEAD para diffs.

Fases

0. Configuração

Faça checkout do PR localmente antes de qualquer análise:

gh pr checkout <PR-number>

Capture base_ref dos metadados do PR para comandos diff.

1. Exploração

Agente: agents/01-scout.md Arquivos: PRINCIPLES.md, arquivo do agente Dados: workspace, repo_path, base_ref, pr_number, contexto do usuário Saída: 00-scout.md

2. Refinar Perguntas

Agente: agents/02-refine-questions.md Arquivos: PRINCIPLES.md, arquivo do agente, 00-scout.md Dados: workspace, repo_path, base_ref, issues/documentação vinculadas Saída: 01-questions.md

Esta fase usa fact-find para preencher lacunas de conhecimento e produz um backlog de perguntas classificado.

3. Responder Perguntas

Para cada pergunta em 01-questions.md, instancie o agente de resposta apropriado:

Tipo	Agente	Saída
FATO	agents/03-answer-fact.md	answers/fact-{id}.md
PESQUISA	agents/04-answer-research.md	answers/research-{id}.md
DESIGN	agents/05-answer-design.md	answers/design-{id}.md
CORRETUDE	agents/06-answer-correctness.md	answers/correctness-{id}.md
INTENÇÃO	(pular—marcar como precisa-do-autor)

Execute os agentes de resposta em paralelo quando possível.

Após todos completarem, consolide em 02-answers.md:

# Perguntas Respondidas

| ID | Tipo | Pergunta | Resumo da Resposta | Detalhe |
|----|------|----------|---------------------|---------|
| Q1 | FATO | ... | ... | [answers/fact-Q1.md] |

## Precisa do Autor
| ID | Pergunta | Por Que Não Podemos Responder |

4. Pré-Avaliação Holística

Agente: agents/07-holistic-pre.md Arquivos: PRINCIPLES.md, arquivo do agente, 01-questions.md, 02-answers.md Dados: workspace, descrição do PR, mensagens de commit Saída: 04-holistic-pre.md

Pode ser executada em paralelo com a Fase 5.

5. Revisão por Commit

Agente: agents/08-commit-review.md (um por commit, em paralelo) Arquivos: PRINCIPLES.md, arquivo do agente, 01-questions.md, 02-answers.md Dados: workspace, repo_path, base_ref, commit_sha, commit_message, commit_number, total_commits, all_commit_messages Saída: 03-commit-NN.md

for each commit in PR:
    spawn commit_reviewer(
        commit_diff=commit.diff,
        commit_number=N,
        ...
    ) → 03-commit-{N}.md
# One agent per commit - do not batch

5.5. Filtrar Implicações

Agente: agents/085-filter-implications.md Arquivos: PRINCIPLES.md, arquivo do agente, todos os 03-commit-*.md Dados: workspace Saída: filtered-implications.md

O agente analisa as implicações e perguntas ao autor diretamente dos arquivos de revisão de commit.

Decisão binária de exposição (expor ou não) mais categorização:

• corretude - Erros lógicos, bugs, comportamento incorreto
• suposição - Suposições não declaradas que podem não se sustentar
• sistema-de-tipos - Preocupações de segurança de tipo, restrições ausentes
• intenção - Perguntas sobre a intenção do autor que precisam de esclarecimento

spawn implication_filter(workspace=workspace) → filtered-implications.md
# Agent extracts implications from 03-commit-*.md files

6. Pós-Avaliação Holística

Agente: agents/09-holistic-post.md Arquivos: PRINCIPLES.md, arquivo do agente, 01-questions.md, 02-answers.md, 04-holistic-pre.md, todos os 03-commit-*.md, filtered-implications.md Dados: workspace Saída: 05-holistic-post.md

7. Sintetizar

Agente: agents/10-synthesize.md Arquivos: PRINCIPLES.md, arquivo do agente, todos os artefatos Dados: workspace Saída: REVIEW.md

Organiza as preocupações expostas por categoria (corretude, suposição, sistema-de-tipos, intenção), não por gravidade.

8. Entregar

Apresente REVIEW.md ao usuário.

⚠️ APENAS LOCAL: Esta skill produz artefatos apenas localmente. NÃO ofereça postar comentários no GitHub ou interagir com o GitHub de qualquer forma além do gh pr checkout inicial. A saída da revisão é para o usuário agir manualmente.

Preservação de Tokens

Você orquestra; subagentes analisam. Confie nas respostas de status.

Não leia artefatos intermediários exceto:

• STATUS: problems → leia as anotações
• O usuário faz uma pergunta
• Depuração de uma falha

Sempre leia: Respostas de status, saída final REVIEW.md.

Arquivos da Skill

skills/review-code/
├── SKILL.md
├── PRINCIPLES.md
└── agents/
    ├── 01-scout.md
    ├── 02-refine-questions.md
    ├── 03-answer-fact.md
    ├── 04-answer-research.md
    ├── 05-answer-design.md
    ├── 06-answer-correctness.md
    ├── 07-holistic-pre.md
    ├── 08-commit-review.md
    ├── 085-filter-implications.md
    ├── 09-holistic-post.md
    └── 10-synthesize.md