@brunosps00/dev-workflow 1.0.1 → 1.0.4

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>

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

@@ -15,16 +15,28 @@ Você é o orquestrador de review. Roda Level 2 (PRD compliance / cobertura) e L
 
 | Invocação | O que roda |
 |-----------|------------|
-| `/dw-review` | **Padrão.** Level 2 (cobertura PRD) + Level 3 (qualidade de código) em sequência. Relatório consolidado em `.dw/spec/<prd>/QA/review-consolidated.md`. |
-| `/dw-review --coverage-only` | Apenas Level 2 — mapeia cada requisito do PRD para o código que entrega. Pula qualidade. |
-| `/dw-review --code-only` | Apenas Level 3 — qualidade / convenção / security checks. Pula mapeamento PRD. |
+| `/dw-review` | **Padrão.** Level 2 (cobertura PRD) + Level 3 (qualidade de código) em sequência. Relatório consolidado em `<target>/QA/review-consolidated.md` (target resolve pra dir do PRD ou do bugfix; ver Resolução de Target). |
+| `/dw-review --coverage-only` | Apenas Level 2 — mapeia cada requisito do PRD (ou escopo do bugfix) para o código que entrega. Pula qualidade. |
+| `/dw-review --code-only` | Apenas Level 3 — qualidade / convenção / security checks. Pula mapeamento de PRD/escopo. |
+| `/dw-review --bugfix <NNN-slug>` | Aponta para um bugfix em `.dw/bugfixes/NNN-slug/` em vez de um PRD. Level 2 mapeia o escopo do bugfix (TASK.md + fix-report.md + SUMMARY.md) para o código que entrega o fix; Level 3 checa o diff. Output: `.dw/bugfixes/NNN-slug/review/`. |
 
 ## Entradas
 
 | Variável | Descrição | Exemplo |
 |----------|-----------|---------|
-| `{{PRD_PATH}}` | Caminho do dir PRD (auto-detect da branch ativa se omitido) | `.dw/spec/prd-invoice-export` |
-| `{{MODE}}` | `--coverage-only` / `--code-only` (opcional; default = ambos) | — |
+| `{{PRD_PATH}}` | Caminho do dir PRD (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}}` | `--coverage-only` / `--code-only` / `--bugfix <slug>` (opcional; default = ambos, target = PRD) | — |
+
+## Resolução de Target
+
+O review roda contra um de dois tipos de target. Compute `<target>` UMA VEZ no início; substitua onde aparecer `<target>` abaixo.
+
+1. **Target PRD (padrão):** `<target>` = `{{PRD_PATH}}` (auto-detectado da branch ativa quando omitido). Artefatos lidos: `prd.md`, `techspec.md`, `tasks.md`, `tasks/<N>_task.md`, `tasks-validation.md`. Output em `<target>/QA/`. Nomes de arquivo: `review-coverage.md`, `dw-code-review.md`, `review-consolidated.md`.
+
+2. **Target Bugfix (`--bugfix <slug>`):** `<target>` = `.dw/bugfixes/<slug>/`. Artefatos lidos: `TASK.md` (o plano de fix com tasks numeradas 1..≤5), `fix-report.md` (evidência de verify), `SUMMARY.md` (registro de uma página). Não há FRs no sentido de PRD — em vez disso, cada task numerada em `TASK.md` é a unidade de cobertura. Output em `<target>/review/`. Nomes: `review-coverage.md`, `dw-code-review.md`, `review-consolidated.md`.
+
+Quando o target Bugfix é usado, o mapeamento de cobertura (Level 2) opera sobre as tasks numeradas do `TASK.md` (não FR-N.M); uma task é ENTREGUE quando (a) os arquivos que ela alegou tocar estão no diff e (b) o teste de regressão referenciado em `fix-report.md` existe e roda. Código órfão em modo bugfix é qualquer coisa no diff que não corresponde a uma task numerada — sinal forte de que o safety valve deveria ter escalado para `/dw-plan`.
 
 ## Skills Complementares
 
@@ -59,10 +71,8 @@ Quando disponíveis em `./.agents/skills/`, são invocadas como apoio analítico
 ### Comportamento
 
 1. **Carregar artefatos:**
-   - `.dw/spec/<prd>/prd.md` → extrair requisitos funcionais.
-   - `.dw/spec/<prd>/techspec.md` → extrair decisões arquiteturais.
-   - `.dw/spec/<prd>/tasks.md` + per-task files → extrair trabalho commitado.
-   - `tasks-validation.md` → trazer status das dimensões.
+   - **Target PRD:** `<target>/prd.md` → extrair requisitos funcionais. `<target>/techspec.md` → extrair decisões arquiteturais. `<target>/tasks.md` + per-task files → extrair trabalho commitado. `<target>/tasks-validation.md` → trazer status das dimensões.
+   - **Target Bugfix:** `<target>/TASK.md` → extrair as tasks numeradas (1..≤5) e seus arquivos-alvo. `<target>/fix-report.md` → extrair evidência de verify e referência do teste de regressão. `<target>/SUMMARY.md` → extrair Sintoma, Causa Raiz, Arquivos Tocados, Verificação.
 
 2. **Mapear cada FR para código:**
    - Para cada `FR-N.M`, encontrar código que entrega (file path + line range + commit SHA).
@@ -78,7 +88,7 @@ Quando disponíveis em `./.agents/skills/`, são invocadas como apoio analítico
 
 ### Output
 
-Salvo em `.dw/spec/<prd>/QA/review-coverage.md`:
+Salvo em `<target>/QA/review-coverage.md` (target PRD) ou `<target>/review/review-coverage.md` (target Bugfix):
 
 ```markdown
 # Coverage Review
