aiox-core 5.0.0

package/docs/aiox-workflows/qa-loop-workflow.md

@@ -0,0 +1,1111 @@
+# QA Loop Workflow - Documentação Completa
+
+**Versão:** 1.0
+**Última Atualização:** 2026-02-04
+**Epic:** 6 - QA Evolution: Autonomous Development Engine (ADE)
+**Story:** 6.5
+**Autor:** @architect (Aria)
+
+---
+
+## Índice
+
+1. [Visao Geral](#visao-geral)
+2. [Diagrama do Workflow](#diagrama-do-workflow)
+3. [Steps Detalhados](#steps-detalhados)
+4. [Agentes Participantes](#agentes-participantes)
+5. [Tasks Executadas](#tasks-executadas)
+6. [Pré-requisitos](#pre-requisitos)
+7. [Entradas e Saidas](#entradas-e-saidas)
+8. [Pontos de Decisão](#pontos-de-decisão)
+9. [Configuração](#configuracao)
+10. [Controle de Execução](#controle-de-execucao)
+11. [Escalação](#escalacao)
+12. [Integração com Dashboard](#integracao-com-dashboard)
+13. [Tratamento de Erros](#tratamento-de-erros)
+14. [Troubleshooting](#troubleshooting)
+15. [Referências](#referencias)
+
+---
+
+## Visão Geral
+
+O **QA Loop Orchestrator** e um workflow automatizado que orquestra o ciclo completo de:
+
+```
+Review -> Fix -> Re-review
+```
+
+Este workflow executa ate um maximo de iterações configuravel (padrao: 5), rastreando os resultados de cada iteracao. Quando o limite maximo e atingido ou uma parada manual e solicitada, o workflow escala para intervenção humana.
+
+### Propósito
+
+- Automatizar o ciclo de revisao de qualidade
+- Reduzir tempo entre feedback e correção
+- Garantir rastreabilidade completa do processo de QA
+- Escalar automaticamente quando necessario
+
+### Tipos de Projeto Suportados
+
+- `aiox-development`
+- `autonomous-development`
+- `qa-automation`
+
+---
+
+## Diagrama do Workflow
+
+### Fluxo Principal
+
+```mermaid
+flowchart TD
+    subgraph TRIGGER["Triggers de Inicio"]
+        T1["*qa-loop {storyId}"]
+        T2["*qa-loop-review"]
+        T3["*qa-loop-fix"]
+    end
+
+    subgraph INIT["Inicialização"]
+        I1["Carregar/Criar loop-status.json"]
+        I2["Definir iteration = 0"]
+        I3["maxIterations = 5 (config)"]
+    end
+
+    subgraph REVIEW["Fase 1: QA Review"]
+        R1["@qa executa qa-review-story.md"]
+        R2["Gera gate-file.yaml"]
+        R3["Retorna verdict + issuesFound"]
+    end
+
+    subgraph CHECK["Fase 2: Verificar Verdict"]
+        C1{"verdict?"}
+        C2["APPROVE"]
+        C3["BLOCKED"]
+        C4["REJECT"]
+    end
+
+    subgraph FIX_REQ["Fase 3: Criar Fix Request"]
+        F1["@qa executa qa-create-fix-request.md"]
+        F2["Gera fix-request.md"]
+        F3["Prioriza issues"]
+    end
+
+    subgraph FIX["Fase 4: Aplicar Fixes"]
+        X1["@dev executa dev-apply-qa-fixes.md"]
+        X2["Aplica correções"]
+        X3["Valida com testes"]
+        X4["Gera fixes-applied.json"]
+    end
+
+    subgraph ITER["Fase 5: Verificar Iteração"]
+        IT1{"iteration >= max?"}
+        IT2["iteration++"]
+    end
+
+    subgraph END["Finalização"]
+        E1["COMPLETE - Story Aprovada"]
+        E2["ESCALATE - Requer Humano"]
+        E3["Gerar Sumario Final"]
+    end
+
+    T1 --> I1
+    T2 --> R1
+    T3 --> X1
+
+    I1 --> I2
+    I2 --> I3
+    I3 --> R1
+
+    R1 --> R2
+    R2 --> R3
+    R3 --> C1
+
+    C1 --> |"APPROVE"| C2
+    C1 --> |"BLOCKED"| C3
+    C1 --> |"REJECT"| C4
+
+    C2 --> E1
+    C3 --> E2
+
+    C4 --> F1
+    F1 --> F2
+    F2 --> F3
+    F3 --> X1
+
+    X1 --> X2
+    X2 --> X3
+    X3 --> X4
+    X4 --> IT1
+
+    IT1 --> |"Sim"| E2
+    IT1 --> |"Não"| IT2
+    IT2 --> R1
+
+    E1 --> E3
+    E2 --> E3
+
+    style TRIGGER fill:#e1f5fe
+    style REVIEW fill:#fff3e0
+    style CHECK fill:#fce4ec
+    style FIX_REQ fill:#f3e5f5
+    style FIX fill:#e8f5e9
+    style ITER fill:#fff8e1
+    style END fill:#e0f2f1
+```
+
+### Diagrama de Estados
+
+```mermaid
+stateDiagram-v2
+    [*] --> pending: *qa-loop {storyId}
+
+    pending --> in_progress: Iniciar Loop
+
+    in_progress --> in_progress: REJECT (iteration < max)
+    in_progress --> completed: APPROVE
+    in_progress --> escalated: BLOCKED
+    in_progress --> escalated: Max Iterations
+    in_progress --> stopped: *stop-qa-loop
+
+    stopped --> in_progress: *resume-qa-loop
+    escalated --> in_progress: *resume-qa-loop
+
+    completed --> [*]
+    escalated --> [*]: Intervencao Humana
+```
+
+### Sequencia de Comunicação entre Agentes
+
+```mermaid
+sequenceDiagram
+    participant U as Usuario
+    participant S as System
+    participant QA as @qa (Quinn)
+    participant DEV as @dev (Dex)
+
+    U->>S: *qa-loop STORY-42
+    S->>S: Inicializar loop-status.json
+
+    loop Ate max iterações ou APPROVE
+        S->>QA: Executar qa-review-story.md
+        QA->>QA: CodeRabbit Self-Healing
+        QA->>QA: Análise Completa
+        QA-->>S: verdict, issuesFound, gate-file
+
+        alt verdict == APPROVE
+            S-->>U: Story APROVADA
+        else verdict == BLOCKED
+            S-->>U: ESCALATE - Requer Humano
+        else verdict == REJECT
+            S->>QA: Executar qa-create-fix-request.md
+            QA-->>S: fix-request.md, prioritizedIssues
+
+            S->>DEV: Executar dev-apply-qa-fixes.md
+            DEV->>DEV: Aplicar Fixes
+            DEV->>DEV: Rodar Testes
+            DEV-->>S: fixes-applied.json, issuesFixed
+
+            S->>S: Incrementar iteration
+        end
+    end
+
+    S-->>U: Sumario Final
+```
+
+---
+
+## Steps Detalhados
+
+### Step 1: Review (Fase 1)
+
+| Atributo | Valor |
+|----------|-------|
+| **Nome** | `review` |
+| **Fase** | 1 - QA Review |
+| **Agente** | `@qa` (Quinn) |
+| **Task** | `qa-review-story.md` |
+| **Timeout** | 30 minutos (1.800.000 ms) |
+
+**Descrição:**
+Executa revisao completa de QA da implementação da story, produzindo um verdict: APPROVE, REJECT ou BLOCKED.
+
+**Inputs:**
+
+```yaml
+storyId: "{storyId}"
+iteration: "{currentIteration}"
+previousIssues: "{history[-1].issuesFound|0}"
+```
+
+**Outputs:**
+
+- `gate-file.yaml` - Arquivo de gate com decisão
+- `verdict` - APPROVE | REJECT | BLOCKED
+- `issuesFound` - Numero de issues encontrados
+
+**On Success:**
+```
+log: "Review complete: {verdict} ({issuesFound} issues)"
+next: check_verdict
+```
+
+**On Failure:**
+```
+action: retry (max 2 tentativas)
+on_exhausted: escalate
+```
+
+---
+
+### Step 2: Check Verdict (Fase 2)
+
+| Atributo | Valor |
+|----------|-------|
+| **Nome** | `check_verdict` |
+| **Fase** | 2 - Verdict Check |
+| **Agente** | `system` |
+
+**Descrição:**
+Avalia o verdict da revisao e determina a próxima acao.
+
+**Lógica de Decisão:**
+
+```mermaid
+flowchart TD
+    V{"verdict?"}
+
+    V -->|"APPROVE"| A["Action: COMPLETE<br/>Story aprovada apos N iterações"]
+    V -->|"BLOCKED"| B["Action: ESCALATE<br/>Requer intervenção humana"]
+    V -->|"REJECT"| C["Action: CONTINUE<br/>Prosseguir para criar fix request"]
+
+    style A fill:#c8e6c9
+    style B fill:#ffcdd2
+    style C fill:#fff9c4
+```
+
+---
+
+### Step 3: Create Fix Request (Fase 3)
+
+| Atributo | Valor |
+|----------|-------|
+| **Nome** | `create_fix_request` |
+| **Fase** | 3 - Create Fix Request |
+| **Agente** | `@qa` (Quinn) |
+| **Task** | `qa-create-fix-request.md` |
+
+**Descrição:**
+Gera um documento estruturado de fix request a partir dos findings da revisao. Prioriza issues e fornece instruções acionaveis de correção.
+
+**Inputs:**
+
+```yaml
+storyId: "{storyId}"
+gateFile: "{outputs.review.gate-file}"
+iteration: "{currentIteration}"
+```
+
+**Outputs:**
+
+- `fix-request.md` - Documento com issues priorizados
+- `prioritizedIssues` - Lista de issues ordenados por prioridade
+
+**On Success:**
+```
+log: "Fix request created with {prioritizedIssues.length} prioritized issues"
+next: fix_issues
+```
+
+**On Failure:**
+```
+action: continue
+fallback: "Use raw gate file for fixes"
+```
+
+---
+
+### Step 4: Fix Issues (Fase 4)
+
+| Atributo | Valor |
+|----------|-------|
+| **Nome** | `fix_issues` |
+| **Fase** | 4 - Apply Fixes |
+| **Agente** | `@dev` (Dex) |
+| **Task** | `dev-apply-qa-fixes.md` |
+| **Timeout** | 60 minutos (3.600.000 ms) |
+
+**Descrição:**
+O agente desenvolvedor aplica as correções baseadas no fix request. Executa testes e valida as mudanças.
+
+**Inputs:**
+
+```yaml
+storyId: "{storyId}"
+fixRequest: "{outputs.create_fix_request.fix-request}"
+iteration: "{currentIteration}"
+```
+
+**Outputs:**
+
+- `fixes-applied.json` - Registro das correções aplicadas
+- `issuesFixed` - Numero de issues corrigidos
+
+**On Success:**
+```
+log: "Fixed {issuesFixed} of {issuesFound} issues"
+next: increment_iteration
+```
+
+**On Failure:**
+```
+action: retry (max 2 tentativas)
+on_exhausted: escalate com razao "Dev agent unable to apply fixes after retries"
+```
+
+---
+
+### Step 5: Increment Iteration (Fase 5)
+
+| Atributo | Valor |
+|----------|-------|
+| **Nome** | `increment_iteration` |
+| **Fase** | 5 - Check Iteration |
+| **Agente** | `system` |
+
+**Descrição:**
+Incrementa o contador de iteracao e verifica contra o maximo. Se max atingido, escala para humano.
+
+**Lógica:**
+
+```mermaid
+flowchart TD
+    I{"iteration >= maxIterations?"}
+
+    I -->|"Sim"| E["ESCALATE<br/>Max iterations reached without APPROVE"]
+    I -->|"Não"| C["CONTINUE<br/>Voltar para Step 1 (review)<br/>iteration++"]
+
+    style E fill:#ffcdd2
+    style C fill:#c8e6c9
+```
+
+---
+
+## Agentes Participantes
+
+### @qa - Quinn (Test Architect)
+
+```yaml
+Nome: Quinn
+ID: qa
+Titulo: Test Architect & Quality Advisor
+Icone: ✅
+Arquetipo: Guardian
+Signo: Virgo
+
+Responsabilidades no QA Loop:
+  - Executar revisao completa de QA (qa-review-story.md)
+  - Criar fix requests estruturados (qa-create-fix-request.md)
+  - Determinar verdict: APPROVE, REJECT, BLOCKED
+  - Gerar gate files com decisoes documentadas
+```
+
+**Ferramentas Utilizadas:**
+
+| Ferramenta | Propósito |
+|------------|-----------|
+| `github-cli` | Code review e PR management |
+| `browser` | End-to-end testing e UI validation |
+| `context7` | Research testing frameworks |
+| `supabase` | Database testing e data validation |
+| `coderabbit` | Automated code review |
+
+**Integração CodeRabbit:**
+
+```yaml
+self_healing:
+  enabled: true
+  type: full
+  max_iterations: 3
+  timeout_minutes: 30
+  severity_filter: [CRITICAL, HIGH]
+  behavior:
+    CRITICAL: auto_fix
+    HIGH: auto_fix
+    MEDIUM: document_as_debt
+    LOW: ignore
+```
+
+---
+
+### @dev - Dex (Full Stack Developer)
+
+```yaml
+Nome: Dex
+ID: dev
+Titulo: Full Stack Developer
+Icone: 💻
+Arquetipo: Builder
+Signo: Aquarius
+
+Responsabilidades no QA Loop:
+  - Aplicar correções baseadas em fix request (dev-apply-qa-fixes.md)
+  - Executar testes para validar correções
+  - Atualizar Dev Agent Record na story
+  - Garantir que fixes nao quebrem funcionalidades existentes
+```
+
+**Ferramentas Utilizadas:**
+
+| Ferramenta | Propósito |
+|------------|-----------|
+| `git` | Local operations: add, commit, status, diff |
+| `context7` | Look up library documentation |
+| `supabase` | Database operations |
+| `browser` | Test web applications |
+| `coderabbit` | Pre-commit code quality review |
+
+---
+
+### System Agent
+
+```yaml
+Tipo: Automatico
+Responsabilidades:
+  - Verificar verdicts
+  - Incrementar iterações
+  - Controlar fluxo do workflow
+  - Gerenciar status do loop
+```
+
+---
+
+## Tasks Executadas
+
+### 1. qa-review-story.md
+
+**Localização:** `.aiox-core/development/tasks/qa-review-story.md`
+
+**Propósito:** Realizar revisao arquitetural de testes com decisão de quality gate.
+
+**Processo de Revisao:**
+
+```mermaid
+flowchart TD
+    subgraph PRE["Pre-Review"]
+        P1["CodeRabbit Self-Healing Loop"]
+        P2["Max 3 iterações CRITICAL/HIGH"]
+    end
+
+    subgraph RISK["Avaliação de Risco"]
+        R1["Auth/Payment/Security?"]
+        R2["Sem testes adicionados?"]
+        R3["Diff > 500 linhas?"]
+        R4["Gate anterior FAIL?"]
+        R5["> 5 ACs?"]
+    end
+
+    subgraph ANALYSIS["Análise Completa"]
+        A1["Requirements Traceability"]
+        A2["Code Quality Review"]
+        A3["Test Architecture Assessment"]
+        A4["NFR Validation"]
+        A5["Testability Evaluation"]
+        A6["Technical Debt Identification"]
+    end
+
+    subgraph OUTPUT["Saidas"]
+        O1["QA Results Section"]
+        O2["gate-file.yaml"]
+    end
+
+    PRE --> RISK
+    RISK --> ANALYSIS
+    ANALYSIS --> OUTPUT
+```
+
+**Critérios de Gate:**
+
+| Gate | Condição |
+|------|----------|
+| **PASS** | Todos requisitos criticos atendidos, sem issues bloqueantes |
+| **CONCERNS** | Issues nao-criticos encontrados, time deve revisar |
+| **FAIL** | Issues criticos que devem ser enderecados |
+| **WAIVED** | Issues reconhecidos mas explicitamente waived pelo time |
+
+---
+
+### 2. qa-create-fix-request.md
+
+**Localização:** `.aiox-core/development/tasks/qa-create-fix-request.md`
+
+**Propósito:** Gerar documento estruturado `QA_FIX_REQUEST.md` para @dev baseado nos findings de QA.
+
+**Workflow:**
+
+```mermaid
+flowchart LR
+    subgraph LOAD["Fase 1: Carregar"]
+        L1["Localizar QA Report"]
+        L2["Parse metadata"]
+    end
+
+    subgraph EXTRACT["Fase 2: Extrair"]
+        E1["Filtrar por severidade"]
+        E2["CRITICAL: sempre"]
+        E3["MAJOR: sempre"]
+        E4["MINOR: opcional"]
+    end
+
+    subgraph GENERATE["Fase 3: Gerar"]
+        G1["Criar QA_FIX_REQUEST.md"]
+        G2["Template estruturado"]
+    end
+
+    subgraph NOTIFY["Fase 4: Notificar"]
+        N1["Output sucesso"]
+        N2["Proximos passos @dev"]
+    end
+
+    LOAD --> EXTRACT --> GENERATE --> NOTIFY
+```
+
+**Estrutura do Fix Request:**
+
+```markdown
+# QA Fix Request: {storyId}
+
+## Instructions for @dev
+- Fix ONLY the issues listed below
+- Do not add features or refactor unrelated code
+
+## Summary
+| Severity | Count | Status |
+|----------|-------|--------|
+| CRITICAL | N | Must fix before merge |
+| MAJOR | N | Should fix before merge |
+| MINOR | N | Optional improvements |
+
+## Issues to Fix
+### 1. [CRITICAL] {title}
+- Location: `{file:line}`
+- Problem: {description}
+- Expected: {expected}
+- Verification: [ ] {steps}
+
+## Constraints
+- [ ] Fix ONLY listed issues
+- [ ] Run all tests: `npm test`
+- [ ] Run linting: `npm run lint`
+```
+
+---
+
+### 3. dev-apply-qa-fixes.md
+
+**Localização:** `.aiox-core/development/tasks/dev-apply-qa-fixes.md`
+
+**Propósito:** Aplicar fixes baseados no feedback de QA e gate review.
+
+**Workflow do Developer:**
+
+```mermaid
+flowchart TD
+    subgraph LOAD["1. Carregar Gate Report"]
+        L1["Carregar gate file"]
+        L2["Ou buscar referencia na story"]
+    end
+
+    subgraph REVIEW["2. Revisar Findings"]
+        R1["Categorizar issues"]
+        R2["BLOCKING: Must fix"]
+        R3["WARNING: Should fix"]
+        R4["RECOMMENDATION: Nice to have"]
+    end
+
+    subgraph PLAN["3. Criar Plano"]
+        P1["Identificar arquivos afetados"]
+        P2["Determinar root cause"]
+        P3["Planejar approach"]
+    end
+
+    subgraph FIX["4. Aplicar Fixes"]
+        F1["Fazer mudanças"]
+        F2["Seguir coding standards"]
+        F3["Atualizar testes"]
+    end
+
+    subgraph VALIDATE["5. Validacao"]
+        V1["npm run lint"]
+        V2["npm test"]
+        V3["npm run typecheck"]
+    end
+
+    subgraph UPDATE["6. Atualizar Story"]
+        U1["Dev Agent Record"]
+        U2["File List"]
+    end
+
+    LOAD --> REVIEW --> PLAN --> FIX --> VALIDATE --> UPDATE
+```
+
+**Exit Criteria:**
+
+- Todos issues BLOCKING resolvidos
+- Todos testes passando (lint, unit, integration)
+- Story file atualizado
+- Código pronto para re-review
+
+---
+
+## Pré-requisitos
+
+### Para Iniciar o QA Loop
+
+| Requisito | Descrição |
+|-----------|-----------|
+| **Story Status** | Deve estar em "Review" |
+| **Implementacao Completa** | Developer completou todas as tasks |
+| **File List Atualizada** | Lista de arquivos no story file esta atual |
+| **Testes Automatizados** | Todos testes automatizados passando |
+| **CodeRabbit Configurado** | CLI instalado no WSL (opcional mas recomendado) |
+
+### Configuração do Ambiente
+
+```yaml
+# Verificar CodeRabbit
+wsl bash -c '~/.local/bin/coderabbit auth status'
+
+# Verificar Node.js
+node --version  # >= 18
+
+# Verificar dependencias
+npm test        # Deve passar
+npm run lint    # Deve passar
+```
+
+---
+
+## Entradas e Saidas
+
+### Entradas do Workflow
+
+| Campo | Tipo | Obrigatório | Descrição |
+|-------|------|-------------|-----------|
+| `storyId` | string | Sim | Identificador da story (ex: "STORY-42") |
+| `maxIterations` | number | Não | Override do max (default: 5) |
+| `mode` | string | Não | `yolo`, `interactive`, `preflight` |
+
+### Saidas do Workflow
+
+| Arquivo | Localização | Descrição |
+|---------|-------------|-----------|
+| `loop-status.json` | `qa/loop-status.json` | Status atual do loop |
+| `gate-file.yaml` | `qa/gates/{storyId}.yaml` | Decisão de quality gate |
+| `fix-request.md` | `qa/QA_FIX_REQUEST.md` | Documento de correções |
+| `fixes-applied.json` | `qa/fixes-applied.json` | Registro de correções |
+| `summary.md` | `qa/summary.md` | Sumario final do loop |
+
+### Schema do Status File
+
+```yaml
+storyId: string              # ID da story
+currentIteration: number     # Iteração atual
+maxIterations: number        # Maximo configurado
+status: enum                 # pending | in_progress | completed | stopped | escalated
+startedAt: ISO-8601          # Timestamp de inicio
+updatedAt: ISO-8601          # Ultima atualizacao
+
+history:
+  - iteration: number
+    reviewedAt: ISO-8601
+    verdict: APPROVE | REJECT | BLOCKED
+    issuesFound: number
+    fixedAt: ISO-8601 | null
+    issuesFixed: number | null
+    duration: number         # milliseconds
+```
+
+---
+
+## Pontos de Decisão
+
+### Diagrama de Decisoes
+
+```mermaid
+flowchart TD
+    subgraph D1["Decisão 1: Verdict"]
+        V1{"Qual o verdict?"}
+        V1 -->|"APPROVE"| V1A["Completar Loop"]
+        V1 -->|"BLOCKED"| V1B["Escalar Imediatamente"]
+        V1 -->|"REJECT"| V1C["Continuar para Fixes"]
+    end
+
+    subgraph D2["Decisão 2: Max Iterations"]
+        I1{"iteration >= max?"}
+        I1 -->|"Sim"| I1A["Escalar: Max Atingido"]
+        I1 -->|"Não"| I1B["Incrementar e Continuar"]
+    end
+
+    subgraph D3["Decisão 3: Fix Failure"]
+        F1{"Fixes aplicados?"}
+        F1 -->|"Sucesso"| F1A["Prosseguir para Review"]
+        F1 -->|"Falha"| F1B{"Retries restantes?"}
+        F1B -->|"Sim"| F1C["Retry"]
+        F1B -->|"Não"| F1D["Escalar: Fix Failure"]
+    end
+
+    subgraph D4["Decisão 4: Review Failure"]
+        R1{"Review completou?"}
+        R1 -->|"Sucesso"| R1A["Processar Verdict"]
+        R1 -->|"Falha"| R1B{"Retries restantes?"}
+        R1B -->|"Sim"| R1C["Retry Review"]
+        R1B -->|"Não"| R1D["Escalar: Review Failure"]
+    end
+```
+
+### Critérios de Escalação
+
+| Trigger | Razao | Ação |
+|---------|-------|------|
+| `max_iterations_reached` | Loop atingiu max sem APPROVE | Escalar com contexto completo |
+| `verdict_blocked` | QA retornou BLOCKED | Escalar imediatamente |
+| `fix_failure` | @dev nao conseguiu aplicar fixes apos retries | Escalar com log de erros |
+| `manual_escalate` | Usuario executou `*escalate-qa-loop` | Escalar sob demanda |
+
+---
+
+## Configuração
+
+### Parametros Configuraveis
+
+```yaml
+config:
+  # Maximo de iterações (AC2)
+  maxIterations: 5
+  configPath: autoClaude.qaLoop.maxIterations
+
+  # Progress tracking
+  showProgress: true
+  verbose: true
+
+  # Localização do status file (AC4)
+  statusFile: qa/loop-status.json
+
+  # Integração com Dashboard (AC7)
+  dashboardStatusPath: .aiox/dashboard/status.json
+  legacyStatusPath: .aiox/status.json
+
+  # Timeout por fase (milliseconds)
+  reviewTimeout: 1800000    # 30 minutos
+  fixTimeout: 3600000       # 60 minutos
+
+  # Configuração de retry
+  maxRetries: 2
+  retryDelay: 5000          # 5 segundos
+```
+
+### Customizacao por Projeto
+
+No arquivo `.aiox-core/core-config.yaml`:
+
+```yaml
+autoClaude:
+  qaLoop:
+    maxIterations: 3        # Reduzir para projetos menores
+    reviewTimeout: 900000   # 15 min para reviews rapidos
+    fixTimeout: 1800000     # 30 min para fixes simples
+```
+
+---
+
+## Controle de Execução
+
+### Comandos Disponiveis
+
+| Comando | Ação | Descrição |
+|---------|------|-----------|
+| `*qa-loop {storyId}` | `start_loop` | Inicia loop completo |
+| `*qa-loop-review` | `run_step: review` | Inicia apenas do step review |
+| `*qa-loop-fix` | `run_step: fix` | Inicia apenas do step fix |
+| `*stop-qa-loop` | `stop_loop` | Para loop e salva estado |
+| `*resume-qa-loop` | `resume_loop` | Retoma loop parado/escalado |
+| `*escalate-qa-loop` | `escalate` | Forca escalacao manual |
+| `*qa-loop --reset` | `reset` | Deleta status e reinicia |
+
+### Fluxo de Stop/Resume
+
+```mermaid
+sequenceDiagram
+    participant U as Usuario
+    participant S as System
+    participant F as loop-status.json
+
+    Note over U,F: STOP
+    U->>S: *stop-qa-loop
+    S->>F: status = "stopped"
+    S->>F: Salvar estado atual
+    S-->>U: Loop parado em iteration N
+
+    Note over U,F: RESUME
+    U->>S: *resume-qa-loop
+    S->>F: Carregar estado
+    S->>S: Verificar status era stopped/escalated
+    S->>F: status = "in_progress"
+    S-->>U: Loop retomado em iteration N
+```
+
+---
+
+## Escalação
+
+### Triggers de Escalação
+
+```yaml
+escalation:
+  enabled: true
+  triggers:
+    - max_iterations_reached
+    - verdict_blocked
+    - fix_failure
+    - manual_escalate
+```
+
+### Pacote de Contexto
+
+Quando ocorre escalacao, o sistema prepara:
+
+| Item | Descrição |
+|------|-----------|
+| `loop-status.json` | Status completo do loop |
+| Gate files | Todos gate files do historico |
+| Fix requests | Todos fix requests gerados |
+| Summary | Resumo de todas iterações |
+
+### Mensagem de Notificação
+
+```
+QA Loop Escalation for {storyId}
+
+Reason: {escalation.reason}
+Iterations completed: {currentIteration}
+Last verdict: {history[-1].verdict}
+Outstanding issues: {history[-1].issuesFound - history[-1].issuesFixed}
+
+Review the context package and decide:
+1. Resume loop: *resume-qa-loop {storyId}
+2. Manually fix and approve
+3. Reject story and create follow-up
+```
+
+### Canais de Notificação
+
+- `log` - Log do sistema
+- `console` - Output no terminal
+
+---
+
+## Integração com Dashboard
+
+### Status JSON Schema
+
+```yaml
+integration:
+  status_json:
+    track_loop: true
+    field: qaLoop
+    update_on_each_iteration: true
+
+    schema:
+      storyId: string
+      status: string
+      currentIteration: number
+      maxIterations: number
+      lastVerdict: string
+      lastIssuesFound: number
+      updatedAt: ISO-8601
+```
+
+### Atualização de Status do Projeto
+
+```yaml
+project_status:
+  update_story_status: true
+  status_field: qaLoopStatus
+```
+
+### Notificações
+
+| Evento | Mensagem | Canais |
+|--------|----------|--------|
+| `on_approve` | "QA Loop APPROVED: {storyId}" | log |
+| `on_escalate` | "QA Loop ESCALATED: {storyId} - needs attention" | log |
+| `on_stop` | "QA Loop STOPPED: {storyId}" | log |
+
+---
+
+## Tratamento de Erros
+
+### Erros Comuns e Resoluções
+
+| Erro | Causa | Resolução | Ação |
+|------|-------|-----------|------|
+| `missing_story_id` | Story ID nao fornecido | "Usage: *qa-loop STORY-42" | prompt |
+| `review_timeout` | Fase de review excedeu timeout | Verificar status do QA agent | escalate |
+| `fix_timeout` | Fase de fix excedeu timeout | Verificar status do Dev agent | escalate |
+| `invalid_status` | Arquivo de status corrompido | "Reset loop: *qa-loop {storyId} --reset" | halt |
+
+### Estrategias de Retry
+
+```yaml
+on_failure:
+  action: retry
+  max_retries: 2              # Maximo de tentativas
+  retryDelay: 5000            # Delay entre tentativas
+  on_exhausted: escalate      # Ação quando retries esgotados
+```
+
+---
+
+## Troubleshooting
+
+### Problema: Loop Travado em Review
+
+**Sintomas:**
+- Review nao completa apos 30 minutos
+- Status permanece "in_progress"
+
+**Diagnóstico:**
+```bash
+# Verificar status do loop
+cat qa/loop-status.json | jq '.status, .currentIteration'
+
+# Verificar ultimo gate file
+ls -la qa/gates/
+```
+
+**Solução:**
+1. Executar `*stop-qa-loop`
+2. Verificar se CodeRabbit esta respondendo
+3. Executar `*resume-qa-loop` para retomar
+
+---
+
+### Problema: Fix Não Aplicado
+
+**Sintomas:**
+- @dev reporta sucesso mas issues persistem
+- Re-review encontra mesmos problemas
+
+**Diagnóstico:**
+```bash
+# Verificar fix request
+cat qa/QA_FIX_REQUEST.md
+
+# Verificar fixes aplicados
+cat qa/fixes-applied.json
+```
+
+**Solução:**
+1. Revisar manualmente o fix-request.md
+2. Verificar se @dev atualizou os arquivos corretos
+3. Rodar testes localmente antes de re-review
+
+---
+
+### Problema: Max Iterations Atingido
+
+**Sintomas:**
+- Loop escala apos 5 iterações sem APPROVE
+
+**Diagnóstico:**
+```bash
+# Ver historico completo
+cat qa/loop-status.json | jq '.history'
+```
+
+**Solução:**
+1. Analisar pattern de issues recorrentes
+2. Verificar se requisitos estao claros
+3. Considerar aumentar maxIterations ou resolver manualmente
+
+---
+
+### Problema: CodeRabbit Não Funciona
+
+**Sintomas:**
+- Erro "coderabbit: command not found"
+- Timeout na fase de self-healing
+
+**Diagnóstico:**
+```bash
+# Verificar instalacao
+wsl bash -c 'which coderabbit'
+
+# Verificar autenticacao
+wsl bash -c '~/.local/bin/coderabbit auth status'
+```
+
+**Solução:**
+1. Reinstalar CodeRabbit no WSL
+2. Executar `coderabbit auth login`
+3. Verificar path no agent config
+
+---
+
+### Problema: Status File Corrompido
+
+**Sintomas:**
+- Erro "invalid_status"
+- Loop nao inicia ou retoma
+
+**Solução:**
+```bash
+# Backup do arquivo corrompido
+mv qa/loop-status.json qa/loop-status.json.bak
+
+# Reiniciar loop
+*qa-loop {storyId} --reset
+```
+
+---
+
+## Referências
+
+### Arquivos do Workflow
+
+| Arquivo | Localização |
+|---------|-------------|
+| Workflow Definition | `.aiox-core/development/workflows/qa-loop.yaml` |
+| QA Review Task | `.aiox-core/development/tasks/qa-review-story.md` |
+| Create Fix Request Task | `.aiox-core/development/tasks/qa-create-fix-request.md` |
+| Apply QA Fixes Task | `.aiox-core/development/tasks/dev-apply-qa-fixes.md` |
+| QA Agent | `.aiox-core/development/agents/qa.md` |
+| Dev Agent | `.aiox-core/development/agents/dev.md` |
+
+### Documentação Relacionada
+
+| Documento | Descrição |
+|-----------|-----------|
+| Epic 6 - QA Evolution | Contexto do Autonomous Development Engine |
+| Story 6.5 | Story de implementação do QA Loop |
+| Story 6.3.3 | CodeRabbit Self-Healing Integration |
+| ADR-XXX | Architecture Decision Record (se existir) |
+
+### Templates
+
+| Template | Localização | Uso |
+|----------|-------------|-----|
+| `qa-gate-tmpl.yaml` | `.aiox-core/development/templates/` | Gate file structure |
+| `story-tmpl.yaml` | `.aiox-core/development/templates/` | Story file structure |
+
+---
+
+## Historico de Alterações
+
+| Data | Versao | Autor | Mudanças |
+|------|--------|-------|----------|
+| 2026-02-04 | 1.0 | Technical Documentation Specialist | Versao inicial |
+
+---
+
+*Documentação gerada automaticamente a partir do workflow `qa-loop.yaml`*