jarvis-ai-framework 5.0.0 → 5.2.0

package/workflows/engineering/eng.pr.md

@@ -44,7 +44,7 @@ Este comando cria a **branch, commita as alterações e abre um Merge Request**.
 | Skills recomendados | `/eng-global-docs-write` | Se houver necessidade de atualizar documentação junto do PR |
 | Agentes recomendados (opcional) | `eng.qa.test-planner` (agente) | Se houver dúvidas sobre cobertura de testes ou mudanças significativas |
 | Fase 4 › 4.4 Criar MR/PR via adapter | `jarvis vcs create-merge` (CLI do Jarvis) | Só se o usuário responder **Sim** na Fase 4.3: abre o MR/PR conforme `VERSION_CONTROL` ou o host do `origin` |
-| Fase 6 › 6.2 Link do MR | `/eng-global-task-comment` | Depois de o MR ser criado (só com o Sim da 4.3): um único comentário no card com o link do MR, seguindo o Passo 6 do skill `eng-global-pr` (freelance pula) |
+| Fase 5 › 5.2 Link do MR | `/eng-global-task-comment` | Depois de o MR ser criado (só com o Sim da 4.3): um único comentário no card com o link do MR, seguindo o Passo 6 do skill `eng-global-pr` (freelance pula) |
 
 ---
 
@@ -134,7 +134,7 @@ Branch de destino: a **`Branch base:`** do `architecture.md` (`{BRANCH_BASE}`).
 git checkout {TASK_MANAGER_KEY}-{titulo-em-kebab-case}
 ```
 
-### 2.2 Verificar Commits da Branch
+### 2.3 Verificar Commits da Branch
 
 ```bash
 git log {BRANCH_BASE}..HEAD --oneline
