@brunosps00/dev-workflow 1.0.0 → 1.0.2

package/scaffold/pt-br/commands/dw-bugfix.md

@@ -9,7 +9,30 @@
     - NÃO use para corrigir bugs encontrados durante testes de QA (use `/dw-qa --fix` em vez disso)
 
     ## Posição no Pipeline
-    **Antecessor:** (bug report) | **Sucessor:** `/dw-commit` e depois `/dw-generate-pr`
+    **Antecessor:** (bug report) | **Sucessor:** `/dw-commit` e depois `/dw-generate-pr` (opcionalmente `/dw-review --bugfix <slug>` e `/dw-qa --bugfix <slug>` no meio para rigor extra)
+
+    ## Localização dos Arquivos
+
+    Todo bugfix tem uma entrada de índice em `.dw/bugfixes/`. Modo Direto mantém o artefato completo lá. Modo Análise e escalações via safety valve dividem: a entrada de índice fica em `.dw/bugfixes/`, mas o `prd.md` que o `/dw-plan` vai consumir é colocado em `.dw/spec/prd-bugfix-<slug>/` (o path que `/dw-plan techspec` e `/dw-plan tasks` já esperam).
+
+    **Casa do índice — sempre criada:**
+
+    - Diretório de índice do bugfix: `.dw/bugfixes/NNN-<slug>/` (NNN com 3 dígitos, sequencial em todos os bugfixes já registrados)
+    - Artefatos modo Direto aqui: `TASK.md` (triagem + plano), `fix-report.md` (evidência de verify), `SUMMARY.md` (registro de uma página)
+    - Artefatos modo Análise / escalação aqui: `TASK.md` (triagem + plano que seria executado), `escalated.md` (uma linha apontando para o diretório do spec que assumiu)
+    - Saída de review downstream (quando `/dw-review --bugfix <slug>` roda): `.dw/bugfixes/NNN-<slug>/review/`
+    - Saída de QA downstream (quando `/dw-qa --bugfix <slug>` roda): `.dw/bugfixes/NNN-<slug>/QA/`
+
+    **Casa do spec — criada apenas em Análise ou escalação via safety valve:**
+
+    - Diretório de spec: `.dw/spec/prd-bugfix-<slug>/`
+    - `prd.md` mora aqui (NÃO em `.dw/bugfixes/`) para que `/dw-plan techspec prd-bugfix-<slug>` e `/dw-plan tasks prd-bugfix-<slug>` operem contra o path que foram desenhados, sem nenhuma modificação ao `/dw-plan`.
+
+    **Templates:** `.dw/templates/bugfix-template.md` (para `TASK.md`/`prd.md`), `.dw/templates/bugfix-summary-template.md` (para `SUMMARY.md`), `.dw/templates/pr-bugfix-template.md` (para o corpo do PR).
+
+    **Descoberta do próximo NNN:** liste `.dw/bugfixes/`, parseie o prefixo de 3 dígitos de cada diretório, tome `max + 1` (ou `1` se vazio). Crie o diretório antes de escrever qualquer coisa. O mesmo `NNN-<slug>` é usado para nomear a parte slug do diretório de spec (ex: bugfix `007-stripe-webhook-retry` escala para spec `.dw/spec/prd-bugfix-stripe-webhook-retry/`).
+
+    **Slug:** kebab-case derivado de `{{BUG_DESCRIPTION}}` (ex: "login-nao-funciona", "erro-500-salvar-usuario").
 
     ## Skills Complementares
 
@@ -34,23 +57,23 @@
 
     | Modo | Quando Usar | Resultado |
     |------|-------------|-----------|
-    | **Direto** (padrão) | Bug simples, <=5 arquivos, sem migration | Executa correção imediata |
-    | **Análise** (`--análise`) | Bug complexo, precisa planejamento | Gera `.dw/spec/dw-bugfix-*/prd.md` para techspec -> tasks |
+    | **Direto** (padrão) | Bug simples, <=5 arquivos, sem migration, <=5 tasks numeradas | Executa correção imediata; persiste `TASK.md` + `fix-report.md` + `SUMMARY.md` em `.dw/bugfixes/NNN-<slug>/` |
+    | **Análise** (`--análise`) | Bug complexo, precisa planejamento | Divide: `.dw/bugfixes/NNN-<slug>/{TASK.md, escalated.md}` como entrada de índice + `.dw/spec/prd-bugfix-<slug>/prd.md` para o pipeline techspec -> tasks |
 
     ### Modo Análise
 
-    Quando o usuário especificar `--análise` ou quando detectar que o bug precisa de mais planejamento:
+    Quando o usuário especificar `--análise` ou quando o safety valve (passo 5.0) disparar:
 
     ```
     /dw-bugfix meu-projeto "Login não funciona" --análise
     ```
 
     Neste modo:
-    1. Segue o fluxo normal de perguntas e análise
-    2. Em vez de executar, gera documento em `.dw/spec/dw-bugfix-[nome]/prd.md`
-    3. O arquivo é nomeado `prd.md` para manter compatibilidade com o pipeline dw-create-techspec/dw-plan tasks
-    4. Depois o usuário pode rodar `/dw-plan techspec .dw/spec/dw-bugfix-[nome]`
-    5. E então `/dw-plan tasks .dw/spec/dw-bugfix-[nome]`
+    1. Segue o fluxo normal de perguntas e análise.
+    2. Aloca `NNN` e cria `.dw/bugfixes/NNN-<slug>/`. Escreve `TASK.md` (a triagem + respostas + plano que seria executado mas não roda aqui).
+    3. Cria o diretório de spec `.dw/spec/prd-bugfix-<slug>/` e escreve `prd.md` lá (usando `.dw/templates/bugfix-template.md`). Este é o path que `/dw-plan techspec` e `/dw-plan tasks` já sabem operar.
+    4. Escreve `.dw/bugfixes/NNN-<slug>/escalated.md` com exatamente uma linha: `Escalated to /dw-plan on <YYYY-MM-DD> → see .dw/spec/prd-bugfix-<slug>/`. Esse cross-reference permite que `/dw-intel --build` inclua o bugfix em `bugfixes.json` mesmo com o planejamento ativo acontecendo em `.dw/spec/`.
+    5. Avise ao usuário os próximos comandos: `/dw-plan techspec prd-bugfix-<slug>` e `/dw-plan tasks prd-bugfix-<slug>`.
 
     ## Fluxo de Trabalho
 