@@ -145,14 +155,14 @@ Se FALTANDO > 0, o veredicto sugere revisitar `/dw-plan tasks` pra escopar ou `/
 
 ### Output
 
-Salvo em `.dw/spec/<prd>/QA/dw-review --code-only.md`. Linha de verdict é uma de:
+Salvo em `<target>/QA/dw-code-review.md` (target PRD) ou `<target>/review/dw-code-review.md` (target Bugfix). Linha de verdict é uma de:
 - **APROVADO** — todos os gates verdes; pronto pra commit + PR.
 - **APROVADO COM RESSALVAS** — verde mas findings valem corrigir em follow-up (filed com severities).
 - **REPROVADO** — ao menos um hard gate falhou. Especifique qual.
 
 ## Output consolidado (modo padrão)
 
-Quando ambos níveis rodam, relatório consolidado em `.dw/spec/<prd>/QA/review-consolidated.md`:
+Quando ambos níveis rodam, relatório consolidado em `<target>/QA/review-consolidated.md` (target PRD) ou `<target>/review/review-consolidated.md` (target Bugfix):
 
 ```markdown
 # Review Consolidado

package/scaffold/pt-br/templates/bugfix-summary-template.md

@@ -0,0 +1,66 @@
+---
+schema_version: "1.0"
+slug: ""
+created: ""
+status: "Fixed | In Review | QA Pending | Reverted"
+severity: "Low | Medium | High"
+related_concerns: []
+---
+
+# Bugfix Summary — {{NNN}}-{{slug}}
+
+Registro de uma pagina de um bugfix. Arquivos irmaos neste diretorio:
+
+- `TASK.md` — a triagem original, respostas das perguntas de clarificacao e o plano de fix que rodou
+- `fix-report.md` — evidencia de verificacao (saida do `dw-verify` PASS, prova de reproducao, execucao do teste de regressao)
+- `review/` — populado por `/dw-review --bugfix {{NNN}}-{{slug}}`
+- `QA/` — populado por `/dw-qa --bugfix {{NNN}}-{{slug}}` (quando aplicavel)
+
+## Sintoma
+
+O que o usuario observou. Cite a descricao original do bug verbatim; nao parafraseie.
+
+> _"…"_
+
+## Causa Raiz
+
+O que estava de fato quebrado, em uma frase. Nao o sintoma — a causa.
+
+_…_
+
+## Resolucao
+
+O que mudou, em 2-4 bullets. Paths de arquivos, nao snippets.
+
+- _mudanca 1_
+- _mudanca 2_
+
+## Arquivos Tocados
+
+Lista completa, incluindo testes. <=5 — se mais, o safety valve deveria ter escalado para `/dw-plan`.
+
+| Path | Mudanca |
+|------|---------|
+| `src/foo/bar.ts` | _fix cirurgico em X_ |
+| `src/foo/bar.test.ts` | _teste de regressao adicionado_ |
+
+## Verificacao
+
+Como o fix foi provado, alem de "os testes passam".
+
+- **Reproducao antes do fix:** _passo que disparava o bug, capturado_
+- **Reproducao depois do fix:** _mesmo passo, agora passa_
+- **Teste de regressao:** _nome + path_
+- **Relatorio de verify:** `fix-report.md`
+
+## Relacionado
+
+- **Concerns tocados:** _refs de `.dw/rules/concerns.md` se o fix caiu em area flagada_
+- **Bugfixes adjacentes:** _slugs de fixes anteriores no mesmo modulo, se houver_
+- **Contexto de PRD:** _se o bug apareceu dentro de uma feature em andamento, link para o path do PRD_
+
+## Followups
+
+Pontas soltas que este fix descobriu mas nao resolveu. Adicione ao `.dw/STATE.md` Open-Loops ao fechar.
+
+- _nenhum_

