Ir para o conteúdo

Data Fix Flow
Tipo Fix puramente de banco (sem alteração de código-fonte)
Trigger /analyze-bug conclui root cause de banco → /data-fix <ticket>
Pré-requisito BugReport em .ns-flow/analysis/<ticket>-bugreport.md gerado pelo /analyze-bug
Agentes db-diagnostic-agent → data-fix-agent
Saída Script SQL idempotente em migrations/ + verification query + patch.md (sem código)
Checkpoints humanos 4

Pré-requisito de instalação: ver 00 — Instalação e Setup.

1. O que é e quando usar

Bifurcação do Bug Flow: quando o bug-investigator conclui que o root cause é puramente de banco (estrutura ausente, dados inconsistentes, índice, ou SP com lógica incorreta), o time não gera código — gera um script SQL idempotente versionado.

A decisão de bifurcar acontece na decisão humana do Checkpoint 1 do /analyze-bug. O comando /analyze-bug não é modificado — ele produz BugReport + ImpactReport normalmente.

Regra de ouro: o agente nunca executa SQL. Ele gera queries e scripts; o humano executa via pipeline e cola os resultados.

Qualidade: sem código-fonte, os gates de cobertura (1) e E2E na UI (3) não se aplicam. A verification query em HML/PROD é a evidência equivalente deste fluxo. Ver Quality Layer.

2. Visão geral do fluxo

/analyze-bug <ticket>                ← fluxo normal, não modificado
       │ bug-investigator sinaliza suspeita de banco (apenas hipótese)
       ▼
⚡ Checkpoint 1 — "Qual a estratégia de fix?"   ← decisão HUMANA
       │  Fix é no BANCO  (senão → bug-flow / generate-fix)
       ▼
db-diagnostic-agent  → kit de queries SELECT
       ▼
⚠️  Humano roda queries em HML (preferível) — PROD apenas via pipeline aprovado — e cola resultados
       ▼
db-diagnostic-agent interpreta + atualiza BugReport
       ▼
/data-fix <ticket>  → data-fix-agent
       ├── classifica categoria (A/B/C/D)
       ├── [Categoria A → PARA e aguarda aprovação especial]
       └── gera script SQL idempotente (PRE-CHECK + fix + POST-CHECK + ROLLBACK)
       ▼
⚡ Checkpoint 2 — DBA/TL aprova o script
       ▼
Humano executa em HML via pipeline + roda verification query
       ▼
/open-pr <ticket>   (sem alteração de código)
       ▼
⚡ Checkpoint 3 — Reviewer aprova o PR
       ▼
/release-check <ticket>
       ▼
⚡ Checkpoint 4 — Aprovação do deploy
       ▼
Humano executa script em PROD via pipeline → learning-agent (cria KI-XXX)

3. Passo a passo

Passo 1 — ⚡ Checkpoint 1 (estratégia de fix)

Decisão humana: [ ] Banco → seguir com investigação (db-diagnostic-agent) e /data-fix | [ ] Código → /generate-fix | [ ] Ambos (banco primeiro, depois código — exige dois tickets ou ordem explícita).

Passo 2 — Investigação de banco — db-diagnostic-agent

Acionado pelo dev após o Checkpoint 1 do /analyze-bug, quando o BugReport indica suspeita de banco. 1. Lê o BugReport e identifica o tipo: [ESTRUTURAL], [DADOS], [PERFORMANCE], [PROCEDURAL]. 2. Gera um kit de queries diagnósticas adaptado ao stack (SQL Server, Oracle, PostgreSQL, MySQL). 3. Apresenta as queries — nunca executa. Todas são SELECT (zero DML/DDL nesta fase). 4. Interpreta os resultados colados pelo humano e atualiza o BugReport com a seção ## Investigação de Banco — Resultados.

Regras: prefira HML; máximo 2 rodadas de queries; root cause só é confirmado com resultado concreto colado pelo humano.