@@ -141,6 +164,27 @@
     - {{TARGET}}/.dw/rules/*.md
     ```
 
+    ### 1.5. Carregar Concerns (Obrigatório quando concerns.md existe)
+
+    Se `.dw/rules/concerns.md` existir:
+    - Leia uma vez.
+    - Para cada arquivo ou módulo referenciado em `{{BUG_DESCRIPTION}}` ou na área suspeita do fix, cruze com Hot Spots, Integrações Frágeis, Código Hostil e Histórico de Bugs Conhecidos.
+    - Se houver match, sinalize ANTES das 3 perguntas de clarificação:
+
+    ```
+    ## Concern detectada
+
+    A área que você está tocando está flagada em `.dw/rules/concerns.md`:
+
+    > [entrada verbatim do concerns.md]
+
+    Isso significa: [traduzir a concern para o que implica neste fix — teste extra, revisor extra, ADR, etc.]
+
+    Prosseguindo — mas o fix-report.md precisa registrar explicitamente qual concern foi tocada e como foi tratada.
+    ```
+
+    Se `.dw/rules/concerns.md` não existir, NÃO crie automaticamente (isso é trabalho do Step 9 do `/dw-analyze-project`). Anote no chat: "ainda sem mapa de concerns — considere rodar `/dw-analyze-project` depois do fix para construir um." Continue.
+
     ### 2. Coletar Evidências (Obrigatório)
 
     Execute comandos para entender o estado atual:
@@ -199,6 +243,40 @@
     | Afeta múltiplos projetos? | Redirecionar para PRD |
     | Estimativa > 2 horas de implementação? | Redirecionar para PRD |
 
+    ### 5.0. Safety Valve (OBRIGATÓRIO antes do passo 5)
+
+    <critical>
+    ANTES de desenhar a lista numerada do passo 5, esboce inline os passos que pretende escrever.
+    Se esse esboço revelar **mais de 5 tasks numeradas distintas**, OU **qualquer dependência cross-file que obrigue ordem específica de execução**, OU **uma task que requeira rodar migration / refactor / novo endpoint / alteração de contrato de API**, então o escopo do bugfix foi SUBESTIMADO e você DEVE escalar.
+    </critical>
+
+    **Por que isso existe:** a triagem do passo 0 pega problemas de escopo a partir da descrição do sintoma. O checkpoint 4.1 pega depois da análise de causa raiz. Esta válvula pega o caso que sobra — quando o fix em si, uma vez listado, revela mais complexidade do que triagem e RCA previram. NÃO existe flag de bypass. Escalar é o desfecho correto.
+
+    **Procedimento de escalação:**
+
+    1. Aloque `NNN` para `.dw/bugfixes/NNN-<slug>/`. Escreva `TASK.md` com a triagem, clarificações, causa raiz e plano que seria executado.
+    2. Crie `.dw/spec/prd-bugfix-<slug>/` e escreva `prd.md` lá (use `.dw/templates/bugfix-template.md`). Este é o path que `/dw-plan` espera.
+    3. Escreva `.dw/bugfixes/NNN-<slug>/escalated.md` com: `Escalated to /dw-plan on <YYYY-MM-DD> — reason: <qual critério da válvula disparou> → see .dw/spec/prd-bugfix-<slug>/`.
+    4. Reporte ao usuário:
+
+    ```
+    ## Escopo maior que bugfix
+
+    Listando o fix produziu [N] tasks / [deps cross-file] / [tipo de mudança proibida].
+    Pelo safety valve, isso não é mais um bugfix cirúrgico.
+
+    Índice do bugfix preservado em `.dw/bugfixes/NNN-<slug>/{TASK.md, escalated.md}`.
+    PRD criado em `.dw/spec/prd-bugfix-<slug>/prd.md`.
+
+    Próximo — escolha um:
+      - Cadeia manual: `/dw-plan techspec prd-bugfix-<slug>` → `/dw-plan tasks prd-bugfix-<slug>` → `/dw-run` → `/dw-qa` → `/dw-review` → `/dw-commit` → `/dw-generate-pr`.
+      - Entregar pro autopilot: `/dw-autopilot --from-prd prd-bugfix-<slug>` — retoma no GATE 1 (aprovação do PRD) e roda o resto automaticamente com os três gates usuais.
+    ```
+
+    5. Pare este comando. Não avance para o passo 5. O usuário (ou autopilot) invoca `/dw-plan` ou `/dw-autopilot --from-prd` em seguida.
+
+    **Se a válvula NÃO disparar:** Continue para o passo 5.
+
     ### 5. Propor Tarefas Numeradas (Obrigatório)
 
     <critical>
@@ -222,29 +300,64 @@
     - `ajustar` - me diga o que modificar no plano
     ```
 
-    ### 5.5. Verificação Final (Modo Direto — obrigatório antes do commit)
+    ### 5.5. Verificação Final + Persistência (Modo Direto — obrigatório antes do commit)
 
     <critical>Após aplicar as tarefas aprovadas em modo Direto, invocar `dw-verify` antes do commit. O VERIFICATION REPORT deve mostrar:
     1. O comando de verificação do projeto (test + lint + build) com exit 0.
     2. Reprodução do sintoma original: o cenário que disparava o bug já NÃO dispara mais.
-    
+
     Sem PASS nos dois, NÃO commit. Reportar o que falhou e retomar da etapa 4 (análise de causa raiz).</critical>
 
+    **Em caso de PASS, persistir o artefato do bugfix (sempre — inclusive em modo Direto):**
+
+    1. Descubra o próximo `NNN` (ver seção Localização dos Arquivos).
+    2. Crie `.dw/bugfixes/NNN-<slug>/` se ainda não foi criado no passo 5.0.
+    3. Escreva `TASK.md` com a triagem, clarificações, causa raiz e plano aprovado como executado (use `.dw/templates/bugfix-template.md` como base).
+    4. Escreva `fix-report.md` com o VERIFICATION REPORT verbatim do `dw-verify` mais o trace antes/depois da reprodução.
+    5. Escreva `SUMMARY.md` usando `.dw/templates/bugfix-summary-template.md`. Preencha slug, data, status `Fixed`, severidade, related_concerns (do passo 1.5), Sintoma (verbatim), Causa Raiz (uma frase), Resolução (2-4 bullets), Arquivos Tocados, Verificação, Relacionado, Followups.
+    6. Se o fix tocou uma concern listada em `.dw/rules/concerns.md`, anexe uma linha à coluna `Last incident` da row daquela concern (ou adicione uma row nova sob Histórico de Bugs Conhecidos) — preserve entradas escritas a mão entre `<!-- preserved:start -->`.
+    7. Reporte os paths dos três arquivos no chat antes do passo de commit.
+
     ### 6. Gerar Documento Bugfix (Modo Análise)
 
     <critical>
     Este passo é executado quando:
     - Usuário especificou `--análise` no início
     - Checkpoint 4.1 detectou escopo excessivo e usuário escolheu `análise`
+    - Safety valve 5.0 disparou
     </critical>
 
     **Ações:**
-    1. Criar diretório: `.dw/spec/dw-bugfix-[nome-do-bug]/`
-    2. Preencher com todas as informações coletadas nos passos anteriores
-    3. Salvar como: `.dw/spec/dw-bugfix-[nome-do-bug]/prd.md` (usa nome `prd.md` para compatibilidade com pipeline)
+    1. Descubra o próximo `NNN` e crie `.dw/bugfixes/NNN-<slug>/`.
+    2. Escreva `TASK.md` no diretório do bugfix (a triagem, clarificações, causa raiz e saída da análise) usando `.dw/templates/bugfix-template.md` como base.
+    3. Crie `.dw/spec/prd-bugfix-<slug>/` e escreva `prd.md` lá usando `.dw/templates/bugfix-template.md`. Este é o path que `/dw-plan` já entende — sem modificação no `/dw-plan`.
+    4. Escreva `.dw/bugfixes/NNN-<slug>/escalated.md` com: `Analysis mode on <YYYY-MM-DD> → see .dw/spec/prd-bugfix-<slug>/`.
+
+    **Slug do bug:** kebab-case da descrição (ex: "login-nao-funciona", "erro-500-salvar-usuario").
+
+    **Por que o split:** `/dw-plan techspec` e `/dw-plan tasks` já hardcodam `.dw/spec/prd-<slug>/prd.md` como entrada. Para manter `/dw-plan` intocado, o PRD vai pra lá; `.dw/bugfixes/NNN-<slug>/` continua a entrada de índice queryable (consumida por `/dw-intel`, `/dw-review --bugfix`, `/dw-qa --bugfix`). O `escalated.md` é o cross-reference.
+
+    **Formato de saída:**
+    ```
+    ## Documento de Bugfix Gerado
+
+    Índice do bugfix: `.dw/bugfixes/NNN-<slug>/{TASK.md, escalated.md}`
+    PRD de planejamento: `.dw/spec/prd-bugfix-<slug>/prd.md`
 
-    **IMPORTANTE:** O arquivo deve ser nomeado `prd.md` para que os comandos
-    `/dw-plan techspec` e `/dw-plan tasks` funcionem sem modificação.
+    **Próximos passos — escolha um:**
+
+    Opção A (cadeia manual, controle completo):
+    1. Revise `.dw/spec/prd-bugfix-<slug>/prd.md`
+    2. Rode: `/dw-plan techspec prd-bugfix-<slug>`
+    3. Rode: `/dw-plan tasks prd-bugfix-<slug>`
+    4. Execute tasks com: `/dw-run` (ou por task ID contra o spec)
+
+    Opção B (entregar pro autopilot):
+    1. Rode: `/dw-autopilot --from-prd prd-bugfix-<slug>`
+    2. Autopilot retoma no GATE 1 (aprovação do PRD) e roda TechSpec, Tasks, Run, QA, Review, Commit, PR com os três gates usuais.
+
+    O índice do bugfix continua queryable via `/dw-intel "bugfix history in <module>"`. Downstream `/dw-review --bugfix <slug>` e `/dw-qa --bugfix <slug>` ainda apontam para `.dw/bugfixes/NNN-<slug>/` quando quiser uma revisão focada apenas no patch cirúrgico final.
+    ```
 
     ## Tipos de Tarefa (permitidos em bugfix)
 
@@ -295,18 +408,21 @@
 
     ## Checklist de Qualidade
 
-    - [ ] **Triagem Bug vs Feature realizada**
-    - [ ] **Checkpoint de escopo realizado (passo 4.1)**
+    - [ ] **Triagem Bug vs Feature realizada (passo 0)**
+    - [ ] **Mapa de concerns consultado se presente (passo 1.5)**
     - [ ] Contexto do projeto/PRD carregado
     - [ ] Evidências coletadas (git log, erros)
     - [ ] **EXATAMENTE 3 perguntas feitas**
     - [ ] Respostas recebidas e analisadas
     - [ ] Causa raiz identificada
+    - [ ] **Checkpoint de escopo realizado (passo 4.1)**
+    - [ ] **Safety valve checado (passo 5.0) — escalado para `/dw-plan` se disparou**
     - [ ] Tarefas numeradas sequencialmente
     - [ ] **Máximo 5 arquivos afetados**
     - [ ] **Sem migrations**
     - [ ] **Tarefa de teste incluída (framework correto do projeto)**
     - [ ] Aguardando aprovação antes de executar
+    - [ ] **`.dw/bugfixes/NNN-<slug>/{TASK,fix-report,SUMMARY}.md` escritos após verify PASS**
 
     <critical>
     PRIMEIRO: Avalie se é bug ou feature (Passo 0).

package/scaffold/pt-br/commands/dw-intel.md

@@ -38,9 +38,10 @@ Voce e o assistente de inteligencia do codebase. Dois modos: consultar o indice
 
 ## Localizacao dos Arquivos
 
-- Intel machine-readable (consulta primeira): `.dw/intel/{stack,files,apis,deps}.json` + `.dw/intel/arch.md`
+- Intel machine-readable (consulta primeira): `.dw/intel/{stack,files,apis,deps,bugfixes}.json` + `.dw/intel/arch.md`
 - Metadados de refresh: `.dw/intel/.last-refresh.json`
-- Rules human-readable (consulta segunda): `.dw/rules/{index,<modulo>,integrations}.md`
+- Rules human-readable (consulta segunda): `.dw/rules/{index,<modulo>,integrations,concerns}.md`
+- Fonte do historico de bugfixes: `.dw/bugfixes/*/SUMMARY.md`
 - Grep direto fallback (consulta por ultimo): os arquivos source do projeto
 
 ## Comportamento Obrigatorio
@@ -67,6 +68,8 @@ Classifique o `{{QUERY}}` em uma das formas documentadas em `.agents/skills/dw-c
 - **api-list** — primario: `apis.json`
 - **find-export** — primario: `files.json` (busca em arrays `exports`)
 - **convention** — primario: `arch.md`, secundario: `.dw/rules/`