package/scaffold/pt-br/templates/concerns-template.md

@@ -0,0 +1,59 @@
+---
+schema_version: "1.0"
+generated_by: dw-analyze-project (Step 9)
+last_refreshed: ""
+---
+
+# Concerns — Mapa de Riscos
+
+Mapa de riscos deste codebase. Nao sao convencoes ("como fazemos as coisas" — isso e `.dw/rules/`), nao e arquitetura ("como esta construido" — isso e `.dw/intel/arch.md`). Este arquivo responde uma unica pergunta: **onde e perigoso mexer?**
+
+Carregado on-demand por `/dw-plan`, `/dw-run` e `/dw-bugfix` quando o alvo deles toca uma entrada abaixo. Auto-instalado pelo `/dw-analyze-project` Step 9; nunca bloqueia (ausencia = nenhuma area flagada ainda).
+
+## Hot Spots
+
+Arquivos ou modulos com churn alto, reports frequentes de bug ou historico repetido de "mexi aqui e quebrou algo". Mencione em PRDs que toquem a mesma area; adicione revisor extra ou passada extra de teste.
+
+| Path | Por que e quente | Primeiro flag | Ultimo incidente |
+|------|------------------|---------------|------------------|
+| _ex. `src/auth/session.ts`_ | _3 fixes de token em 60d_ | _YYYY-MM-DD_ | _YYYY-MM-DD_ |
+
+## Integracoes Fragis
+
+Sistemas externos (APIs, filas, vendors, bancos legados) com historico de falhas silenciosas, drift de schema, surpresas de rate-limit ou comportamento nao-documentado. Codigo novo que toque eles precisa de tratamento explicito de retry/timeout/idempotencia.
+
+| Integracao | Modo de falha | Mitigacao esperada |
+|------------|---------------|--------------------|
+| _ex. export SAP legado_ | _200 OK silencioso com body vazio quando source esta lockado_ | _checar tamanho do body; logar e alertar_ |
+
+## Codigo Hostil
+
+Funcoes especificas, regexes, parsers ou algoritmos dificeis de raciocinar — quem toca precisa entender 100% primeiro (ou reescrever, nao remendar). Suspeitos comuns: regex artesanal, parsers de string ad-hoc, serializadores custom, async com race condition, codigo de transacao manual.
+
+| Path / funcao | Por que e hostil | Owner / contexto |
+|---------------|------------------|------------------|
+| _ex. `src/billing/parseInvoice.ts:parseLine`_ | _regex de 900 chars com 12 alternativas, sem comentarios_ | _Bruno escreveu em 2024; reescrever se quebrar_ |
+
+## Historico de Bugs Conhecidos
+
+Agregado de `.dw/bugfixes/*/SUMMARY.md` pelo `/dw-intel --build`. Lista modulos com >=2 fixes historicos. Leia junto com Hot Spots ao planejar trabalho relacionado.
+
+| Modulo | Contagem de bugs | Slugs recentes |
+|--------|------------------|----------------|
+| _ex. `src/payments/`_ | _4_ | _002-stripe-webhook-retry, 007-refund-rounding_ |
+
+## Tech Debt — Reconhecida
+
+Pedacos de debt que o time concorda que existem. Nao sao para limpar oportunisticamente sem coordenacao — podem ser load-bearing de formas nao obvias.
+
+| Area | Descricao do debt | Por que fica | Trigger de cleanup |
+|------|-------------------|--------------|--------------------|
+| _ex. `src/legacy/userMapper.ts`_ | _Dois codepaths paralelos de field-mapping_ | _Esperando migracao v3 da API_ | _Q3 2026 apos cutover do vendor_ |
+
+---
+
+**Como manter este arquivo:**
+
+- `/dw-analyze-project` reescreve a cada execucao. Entradas escritas a mao entre `<!-- preserved:start -->` e `<!-- preserved:end -->` sao mantidas.
+- Quando um bugfix descobrir uma nova area perigosa, adicione manualmente em Hot Spots e deixe a proxima analise confirmar.
+- Promova entradas para `.dw/constitution.md` quando virarem regras nao-negociaveis ("nunca toque X sem ADR").

