Ir para o conteúdo

Bug Flow
Tipo Bug (P1 | P2 | P3 | P4)
Trigger /analyze-bug <ticket>
Agentes bug-investigator → impact-analyzer → architecture-agent → builder-agent → code-reviewer-agent → test-validator → pr-generator → release-agent → learning-agent
Checkpoints humanos 4

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

1. O que é e quando usar

Fluxo para defeito reportado com root cause única e fix localizado (1 arquivo, 1 método). Aplica Hypothesis First: o investigador formula hipóteses explícitas antes de buscar no código.

Use quando: há um sintoma específico reportado por usuário e o fix é focado.

Não use quando: - O fix é só de banco, sem código → Data Fix - É ajuste leve sem lógica de negócio → Small Improvement - É uma classe inteira de problema de security (CWE) → Vulnerability

2. Visão geral do fluxo

/analyze-bug
    └── bug-investigator     → BugReport
    └── impact-analyzer      → ImpactReport
             ↓
    ⚡ CHECKPOINT 1 — humano revisa e aprova a estratégia
             ↓
/generate-fix
    └── architecture-agent   → ArchGuidance / Mini RFC (se necessário)
    └── builder-agent        → PatchBundle
    └── code-reviewer-agent  → CodeReviewReport (revisão automatizada antes do humano)
             ↓
    ⚡ CHECKPOINT 2 — humano revisa o patch (com o code review ao lado)
             ↓
/run-regression
    └── test-validator       → ValidationReport + Gate 1 (1a cobertura do diff + 1b execução no dev)
             ↓
    Esteira de Qualidade: /smoke (Gate 2) → /validacao-testes (Gate 3) → /qa-gate (4 verdes)
             ↓
/open-pr
    └── pr-generator         → PR Description + Rollback Plan
             ↓
    ⚡ CHECKPOINT 3 — reviewer aprova o PR
             ↓
/release-check
    └── release-agent        → ReleasePackage
             ↓
    ⚡ CHECKPOINT 4 — humano aprova o deploy
             ↓
    [deploy via pipeline] → learning-agent → atualiza Speckit

3. Passo a passo

Passo 1 — /analyze-bug <ticket> — bug-investigator → impact-analyzer

  1. Lê .speckit/known-issues/ — há match com padrão conhecido?
  2. Lê .speckit/architecture/risk-map.md — arquivo suspeito é hotspot?
  3. Lê .speckit/domain/system-overview.md e .speckit/business-rules/ — é bug ou regra?
  4. Analisa o código nos arquivos suspeitos e formula hipótese de root cause.
  5. Encadeia o impact-analyzer automaticamente (blast radius). Output: .ns-flow/analysis/<ticket>-bugreport.md + .ns-flow/analysis/<ticket>-impact.md → Parar. Checkpoint 1.

Passo 2 — /generate-fix <ticket> — architecture-agent → builder-agent → code-reviewer-agent

  1. architecture-agent valida a abordagem contra ADRs e políticas:
  2. Hotspot → Mini RFC obrigatória; mudança de banco → db-change-policy; SQL → security-policy.
  3. builder-agent gera o patch mínimo.
  4. Verificações automáticas: nenhuma credencial, SQL parametrizado, sem acesso a produção.
  5. code-reviewer-agent revisa o diff (escopo, corretude, segurança, reuso, testes, UX) antes do humano — finding Blocker volta ao builder-agent. Output: .ns-flow/design/<ticket>-arch-guidance.md (se necessário) + .ns-flow/delivery/<ticket>-patch.md + .ns-flow/delivery/<ticket>-code-review.md → Parar. Checkpoint 2.

Passo 3 — /run-regression <ticket> — test-validator (Gate 1)

Identifica testes existentes dos arquivos modificados, garante que passam, escreve teste do cenário do bug (RED→GREEN) e verifica a cobertura do código alterado — esse é o Gate 1a (Cobertura) (ou N/A-por-ADR quando o stack não permite unit). O Gate 1 também executa o 1b (Execução no dev/stg): o QA Plan (CTs) executado via Playwright no ambiente dev/stg (nunca HML — HML é o Gate 3), reusando o motor do qa-expert com ambiente=dev. Gate 1 verde = 1a (verde ou N/A-por-ADR) E 1b (verde). Output: .ns-flow/delivery/<ticket>-validation.md + testes em tests/<ticket>/

Passo 3b — Esteira de Qualidade (Gates 2 e 3) — antes do PR

  • Gate 2 — smoke: /smoke <ticket> (caminho crítico)
  • Gate 3 — E2E: /validacao-testes <ticket> (FEAT-{N}/critérios com evidência) → alimenta o Checkpoint 3
  • Meta-gate: /qa-gate <ticket> — os 4 verdes liberam o PR/release. Ver Quality Layer.

Passo 4 — /open-pr <ticket> — pr-generator

Output: .ns-flow/delivery/<ticket>-pr-description.md + PR criado no repositório → Parar. Checkpoint 3.

Passo 5 — /release-check <ticket> — release-agent

Verifica quality gates e gera o ReleasePackage com instrução de deploy e monitoramento. Output: .ns-flow/delivery/<ticket>-release.md → Parar. Checkpoint 4.

Passo 6 — Pós-deploy — learning-agent

Atualiza .speckit/known-issues/ (padrão novo), risk-map.md (hotspot confirmado), metrics-feed.jsonl (type: "bug") e speckit-updates.md. Encerra o ticket.

4. Checkpoints humanos

# Quando Quem aprova Verifica
1 Após análise Dev/TL Root cause faz sentido? Blast radius correto? Estratégia aprovada?
2 Após patch Dev/Reviewer CodeReviewReport lido (Blockers resolvidos)? Muda só o que o root cause exige? Sem refactoring? Sem credencial? SQL parametrizado?
3 No PR Reviewer Descrição correta? Rollback executável? Homologação (Gate 3 E2E) feita? /qa-gate verde?
4 Antes do deploy Responsável de release 4 gates de qualidade ✅? Janela adequada? On-call ciente?

Se rejeitado no CP1/CP2: acrescente contexto e re-rode o comando da etapa (/analyze-bug ou /generate-fix) com instrução adicional.

5. Pastas e arquivos gerados

Etapa Arquivo
Investigação .ns-flow/analysis/<ticket>-bugreport.md
Impacto .ns-flow/analysis/<ticket>-impact.md
Arquitetura (se necessário) .ns-flow/design/<ticket>-arch-guidance.md
Patch .ns-flow/delivery/<ticket>-patch.md
Code Review .ns-flow/delivery/<ticket>-code-review.md
Validação .ns-flow/delivery/<ticket>-validation.md + tests/<ticket>/
PR .ns-flow/delivery/<ticket>-pr-description.md
Release .ns-flow/delivery/<ticket>-release.md
Encerramento atualizações em .speckit/ + linha em metrics-feed.jsonl

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

Papel Responsabilidade
Dev Dispara /analyze-bug, valida root cause (CP1), gera e revisa o patch (CP2)
Tech Lead Decide Mini RFC em hotspots; pode aprovar CP1/CP2
Reviewer Aprova o PR e o rollback plan (CP3)
Release / On-call Aprova e confirma o deploy (CP4) → aciona o learning-agent

Para investigações longas (várias sessões), mantenha .ns-flow/state/<ticket>-state.md.

Referências

Voltar ao topo