+- **bugfix-history** — primario: `bugfixes.json`, secundario: `.dw/rules/concerns.md` (gatilhos: "bugs em <modulo>", "fixes recentes", "o que quebrou em X", "historico de fix de Y")
+- **risk-area** — primario: `.dw/rules/concerns.md`, secundario: `bugfixes.json` (gatilhos: "X eh arriscado", "o que eh fragil", "hot spots", "tech debt")
 
 ### 3. Execucao da busca
 
@@ -143,7 +146,31 @@ Quando invocado com `--build`, o comando produz ou atualiza o indice queryable d
 5. **Extracao de API.** Routes, RPC handlers, GraphQL resolvers, superficie de CLI publica. Output em `.dw/intel/apis.json`. Budget ≤1.5K tokens.
 6. **Mapa de dependencias.** Imports internos cross-module + pacotes externos com arrays `used_by`. Output em `.dw/intel/deps.json`. Budget ≤1K tokens.
 7. **Sumario de arquitetura.** Documento em prosa descrevendo a forma do projeto, padroes-chave, request flows, topologia de deployment. Output em `.dw/intel/arch.md`. Budget ≤1.5K tokens.
-8. **Metadata de refresh.** Escrever `.dw/intel/.last-refresh.json` com `updated_at`, `version`, `mode` (full ou incremental), contagem de arquivos scanned.
+8. **Historico de bugfixes.** Se `.dw/bugfixes/` existir e nao estiver vazio, escanear todo `SUMMARY.md` e construir `.dw/intel/bugfixes.json` (budget ≤1K tokens). Schema:
+   ```json
+   {
+     "schema_version": "1.0",
+     "fixes": [
+       {
+         "slug": "001-login-nao-funciona",
+         "date": "YYYY-MM-DD",
+         "status": "Fixed",
+         "severity": "Medium",
+         "symptom_one_line": "...",
+         "root_cause_one_line": "...",
+         "modules_touched": ["src/auth/", "src/api/login/"],
+         "files_touched": ["src/auth/session.ts", "src/auth/session.test.ts"],
+         "related_concerns": ["src/auth/session.ts"],
+         "path": ".dw/bugfixes/001-login-nao-funciona/"
+       }
+     ],
+     "by_module": {
+       "src/auth/": ["001-login-nao-funciona", "007-refresh-token-leak"]
+     }
+   }
+   ```
+   Pular se `.dw/bugfixes/` nao existir. Rejeitar SUMMARY.md que falhem validacao de frontmatter; logar no relatorio do build. **Bugfixes escalados** (aqueles com `escalated.md` mas sem `SUMMARY.md` porque o fix vive em `.dw/spec/prd-bugfix-<slug>/`) sao pulados do `bugfixes.json` ate o spec entregar um fix — eles re-entram no indice quando o SUMMARY.md for finalmente escrito. O `TASK.md` escalado continua acessivel via grep direto; o indice so registra fixes concluidos.
+9. **Metadata de refresh.** Escrever `.dw/intel/.last-refresh.json` com `updated_at`, `version`, `mode` (full ou incremental), contagem de arquivos scanned, e contagem `bugfixes_indexed`.
 
 ### Skill complementar para build mode
 