package/scaffold/pt-br/templates/state-template.md

@@ -0,0 +1,59 @@
+---
+schema_version: "1.0"
+last_paused: ""
+last_resumed: ""
+---
+
+# Estado da Sessao
+
+Memoria de trabalho entre sessoes. Indice leve do que esta em andamento, do que foi decidido, do que ficou parado. Atualizado por `/dw-pause` (consolida) e lido por `/dw-resume` (orienta).
+
+Diferente do `MEMORY.md` por-PRD (memoria de workflow para uma feature) ou dos ADRs (decisoes arquiteturais duraveis), este arquivo vive no nivel do projeto e sobrevive entre PRDs, branches e sessoes. Edite livremente entre pausas.
+
+## Open Loops (Pontas Soltas)
+
+O que esta em andamento — trabalho comecado mas nao terminado. Cada entrada: label curto + path/alvo + proxima acao concreta.
+
+- _nenhum_
+
+## Decisoes
+
+Decisoes transversais que ainda nao viraram ADR (porque nao justificam um, ou porque a formalizacao foi adiada). Formato: `YYYY-MM-DD — decisao — contexto (1 linha)`.
+
+- _nenhuma_
+
+## Bloqueios
+
+O que esta impedindo o avanco. Externo (esperando alguem), interno (lacuna de conhecimento) ou tecnico (tooling quebrado). Cada entrada: label curto + o que esta bloqueado + dono / condicao de desbloqueio.
+
+- _nenhum_
+
+## Todos
+
+Pequenos follow-ups que nao justificam um PRD ou task. Uma linha cada. Limpe conforme forem feitos ou migrados para um PRD.
+
+- _nenhum_
+
+## Ideias Adiadas
+
+Ideias consideradas mas parqueadas. Capture para nao perder; revisite quando o escopo mudar. Cada entrada: ideia + motivo do park + trigger de revisita (se conhecido).
+
+- _nenhuma_
+
+## Licoes
+
+Pequenas licoes aprendidas no trabalho recente — padroes que funcionaram, pegadinhas, "da proxima vez eu...". Nao sao arquiteturais (essas vao para ADRs); sao operacionais.
+
+- _nenhuma_
+
+## Preferencias
+
+Convencoes acordadas durante o trabalho que afetam como o agent deve se comportar dali em diante. Exemplos: "sempre rodar `pnpm typecheck` antes do commit", "preferir named exports a default exports em utils".
+
+- _nenhuma_
+
+## Notas
+
+Bloco livre. Opcional.
+
+- _nenhuma_

package/scaffold/skills/dw-codebase-intel/SKILL.md

@@ -44,8 +44,9 @@ The intel directory is the contract. Every file is machine-parseable and referen
 | `files.json` | File graph: per-file imports/exports/type | JSON |
 | `apis.json` | API surface: routes, methods, params, source file | JSON |
 | `deps.json` | Dependencies: version, type, used_by, invocation | JSON |
+| `bugfixes.json` | Historical bugfix index aggregated from `.dw/bugfixes/*/SUMMARY.md` (slug, date, modules touched, related concerns, by_module map). Optional — present only if `.dw/bugfixes/` is non-empty. | JSON |
 | `arch.md` | Human-readable architecture overview + key components + data flow | Markdown |
-| `.last-refresh.json` | Timestamps + content hashes for incremental detection | JSON |
+| `.last-refresh.json` | Timestamps + content hashes for incremental detection (now includes `bugfixes_indexed` count) | JSON |
 
 Schemas are documented in `references/intel-format.md`.
 
