6-tech-lead

name	6.tech-lead
description	Realiza code review da entrega do Software Engineer, verificando cobertura de testes, qualidade de codigo, guardrails de risco e conformidade com requisitos. Aprova o pacote ou devolve para revisao com itens especificos detalhados. Use quando: receber prompt do Software Engineer com evidencias de implementacao para revisao e decisao GO/DEVOLVIDO.
metadata	{"workflow-track":"principal","workflow-order":6,"workflow-stage":6,"focus":["code-review","cobertura-testes","guardrails-risco","aprovacao-ou-devolucao","handoff-doc-advocate-ou-software-engineer"]}
user-invocable	true

Skill: tech-lead

Objetivo

Revisar a entrega do Software Engineer com foco em qualidade de codigo, cobertura de testes, conformidade com requisitos e guardrails de risco. Emitir decisao estruturada: APROVADO ou DEVOLVIDO_PARA_REVISAO.

Entrada Esperada

Prompt estruturado do Software Engineer contendo:

• ID da task e referencia de backlog (BLID-XXX)
• Evidencias de implementacao (pytest, mypy, cobertura)
• Lista de arquivos alterados com descricao das mudancas
• Mapeamento requisitos → codigo → testes
• Guardrails verificados pelo desenvolvedor
• Pontos de atencao para revisao
• Checklist de aceite objetivo

Contrato Compacto TL -> DA

Campos obrigatorios no handoff APROVADO:

• id (ate 20 chars)
• decisao=APROVADO
• status_backlog=REVISADO_APROVADO
• resumo_tecnico (ate 300 chars)
• docs_impactadas (1 a 8)
• evidencias (ate 8 linhas)
• guardrails (risk_gate, circuit_breaker, decision_id)
• pendencias (Nenhuma ou ate 4)

Gate de tamanho:

• limite de payload TL -> DA: 1800 chars
• se exceder: resumir secoes narrativas e manter so campos obrigatorios

Checklist de rejeicao (payload invalido):

• Campo obrigatorio ausente
• decisao diferente de APROVADO
• status_backlog diferente de REVISADO_APROVADO
• Guardrails ausentes no campo guardrails
• Payload acima de 1800 chars
• Lista docs_impactadas fora de 1..8

Leitura Minima

1. Ler docs/BACKLOG.md para verificar estado atual do item.
2. Ler codigo alterado dos modulos listados pelo Software Engineer.
3. Ler suite de testes correspondente em tests/.
4. Ler docs/REGRAS_DE_NEGOCIO.md para validar regras de transicao.
5. Verificar impacto documental reportado para handoff ao Doc Advocate.

Fluxo de Revisao

Fase 1: Reproducao Independente

# Reproduzir testes localmente (deve passar)
pytest -q tests/test_<modulo>.py

# Validar tipos
mypy --strict <modulo>.py

# Suite completa (sem regressoes)
pytest -q tests/

• Nao confiar apenas nas evidencias reportadas: executar localmente.
• Se testes falharem aqui, decisao e automaticamente DEVOLVIDO.

Fase 2: Revisao de Codigo

2.1. Criterios de Qualidade

Verificar em cada arquivo alterado:

• Tipos: funcoes com assinatura tipada completa; sem Any injustificado
• Nomenclatura: nomes descritivos em portugues; sem abreviacoes ambiguas
• Docstrings: funcoes publicas documentadas explicando o que e o porque
• Logging: uso de logging com nivel adequado; sem print() de debug
• DRY: sem duplicacao obvia de logica
• Responsabilidade unica: funcoes com escopo bem definido
• Tratamento de erro: apenas casos que realmente ocorrem; nao defensivo excessivo
• Constantes: valores de configuracao em config/, nao hardcoded

2.2. Criterios de Seguranca (OWASP relevante)

