Resolve Bugfix | Documentação

Guia canônico para estabilizar código avariado ou lidar com comportamentos divergentes. O Nébula Spec Kit barra a alteração ad-hoc sem documentação prévia; toda correção deve nascer de análises concretas, garantir reprodução estrita de causa e manter o histórico do incidente vivo.

Objetivo: Diagnosticar, corrigir, validar e registrar reparos, preservando a Rastreabilidade sem introduzir escopo oculto ("refatorações" que quebram contratos).
Fontes da Verdade: Workflows/bug-fix.md e Workflows/hotfix.md

Estrutura — O Rito de Estabilização

Qualquer intervenção na base deve obedecer a governança das matrizes abaixo. Jamais faça merges corretivos diretos que burlem este pipeline de documentação.

1. Seleção Estrita de Workflow e Gatilho

Decisão mandatória baseada em Urgência x Risco:
 
GATILHO: Falha em produção branda, teste quebrando, desvio mapeado na sprint.
Workflow Associado: bug-fix
Contexto: Foca na repetição do cenário, lint estrito, e não interrompe pipeline geral.
 
GATILHO: Incidente CRÍTICO c/ impacto terminal em produção corrompendo core.
Workflow Associado: hotfix
Contexto: Rota expressa para mitigar risco. Pula o ciclo normal da feature, mas reforça os testes pós-deploy em nuvem de imediato.

2. A Regra de Ouro (Governança de Correção)

Leis de Manutenção (resgatadas do Baseline de Execução):

1. Proibido adicionar Nova Feature ("já que estou corrigindo aqui...") através de uma task de bugfix.
2. A edição de código atua exclusivamente em estado de 'edição' de arquivos prévios.
3. A correção atômica gera OBRIGATORIAMENTE apenas 1 Commit de reparo.

3. Documentos Principais Editados

Artefatos cujo conteúdo técnico pauta ou é modificado pela caçada ao erro:

Para bug-fix:
- Docs/control.md (Anota a dor base, o desvio logado e o Risco resolvido)
- Docs/contract.yaml (Se a correção alterou interfaces e retornos brutos)
- Docs/architecture.md (Se o Bug era na topologia de containers ou conexões)
- Docs/user-stories.md (Se o código antigo apenas seguia regras erradas ali descritas)
 
Para hotfix, adicione:
- Docs/deploy.md (Para readequar plano de rollback estourado e rever variáveis)

4. Sequência Recomendada de Execução (Bug Fix)

Os 8 passos da correção cirúrgica rastreável orientada pelo Workflow bug-fix:

1. Logs (Coleta forense do pânico/erro no terminal nativo).
2. Refatoração (Diagnóstico técnico e isolamento estrutural do problema).
3. Contratos (Checar a quebra via inputs).
4. Testes (Reprodução estrita forçando a repetição contínua do defeito — "Mantra: sem reprodução = sem commit").
5. Implementação (O patch curativo).
6. Curl (Validação isolada quando houver API).
7. Quality Gate (Execução da matriz limpa sem pulos de lint).
8. Atualização de Docs/control.md (Onde entra a causa e efeito desvendados).

5. Sequência Recomendada de Execução (Hotfix)

Os 9 passos da contenção emergencial orientada pelo Workflow hotfix:

1. Logs (Extração na nuvem afetada).
2. Contratos (Avaliar limites restritos de segurança violados).
3. Testes mínimos (Checar a replicação básica com menor tempo possível de build).
4. Implementação de Menor Risco (Não se refatora sistema inteiro no calor do fogo).
5. Deploy (Envio prioritário saltando branches passivas diretas em Main/Master se preciso para estancar hemorragia).
6. Curl (Ping obrigatório pós release vivo).
7. Logs Pós-Deploy (Atestar sobrevida do sistema nos 5 min posteriores).
8. Quality Gate (Check do painel).
9. Atualização de Docs/control.md (Baixa oficial do incidente mitigado alertando riscos residuais abertos).

6. Card de Cenário da Correção

Como padronizado pelo framework em Manuais, o preenchimento mínimo exigido no momento do resgate tático:

# Contexto
[Diagnóstico observado: Função Z quebrando após subir nova API externa na sprint Y.]
 
# Objetivo
[Remover causa imediata de tela branca preservando regra da entidade X.]
 
# Workflow e Skills
Workflows/[bug-fix|hotfix] focado estritamente na reparação de danos.
 
# Evidências Duras Fixadas
- Risco Residual guardado do Control.md (EX: o sistema suporta 1k reqs denovo, mas no BD continua pesado, gerar task técnica amanhã).
- O Hash do Hotfix formalizado.

Prompt para tratar via agente (Diagnosticar e Corrigir)

Use esta matriz com AIs ao terceirizar o refactoring, impedindo-as de quebrarem regras nativas de escopo.

Atue como ExecutionAgent.
Objetivo: Diagnosticar e aplicar workflow [bug-fix ou hotfix] relacionado à [TASK-ID do Erro X].
Workflow ativado: Workflows/bug-fix.md
 
Leia as Logs copiadas de [terminal]. Vá checar os limites estabelecidos nas regras do projeto nos arquivos `Docs/architecture.md` e `Docs/contract.yaml`.
Baseado na Sequência Recomendada de Execução, não tente implementar o código antes de conseguir isolar um teste unitário mínimo confirmando minha queixa original e pare solicitando aprovação da tese!
No fim, acione Quality Gate e retorne Risco Residual para fechamento.

Definição de pronto

Entende-se o Reparo tecnicamente apto e documentado de acordo no framework quando:

O comportamento destrutivo / incorreto cessou no ambiente base.
Não foram mascaradas falhas ou "passar a sujeira pra baixo" de outro módulo interligando componentes cruzados acidentalmente.
O teste recém construído confirmou em vermelho a falha pré-implantação.
O Docs/control.md acusa a versão limpa, declarando qual risco ainda sobra pra manutenções futuras em nuvem.

Corrigir o Sintoma em vez da Causa Oculta é falha técnica de maturidade. Se uma classe de "Usuário" lança o erro, é na abstração da classe de usuário que o Bug Fix atua. Não silencie o Catch na tela de front-end se o Back-end está estourando. Isso agrava em escala um Hotfix futuro imensurável pelas dores de gargalo cruzado.