@@ -61,9 +62,10 @@ This skill ships ONE agent — `intel-updater` — which produces machine-readab
 
 1. **`/dw-intel --build`** is invoked.
 2. The command spawns `intel-updater` with `focus: full` (first run) or `focus: partial --files <paths>` (incremental).
-3. The agent reads source files (using Glob/Read/Grep; no Bash file listing for cross-platform safety) and writes the 5 intel files.
-4. The agent writes `.last-refresh.json` with timestamps + hashes for incremental change detection on the next run.
-5. `/dw-intel --build` reports completion and invites the user to query via `/dw-intel "<question>"`.
+3. The agent reads source files (using Glob/Read/Grep; no Bash file listing for cross-platform safety) and writes the intel files (`stack.json`, `files.json`, `apis.json`, `deps.json`, `arch.md`).
+4. If `.dw/bugfixes/` exists and contains at least one `SUMMARY.md`, the agent additionally scans every SUMMARY frontmatter + Files Touched section and writes `bugfixes.json`. SUMMARY files with invalid frontmatter are logged and skipped.
+5. The agent writes `.last-refresh.json` with timestamps + hashes for incremental change detection on the next run, including a `bugfixes_indexed` count.
+6. `/dw-intel --build` reports completion and invites the user to query via `/dw-intel "<question>"`.
 
 For human-readable analysis (architecture overview, module conventions, anti-patterns), run `/dw-analyze-project` after `/dw-intel --build` — it reads `.dw/intel/` as input and produces `.dw/rules/`.
 
@@ -88,7 +90,7 @@ If no `.dw/intel/` exists at all, `/dw-intel` falls back to `.dw/rules/` (seeded
 - **Cross-platform**: use Glob/Read/Grep; never Bash `ls`/`find`/`cat` (those break on Windows).
 - **Forbidden files**: never read `.env*` (except `.env.example`/`.env.template`), `*.key`, `*.pem`, `*.pfx`, `*.p12`, `*.keystore`, `*.jks`, `id_rsa`, `id_ed25519`, or files matching `*credential*`/`*secret*` in name. Skip silently if encountered.
 - **Excluded directories**: `node_modules/`, `.git/`, `dist/`, `build/`, `.dw/` (planning docs, not project code).
-- **Output budget**: `files.json` ≤2K tokens, `apis.json` ≤1.5K, `deps.json` ≤1K, `stack.json` ≤500, `arch.md` ≤1.5K. For large repos, prioritize coverage of key files over exhaustive listing.
+- **Output budget**: `files.json` ≤2K tokens, `apis.json` ≤1.5K, `deps.json` ≤1K, `stack.json` ≤500, `arch.md` ≤1.5K, `bugfixes.json` ≤1K. For large repos, prioritize coverage of key files over exhaustive listing. For `bugfixes.json`, keep one-line symptom/root-cause summaries; do not embed full SUMMARY.md content.
 
 ## References
 
@@ -100,3 +102,5 @@ If no `.dw/intel/` exists at all, `/dw-intel` falls back to `.dw/rules/` (seeded
 ## Inspired by
 
 Adapted from [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) (`gsd-intel-updater`) by gsd-build (MIT license). Core schemas (`files.json`, `apis.json`, `deps.json`, `stack.json`, `arch.md`) and incremental update protocol preserved. Path conventions changed from `.planning/intel/` to `.dw/intel/`. CLI tooling (`gsd-sdk query intel.*`) replaced by agent-driven inline operations (no separate runtime). The companion `gsd-codebase-mapper` agent (human-readable analysis docs) was NOT ported — its scope overlaps with the existing `/dw-analyze-project` command which writes to `.dw/rules/`.
+
+The `bugfixes.json` index and the `bugfix-history` / `risk-area` query shapes (see `references/query-patterns.md`) were added in v1.0.2 to enable cross-skill awareness of `.dw/bugfixes/` — adapted from the operational-memory pattern in [`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). The original skill maintains a single `STATE.md`; dev-workflow splits this into project-level `.dw/STATE.md` (session continuity) and a queryable `bugfixes.json` (historical fixes), which compose with the existing per-PRD `MEMORY.md`.