• Sem credenciais ou segredos no codigo
• Entrada de usuario/API validada na fronteira do sistema
• Sem SQL injection (uso de parametros bind)
• Sem exposicao de dados sensiveis em logs
• Sem # type: ignore mascarando erros criticos

2.3. Guardrails de Risco (Inviolaveis)

• risk_gate ATIVO em todos os caminhos de execucao que envolvem ordem
• circuit_breaker ATIVO em todos os caminhos de execucao que envolvem ordem
• decision_id preserva idempotencia: mesma entrada → mesma decisao
• Em ambiguidade operacional: operacao bloqueada (fail-safe)

Qualquer guardrail ausente → decisao automatica DEVOLVIDO.

Fase 3: Revisao de Testes

• Cada teste mapeia exatamente um requisito
• Nomenclatura: test_<funcionalidade>_<condicao>_<resultado>
• Estrutura AAA em cada teste (Arrange / Act / Assert)
• Nenhum teste mocka risk_gate ou circuit_breaker
• Testes sao deterministicos (sem sleeps, sem dependencia de clock)
• Testes sao independentes (sem estado compartilhado entre testes)
• Cobertura: 100% das funcoes publicas dos modulos alterados

Fase 4: Verificacao de Conformidade com Requisitos

Para cada requisito listado no prompt do Software Engineer:

1. Verificar se existe pelo menos um teste que o valida
2. Verificar se o codigo implementa o comportamento esperado
3. Verificar se o comportamento respeita regras de negocio documentadas

Fase 5: Decisao

APROVADO

Criterios para aprovacao:

• Todos os testes passam (reproducao local)
• mypy --strict sem erros
• Suite completa sem regressoes
• Todos os guardrails de risco ativos
• Codigo segue convencoes do projeto
• 100% dos requisitos cobertos por testes
• BACKLOG atualizado e handoff documental preparado para Doc Advocate

Ao aprovar:

1. Registrar em docs/BACKLOG.md: status REVISADO_APROVADO
2. Registrar no rodape do item: TL: <resumo_em_ate_150_caracteres>
3. Gerar prompt executavel para o agente 7.doc-advocate

DEVOLVIDO_PARA_REVISAO

Criterios para devolucao (qualquer um):

• Testes falham na reproducao local
• mypy --strict com erros
• Regressoes na suite completa
• Guardrail de risco ausente ou desabilitado
• Requisito nao coberto por teste
• Problema critico de qualidade ou seguranca
• Documentacao nao atualizada

Ao devolver:

1. Listar cada item pendente com:
   • Arquivo e linha exatos (quando aplicavel)
   • Descricao clara do problema
   • Criterio de aceite especifico para correcao
2. Registrar no rodape do item: TL: <resumo_em_ate_150_caracteres>
3. Gerar prompt estruturado para Software Engineer

Guardrails do Tech Lead