Passo 3 — Geração do script — data-fix-agent (/data-fix <ticket>)

  1. Lê o BugReport — deve conter a seção ## Investigação de Banco — Resultados.
  2. Classifica a categoria (define quem aprova e a janela):
Categoria Tipo Aprovação Janela
A DDL destrutivo (DROP, ALTER tipo/tamanho) DBA + TL + management Especial agendada
B DDL aditivo (ADD COLUMN, CREATE INDEX, CREATE/ALTER SP) DBA + TL Baixo tráfego
C DML em massa (> 1.000 registros) DBA Baixo tráfego
D DML cirúrgico (registros específicos) TL Normal
  1. Categoria A → PARA imediatamente e aguarda aprovação especial antes de gerar qualquer SQL.
  2. Gera o script seguindo o template obrigatório: PRE-CHECK → BEGIN TRANSACTION + fix + COMMIT → POST-CHECK → ROLLBACK PLAN (acionável por DBA sem contexto).
  3. Gera a verification query (equivalente SQL ao teste de regressão).

Passo 4 — ⚡ Checkpoint 2 (aprovação do script)

DBA/TL revisa: idempotência (rodar 2× = resultado idêntico), PRE-CHECK, rollback executável, categoria correta, aprovação do responsável obtida.

Passo 5 — Execução em HML (humano)

Humano executa o script via pipeline de HML, roda a verification query e cola o resultado. OK → /open-pr. Falhou → revisar e repetir /data-fix.

Passo 6 — /open-pr <ticket> → ⚡ Checkpoint 3

PR sem código-fonte: referência ao script em migrations/, resultado da verification em HML, rollback plan, checklist de deploy.

Passo 7 — /release-check <ticket> → ⚡ Checkpoint 4

release-agent verifica CI verde, PR aprovado e verification de HML documentada. Humano executa o script em PROD via pipeline e roda a verification em PROD.

Passo 8 — Encerramento — learning-agent

Registra Known Issue (cria/atualiza KI-XXX para padrões de banco) e grava em metrics-feed.jsonl (type: "data-fix", categoria, registros corrigidos).

4. Checkpoints humanos

# Quando Quem aprova Verifica
1 Estratégia de fix Dev/TL É banco, código ou ambos?
2 Script gerado DBA + TL (A/B); DBA (C); TL (D) Idempotente? PRE-CHECK/rollback OK? Categoria certa?
3 PR Reviewer Script correto e idempotente? Verification HML passou? Sem código alterado?
4 Deploy DBA / responsável Executado em PROD? Verification PROD OK? Rollback preparado?

5. Pastas e arquivos gerados

Etapa Arquivo
Investigação atualização em .ns-flow/analysis/<ticket>-bugreport.md
Script de fix migrations/<ticket>-<descricao-slug>.sql
Verification query .ns-flow/delivery/<ticket>-db-verification.md
Documentação (sem código) .ns-flow/delivery/<ticket>-patch.md
PR .ns-flow/delivery/<ticket>-pr-description.md
Encerramento KI-XXX em .speckit/known-issues/ + linha em metrics-feed.jsonl

6. Aplicação pelo time (papéis)

Papel Responsabilidade
Dev Aciona db-diagnostic-agent e /data-fix; executa queries em HML e cola resultados
DBA Aprova o script conforme categoria; executa em PROD via pipeline; roda verification
Tech Lead Aprova categorias D (e B/A junto ao DBA); decide ordem em fix misto
Management Aprovação adicional em Categoria A (DDL destrutivo)
Reviewer Aprova o PR (CP3)

7. Restrições do fluxo

  • Nunca executar script diretamente — apenas via pipeline.
  • Script deve existir em migrations/ antes de abrir o PR.
  • Verification query rodada em HML antes do PR.
  • Categoria A nunca avança sem aprovação de DBA + TL + management.
  • Fix misto (banco + código): banco primeiro, código depois.
  • learning-agent é obrigatório — sem ele o Speckit fica desatualizado.

Referências

Voltar ao topo