@@ -211,7 +211,7 @@ Mostre o `pull-request.md` (título e resumo das seções) e pergunte com `AskUs
 
 Pergunte com `AskUserQuestion` (**Sim / Não**): **"Publicar o PR agora?"**
 
-- **Não:** nada é enviado. O `pull-request.md` fica na sessão para você publicar quando quiser (à mão ou rodando o `/eng.pr` de novo). Pule para a Fase 7, com a mensagem "PR não publicado".
+- **Não:** nada é enviado. O `pull-request.md` fica na sessão para você publicar quando quiser (à mão ou rodando o `/eng.pr` de novo). Pule para a Fase 7 (sem `daily.md`, que só existe com PR aberto), com a mensagem "PR não publicado".
 - **Sim:** faça o push (Fase 3) e crie o MR/PR (4.4).
 
 ### 4.4 Criar MR/PR via adapter
@@ -248,15 +248,15 @@ Se o CLI `jarvis` não estiver instalado no repo alvo, usar `node {caminho-do-cl
 
 ---
 
-## Fase 6: Atualizar Board
+## Fase 5: Atualizar Board
 
 Pular se `TASK_MANAGER` estiver vazio (freelance).
 
-### 6.1 Mover Card
+### 5.1 Mover Card
 
 Mova o card para a etapa equivalente a "em revisão" no seu board. Quem assumiu o card o move; não é preciso esperar o TECH LEAD ou o PM.
 
-### 6.2 Link do MR no card
+### 5.2 Link do MR no card
 
 Siga o Passo 6 do skill `eng-global-pr`: um único comentário no card, com o link e a branch. É o único comentário do `eng.pr` no card.
 
@@ -264,11 +264,11 @@ Siga o Passo 6 do skill `eng-global-pr`: um único comentário no card, com o li
 
 ## Fase 6: Processar Code Review
 
-### 7.1 Aguardar Comentários
+### 6.1 Aguardar Comentários
 
 Aguarde 3-5 minutos para a ferramenta de code review processar.
 
-### 7.2 Analisar Comentários
+### 6.2 Analisar Comentários
 
 Para cada comentário:
 
@@ -276,7 +276,7 @@ Para cada comentário:
 2. Avaliar se pode ser explicado/ignorado
 3. Apresentar ao usuário
 
-### 7.3 Aplicar Correções
+### 6.3 Aplicar Correções
 
 Se necessário:
 
@@ -291,7 +291,7 @@ git push
 
 ## Fase 7: Conclusão
 
-### 8.1 Registrar Métricas de Lead Time
+### 7.1 Registrar Métricas de Lead Time
 
 Calcule e registre o lead time (tempo desde eng.start até PR criado):
 
@@ -323,7 +323,34 @@ else
 fi
 ```
 
-### 8.2 Mensagem Final
+### 7.2 Registrar o esforço em `daily.md`
+
+Regras em `$IDE/rules-on-demand/engineering/eng.pr-rules.md` (seção "daily.md"); template em `$IDE/templates/engineering/daily-template.md`. Arquivo: `$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/daily.md`, **só na sessão, nunca publicado**.
+
+1. **Há PR aberto?** Vale o criado na 4.4 ou o PR da branch que já existe e está aberto (CLI/adapter do vendor, ex.: `gh pr view --json state,number,url`). Sem PR aberto (Não na 4.3 e nenhum PR existente), **não gere** o `daily.md` e siga para a 7.3. Se não for possível confirmar, pergunte.
+2. **Data:** pergunte com `AskUserQuestion`: **"Registrar o esforço com qual data?"** → `Hoje ({AAAA-MM-DD})` | `Outra data` (o usuário digita `AAAA-MM-DD`).
+3. **Dias trabalhados** (só se o período entre a data do `.timestamp_start` e a data do registro tiver mais de um dia), uma pergunta por vez:
+   - se o período tiver sábado ou domingo: **"Você trabalhou em {datas de sábado/domingo}?"** (Sim / Não; com várias datas, pode responder por data);
+   - **"Houve feriado no período?"** → Não | Sim (o usuário informa as datas);
+   - **"Teve algum dia em que você não trabalhou no período?"** → Não | Sim (o usuário informa as datas).
+
+   Dias trabalhados = datas do período − fim de semana não trabalhado − feriados − dias não trabalhados. Registre no `worked_days` do frontmatter.
+4. ***Post mortem*:**
+   - **automático** se o `context.md` tiver `tipo: bugfix` ou `hotfix`, ou se houver **mais de 1 dia trabalhado**;
+   - nos outros casos, pergunte (**Sim / Não**): **"A tarefa exigiu investigação ou análise longa?"**
+5. **Nova execução** (o `daily.md` já existe): entenda o contexto e pergunte com `AskUserQuestion`: **"De onde veio a mudança desde o último registro?"**
+   - **Ajuste meu:** reescreva o registro **focando no que foi entregue**, sem mencionar troca de escopo nem retrabalho.
+   - **Pedido da liderança** (gerente, PM, tech lead): documente na seção "Mudança de escopo" o que mudou, quem pediu (como o usuário informar) e o impacto.
+
+   Atualize a seção da data escolhida. Se a data for nova, acrescente uma seção `## AAAA-MM-DD`.
+6. **Gerar** a descrição detalhada **e** a linha de timesheet, juntas.
+   - **Fontes:** `architecture.md`, `plan.md`, `gate-checklist.md`, `pull-request.md`, `git log {BRANCH_BASE}..HEAD`, o PR/MR e o card.
+   - **Descrição:** um parágrafo narrativo (contexto técnico, trabalho realizado, decisões), mais o *post mortem* quando couber (problema e causa raiz, investigação, solução/direcionamento), com detalhe suficiente para embasar questionamentos futuros.
+   - **Timesheet:** **uma única linha** (`{TASK_KEY} — {resumo}`).
+   - Sem e-mails, tokens nem valores de variáveis.
+7. **Revisão conjunta:** mostre a descrição e a linha de timesheet **juntas** e pergunte com `AskUserQuestion`: `[Aprovar]` / `[Ajustar]`. Com Ajustar, aplique os ajustes pontuais **nas duas** e mostre de novo, até aprovar.
+
+### 7.3 Mensagem Final
 
 ```
 ✅ MERGE REQUEST CRIADO COM SUCESSO!
@@ -340,6 +367,9 @@ fi
 
 {LEAD_TIME_MSG}
 
+📝 Daily: $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/daily.md
+🕒 Timesheet: {LINHA_DE_TIMESHEET_APROVADA}
+
 📌 Próximos passos:
 1. /eng.spec-consolidate {TASK_MANAGER_KEY} → registrar no Central docs o que esta entrega implementou
 2. Aguardar revisão do time e processar os comentários do code review
@@ -372,6 +402,7 @@ fi
 - ✅ Preencher template do MR completamente
 - ✅ Mover card para "In Review"
 - ✅ Gerar o `pull-request.md` na sessão e só publicar com o **Sim** (Fase 4.3)
+- ✅ Com PR aberto, registrar o esforço no `daily.md` (7.2), com revisão conjunta da descrição e do timesheet
 - ✅ **Nunca apagar a sessão:** o `/eng.spec-consolidate` precisa dela
 
 ---

package/workflows/engineering/eng.start.md

@@ -121,6 +121,10 @@ CONTEXT_PROFILE:
 O perfil detectado será apresentado automaticamente pelo skill.
 Se o usuário solicitar ajustes, re-execute com `--override`.
 
+### Warm-up (se houver)
+
+Se `$SESSIONS_DIR/warm-ups/` tiver aquecimentos, leia `$IDE/rules-on-demand/warm-up-consume-rules.md` e siga-o: o aquecimento escolhido entra no `context.md` gerado acima e a pasta dele é apagada. Sem aquecimentos, siga sem perguntar.
+
 ---
 
 ## Fase 0.5: Advisor (opcional)

package/workflows/product/prod.spec.ard.md

@@ -25,6 +25,8 @@ Utilize o `$ARGUMENTS` que o usuário passar como ponto de partida e para entend
 #$ARGUMENTS
 </requirement>
 
+> 🔥 **Warm-up**: se `$SESSIONS_DIR/warm-ups/` tiver aquecimentos, leia `$IDE/rules-on-demand/warm-up-consume-rules.md` e siga-o antes de começar (grava em `$SESSIONS_DIR/prod/{id do documento}/context.md`).
+
 ## Quando usar
 - Depois de um PRD ou FRD aprovado, quando falta registrar os requisitos arquiteturais da iniciativa
 - Quando o PM precisa deixar claro para a engenharia o que a arquitetura precisa atender (volumes, prazos, integrações, regras de negócio com impacto técnico)

package/workflows/product/prod.spec.breakdown.md

@@ -26,6 +26,8 @@ Utilize o `$ARGUMENTS` como ponto de partida (caminho da spec, nome da feature o
 #$ARGUMENTS
 </requirement>
 
+> 🔥 **Warm-up**: se `$SESSIONS_DIR/warm-ups/` tiver aquecimentos, leia `$IDE/rules-on-demand/warm-up-consume-rules.md` e siga-o antes de começar (grava em `$SESSIONS_DIR/prod/{id do documento}/context.md`).
+
 ## Quando usar
 
 - Documento de Requisitos de Produto ou Documento de Requisitos Funcionais monolítico

package/workflows/product/prod.spec.clarify.md

@@ -8,6 +8,8 @@ model_tier: medium
 model_justification: Esclarecimento de specs requer análise estruturada e formulação de perguntas, mas segue processo bem definido
 ---
 
+> 🔥 **Warm-up**: se `$SESSIONS_DIR/warm-ups/` tiver aquecimentos, leia `$IDE/rules-on-demand/warm-up-consume-rules.md` e siga-o antes de começar (grava em `$SESSIONS_DIR/prod/{id do documento}/context.md`).
+
 ## Clarify workflow
 
 > 🎓 **Modo de condução**: leia `PROD_MODE` no `$IDE/ENV.md`. Se for `developer-guided`, **antes de começar leia `$IDE/rules-on-demand/product/prod.guided-rules.md` e siga-o** em toda a conversa. Vazio ou `product-led`: siga este fluxo como está.

package/workflows/product/prod.spec.discovery.md

@@ -1,166 +1,106 @@
 ---
 name: prod.spec.discovery
-description: Investigação inicial de uma ideia: entrevista o usuário sobre a ideia, o problema, os requisitos iniciais e a viabilidade, sem chutar, e registra um rascunho estruturado com veredito e próximo passo sugerido.
+description: Investigação inicial de uma ideia: mostra primeiro o que entendeu, faz poucas perguntas de alto impacto (com recomendação), propõe abordagens e registra um rascunho com scorecard, veredito e próximo passo sugerido, sem chutar.
 auto_execution_mode: 3
 env_file: "@/ENV.md"
 recommended_model: opus
 model_tier: high
-model_justification: Discovery exige conduzir uma entrevista adaptativa, julgar evidências e registrar hipóteses sem presumir dados
+model_justification: Discovery exige separar fatos de suposições, escolher as perguntas de maior impacto e julgar evidências sem presumir dados
 ---
 
 # Discovery (investigação inicial de uma ideia)
 
-> 🎓 **Modo de condução**: leia `PROD_MODE` no `$IDE/ENV.md`. Se for `developer-guided`, **antes de começar leia `$IDE/rules-on-demand/product/prod.guided-rules.md` e siga-o** em toda a conversa. Vazio ou `product-led`: siga este fluxo como está.
+> 🎓 **Modo de condução**: leia `PROD_MODE` no `$IDE/ENV.md`. Se for `developer-guided`, **antes de começar leia `$IDE/rules-on-demand/product/prod.guided-rules.md` e siga-o** em toda a conversa. `[Explicar melhor]` e `[Dúvida]` **não contam** no orçamento de perguntas. Vazio ou `product-led`: siga este fluxo como está.
 >
 > 🤖 **Modelo**: se a IDE informar o modelo desta sessão e ele for de outra família que o `recommended_model` do documento (ou do template, se o documento for novo), avise em uma linha e siga, sem bloquear e sem repetir. Sem essa informação, não avise.
 
-Este comando conduz uma **entrevista** para investigar uma ideia ainda crua e registrar o resultado em um **rascunho estruturado**: o problema, o que precisaria ser verdade e se parece viável.
+> 🔥 **Warm-up**: se `$SESSIONS_DIR/warm-ups/` tiver aquecimentos, leia `$IDE/rules-on-demand/warm-up-consume-rules.md` e siga-o antes de começar (grava em `$SESSIONS_DIR/prod/{id do documento}/context.md`).
 
-Antes de iniciar, revise as regras invioláveis em `$PROD_RULES/**/*`.
-
-- **Agente:** `$IDE/agents/product/prod.discovery-interviewer.md` conduz a entrevista; siga a postura dele.
-- **Template:** `$PROD_TEMPLATES/prod-discovery-template.md` define a estrutura do arquivo. Siga a estrutura exata do template.
-- **Guia humano (termos por extenso):** `docs/produto/prod.spec.discovery.md`.
-
-Utilize o `$ARGUMENTS` como ponto de partida (a ideia, ou o caminho ou nome de um discovery existente para retomar):
+Investiga uma ideia crua com **poucas perguntas certas** e grava um **rascunho** em `$PROD_DOCS/discoveries/discovery-{id}-{nome}.md`, pelo template `$PROD_TEMPLATES/prod-discovery-template.md`. Postura: agente `$IDE/agents/product/prod.discovery-interviewer.md`. Guia humano: `docs/produto/prod.spec.discovery.md`. Siga `$PROD_RULES` (ENV, idioma, `AskUserQuestion` uma pergunta por vez).
 
 <requirement>
 #$ARGUMENTS
 </requirement>
 
-## O que este comando é e o que não é
-
-O discovery é um **rascunho**: registra o que se sabe, o que é hipótese e o que ainda é lacuna. Nada nele é verdade absoluta.
-
-Ele **não** gera PRD, FRD, épico, issue, tarefas, histórias, critérios de aceitação nem estimativas, e **não** escreve código. Se o usuário pedir qualquer uma dessas coisas, explique que é outra etapa e indique o comando certo (`$PROD_FLOWS/prod.spec.prd.md`, `prod.spec.frd.md`, `prod.spec.epic.md`, `prod.spec.issue.md`; para implementar, o fluxo `/eng.start`).
-
-## Regras do framework
-
-O comando e o agente seguem obrigatoriamente `$PROD_RULES` (`prod-rules.md`):
-
-- Validar o `$IDE/ENV.md` antes de começar (se estiver ausente ou incompleto, aplicar o fluxo do `prod-rules.md`)
-- Idioma: português do Brasil por padrão, ou o idioma da interação do usuário
-- Perguntas: use o `AskUserQuestion` se estiver disponível; senão, o formato de tabela do `prod-rules.md`. **Uma pergunta por vez**
-- Confirmar com o usuário o caminho e o nome antes de salvar arquivo
+**Não é** PRD, FRD, épico, issue, histórias, critérios de aceitação, estimativa nem código. Pedido disso: diga que é outra etapa e indique o comando (`/prod.spec.prd`, `frd`, `epic`, `issue`; para implementar, `/eng.start`).
 
 ### Skills invocados durante o workflow
 
 | Passo | Skill | Condição |
 |-------|-------|----------|
-| Regras do framework / Passo 4 — A entrevista | `prod.discovery-interviewer` (agente) | Sempre — conduz a entrevista, e o comando segue a postura dele |
-| Passo 2 — Reconhecer o projeto | `/jarvis-docs-central` | Se `CENTRAL_DOCS_STORAGE` estiver configurado |
-| Passo 2 — Reconhecer o projeto | `/jarvis-context-detect` | Para calibrar a profundidade da entrevista |
-| Passo 2 — Reconhecer o projeto | `/eng-backend-arch-c4` | Só com a confirmação do usuário; o retorno é tratado como suposição a validar |
-| Passo 2 — Reconhecer o projeto | `/eng-platform` + `PLATFORM_SPECIALIZATIONS` | Só com a confirmação do usuário; o retorno é tratado como suposição a validar |
-
-## Passo 0 — Entender o que foi pedido
+| Passo 1 — Ler em silêncio | `prod.discovery-interviewer` (agente) | Sempre — a postura da entrevista |
+| Passo 1 — Ler em silêncio | `/jarvis-docs-central` | Se `CENTRAL_DOCS_STORAGE` estiver configurado (o que já foi implementado) |
+| Passo 1 — Ler em silêncio | `/eng-backend-arch-c4` | Só com a confirmação do usuário; o retorno é suposição a validar |
+| Passo 1 — Ler em silêncio | `/eng-platform` + `PLATFORM_SPECIALIZATIONS` | Só com a confirmação do usuário; o retorno é suposição a validar |
 
-1. **Sem `$ARGUMENTS`:** pergunte qual é a ideia antes de qualquer outra coisa.
-2. **Com `$ARGUMENTS` apontando um discovery existente** (caminho ou nome): vá para a **Retomada** (Passo 1).
-3. **Com uma ideia em `$ARGUMENTS`:** use esse texto como ponto de partida e **não repita perguntas** cuja resposta já está nele. Antes de criar um arquivo novo, procure em `$PROD_DOCS/discoveries/` um discovery **parecido** (leia só o título e a seção Ideia). Se achar, avise e pergunte se o usuário quer retomar aquele ou começar um novo, sem sobrescrever nada em silêncio.
-4. Se já existir PRD ou FRD em `$PROD_DOCS` que cubra a ideia, avise qual é e pergunte se o usuário quer seguir com o discovery (por exemplo, para reavaliar) ou ir para `$PROD_FLOWS/prod.spec.clarify.md`.
+## Passo 0 — Entrada
 
-## Passo 1 — Retomada de um discovery existente
+Sem ideia: pergunte qual é, antes de tudo. Caminho, nome ou id de um discovery existente: vá para a **Retomada**. Uma ideia: siga para o Passo 1.
 
-1. Leia o arquivo inteiro.
-2. **Resuma onde parou:** temas cobertos, hipóteses de importância alta e certeza baixa, perguntas em aberto e o histórico das sessões.
-3. Continue a entrevista pelos **temas incompletos** e pelas **perguntas em aberto**, sem repetir o que já foi respondido.
-4. Acrescente uma linha ao **Histórico das sessões** e atualize `updated_at` e `last_editor`.
-5. Se o discovery está `cancelled` ou com `verdict: do_not_proceed`, avise o motivo registrado e só reabra com confirmação do usuário.
+## Passo 1 — Ler em silêncio
 
-## Passo 2 — Reconhecer o projeto
+Antes de perguntar qualquer coisa, leia: o `$ARGUMENTS`; em `$PROD_DOCS`, os PRD/FRD que já cobrem a ideia e os discoveries parecidos (só título e Entendimento/Ideia); o código e os commits, se ajudarem a viabilidade; o Central docs, se configurado. Não repita perguntas cuja resposta já está em algum desses.
 
-Antes de perguntar, consulte o que já existe:
+## Passo 2 — Entendimento (uma confirmação)
 
-- Documentos em `$PROD_DOCS` (PRDs, FRDs e discoveries), para não duplicar o que já está especificado
-- O código e os últimos commits, quando ajudarem a embasar a viabilidade
-- `jarvis-docs-central`, se `CENTRAL_DOCS_STORAGE` estiver configurado
-- `jarvis-context-detect`, para calibrar a profundidade da entrevista
-- `eng-backend-arch-c4` e `eng-platform` (+ `PLATFORM_SPECIALIZATIONS`) são skills de engenharia: só consulte **com a confirmação do usuário**, e trate o retorno como **suposição a validar**, não como fato
+Mostre **"O que entendi"** e peça **uma** confirmação:
 
-## Passo 3 — Criar o arquivo
+- **Dito por você** | **Suposição minha** (com a origem) | **Lacuna** (marque as críticas: mudam o veredito)
+- **Tamanho** e orçamento de perguntas:
 
-Crie o arquivo **logo no início** da entrevista, para que uma conversa interrompida possa ser retomada:
+  | `size` | Quando | Perguntas | Próximo passo típico |
+  |---|---|---|---|
+  | `small` | Trabalho pequeno e já claro | 0–2 | `/prod.spec.issue` |
+  | `bounded` | Funcionalidade delimitada num produto existente | até 5 | `/prod.spec.frd` |
+  | `broad` | Ideia ampla, com várias entregas | até 8 | `/prod.spec.prd` e depois `/prod.spec.breakdown` |
 
-1. **Pasta:** `$PROD_DOCS/discoveries/`. Se não existir, crie-a e comece no `001`, confirmando o caminho com o usuário.
-2. **Id:** sequencial, pela listagem dos arquivos `discovery-*.md` da pasta (maior número + 1, com 3 dígitos).
-3. **Nome:** `{nome}` em kebab-case, sem acentos, derivado da ideia. Proponha e peça a confirmação do usuário.
-4. **Arquivo:** `$PROD_DOCS/discoveries/discovery-{id}-{nome}.md`, pelo template, com `status: in_review` e `verdict` vazio.
-5. **Metadados:** `created_at`, `updated_at`, `created_by` e `last_editor` (do `ENV.md`: `USER`).
+- **Arquivo:** `discovery-{id}-{nome}.md` (id = maior número da pasta + 1, 3 dígitos; nome em kebab-case, sem acentos). Pasta inexistente: crie e comece no `001`.
+- **Avisos:** PRD/FRD que já cobre a ideia (sugira `/prod.spec.clarify`); discovery parecido.
 
-## Passo 4 — A entrevista
+`AskUserQuestion`: **Confirmar (Recomendada)** | **Corrigir** | **Retomar o parecido** (só se houver). Ao confirmar, crie o arquivo pelo template (`status: in_review`, `verdict` vazio, `size`, datas, `created_by`/`last_editor` = `USER`) com o Entendimento e o Problema já preenchidos.
 
-Conduza como o agente `prod.discovery-interviewer`:
+## Passo 3 — Perguntas de alto impacto
 
-1. Explique em poucas linhas que vai entrevistar, quais temas serão cobertos (ideia, problema, requisitos, viabilidade) e que o usuário pode responder "não sei" a qualquer momento.
-2. **Uma pergunta por vez.** Se o usuário não responde ou diz "não sei", não repita a pergunta: registre "não informado" e siga.
-3. Trate o roteiro abaixo como **perguntas-semente**, não como lista fixa: adapte a próxima pergunta ao que já foi respondido e priorize as de maior impacto na decisão de seguir ou não.
-4. **Aprofunde** respostas rasas ("por quê?", "para quem?", "com que frequência?", "me dá um exemplo real", "o que acontece hoje?"). Diante de uma afirmação sem evidência ("todo mundo quer"), pergunte qual é a evidência e registre se é dado, observação ou suposição.
-5. **Aponte contradições**, entre respostas ou com o que foi encontrado no projeto, e peça que o usuário resolva.
-6. **Levante o que o usuário provavelmente não considerou**: quem mais é impactado, custo de manutenção, o que acontece se der errado, a alternativa mais simples.
-7. Ao cobrir um tema, **resuma** o que entendeu e peça confirmação antes de seguir. Em seguida, **atualize o arquivo** (Passo 5).
+- Pergunte **só lacunas que mudam o veredito**, da mais para a menos impactante. Nada de roteiro fixo.
+- Cada pergunta, com `AskUserQuestion`: **"Pergunta N de até M"**, **Por que importa** (uma frase), opções com a **(Recomendada)** primeiro e o motivo da recomendação.
+- **"Não sei"**: registre como lacuna e siga, sem repetir.
+- **Default razoável** (formato, padrão de mercado, comportamento comum): não pergunte; registre como **suposição explícita**.
+- Peça evidência ou aponte contradição **só** quando a resposta mudar o veredito.
+- **Teto atingido:** `AskUserQuestion` **Encerrar (Recomendada)** | **Mais perguntas**.
+- Atualize o arquivo ao fim do bloco (Entendimento, Problema, `updated_at`).
 
-### Temas e perguntas-semente
+## Passo 4 — Abordagens
 
-| Tema | Perguntas-semente |
-|---|---|
-| **Ideia** | O que é, em uma frase? Para quem? |
-| **Problema** | Qual é o problema (sem falar de solução)? Quem sofre com ele e em que situação? Como se resolve hoje? Que evidência existe? Por que agora? Como saberemos que funcionou? |
-| **Hipóteses** | O que precisaria ser verdade para isso funcionar? Quais dessas coisas você tem certeza e quais são palpite? Como confirmaríamos cada uma? |
-| **Viabilidade** | Valor: alguém vai querer e usar? Usabilidade: as pessoas conseguem usar? Técnica: o que já existe no projeto ajuda ou atrapalha? Negócio: custo, prazo e risco fazem sentido? |
-| **Alternativas e riscos** | E se não fizéssemos nada? Existe algo pronto que resolva? O que pode dar errado? Do que isso depende? |
+Proponha **2–3** abordagens, sempre com **a menor coisa que funciona** e **não fazer / usar algo existente**, com prós, contras, riscos e dependências. Indique a **recomendada** e peça a confirmação numa pergunta (Concordo (Recomendada) | Prefiro outra | Ajustar).
 
-## Passo 5 — Manter o arquivo
+## Passo 5 — Scorecard, veredito e próximo passo
 
-- Ao fim de **cada tema**, atualize as seções correspondentes do arquivo e o `updated_at`.
-- Registre cada sessão no **Histórico das sessões** (data e o que foi coberto).
-- Na tabela de **Hipóteses**, registre sempre a **origem** (dado, observação do usuário ou suposição).
-- **Nunca** grave credenciais, tokens nem dados pessoais de clientes: o arquivo é versionado.
-- Uma entrevista interrompida deixa o arquivo com `status: in_review` e `verdict` vazio, com os temas já cobertos.
+1. **Scorecard:** Valor, Usabilidade, Técnica e Negócio → `forte`, `adequado`, `fraco` ou `desconhecido`, com uma linha de justificativa.
+2. **Veredito** (recomendação, não aprovação): `proceed` (sem lacuna crítica) · `investigate_more` (lacuna crítica aberta ou lente crítica `desconhecido`) · `do_not_proceed` (motivo; `status: cancelled`).
+3. **Próximo passo**, sempre, com o **comando pronto com o id** (ex.: `/prod.spec.frd discovery-002`). **Nunca** o execute: o usuário pode escolher outro caminho ou parar. Pelo tamanho (tabela do Passo 2); `investigate_more` → retomar este discovery pelas lacunas; lacuna crítica técnica → `/eng.light-arch` ou `/eng.create-rfc` (só sugerir); `do_not_proceed` → arquivar, mantendo o registro.
 
-## Passo 6 — Não chute (regra inviolável)
+4. Linha no **Histórico** (data, "N de até M" perguntas, lacunas pendentes).
 
-- Quando faltar uma informação (público, volume, custo, prazo, restrição técnica, comportamento de usuários, estado atual do código), **não presuma**: pergunte, busque no projeto ou registre como **lacuna**.
-- Todo fato citado indica a origem (resposta do usuário, arquivo do projeto ou documentação consultada). O que não tem origem entra como **suposição a validar**.
-- Se o usuário pedir "preencha o que faltar" ou "assuma o padrão", registre o item como **suposição explícita**, nunca como fato, e não a use para sustentar o veredito.
-- Quando a viabilidade técnica depender de bibliotecas, APIs ou serviços, consulte a documentação atual (por exemplo, Context7), não a memória.
-- Uma **lacuna crítica nunca** resulta em `proceed`.
+## Retomada
 
-## Passo 7 — Encerrar
+1. Leia o arquivo **inteiro** e resuma onde parou: lacunas abertas, perguntas já usadas, veredito.
+2. `cancelled` ou `do_not_proceed`: mostre o motivo e só reabra com confirmação.
+3. **Formato antigo** (tem as seções "Hipóteses" ou "Perguntas em aberto"): converta para o template novo **no mesmo caminho** (mesmo id e nome, para os `related_discovery` continuarem válidos) e avise em uma linha. Mapeamento: Ideia → Entendimento (frase); Hipóteses → suposições (com a origem); Perguntas em aberto → lacunas; Alternativas e riscos → Abordagens; Viabilidade → Scorecard (alto/médio/baixo → forte/adequado/fraco); Histórico das sessões → Histórico. Defina o `size` no Entendimento.
+4. Siga pelo Passo 3 com o orçamento restante, depois os Passos 4 e 5.
 
-1. Quando achar que tem informação suficiente, **proponha encerrar** e pergunte se o usuário quer acrescentar algo.
-2. Complete o documento: viabilidade por lente (sinal alto, médio ou baixo, com justificativa), alternativas e riscos, perguntas em aberto e o histórico.
-3. **Veredito** (em `verdict`), sempre como **recomendação**, nunca como aprovação:
-   - `proceed`: vale especificar; sem lacuna crítica aberta
-   - `investigate_more`: há lacuna crítica; liste o que falta
-   - `do_not_proceed`: informe o motivo; mude o `status` para `cancelled`
-4. **Próximo passo sugerido**, **sempre**, qualquer que seja o veredito (comando recomendado, motivo e, se houver, alternativa). É **só uma sugestão**: mostre o **comando pronto com o id deste discovery** (por exemplo `/prod.spec.prd discovery-002`) para o usuário usá-lo como insumo, **nunca execute o comando sozinho**, e deixe claro que o usuário pode escolher outro caminho ou parar ali.
+## Não chute (regra inviolável)
 
-### Mapa de escolha do próximo passo
-
-| O que o discovery revelou | Próximo passo sugerido |
-|---|---|
-| Ideia ampla, com várias entregas | `/prod.spec.prd` e depois `/prod.spec.breakdown` |
-| Funcionalidade delimitada dentro de um produto existente | `/prod.spec.frd` |
-| Trabalho pequeno e já claro | `/prod.spec.issue` |
-| Lacunas críticas ou veredito `investigate_more` | Retomar este discovery, com as perguntas em aberto |
-| Lacuna crítica na viabilidade técnica | Investigação técnica no fluxo de engenharia (`/eng.light-arch` ou `/eng.create-rfc`), sugerida sem acioná-la |
-| Veredito `do_not_proceed` | Arquivar a ideia, mantendo o registro |
+- Faltou informação (público, volume, custo, prazo, restrição técnica, estado do código): pergunte, busque no projeto ou registre como **lacuna**. Nunca complete com "o que costuma ser".
+- Todo fato tem origem (usuário, arquivo do projeto ou documentação). Sem origem, é **suposição**.
+- "Preencha o que faltar" ou "assuma o padrão": registre como **suposição explícita**; ela nunca sustenta o veredito.
+- Bibliotecas, APIs e serviços: consulte a documentação atual (`context7`, se o MCP estiver disponível), não a memória.
+- **Lacuna crítica nunca dá `proceed`.** Nunca grave credenciais, tokens nem dados pessoais de clientes.
 
 ## Casos extremos
 
 | Situação | O que fazer |
 |---|---|
-| Ideia vaga demais ("melhorar o sistema") | Peça um recorte mínimo (quem, qual dor, em qual fluxo); se o usuário não conseguir, o veredito é `investigate_more` |
-| Ideia grande demais (várias funcionalidades) | Sinalize no documento e recomende, no próximo passo, a decomposição (`/prod.spec.prd` e `/prod.spec.breakdown`) ou separar em discoveries menores, sem forçar |
-| Viabilidade técnica depende de conhecimento que você não tem | Registre como lacuna nas perguntas em aberto, indicando quem pode responder, sem afirmar viabilidade |
-| Pasta `discoveries/` inexistente | Crie a pasta e o arquivo `001`, confirmando o caminho |
-| Ideia já coberta por PRD ou FRD existente | Avise qual documento cobre e pergunte como seguir |
-| Discovery com `do_not_proceed` | Mantenha o arquivo como registro da decisão |
-
-## Limites
-
-- Pedido de PRD, FRD, épico ou issue: indique o comando correto, sem gerar o documento
-- Pedido de tarefas, histórias, critérios de aceitação ou estimativas: recuse, por ser outra etapa
-- Pedido de implementação: recuse; o discovery só investiga e não escreve código
-- A entrevista é sempre com o usuário que executou o comando (não entrevista terceiros)
+| Ideia vaga ("melhorar o sistema") | Peça um recorte mínimo (quem, qual dor, em qual fluxo); sem recorte, `investigate_more` |
+| Ideia grande demais | `size: broad`; sugira `/prod.spec.prd` + `/prod.spec.breakdown` ou discoveries menores |
+| Viabilidade técnica fora do seu conhecimento | Lacuna crítica, com quem pode responder; não afirme viabilidade |
+| Entrevista interrompida | O arquivo fica `in_review`, `verdict` vazio; a Retomada continua dali. A entrevista é só com quem executou o comando |

package/workflows/product/prod.spec.epic.md

@@ -23,6 +23,8 @@ Utilize o `$ARGUMENTS` que o usuário passar como ponto de partida e para entend
 #$ARGUMENTS
 </requirement>
 
+> 🔥 **Warm-up**: se `$SESSIONS_DIR/warm-ups/` tiver aquecimentos, leia `$IDE/rules-on-demand/warm-up-consume-rules.md` e siga-o antes de começar (grava em `$SESSIONS_DIR/prod/{id do documento}/context.md`).
+
 ## Quando usar
 - Ao dividir grandes recursos ou PRDs em partes gerenciáveis
 - Quando o trabalho abrange vários sprints ou iterações

package/workflows/product/prod.spec.frd.md

@@ -23,6 +23,8 @@ Utilize o `$ARGUMENTS` que o usuário passar como ponto de partida e para entend
 #$ARGUMENTS
 </requirement>
 
+> 🔥 **Warm-up**: se `$SESSIONS_DIR/warm-ups/` tiver aquecimentos, leia `$IDE/rules-on-demand/warm-up-consume-rules.md` e siga-o antes de começar (grava em `$SESSIONS_DIR/prod/{id do documento}/context.md`).
+
 ## Quando usar
 - Quando é necessário documentar requisitos funcionais detalhados para uma feature
 - Antes do desenvolvimento para garantir clareza sobre o que deve ser construído

package/workflows/product/prod.spec.issue.md

@@ -22,6 +22,8 @@ Uma issue é a menor unidade de trabalho que pode ser feita. Ela deve entregar v
 
 Um grupo de histórias de um mesmo assunto podem formar um épico.
 
+> 🔥 **Warm-up**: se `$SESSIONS_DIR/warm-ups/` tiver aquecimentos, leia `$IDE/rules-on-demand/warm-up-consume-rules.md` e siga-o antes de começar (grava em `$SESSIONS_DIR/prod/{id do documento}/context.md`).
+
 ## Quando Usar
 - Ao decompor épicos em histórias de usuário implementáveis
 - Criar tarefas técnicas

package/workflows/product/prod.spec.md

@@ -14,6 +14,8 @@ model_justification: Especificações de produto requerem compreensão de requis
 
 Estas instruções ajudam a orientar o usuário que deseja começar a construir uma especificação. Esta especificação pode variar desde um PRD, história de usuário até tarefas. Devemos orientá-lo nessa construção de forma que a especificação, seja ela macro ou micro seja criada de acordo com as instruções e padrões do projeto.
 
+> 🔥 **Warm-up**: se `$SESSIONS_DIR/warm-ups/` tiver aquecimentos, leia `$IDE/rules-on-demand/warm-up-consume-rules.md` e siga-o antes de começar (grava em `$SESSIONS_DIR/prod/{id do documento}/context.md`).
+
 ## Quando usar
 - Esse comando serve para unificar a criação de todos os tipos de especificações do projeto.
 - Ao iniciar uma nova especificação de projeto ou modificar um PRD existente

package/workflows/product/prod.spec.prd.md

@@ -23,6 +23,8 @@ Utilize o `$ARGUMENTS` que o usuário passar como ponto de partida e para entend
 #$ARGUMENTS
 </requirement>
 
+> 🔥 **Warm-up**: se `$SESSIONS_DIR/warm-ups/` tiver aquecimentos, leia `$IDE/rules-on-demand/warm-up-consume-rules.md` e siga-o antes de começar (grava em `$SESSIONS_DIR/prod/{id do documento}/context.md`).
+
 ## Quando usar
 - Ao iniciar uma nova especificação de PRD (Product Requirment Document)
 - Precisar modificar um PRD existente