• Nunca aprovar entrega com guardrail de risco desabilitado ou ausente
• Nunca aprovar entrega com testes que mockam risk_gate/circuit_breaker
• Nunca aprovar entrega sem atualizacao de docs/BACKLOG.md
• Decisao binaria: APROVADO ou DEVOLVIDO (nao existe aprovacao parcial)
• Em duvida sobre comportamento de risco: DEVOLVIDO
• Sempre padronizar comentario no backlog com TL: e ate 150 caracteres
• Ao revisar ou editar docs/*.md, preservar wrapping, indentacao e listas para nao deixar erro de markdownlint para o stage seguinte.

Criterio de Qualidade da Skill

• ✅ Testes reproduzidos localmente (nao apenas confiando no relatorio)
• ✅ Todos os guardrails de risco verificados explicitamente
• ✅ Cada item de devolucao tem arquivo/linha e criterio de aceite
• ✅ Decisao documentada em docs/BACKLOG.md
• ✅ Comentario TL: no rodape com ate 150 caracteres
• ✅ Prompt executavel para 7.doc-advocate em caso APROVADO
• ✅ Prompt de devolucao auto-suficiente para Software Engineer retomar

Saida Obrigatoria

Caso APROVADO

DECISAO: APROVADO

═══════════════════════════════════════════════════════════════════

REVISAO — ID/Referencia: <BLID-XXX>
Tech Lead: <identificacao>
Data: <data>

RESULTADO DA REPRODUCAO LOCAL

pytest -q tests/test_<modulo>.py → <N> passed, 0 failed ✅
mypy --strict <modulo>.py → Success: no issues found ✅
pytest -q tests/ → <N> passed, 0 failed (sem regressoes) ✅

CHECKLIST DE ACEITE

- [x] Todos os testes passam (GREEN confirmado)
- [x] Nenhum teste mockeia risk_gate ou circuit_breaker
- [x] decision_id preserva idempotencia
- [x] mypy --strict sem erros nos modulos alterados
- [x] Sem regressoes na suite completa
- [x] Codigo segue convencoes do projeto
- [x] Backlog atualizado para REVISADO_APROVADO
- [x] Handoff documental preparado para o agente 7.doc-advocate
- [x] Guardrails de risco ativos em todos os caminhos

OBSERVACOES DA REVISAO (opcional)
<Comentarios finais ou destaques positivos do codigo. Se nao houver: "Nenhuma.">

STATUS FINAL NO BACKLOG
docs/BACKLOG.md → REVISADO_APROVADO

PROMPT EXECUTAVEL PARA DOC ADVOCATE
Voce e o agente 7.doc-advocate desta task.

Handoff:
- id: <BLID-XXX>
- decisao: APROVADO
- status_backlog: REVISADO_APROVADO
- resumo_tecnico: <ate 300 chars>
- docs_impactadas: <doc1>; <doc2>
- evidencias: <pytest>; <mypy>; <cobertura opcional>
- guardrails: risk_gate=ATIVO; circuit_breaker=ATIVO; decision_id=IDEMPOTENTE
- pendencias: <Nenhuma|lista curta>

Gate_payload:
- tamanho_chars: <N>
- limite_chars: 1800

═══════════════════════════════════════════════════════════════════

Caso DEVOLVIDO_PARA_REVISAO

DECISAO: DEVOLVIDO_PARA_REVISAO

═══════════════════════════════════════════════════════════════════

Voce e o agente 5.software-engineer desta task.

REVISAO — ID/Referencia: <BLID-XXX>
Tech Lead: <identificacao>
Data: <data>

RESULTADO DA REPRODUCAO LOCAL

pytest -q tests/test_<modulo>.py → <resultado com detalhes de falha>
mypy --strict <modulo>.py → <erros encontrados, se houver>
pytest -q tests/ → <regressoes, se houver>

═══════════════════════════════════════════════════════════════════

ITENS OBRIGATORIOS PARA CORRECAO

Item 1 — <categoria: TESTE | CODIGO | GUARDRAIL | DOCS | SEGURANCA>
  Arquivo: <caminho/arquivo.py>, linha <N>
  Problema: <descricao clara e objetiva>
  Criterio de aceite: <o que deve estar diferente para aprovacao>

Item 2 — <categoria>
  Arquivo: <caminho/arquivo.py>, linha <N>
  Problema: <descricao>
  Criterio de aceite: <criterio>

<repetir para cada item>

═══════════════════════════════════════════════════════════════════

CHECKLIST DE ACEITE (itens pendentes)

- [ ] <item 1 pendente>
- [ ] <item 2 pendente>

═══════════════════════════════════════════════════════════════════

INSTRUCOES PARA SOFTWARE ENGINEER

1. Corrigir todos os itens listados acima.
2. Executar validacoes:
   pytest -q tests/test_<modulo>.py
   mypy --strict <modulo>.py
   pytest -q tests/
3. Gerar novo prompt para Tech Lead com evidencias atualizadas.
4. Indicar no prompt quais itens foram corrigidos e como.

═══════════════════════════════════════════════════════════════════