package/scaffold/pt-br/commands/dw-pause.md

@@ -0,0 +1,92 @@
+<system_instructions>
+Voce e um agent de session-handoff. Seu trabalho e consolidar o estado mental da sessao atual em `.dw/STATE.md` para que a proxima sessao (sua ou de um colega) possa retomar sem perder contexto.
+
+## Quando Usar
+- Use quando o usuario disser "pausar trabalho", "encerrar sessao", "preciso parar agora", "salvar o que estamos fazendo"
+- Use proativamente antes de uma pausa longa, antes de trocar de projeto ou antes de uma compactacao iminente do context window
+- NAO use no meio de uma task quando nada foi decidido ou aprendido (nada a consolidar)
+- NAO use como substituto de `/dw-commit` — STATE.md e estado mental, nao mudancas de codigo
+
+## Posicao na Pipeline
+**Predecessor:** qualquer sessao de trabalho | **Sucessor:** `/dw-resume` (numa sessao futura)
+
+## O que este comando NAO faz
+- NAO commita codigo (use `/dw-commit`)
+- NAO substitui o `MEMORY.md` por-PRD (memoria de workflow para uma feature unica vive la; skill `dw-memory` gerencia)
+- NAO promove nada para ADRs (use `/dw-adr` para decisoes arquiteturais duraveis)
+
+## Local do Arquivo
+- Artefato unico: `.dw/STATE.md` (nivel de projeto, nao por-PRD)
+- Template: `.dw/templates/state-template.md` (usado apenas na primeira criacao)
+
+## Workflow
+
+### 1. Garantir que STATE.md existe
+- Se `.dw/STATE.md` nao existir, copie `.dw/templates/state-template.md` para `.dw/STATE.md`. Avise no chat: "STATE.md nao encontrado — inicializado a partir do template."
+- Se `.dw/templates/state-template.md` tambem nao existir (projeto muito antigo), crie um STATE.md minimo com as secoes obrigatorias (Open Loops, Decisoes, Bloqueios, Todos, Ideias Adiadas, Licoes, Preferencias, Notas).
+
+### 2. Mapear a sessao
+Leia o contexto da conversa e identifique, **sem inventar**:
+
+- **Pontas soltas (Open Loops)**: tarefas/trabalho iniciados mas nao finalizados (ex: "PRD `prd-foo` esta no estagio TechSpec, aguardando aprovacao"; "Task 3 do `prd-bar` falhando no lint")
+- **Decisoes tomadas**: escolhas acordadas entre usuario e agent durante a sessao que afetam trabalho futuro
+- **Bloqueios encontrados**: o que parou o avanco (esperando input, tooling quebrado, lacuna de conhecimento)
+- **Todos mencionados de passagem** que ainda nao tem PRD ou task
+- **Ideias exploradas e parqueadas** (com motivo do park)
+- **Licoes aprendidas** — pequenas licoes operacionais que valem registrar
+- **Preferencias expressas** — convencoes que o usuario quer aplicadas dali em diante
+
+### 3. Merge no STATE.md
+
+<critical>NUNCA sobrescreva STATE.md cegamente. Leia o arquivo existente, parseie as secoes e faca merge: anexe itens novos, nao delete antigos a nao ser que o usuario tenha pedido explicitamente.</critical>
+
+Regras:
+- Cada entrada nova ganha prefixo de data `YYYY-MM-DD` (data de hoje).
+- Use bullet lists. Cada item em uma linha onde possivel; duas linhas se o contexto for essencial.
+- Se uma secao acabar com placeholder `_nenhum_` e voce nao tiver nada a acrescentar, mantenha `_nenhum_`.
+- Atualize o campo `last_paused` no frontmatter para a data de hoje (YYYY-MM-DD).
+
+### 4. Passada de Compactacao (quando STATE.md cresceu)
+
+Se apos o merge o STATE.md ultrapassar **~6KB** ou qualquer secao tiver mais que **20 itens**, compacte:
+
+- **Pontas soltas resolvidas durante a sessao**: remova.
+- **Todos concluidos durante a sessao**: remova.
+- **Decisoes com mais de 30 dias que foram formalizadas em ADR ou na constitution**: remova (o ADR e o registro duravel).
+- **Licoes com mais de 60 dias**: mantenha apenas as ainda relevantes; descarte conselhos taticos datados.
+- **Ideias Adiadas com mais de 90 dias sem trigger de revisita**: pergunte ao usuario antes de descartar.
+
+Se a compactacao remover mais de 5 itens, liste no chat para o usuario poder vetar.
+
+### 5. Report
+
+Apresente um resumo curto ao usuario:
+
+```
+## Sessao Pausada
+
+Atualizado `.dw/STATE.md`:
+- Pontas soltas: +N (agora: X total)
+- Decisoes: +N
+- Bloqueios: +N (Y nao resolvidos)
+- Todos: +N (Z total)
+- Adiadas: +N
+
+[Se compactacao rodou: linhas removidas e motivo]
+
+Retome com `/dw-resume` na proxima sessao.
+```
+
+## Comportamento Obrigatorio
+
+<critical>NUNCA fabrique estado. Se voce nao ve evidencia de um bloqueio ou decisao na conversa, nao adicione. Secoes vazias estao ok.</critical>
+
+<critical>NUNCA toque em arquivos de memoria por-PRD (`.dw/spec/*/MEMORY.md`, `.dw/spec/*/tasks/*_memory.md`). Esses sao gerenciados pela skill `dw-memory` e sao locais ao PRD.</critical>
+
+<critical>NUNCA descarte conteudo do usuario em silencio. Se compactar, liste o que removeu.</critical>
+
+## Inspirado em
+
+Este comando adapta o pattern de session-handoff de [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) (CC-BY-4.0, Felipe Rodrigues). Adaptacoes: local `.dw/STATE.md` em vez de `.specs/project/STATE.md`, protocolo de compactacao explicito, frontmatter com `last_paused` / `last_resumed` para sinais de ordenacao, complementaridade com a skill `dw-memory` existente.
+
+</system_instructions>

