| name | bugfix |
| version | 1.2.0 |
| category | governance |
| description | Corrige bugs pela causa raiz com testes de regressao obrigatorios e evidencia de validacao. Use quando o usuario pedir para corrigir bugs ou referenciar bugs.md, especialmente a partir de achados emitidos pela skill review. Nao use para review ou auditoria sem alteracao, nem para refatoracao sem defeito confirmado. |
Corrigir Bugs
Procedimentos
Etapa 1: Validar entrada e escopo
- Verificar profundidade de invocação: resolver a raiz com
repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)" e localizar check-invocation-depth.sh em cascata .agents/lib/ → scripts/lib/ (B1, suporta bootstrap em projetos que copiam apenas .agents/):
_depth_lib=""
for d in "$repo_root/.agents/lib" "$repo_root/scripts/lib"; do
[[ -r "$d/check-invocation-depth.sh" ]] && { _depth_lib="$d/check-invocation-depth.sh"; break; }
done
[[ -n "$_depth_lib" ]] || { echo "failed: check-invocation-depth.sh ausente em .agents/lib/ e scripts/lib/"; exit 1; }
source "$_depth_lib" || { echo "failed: depth limit exceeded"; exit 1; }
- Confirmar que a lista de bugs foi recebida no formato canonico
{ id, severity, file, line, reproduction, expected, actual }. A severity segue o enum do schema (critical, major, minor); interpretar conforme .agents/skills/agent-governance/references/severity-mapping.md — critical/major exigem correcao no escopo, minor pode virar risco residual conforme orcamento.
- Ler
references/canonical-bug-format.md quando houver duvida sobre campos obrigatorios, severidades ou estados canonicos.
- Se a lista vier em arquivo JSON, validar contra o schema canonico com
python3 "$repo_root/.agents/skills/bugfix/scripts/validate-bug-input.py" --input <caminho> antes de prosseguir. O script tenta JSON Schema (jsonschema) e cai para validacao manual equivalente quando a lib nao esta disponivel.
- Se a lista estiver ausente, incompleta ou fora do formato canonico, retornar
needs_input com os campos faltantes.
- Confirmar o escopo de bugs a corrigir antes de editar qualquer arquivo.
Etapa 2: Carregar o contexto tecnico
- Confirmar que o contrato de carga base definido em
AGENTS.md foi cumprido.
- Se a correcao tocar codigo Go, ler tambem
.agents/skills/go-implementation/SKILL.md e apenas as referencias exigidas pela mudanca. Para outras linguagens, carregar a skill .agents/skills/<lang>-implementation/SKILL.md quando existir; caso contrario, seguir apenas com governanca transversal.
- Ler
bugs.md, prd.md, techspec.md, arquivos de tarefa ou contexto de issue quando estiverem disponiveis e forem relevantes para o bug.
- Mapear contratos publicos, comportamento esperado, pontos de integracao e risco de regressao antes de propor a correcao.
Etapa 3: Priorizar e diagnosticar
- Ordenar os bugs por severidade:
critical, major, minor.
- Identificar a causa raiz de cada bug antes de editar.
- Marcar como
blocked qualquer bug que dependa de contexto externo indisponivel e seguir com os demais bugs do escopo.
- Evitar patches superficiais quando a causa raiz ainda nao estiver clara.
Etapa 4: Corrigir e testar
- Aplicar a menor mudanca segura focada na causa raiz.
- Criar um teste de regressao para cada bug corrigido que reproduza
reproduction e valide expected.
- Seguir Etapa 4 de
.agents/skills/agent-governance/SKILL.md.
- Se a validacao falhar, analisar o log e tentar apenas uma remediacao limitada adicional para o mesmo bug.
- Se o limite de duas tentativas por bug for excedido, marcar o bug como
failed, registrar o diagnostico e seguir para o proximo bug elegivel.
Etapa 5: Revisar e registrar evidencias
- Registrar para cada bug o arquivo alterado, o teste de regressao adicionado e o resultado da validacao.
- Registrar a origem de cada bug (campo
Origem: com RF, task, finding de review ou issue) — rastreabilidade exigida por padrao pelo validador.
- Atualizar o estado de cada bug usando apenas
fixed, blocked, skipped ou failed.
- Ler
assets/bugfix-report-template.md.
- Salvar o relatorio em
.specs/prd-<feature-slug>/bugfix_report.md quando estiver em contexto de tarefa; caso contrario, em ./bugfix_report.md.
- Validar o relatorio com o validador resolvido em cascata portátil (
.agents/scripts/validate-bugfix-evidence.sh → .claude/scripts/validate-bugfix-evidence.sh → scripts/validate-bugfix-evidence.sh): bash "<primeiro-existente>" <caminho-do-relatorio> (a rastreabilidade de origem e default-on; quando os IDs de RF forem conhecidos, passar --rf <RF-ID> para casar cada um); corrigir secoes faltantes antes de encerrar.
Etapa 6: Encerrar o fluxo
- Informar total de bugs no escopo, quantos foram corrigidos, quantos testes de regressao foram adicionados e quais itens ficaram pendentes com motivo.
- Retornar apenas um destes estados canonicos:
done: escopo acordado corrigido e validadoblocked: existe bug critico bloqueado por contexto externoneeds_input: faltam dados obrigatorios de reproducao ou escopofailed: limite de remediacao excedido ou validacao nao comprovou a correcao
Tratamento de Erros
- Se a entrada nao corresponder ao formato canonico, solicitar a conversao antes de prosseguir com a correcao.
- Se uma correcao alterar comportamento publico, parar e explicitar a mudanca a menos que ela tenha sido solicitada.
- Se
go test ./... ou o equivalente do projeto falhar apos a correcao, analisar o log de falha antes de reexecutar.
- Se a baseline do repositorio ja estiver quebrada, separar claramente a falha preexistente das falhas introduzidas pela correcao.
- Respeitar o limite de profundidade de invocacao definido em
.agents/skills/agent-governance/SKILL.md. Bugfix nao deve re-invocar review se ja estiver sendo executado dentro de um ciclo review -> bugfix.
Resolução de paths
Todo caminho .specs/prd-<slug>/ referenciado neste documento resolve para ${AI_TASKS_ROOT:-.specs}/${AI_PRD_PREFIX:-prd-}<slug>/. Defaults preservam o layout histórico. Customização via .claude/config.yaml ou .agents/config.yaml:
tasks_root: .specs
prd_prefix: prd-
evidence_dir: ""
check-invocation-depth.sh (Etapa 1, resolvido em cascata .agents/lib/ → scripts/lib/) exporta AI_TASKS_ROOT, AI_PRD_PREFIX, AI_EVIDENCE_DIR, AI_TOOL para skills, validators e runtime, garantindo paridade exata entre Claude Code, Codex, Gemini e Copilot.