package/scaffold/pt-br/commands/dw-qa.md

@@ -19,6 +19,8 @@ Você é o orquestrador de QA. Dois modos: rodar QA contra a implementação (UI
 | `/dw-qa --fix` | QA pass seguido de loop iterativo fix+retest. Cada bug detectado → root-cause → fix → retest com evidência → marcar resolvido. Continua até todos os bugs marcados Closed ou usuário aceitar lista deferida. |
 | `/dw-qa --api` | Força modo API-only (pula UI mesmo com frontend deps). Útil pra sub-features backend-only em repos fullstack. |
 | `/dw-qa --ai` | Adiciona avaliação de feature AI contra reference dataset em `.dw/eval/datasets/<feature>/`. Computa precision@k / faithfulness / outcome accuracy. Loga JSONL em `QA/logs/ai/`. |
+| `/dw-qa --uat` | **Walkthrough UAT interativo.** O agent conduz o usuário pela feature passo a passo, fazendo perguntas direcionadas ("isso bate com a expectativa?", "qual o comportamento esperado no caso X?"). Sem Playwright auto, sem AI eval. Output: `QA/uat-report.md`. Usar após `--fix` (ou no lugar de `/dw-qa` para features predominantemente baseadas em julgamento humano). |
+| `/dw-qa --bugfix <NNN-slug>` | Aponta para um bugfix em `.dw/bugfixes/NNN-slug/` em vez de um PRD. Roda o fluxo de QA padrão escopado aos arquivos tocados pelo fix; output em `.dw/bugfixes/NNN-slug/QA/`. Combina com `--fix`/`--api`/`--ai`/`--uat`. |
 
 ## Auto-detecção de modo
 
@@ -32,8 +34,17 @@ Default `/dw-qa` inspeciona projeto pra escolher UI vs API:
 
 | Variável | Descrição | Exemplo |
 |----------|-----------|---------|
-| `{{PRD_PATH}}` | Caminho do dir PRD com tasks (auto-detect da branch ativa se omitido) | `.dw/spec/prd-invoice-export` |
-| `{{MODE}}` | `--fix` / `--api` / `--ai` (opcional; default = auto-detect) | — |
+| `{{PRD_PATH}}` | Caminho do dir PRD com tasks (auto-detect da branch ativa se omitido; ignorado quando `--bugfix` é usado) | `.dw/spec/prd-invoice-export` |
+| `{{BUGFIX_SLUG}}` | Slug do bugfix quando a flag `--bugfix` é usada | `001-login-nao-funciona` |
+| `{{MODE}}` | `--fix` / `--api` / `--ai` / `--uat` / `--bugfix <slug>` (opcional; default = auto-detect, target = PRD) | — |
+
+## Resolução de Target
+
+Compute `<target>` UMA VEZ no início; substitua onde aparecer `<target>` abaixo.
+
+1. **Target PRD (padrão):** `<target>` = `{{PRD_PATH}}`. Artefatos lidos: `prd.md` (FRs), `techspec.md`, `tasks.md`, per-task files. Output em `<target>/QA/`.
+
+2. **Target Bugfix (`--bugfix <slug>`):** `<target>` = `.dw/bugfixes/<slug>/`. Artefatos lidos: `TASK.md` (tasks numeradas + arquivos tocados), `fix-report.md` (evidência verify + trace de reprodução), `SUMMARY.md`. QA escopado aos arquivos da tabela `Arquivos Tocados` e às superfícies adjacentes que esses arquivos expõem. Output em `<target>/QA/`. O `qa-report.md` é mais curto — há no máximo 5 tasks e uma única causa raiz a validar, não uma matriz de FR completa.
 
 ## Skills Complementares
 
@@ -50,19 +61,20 @@ Quando disponíveis em `./.agents/skills/`, invocadas operacionalmente:
 ## Estrutura de Output
 
 ```
-.dw/spec/<prd>/QA/
-├── qa-report.md                  # Test plan + execution summary
-├── bugs.md                       # Catálogo de bugs com status
+<target>/QA/                          # <target> = .dw/spec/<prd>/ OU .dw/bugfixes/<NNN-slug>/
+├── qa-report.md                      # Test plan + execution summary
+├── bugs.md                           # Catálogo de bugs com status
+├── uat-report.md                     # (apenas modo --uat) Log do walkthrough + observações do usuário
 ├── scripts/
-│   ├── ui/<RF>-<slug>.spec.ts    # Playwright scripts (modo UI)
-│   ├── api/<RF>-<slug>.http      # API test files
-│   └── ai/<feature>-eval.ts      # AI eval scripts (--ai)
+│   ├── ui/<RF>-<slug>.spec.ts        # Playwright scripts (modo UI)
+│   ├── api/<RF>-<slug>.http          # API test files
+│   └── ai/<feature>-eval.ts          # AI eval scripts (--ai)
 ├── evidence/
-│   ├── ui/                       # Screenshots per RF + retests
+│   ├── ui/                           # Screenshots per RF + retests
 │   └── ...
 └── logs/
-    ├── api/<RF>-<slug>.log       # JSONL request/response per call
-    └── ai/<feature>-<date>.jsonl # AI eval results
+    ├── api/<RF>-<slug>.log           # JSONL request/response per call
+    └── ai/<feature>-<date>.jsonl     # AI eval results
 ```
 
 ## Modo 1: Default (`/dw-qa`)
@@ -105,6 +117,70 @@ Quando disponíveis em `./.agents/skills/`, invocadas operacionalmente:
 4. Comparar com JSONL da run anterior — alertar em regressão >10% em qualquer métrica.
 5. Anexar seção modo-AI em `qa-report.md`.
 
+## Modo 1.5: UAT Interativo (`/dw-qa --uat`)
+
+O modo UAT é um **walkthrough humano-no-loop**. Não há Playwright auto, não há AI eval. O agent é o navegador; o usuário é o verificador. Use quando o comportamento é baseado em julgamento — um redesign, um fluxo de muito conteúdo, um fluxo novo cujos critérios de aceitação são parcialmente estéticos, ou um bugfix cuja manifestação user-facing precisa de olho humano para confirmar.
+
+### Pre-flight
+
+1. **Target Bugfix:** ler `<target>/SUMMARY.md` → Sintoma + Resolução. O walkthrough é o trace de reprodução do `fix-report.md` (antes → depois), agora confirmado ao vivo.
+2. **Target PRD:** ler `<target>/prd.md` → para cada FR, esboçar uma pergunta de uma linha "o que você deveria ver quando X acontece?".
+3. Suba o dev server do projeto (ou instrua o usuário a subir se precisar credenciais interativas).
+
+### Loop do walkthrough
+
+Para cada FR (target PRD) ou cada task numerada em `TASK.md` (target Bugfix):
+
+1. **Agent descreve o próximo passo em palavras claras.** Exemplo: "Abra `/invoices/export` logado como viewer. O botão de export deve estar desabilitado e um tooltip explicar por quê."
+2. **Usuário executa o passo no browser/app** e reporta o que observou.
+3. **Agent faz uma pergunta de follow-up direcionada** casada com a FR/task — nunca mais que uma pergunta aberta por turno:
+   - "O estado disabled comunica visualmente o porquê? (texto, ícone, contraste — você decide)"
+   - "Se você tabula até o botão, o tooltip fica acessível por teclado?"
+   - "O que apareceu no network panel?" (só se comportamento de backend for relevante)
+4. **Agent registra a resposta verbatim** em `uat-report.md` sob a seção dessa FR/task. Sem interpretação, sem paráfrase.
+5. **Agent sinaliza um finding** quando o usuário reportar comportamento inesperado. O finding vai para `bugs.md` com `source: uat` e `severity: <escolha do usuário>`.
+6. **Repita até todas as FRs / tasks numeradas terem sido percorridas.**
+
+### Output
+
+Salvar em `<target>/QA/uat-report.md`:
+
+```markdown
+# Walkthrough UAT — <target>
+
+Data: YYYY-MM-DD
+Conduzido por: <identificador do usuário ou "usuário">
+Browser/env: <conforme reportado>
+
+## FR-1.1 (ou Task 1) — <escopo em uma linha>
+
+- Passo: <o que o agent pediu>
+- Observação do usuário: <verbatim>
+- Veredicto: PASS / FAIL / NEEDS-DESIGN-INPUT
+- Notas: <follow-up>
+
+## FR-1.2 (ou Task 2) — ...
+...
+
+## Sumário
+
+- Percorridas: N FRs / tasks
+- PASS: N
+- FAIL: N (cross-ref entradas no bugs.md com source:uat)
+- NEEDS-DESIGN-INPUT: N (não é bug; spec estava sub-definida ali)
+```
+
+### Comportamento obrigatório
+
+<critical>
+- NUNCA dirija o browser automaticamente em modo `--uat`. O usuário navega; você observa.
+- NUNCA parafraseie a observação do usuário. Cite verbatim sob cada FR/task.
+- NUNCA marque um finding como bug sem o usuário dizer explicitamente "sim, é bug" — findings de UAT também podem indicar specs ambíguas (NEEDS-DESIGN-INPUT), que não são bugs.
+- Limite cada FR a uma pergunta aberta por turno. UAT é interativo, não interrogatório.
+</critical>
+
+UAT compõe com `--bugfix <slug>` (percorre o caminho do teste de regressão com o usuário em vez de FRs) e com `--fix` (após um fix aterrissar, UAT é o green-light humano antes do commit).
+
 ## Modo 2: Fix loop (`/dw-qa --fix`)
 
 ### Comportamento

package/scaffold/pt-br/commands/dw-resume.md

@@ -0,0 +1,90 @@
+<system_instructions>
+Voce e um agent de retomada de sessao. Seu trabalho e ler `.dw/STATE.md`, se orientar e orientar o usuario, e rotear para o proximo passo mais util. Este comando e o inverso do `/dw-pause`.
+
+## Quando Usar
+- Use quando o usuario disser "retomar trabalho", "continuar", "onde paramos?", "voltar de onde parei", ou comecar uma sessao nova em um projeto existente
+- Use proativamente no inicio de qualquer sessao que abrir um projeto com `.dw/STATE.md` nao-vazio e o usuario ainda nao tiver expressado uma intencao
+
+## Posicao na Pipeline
+**Predecessor:** `/dw-pause` (sessao anterior) | **Sucessor:** depende do que esta aberto (tipicamente `/dw-run --resume`, `/dw-bugfix`, `/dw-plan`, `/dw-qa` ou `/dw-review`)
+
+## Local do Arquivo
+- Alvo read-only: `.dw/STATE.md`
+- Cross-reference: `.dw/spec/` (listar PRDs ativos), `.dw/bugfixes/` (listar bugfixes abertos), `.dw/incidents/` (se houver)
+
+## Workflow
+
+### 1. Ler STATE.md
+- Se `.dw/STATE.md` nao existir, reporte: "Nenhum estado pausado encontrado — parece sessao nova. Rode `/dw-help` para proximos passos." Pare aqui.
+- Se `STATE.md` existir mas toda secao for `_nenhum_`, reporte: "STATE.md vazio — nada a retomar. Me diga o que voce quer fazer."
+
+### 2. Cross-reference com disco
+Verifique que o estado ainda bate com o filesystem:
+
+- Para cada Open Loop referenciando path de PRD, rode `ls` em `.dw/spec/<slug>/`. Se faltar, sinalize `[stale: PRD nao encontrado]` e pergunte se quer remover.
+- Para cada Open Loop referenciando slug de bugfix, cheque `.dw/bugfixes/<NNN-slug>/`.
+- Para cada Bloqueio referenciando sistema externo, nao verifique — apenas mostre.
+- Se `last_paused` no frontmatter tem mais de 14 dias, sinalize com destaque (estado pode estar stale).
+
+### 3. Produzir TLDR
+
+Apresente um resumo conciso, **nao o STATE.md cru**:
+
+```
+## Onde voce parou
+
+Ultima pausa: YYYY-MM-DD (Nd atras)
+
+### Pontas Soltas (N)
+- [path ou label] — proximo: <proxima acao em uma linha> [<flag se stale>]
+- ...
+
+### Bloqueios (N nao resolvidos)
+- [label] — esperando <X>
+
+### Top Todos (ate 5)
+- ...
+
+[Decisoes, Licoes, Preferencias — so mencione se relevantes para loops ativos]
+```
+
+Mantenha o TLDR em menos de 30 linhas. Se STATE.md tiver mais, resuma e ofereca `cat .dw/STATE.md` como follow-up.
+
+### 4. Sugerir proximo passo
+
+Baseado no TLDR, roteie para um comando concreto. Use estas heuristicas:
+
+| Sinal mais forte no STATE.md | Comando sugerido |
+|------------------------------|------------------|
+| Open Loop num PRD em estagio `tasks/` | `/dw-run --resume` |
+| Open Loop num PRD em estagio `techspec` | `/dw-plan techspec` |
+| Open Loop num PRD em estagio `prd` | `/dw-plan tasks` (se PRD aprovado) ou continuar PRD |
+| Open Loop num slug de bugfix | `/dw-bugfix --resume <slug>` ou `/dw-qa --bugfix <slug>` |
+| Bloqueio esperando input externo | Sugerir que o usuario resolva o bloqueio primeiro |
+| So Todos e Decisoes, sem trabalho ativo | Perguntar o que comecar |
+
+Formule a sugestao como pergunta, nao como ordem:
+
+```
+Quer que eu rode <comando sugerido>?
+- sim → rodo
+- nao, <outra intencao> → me diga o que prefere
+```
+
+### 5. Atualizar frontmatter do STATE.md
+
+Setar `last_resumed` para a data de hoje (YYYY-MM-DD). Nao modificar conteudo das secoes — agora a sessao esta de volta e isso e do usuario.
+
+## Comportamento Obrigatorio
+
+<critical>NUNCA auto-execute o comando sugerido. `/dw-resume` so propoe; o usuario confirma antes de qualquer `/dw-run`, `/dw-plan` ou `/dw-bugfix`.</critical>
+
+<critical>NUNCA fabrique resultados de stale-detection. Se voce nao rodou `ls`, nao reporte que o arquivo existe ou nao.</critical>
+
+<critical>NUNCA jogue o STATE.md inteiro no chat. Resuma. Arquivos de estado longos sinalizam que compactacao e necessaria — sugira `/dw-pause` para compactar da proxima vez.</critical>
+
+## Inspirado em
+
+Este comando adapta o pattern de session-handoff de [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) (CC-BY-4.0, Felipe Rodrigues). Adaptacoes: heuristicas de routing mapeiam conteudo do STATE.md para comandos `dw-*` especificos; cross-reference com `.dw/spec/` e `.dw/bugfixes/` para detectar staleness; nunca auto-executa.
+
+</system_instructions>