@luanpdd/kit-mcp 1.33.0 → 1.35.0

package/kit/framework/workflows/discuss-phase.md

@@ -1,784 +1,784 @@
-<purpose>
-Extrair decisões de implementação que agentes downstream precisam. Analisar a fase para identificar áreas cinzentas, deixar o usuário escolher o que discutir, então fazer deep-dive em cada área selecionada até a satisfação.
-
-Você é um parceiro de pensamento, não um entrevistador. O usuário é o visionário — você é o construtor. Seu trabalho é capturar decisões que guiarão pesquisa e planejamento, não descobrir a implementação por conta própria.
-</purpose>
-
-<downstream_awareness>
-**CONTEXT.md alimenta:**
-
-1. **phase-researcher** — Lê CONTEXT.md para saber O QUE pesquisar
-   - "Usuário quer layout baseado em cards" → pesquisador investiga padrões de componentes de card
-   - "Scroll infinito decidido" → pesquisador investiga bibliotecas de virtualização
-
-2. **planner** — Lê CONTEXT.md para saber QUAIS decisões estão bloqueadas
-   - "Pull-to-refresh no mobile" → planejador inclui isso nas especificações de tarefas
-   - "Discrição do Claude: skeleton de carregamento" → planejador pode decidir a abordagem
-
-**Seu trabalho:** Capturar decisões claramente o suficiente para que agentes downstream possam agir nelas sem perguntar ao usuário novamente.
-
-**Não é seu trabalho:** Descobrir COMO implementar. Isso é o que pesquisa e planejamento fazem com as decisões que você captura.
-</downstream_awareness>
-
-<philosophy>
-**Usuário = visionário. Claude = construtor.**
-
-Usuário SABE: como imagina, visual/sensação, essencial vs nice-to-have, referências específicas.
-Usuário NÃO sabe (não pergunte): padrões da codebase (pesquisador lê), riscos técnicos (pesquisador), abordagem de implementação (planejador), métricas (inferidas).
-
-Pergunte sobre visão e escolhas; capture decisões pra agentes downstream.
-</philosophy>
-
-<scope_guardrail>
-**CRÍTICO: sem expansão de escopo.** Limite da fase vem do ROADMAP e é FIXO. Discussão clarifica COMO, nunca SE adicionar capacidades.
-
-| Permitido (clarifica) | Não permitido (expande) |
-|---|---|
-| "Como exibir posts?" (layout, densidade) | "Adicionar comentários?" (nova capacidade) |
-| "O que em estado vazio?" | "E busca/filtragem?" |
-| "Pull-to-refresh ou manual?" | "Incluir favoritos?" |
-
-**Heurística:** clarifica o que já está na fase, ou adiciona capacidade que merece fase própria?
-
-**Quando usuário sugere expansão:** "[X] seria nova capacidade — fase própria. Anoto pro backlog. De volta a [tópico]." Capture em "Ideias Adiadas". Não perca, não aja.
-</scope_guardrail>
-
-<supabase_detection>
-**Detecção de fase Supabase:** antes de identificar áreas cinzentas genéricas, verifique se a fase mexe em Supabase (DB/Auth/Realtime/Edge Functions/Storage/RLS/migrations).
-
-Sinais de fase Supabase no objetivo do ROADMAP.md ou nos REQs mapeados:
-- Menções a "Supabase", "Postgres", "RLS", "policy", "migration", "supabase/migrations/", "supabase/schemas/", "supabase/functions/"
-- Menções a "Auth Next.js", "@supabase/ssr", "magic link", "OAuth", "MFA"
-- Menções a "broadcast", "realtime", "presence", "postgres_changes"
-- Menções a "Edge Function", "Deno", "pgvector", "RAG", "pg_cron", "pgmq"
-- Menções a "bucket", "signed URL", "storage.objects"
-
-**Se for fase Supabase:** considere delegar a discussão para o agent `supabase-architect` em vez de gerar áreas cinzentas genéricas. O architect já tem template de perguntas Supabase-específicas (tier Free/Pro, branches, RLS strategy multi-tenant, schema design, topology realtime, custos de egress/branches).
-
-```
-Task(subagent_type=supabase-architect, prompt="Projete schema + RLS + topologia para esta fase Supabase: {phase_goal}. Retorne plano em formato Markdown estruturado para servir de base ao CONTEXT.md.")
-```
-
-Use o output do architect como base do `<decisions>` do CONTEXT.md em vez de fazer questionamento manual. **Para fases mistas** (parte Supabase, parte genérica) — use architect só para a parte Supabase, depois faça discussão padrão para o resto.
-</supabase_detection>
-
-<gray_area_identification>
-Áreas cinzentas são **decisões de implementação que o usuário se importa** — coisas que podem ir de múltiplas formas e mudariam o resultado.
-
-**Como identificar áreas cinzentas:**
-
-1. **Ler o objetivo da fase** do ROADMAP.md
-2. **Entender o domínio** — Que tipo de coisa está sendo construída?
-   - Algo que usuários VÊM → apresentação visual, interações, estados importam
-   - Algo que usuários CHAMAM → contratos de interface, respostas, erros importam
-   - Algo que usuários EXECUTAM → invocação, saída, modos de comportamento importam
-   - Algo que usuários LÊM → estrutura, tom, profundidade, fluxo importam
-   - Algo sendo ORGANIZADO → critérios, agrupamento, tratamento de exceções importam
-3. **Gerar áreas cinzentas específicas da fase** — Não categorias genéricas, mas decisões concretas para ESTA fase
-
-**Não use rótulos genéricos** (UI/UX/Comportamento). Gere áreas específicas. Exemplos: Auth → sessão, erros, multi-device, recuperação. Backups CLI → output, flags, progress, recovery. Foto biblioteca → agrupamento, duplicatas, nomenclatura, pastas. API docs → estrutura, exemplos, versionamento, interativos.
-
-**Pergunta-chave:** quais decisões mudariam o resultado que o usuário deveria opinar?
-
-**Claude trata sozinho (não perguntar):** detalhes técnicos, padrões de arquitetura, otimização, escopo (roadmap define).
-</gray_area_identification>
-
-<answer_validation>
-**IMPORTANTE: Validação de resposta** — Após cada chamada AskUserQuestion, verificar se a resposta está vazia ou contém apenas espaços em branco. Se sim:
-1. Tentar a pergunta novamente com os mesmos parâmetros
-2. Se ainda vazia, apresentar as opções como uma lista numerada em texto simples e pedir ao usuário que digite o número da sua escolha
-Nunca prosseguir com uma resposta vazia.
-
-**Modo texto (`workflow.text_mode: true` na config ou flag `--text`):**
-Quando o modo texto estiver ativo, **não use AskUserQuestion de forma alguma**. Em vez disso, apresente cada
-pergunta como uma lista numerada em texto simples e peça ao usuário que digite o número da sua escolha.
-Isso é necessário para sessões remotas do Claude Code (modo `/rc`) onde o App Claude
-não pode encaminhar seleções de menu TUI de volta ao host.
-
-Ativar modo texto:
-- Por sessão: passar flag `--text` para qualquer comando (ex: `/discutir-fase --text`)
-- Por projeto: `tools config-set workflow.text_mode true`
-
-O modo texto aplica-se a TODOS os workflows na sessão, não apenas ao discuss-phase.
-</answer_validation>
-
-<process>
-
-**Caminho expresso disponível:** Se você já tem um PRD ou documento de critérios de aceitação, use `/planejar-fase {fase} --prd caminho/para/prd.md` para pular esta discussão e ir direto ao planejamento.
-
-<step name="initialize" priority="first">
-Número da fase do argumento (obrigatório).
-
-```bash
-INIT=$(node "./.claude/framework/bin/tools.cjs" init phase-op "${PHASE}")
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-AGENT_SKILLS_ADVISOR=$(node "./.claude/framework/bin/tools.cjs" agent-skills advisor 2>/dev/null)
-```
-
-Analisar JSON para: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `has_verification`, `plan_count`, `roadmap_exists`, `planning_exists`.
-
-**Se `phase_found` for false:**
-```
-Fase [X] não encontrada no roadmap.
-
-Use /progresso ${WS} para ver as fases disponíveis.
-```
-Sair do workflow.
-
-**Se `phase_found` for true:** Continuar para check_existing.
-
-**Modo auto** — Se `--auto` estiver presente em ARGUMENTS:
-- Em `check_existing`: auto-selecionar "Pular" (se contexto existir) ou continuar sem prompt (se sem contexto/planos)
-- Em `present_gray_areas`: auto-selecionar TODAS as áreas cinzentas sem perguntar ao usuário
-- Em `discuss_areas`: para cada pergunta de discussão, escolher a opção recomendada (primeira opção, ou a marcada como "recomendada") sem usar AskUserQuestion
-- Logar cada escolha auto-selecionada inline para que o usuário possa revisar decisões no arquivo de contexto
-- Após a discussão concluir, avançar automaticamente para plan-phase (comportamento existente)
-</step>
-
-<step name="check_existing">
-Verificar se CONTEXT.md já existe usando `has_context` do init.
-
-```bash
-ls ${phase_dir}/*-CONTEXT.md 2>/dev/null || true
-```
-
-**Se existir:**
-
-**Se `--auto`:** Auto-selecionar "Atualizar" — carregar contexto existente e continuar para analyze_phase. Logar: `[auto] Contexto existe — atualizando com decisões auto-selecionadas.`
-
-**Caso contrário:** Usar AskUserQuestion:
-- header: "Contexto"
-- question: "Fase [X] já tem contexto. O que você quer fazer?"
-- options:
-  - "Atualizar" — Revisar e revisar contexto existente
-  - "Visualizar" — Me mostra o que há
-  - "Pular" — Usar contexto existente como está
-
-Se "Atualizar": Carregar existente, continuar para analyze_phase
-Se "Visualizar": Exibir CONTEXT.md, então oferecer atualizar/pular
-Se "Pular": Sair do workflow
-
-**Se não existir:**
-
-Verificar `has_plans` e `plan_count` do init. **Se `has_plans` for true:**
-
-**Se `--auto`:** Auto-selecionar "Continuar e replanejar depois". Logar: `[auto] Planos existem — continuando com captura de contexto, replanejará depois.`
-
-**Caso contrário:** Usar AskUserQuestion:
-- header: "Planos existem"
-- question: "Fase [X] já tem {plan_count} plano(s) criado(s) sem contexto do usuário. Suas decisões aqui não afetarão os planos existentes a menos que você replane."
-- options:
-  - "Continuar e replanejar depois" — Capturar contexto, então executar /planejar-fase {X} ${WS} para replanejar
-  - "Visualizar planos existentes" — Mostrar planos antes de decidir
-  - "Cancelar" — Pular discuss-phase
-
-Se "Continuar e replanejar depois": Continuar para analyze_phase.
-Se "Visualizar planos existentes": Exibir arquivos de plano, então oferecer "Continuar" / "Cancelar".
-Se "Cancelar": Sair do workflow.
-
-**Se `has_plans` for false:** Continuar para load_prior_context.
-</step>
-
-<step name="load_prior_context">
-Ler PROJECT.md (visão/princípios/inegociáveis), REQUIREMENTS.md (critérios/must-haves), STATE.md (progresso/flags). Encontrar CONTEXT.md anteriores (`find .planning/phases -name "*-CONTEXT.md" | sort`); pra cada um com número < fase atual, extrair `<decisions>` (preferências bloqueadas) e `<specifics>` (refs particulares).
-
-Construir contexto interno `<prior_decisions>` com seções "Nível de Projeto" + "Das Fases Anteriores".
-
-**Uso downstream:** `analyze_phase` pula áreas já decididas; `present_gray_areas` anota com refs ("Você escolheu X na Fase 5"); `discuss_areas` pré-preenche ou sinaliza conflitos. Sem contexto anterior → continuar (esperado pra fases iniciais).
-</step>
-
-<step name="cross_reference_todos">
-Verificar se alguma tarefa pendente é relevante ao escopo desta fase. Exibe itens do backlog que de outra forma poderiam ser perdidos.
-
-**Carregar e corresponder tarefas:**
-```bash
-TODO_MATCHES=$(node "./.claude/framework/bin/tools.cjs" todo match-phase "${PHASE_NUMBER}")
-```
-
-Analisar JSON para: `todo_count`, `matches[]` (cada um com `file`, `title`, `area`, `score`, `reasons`).
-
-**Se `todo_count` for 0 ou `matches` estiver vazio:** Pular silenciosamente — sem atraso no workflow.
-
-**Se correspondências encontradas:**
-
-Apresentar tarefas correspondentes ao usuário. Mostrar cada correspondência com seu título, área e por que correspondeu:
-
-```
-📋 Encontradas {N} tarefa(s) pendente(s) que podem ser relevantes para a Fase {X}:
-
-{Para cada correspondência:}
-- **{título}** (área: {área}, relevância: {score}) — correspondeu em {reasons}
-```
-
-Usar AskUserQuestion (multiSelect) perguntando quais tarefas incorporar ao escopo desta fase:
-
-```
-Quais dessas tarefas devem ser incorporadas ao escopo da Fase {X}?
-(Selecione as que se aplicam, ou nenhuma para pular)
-```
-
-**Para tarefas selecionadas (incorporadas):**
-- Armazenar internamente como `<folded_todos>` para inclusão na seção `<decisions>` do CONTEXT.md
-- Estes se tornam itens de escopo adicionais que agentes downstream (pesquisador, planejador) verão
-
-**Para tarefas não selecionadas (revisadas mas não incorporadas):**
-- Armazenar internamente como `<reviewed_todos>` para inclusão na seção `<deferred>` do CONTEXT.md
-- Isso evita que fases futuras re-exibam as mesmas tarefas como "perdidas"
-
-**Modo auto (`--auto`):** Incorporar todas as tarefas com score >= 0,4 automaticamente. Logar a seleção.
-</step>
-
-<step name="scout_codebase">
-Varredura leve do código existente para informar identificação de áreas cinzentas e discussão. Usa ~10% do contexto — aceitável para uma sessão interativa.
-
-**Passo 1: Verificar mapas de codebase existentes**
-```bash
-ls .planning/codebase/*.md 2>/dev/null || true
-```
-
-**Mapas de codebase existem (`.planning/codebase/*.md`):** ler CONVENTIONS/STRUCTURE/STACK conforme tipo da fase. Extrair: ativos reutilizáveis, padrões estabelecidos, pontos de integração.
-
-**Sem mapas:** grep direcionado por termos-chave do objetivo (`grep -rl "termo1\|termo2" src/ app/ --include='*.{ts,tsx,js,jsx}' | head -10`) + `ls src/{components,hooks,lib,utils}/`. Ler 3-5 arquivos mais relevantes.
-
-Construir `<codebase_context>` interno: ativos reutilizáveis, padrões, pontos de integração, opções criativas que a arquitetura habilita/restringe. Não escreve em arquivo — só sessão atual.
-</step>
-
-<step name="analyze_phase">
-Analisar a fase para identificar áreas cinzentas que valem a discussão. **Usar tanto `prior_decisions` quanto `codebase_context` para embasar a análise.**
-
-**Ler a descrição da fase do ROADMAP.md e determinar:**
-
-1. **Limite de domínio** — Qual capacidade esta fase está entregando? Declará-la claramente.
-
-1b. **Inicializar acumulador de refs canônicas** — Começar a construir a lista `<canonical_refs>` para CONTEXT.md. Isso se acumula ao longo de toda a discussão, não apenas neste passo.
-
-   **Fonte 1 (agora):** Copiar `Canonical refs:` do ROADMAP.md para esta fase. Expandir cada uma para um caminho relativo completo.
-   **Fonte 2 (agora):** Verificar REQUIREMENTS.md e PROJECT.md por quaisquer specs/ADRs referenciados para esta fase.
-   **Fonte 3 (scout_codebase):** Se código existente referencia docs (ex: comentários citando ADRs), adicionar esses.
-   **Fonte 4 (discuss_areas):** Quando o usuário disser "leia X", "verifique Y", ou referenciar qualquer doc/spec/ADR durante a discussão — adicionar imediatamente. Estes são frequentemente as refs MAIS importantes porque representam docs que o usuário especificamente quer seguidos.
-
-   Esta lista é OBRIGATÓRIA no CONTEXT.md. Cada ref deve ter um caminho relativo completo para que agentes downstream possam lê-la diretamente. Se não existirem docs externos, note isso explicitamente.
-
-2. **Verificar decisões anteriores** — Antes de gerar áreas cinzentas, verificar se alguma já foi decidida:
-   - Escanear `<prior_decisions>` por escolhas relevantes (ex: "Somente Ctrl+C, sem atalhos de tecla única")
-   - Estas estão **pré-respondidas** — não re-perguntar a menos que esta fase tenha necessidades conflitantes
-   - Notar decisões anteriores aplicáveis para uso na apresentação
-
-3. **Áreas cinzentas por categoria** — Para cada categoria relevante (UI, UX, Comportamento, Estados Vazios, Conteúdo), identificar 1-2 ambiguidades específicas que mudariam a implementação. **Anotar com contexto de código onde relevante** (ex: "Você já tem um componente Card" ou "Sem padrão existente para isso").
-
-4. **Avaliação de pulo** — Se não existirem áreas cinzentas significativas (infraestrutura pura, implementação clara, ou tudo já decidido em fases anteriores), a fase pode não precisar de discussão.
-
-**Detecção de Modo Advisor:**
-
-`ADVISOR_MODE = exists("./.claude/framework/USER-PROFILE.md")`. Se false, pular todos os passos advisor — workflow conversacional inalterado.
-
-Se true, resolver `calibration_tier` por prioridade: (1) `config.json > preferences.vendor_philosophy` (project), (2) USER-PROFILE.md Vendor Choices/Philosophy (global), (3) default `standard`. Mapeamento: `conservative`/`thorough-evaluator` → `full_maturity`; `opinionated` → `minimal_decisive`; `pragmatic-fast` ou outro/vazio → `standard`.
-
-`ADVISOR_MODEL=$(node "./.claude/framework/bin/tools.cjs" resolve-model advisor-researcher --raw)`
-
-**Produzir sua análise internamente, então apresentar ao usuário.**
-
-Exemplo de análise para fase "Feed de Posts" (com código e contexto anterior):
-```
-Domínio: Exibindo posts de usuários seguidos
-Existente: Componente Card (src/components/ui/Card.tsx), hook useInfiniteQuery, Tailwind CSS
-Decisões anteriores: "UI minimalista preferida" (Fase 2), "Sem paginação — sempre scroll infinito" (Fase 4)
-Áreas cinzentas:
-- UI: Estilo de layout (cards vs timeline vs grid) — Componente Card existe com variantes shadow/rounded
-- UI: Densidade de informação (posts completos vs prévias) — sem padrões de densidade existentes
-- Comportamento: Padrão de carregamento — JÁ DECIDIDO: scroll infinito (Fase 4)
-- Estado Vazio: O que mostra quando não há posts — Componente EmptyState existe em ui/
-- Conteúdo: Quais metadados exibir (hora, autor, contagem de reações)
-```
-</step>
-
-<step name="present_gray_areas">
-Apresentar o limite de domínio, decisões anteriores e áreas cinzentas ao usuário.
-
-**Primeiro, declarar o limite e quaisquer decisões anteriores que se aplicam:**
-```
-Fase [X]: [Nome]
-Domínio: [O que esta fase entrega — da sua análise]
-
-Vamos clarificar COMO implementar isso.
-(Novas capacidades pertencem a outras fases.)
-
-[Se decisões anteriores se aplicam:]
-**Carregando de fases anteriores:**
-- [Decisão da Fase N que se aplica aqui]
-- [Decisão da Fase M que se aplica aqui]
-```
-
-**Se `--auto`:** Auto-selecionar TODAS as áreas cinzentas. Logar: `[auto] Selecionadas todas as áreas cinzentas: [lista de nomes das áreas].` Pular o AskUserQuestion abaixo e continuar diretamente para discuss_areas com todas as áreas selecionadas.
-
-**Caso contrário, usar AskUserQuestion (multiSelect: true):**
-- header: "Discutir"
-- question: "Quais áreas você quer discutir para [nome da fase]?"
-- options: Gerar 3-4 áreas cinzentas específicas da fase, cada uma com:
-  - "[Área específica]" (rótulo) — concreto, não genérico
-  - [1-2 perguntas que isso cobre + anotação de contexto de código] (descrição)
-  - **Destacar a escolha recomendada com breve explicação do porquê**
-
-**Anotações de decisão anterior:** Quando uma área cinzenta já foi decidida em uma fase anterior, anotá-la:
-```
-☐ Atalhos de saída — Como os usuários devem sair?
-  (Você decidiu "Somente Ctrl+C, sem atalhos de tecla única" na Fase 5 — revisitar ou manter?)
-```
-
-**Anotações de contexto de código:** Quando o scout encontrou código existente relevante, anotar a descrição da área cinzenta:
-```
-☐ Estilo de layout — Cards vs lista vs timeline?
-  (Você já tem um componente Card com variantes shadow/rounded. Reutilizá-lo mantém o app consistente.)
-```
-
-**Combinando ambos:** Quando tanto decisões anteriores quanto contexto de código se aplicam:
-```
-☐ Comportamento de carregamento — Scroll infinito ou paginação?
-  (Você escolheu scroll infinito na Fase 4. Hook useInfiniteQuery já configurado.)
-```
-
-**NÃO incluir opção "pular" ou "você decide".** O usuário executou este comando para discutir — dar escolhas reais.
-
-**Exemplos por domínio:**
-- Feed de Posts: layout (cards/lista/timeline), carregamento (infinito/paginação), ordenação, metadados
-- Backup CLI: output (JSON/tabela/texto), flags (curtas/longas), progress (silencioso/bar/verbose), recovery (fail-fast/retry)
-- Foto biblioteca: agrupamento (data/local/face/evento), duplicatas (melhor/todos/prompt), nomenclatura, pastas
-
-Continuar para discuss_areas com áreas selecionadas (ou advisor_research se ADVISOR_MODE for true).
-</step>
-
-<step name="advisor_research">
-**Pesquisa Advisor** (somente quando ADVISOR_MODE for true)
-
-Após o usuário selecionar áreas cinzentas em present_gray_areas, criar agentes de pesquisa paralelos.
-
-1. Exibir status breve: "Pesquisando {N} áreas..."
-
-2. Para CADA área cinzenta selecionada pelo usuário, criar um Task() em paralelo:
-
-   Task(
-     prompt="First, read @./.claude/agents/advisor-researcher.md for your role and instructions.
-
-     <gray_area>{area_name}: {area_description from gray area identification}</gray_area>
-     <phase_context>{phase_goal and description from ROADMAP.md}</phase_context>
-     <project_context>{project name and brief description from PROJECT.md}</project_context>
-     <calibration_tier>{resolved calibration tier: full_maturity | standard | minimal_decisive}</calibration_tier>
-
-     Research this gray area and return a structured comparison table with rationale.
-     ${AGENT_SKILLS_ADVISOR}",
-     subagent_type="general-purpose",
-     model="{ADVISOR_MODEL}",
-     description="Research: {area_name}"
-   )
-
-   Todas as chamadas Task() criam simultaneamente — NÃO aguardar uma antes de iniciar a próxima.
-
-3. Após TODOS os agentes retornarem, SINTETIZAR resultados antes de apresentar:
-   Para o retorno de cada agente:
-   a. Analisar a tabela de comparação markdown e parágrafo de raciocínio
-   b. Verificar se todas as 5 colunas estão presentes (Option | Pros | Cons | Complexity | Recommendation) — preencher colunas ausentes em vez de mostrar tabela quebrada
-   c. Verificar contagem de opções contra o tier de calibração:
-      - full_maturity: 3-5 opções aceitável
-      - standard: 2-4 opções aceitável
-      - minimal_decisive: 1-2 opções aceitável
-      Se agente retornou demais, remover as menos viáveis. Se poucas demais, aceitar como está.
-   d. Reescrever parágrafo de raciocínio para incorporar contexto do projeto e contexto de discussão em andamento ao qual o agente não tinha acesso
-   e. Se agente retornou apenas 1 opção, converter de formato de tabela para recomendação direta: "Abordagem padrão para {área}: {opção}. {raciocínio}"
-
-4. Armazenar tabelas sintetizadas para uso em discuss_areas.
-
-**Se ADVISOR_MODE for false:** Pular este passo inteiramente — prosseguir diretamente de present_gray_areas para discuss_areas.
-</step>
-
-<step name="discuss_areas">
-Discutir cada área selecionada com o usuário. O fluxo depende do modo advisor.
-
-**Se ADVISOR_MODE for true:**
-
-Fluxo de discussão com tabela primeiro — apresentar tabelas de comparação baseadas em pesquisa, então capturar escolhas do usuário.
-
-**Para cada área selecionada:**
-
-1. **Apresentar a tabela de comparação sintetizada + parágrafo de raciocínio** (do passo advisor_research)
-
-2. **Usar AskUserQuestion:**
-   - header: "{area_name}"
-   - question: "Qual abordagem para {area_name}?"
-   - options: Extrair da coluna Option da tabela (AskUserQuestion adiciona "Outro" automaticamente)
-
-3. **Registrar a seleção do usuário:**
-   - Se o usuário escolher das opções da tabela → registrar como decisão bloqueada para essa área
-   - Se o usuário escolher "Outro" → receber seu input, refletir de volta para confirmação, registrar
-
-4. **Após registrar escolha, Claude decide se perguntas de acompanhamento são necessárias:**
-   - Se a escolha tem ambiguidade que afetaria o planejamento downstream → fazer 1-2 perguntas de acompanhamento direcionadas usando AskUserQuestion
-   - Se a escolha é clara e autocontida → mover para próxima área
-   - NÃO fazer as 4 perguntas padrão — a tabela já forneceu o contexto
-
-5. **Após todas as áreas processadas:**
-   - header: "Concluído"
-   - question: "Isso cobre [listar áreas]. Pronto para criar contexto?"
-   - options: "Criar contexto" / "Revisitar uma área"
-
-**Tratamento de expansão de escopo (modo advisor):**
-Se o usuário mencionar algo fora do domínio da fase:
-```
-"[Funcionalidade] parece uma nova capacidade — pertence à sua própria fase.
-Vou anotá-la como uma ideia adiada.
-
-De volta a [área atual]: [retornar à pergunta atual]"
-```
-
-Rastrear ideias adiadas internamente.
-
----
-
-**Se ADVISOR_MODE for false:**
-
-Para cada área selecionada, conduzir um loop de discussão focado.
-
-**Modos opcionais (lidos de config + args):**
-
-- **`workflow.research_before_questions: true`** ou padrão off — antes de cada área, fazer 2-3 bullet de melhores práticas via web, apresentar com a pergunta. Ex: "OAuth 2.0 + PKCE é padrão atual pra SPAs; cookies httpOnly preferidos vs localStorage; passkey/WebAuthn em alta 2025-2026."
-- **`--text` ou `workflow.text_mode: true`** — substitui TODOS AskUserQuestion por listas numeradas em texto simples (necessário em sessões remotas Claude Code `/rc`).
-- **`--batch[=N]`** (default 4 quando ausente, range 2-5) — 1 turno agrupado com N perguntas numeradas em vez de N turnos de pergunta única. Após responder, refletir capturas e fazer follow-up mínimo.
-- **`--analyze`** — antes de cada pergunta (ou batch), fornecer mini-tabela de trade-offs (2-3 opções, prós/contras baseados na codebase + padrões), recomendação destacada, pitfalls.
-
-**Filosofia:** adaptativo, usuário escolhe o ritmo. Default: 4 turnos de pergunta única, depois verifica continuar. `--batch`: 1 turno agrupado, depois verifica.
-
-Cada resposta (ou conjunto de respostas, no modo batch) deve revelar a próxima pergunta ou próximo batch.
-
-**Modo auto (`--auto`):** Para cada área, Claude seleciona a opção recomendada (primeira opção, ou a explicitamente marcada como "recomendada") para cada pergunta sem usar AskUserQuestion. Logar cada escolha auto-selecionada:
-```
-[auto] [Área] — P: "[texto da pergunta]" → Selecionado: "[opção escolhida]" (padrão recomendado)
-```
-Após todas as áreas serem auto-resolvidas, pular o prompt "Explorar mais áreas cinzentas" e prosseguir diretamente para write_context.
-
-**Modo interativo (sem `--auto`):**
-
-**Para cada área:**
-
-1. **Anunciar a área:**
-   ```
-   Vamos falar sobre [Área].
-   ```
-
-2. **Fazer perguntas usando o ritmo selecionado:**
-
-   **Padrão (sem `--batch`): Fazer 4 perguntas usando AskUserQuestion**
-   - header: "[Área]" (máx 12 chars — abreviar se necessário)
-   - question: Decisão específica para esta área
-   - options: 2-3 escolhas concretas (AskUserQuestion adiciona "Outro" automaticamente), com a escolha recomendada destacada e breve explicação do porquê
-   - **Anotar opções com contexto de código** quando relevante:
-     ```
-     "Como os posts devem ser exibidos?"
-     - Cards (reutiliza o componente Card existente — consistente com Mensagens)
-     - Lista (mais simples, seria um novo padrão)
-     - Timeline (precisa de novo componente Timeline — nenhum existe ainda)
-     ```
-   - Incluir "Você decide" como opção quando razoável — captura discrição do Claude
-   - **Context7 para escolhas de biblioteca:** Quando uma área cinzenta envolve seleção de biblioteca (ex: "magic links" → consultar docs do next-auth) ou decisões de abordagem de API, usar ferramentas `mcp__context7__*` para buscar documentação atual e informar as opções. Não usar Context7 para cada pergunta — apenas quando conhecimento específico da biblioteca melhora as opções.
-
-   **Modo batch (`--batch`): Fazer 2-5 perguntas numeradas em um turno de texto simples**
-   - Agrupar perguntas intimamente relacionadas para a área atual em uma única mensagem
-   - Manter cada pergunta concreta e respondível em uma resposta
-   - Quando opções são úteis, incluir escolhas inline curtas por pergunta em vez de um AskUserQuestion separado para cada item
-   - Após a resposta do usuário, refletir de volta as decisões capturadas, notar itens não respondidos, e fazer apenas o mínimo de acompanhamento necessário antes de prosseguir
-   - Preservar adaptabilidade entre batches: usar o conjunto completo de respostas para decidir o próximo batch ou se a área está suficientemente clara
-
-3. **Após o conjunto atual de perguntas, verificar:**
-   - header: "[Área]" (máx 12 chars)
-   - question: "Mais perguntas sobre [área], ou mover para próxima? (Restantes: [listar outras áreas não visitadas])"
-   - options: "Mais perguntas" / "Próxima área"
-
-   Ao construir o texto da pergunta, listar as áreas não visitadas restantes para que o usuário saiba o que vem a seguir. Por exemplo: "Mais perguntas sobre Layout, ou mover para próxima? (Restantes: Comportamento de carregamento, Ordenação de conteúdo)"
-
-   Se "Mais perguntas" → fazer mais 4 perguntas únicas, ou mais um batch de 2-5 perguntas quando `--batch` estiver ativo, então verificar novamente
-   Se "Próxima área" → prosseguir para próxima área selecionada
-   Se "Outro" (texto livre) → interpretar intenção: frases de continuação ("mais", "continuar", "sim", "mais perguntas") mapeiam para "Mais perguntas"; frases de avanço ("feito", "continuar", "próximo", "pular") mapeiam para "Próxima área". Se ambíguo, perguntar: "Continuar com mais perguntas sobre [área], ou mover para a próxima área?"
-
-4. **Após todas as áreas inicialmente selecionadas concluírem:**
-   - Resumir o que foi capturado da discussão até agora
-   - AskUserQuestion:
-     - header: "Concluído"
-     - question: "Discutimos [listar áreas]. Quais áreas cinzentas permanecem pouco claras?"
-     - options: "Explorar mais áreas cinzentas" / "Estou pronto para o contexto"
-   - Se "Explorar mais áreas cinzentas":
-     - Identificar 2-4 áreas cinzentas adicionais com base no que foi aprendido
-     - Retornar à lógica de present_gray_areas com essas novas áreas
-     - Loop: discutir novas áreas, então solicitar novamente
-   - Se "Estou pronto para o contexto": Prosseguir para write_context
-
-**Acumulação de refs canônicas:** quando usuário referencia doc/spec/ADR (ex: "leia adr-014"), imediatamente: leia o doc, adicione ao acumulador com caminho relativo completo, use pra informar perguntas seguintes. Esses são frequentemente MAIS importantes que refs do ROADMAP — usuário quer que agentes downstream sigam. Nunca perca.
-
-**Design de perguntas:** opções concretas (não "Opção A"), cada resposta informa a próxima. Se usuário escolher "Outro" pra texto livre, faça acompanhamento em prompt simples (NÃO outro AskUserQuestion); reflita de volta e confirme.
-
-**Expansão de escopo:** ver `<scope_guardrail>` acima — anote como Ideia Adiada, retorne ao tópico.
-
-**Log interno por pergunta:** área, opções apresentadas, seleção do usuário, notas de acompanhamento. Usado pra gerar DISCUSSION-LOG.md no `write_context`.
-</step>
-
-<step name="write_context">
-Criar CONTEXT.md capturando as decisões tomadas.
-
-**Também gerar DISCUSSION-LOG.md** — uma trilha de auditoria completa do Q&A do discuss-phase.
-Este arquivo é apenas para referência humana (auditorias de software, revisões de conformidade). NÃO é
-consumido por agentes downstream (pesquisador, planejador, executor).
-
-**Encontrar ou criar diretório de fase:**
-
-Usar valores do init: `phase_dir`, `phase_slug`, `padded_phase`.
-
-Se `phase_dir` for null (fase existe no roadmap mas sem diretório):
-```bash
-mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"
-```
-
-**Localização do arquivo:** `${phase_dir}/${padded_phase}-CONTEXT.md`
-
-**Estruturar o conteúdo pelo que foi discutido:**
-
-```markdown
-# Fase [X]: [Nome] - Contexto
-
-**Coletado:** [data]
-**Status:** Pronto para planejamento
-
-<domain>
-## Limite da Fase
-
-[Declaração clara do que esta fase entrega — a âncora de escopo]
-
-</domain>
-
-<decisions>
-## Decisões de Implementação
-
-### [Categoria 1 que foi discutida]
-- **D-01:** [Decisão ou preferência capturada]
-- **D-02:** [Outra decisão se aplicável]
-
-### [Categoria 2 que foi discutida]
-- **D-03:** [Decisão ou preferência capturada]
-
-### Discrição do Claude
-[Áreas onde o usuário disse "você decide" — notar que Claude tem flexibilidade aqui]
-
-### Tarefas Incorporadas
-[Se alguma tarefa foi incorporada ao escopo do passo cross_reference_todos, listá-las aqui.
-Cada entrada deve incluir o título da tarefa, problema original e como se encaixa no escopo desta fase.
-Se nenhuma tarefa foi incorporada: omitir esta subseção inteiramente.]
-
-</decisions>
-
-<canonical_refs>
-## Referências Canônicas
-
-**Agentes downstream DEVEM ler estas antes de planejar ou implementar.**
-
-[Seção OBRIGATÓRIA. Escrever aqui a lista COMPLETA de refs canônicas acumuladas.
-Fontes: refs do ROADMAP.md + refs do REQUIREMENTS.md + docs referenciados pelo usuário durante
-a discussão + quaisquer docs descobertos durante a varredura da codebase. Agrupar por área de tópico.
-Cada entrada precisa de um caminho relativo completo — não apenas um nome.]
-
-### [Área de tópico 1]
-- `caminho/para/adr-ou-spec.md` — [O que decide/define que é relevante]
-- `caminho/para/doc.md` §N — [Referência de seção específica]
-
-### [Área de tópico 2]
-- `caminho/para/feature-doc.md` — [O que este doc define]
-
-[Se sem specs externas: "Sem specs externas — requisitos totalmente capturados nas decisões acima"]
-
-</canonical_refs>
-
-<code_context>
-## Insights de Código Existente
-
-### Ativos Reutilizáveis
-- [Componente/hook/utilitário]: [Como poderia ser usado nesta fase]
-
-### Padrões Estabelecidos
-- [Padrão]: [Como restringe/habilita esta fase]
-
-### Pontos de Integração
-- [Onde novo código se conecta ao sistema existente]
-
-</code_context>
-
-<specifics>
-## Ideias Específicas
-
-[Quaisquer referências particulares, exemplos, ou momentos "quero como X" da discussão]
-
-[Se nenhum: "Sem requisitos específicos — aberto a abordagens padrão"]
-
-</specifics>
-
-<deferred>
-## Ideias Adiadas
-
-[Ideias que surgiram mas pertencem a outras fases. Não as perder.]
-
-### Tarefas Revisadas (não incorporadas)
-[Se alguma tarefa foi revisada em cross_reference_todos mas não incorporada ao escopo,
-listá-las aqui para que fases futuras saibam que foram consideradas.
-Cada entrada: título da tarefa + motivo pelo qual foi adiada (fora do escopo, pertence à Fase Y, etc.)
-Se sem tarefas revisadas-mas-adiadas: omitir esta subseção inteiramente.]
-
-[Se nenhum: "Nenhum — discussão ficou dentro do escopo da fase"]
-
-</deferred>
-
----
-
-*Fase: XX-nome*
-*Contexto coletado: [data]*
-```
-
-Escrever arquivo.
-</step>
-
-<step name="confirm_creation">
-Apresentar resumo e próximos passos:
-
-```
-Criado: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
-
-## Decisões Capturadas
-
-### [Categoria]
-- [Decisão-chave]
-
-### [Categoria]
-- [Decisão-chave]
-
-[Se ideias adiadas existirem:]
-## Anotado para Depois
-- [Ideia adiada] — fase futura
-
----
-
-## ▶ Próximo Passo
-
-**Fase ${PHASE}: [Nome]** — [Objetivo do ROADMAP.md]
-
-`/planejar-fase ${PHASE} ${WS}`
-
-<sub>`/clear` primeiro → janela de contexto fresca</sub>
-
----
-
-**Também disponível:**
-- `/planejar-fase ${PHASE} --skip-research ${WS}` — planejar sem pesquisa
-- `/fase-ui ${PHASE} ${WS}` — gerar contrato de design de UI antes do planejamento (se a fase tem trabalho de frontend)
-- Revisar/editar CONTEXT.md antes de continuar
-
----
-```
-</step>
-
-<step name="git_commit">
-**Escrever DISCUSSION-LOG.md antes de commitar:**
-
-**Localização do arquivo:** `${phase_dir}/${padded_phase}-DISCUSSION-LOG.md`
-
-```markdown
-# Fase [X]: [Nome] - Log de Discussão
-
-> **Somente trilha de auditoria.** Não usar como entrada para agentes de planejamento, pesquisa ou execução.
-> Decisões são capturadas no CONTEXT.md — este log preserva as alternativas consideradas.
-
-**Data:** [data ISO]
-**Fase:** [número-fase]-[nome-fase]
-**Áreas discutidas:** [lista separada por vírgula]
-
----
-
-[Para cada área cinzenta discutida:]
-
-## [Nome da Área]
-
-| Opção | Descrição | Selecionada |
-|-------|-----------|-------------|
-| [Opção 1] | [Descrição do AskUserQuestion] | |
-| [Opção 2] | [Descrição] | ✓ |
-| [Opção 3] | [Descrição] | |
-
-**Escolha do usuário:** [Opção selecionada ou resposta em texto livre]
-**Notas:** [Quaisquer esclarecimentos, contexto de acompanhamento, ou raciocínio fornecido pelo usuário]
-
----
-
-[Repetir para cada área]
-
-## Discrição do Claude
-
-[Listar áreas onde o usuário disse "você decide" ou delegou ao Claude]
-
-## Ideias Adiadas
-
-[Ideias mencionadas durante a discussão que foram anotadas para fases futuras]
-```
-
-Escrever arquivo.
-
-Commitar contexto da fase e log de discussão:
-
-```bash
-node "./.claude/framework/bin/tools.cjs" commit "docs(${padded_phase}): capture phase context" --files "${phase_dir}/${padded_phase}-CONTEXT.md" "${phase_dir}/${padded_phase}-DISCUSSION-LOG.md"
-```
-
-Confirmar: "Commitado: docs(${padded_phase}): capturar contexto da fase"
-</step>
-
-<step name="update_state">
-Atualizar STATE.md com informações da sessão:
-
-```bash
-node "./.claude/framework/bin/tools.cjs" state record-session \
-  --stopped-at "Phase ${PHASE} context gathered" \
-  --resume-file "${phase_dir}/${padded_phase}-CONTEXT.md"
-```
-
-Commitar STATE.md:
-
-```bash
-node "./.claude/framework/bin/tools.cjs" commit "docs(state): record phase ${PHASE} context session" --files .planning/STATE.md
-```
-</step>
-
-<step name="auto_advance">
-**Detecção:** flag `--auto` em $ARGUMENTS, OR `workflow._auto_chain_active=true`, OR `workflow.auto_advance=true`.
-
-**Sync de cadeia:** se usuário invocou manualmente (sem `--auto`), zere `workflow._auto_chain_active` (mas NÃO toque `workflow.auto_advance` — preferência do usuário). Se `--auto` presente e cadeia não estava ativa, set `_auto_chain_active=true` (handle uso direto de `--auto` sem new-project).
-
-**Quando ativo:** dispare `Skill(skill="framework:planejar-fase", args="${PHASE} --auto ${WS}")` (use Skill, não Task aninhado — evita freeze de runtime, issue #686).
-
-**Roteamento de retorno do plan-phase:**
-- `FASE CONCLUÍDA` → cadeia completa. Próximo: `/discutir-fase ${NEXT_PHASE} --auto ${WS}` (após `/clear`)
-- `PLANEJAMENTO CONCLUÍDO` → execução parou. Continuar: `/executar-fase ${PHASE} ${WS}`
-- `PLANEJAMENTO INCONCLUSIVO / CHECKPOINT` → parou. Continuar: `/planejar-fase ${PHASE} ${WS}`
-- `LACUNAS ENCONTRADAS` → parou. Continuar: `/planejar-fase ${PHASE} --gaps ${WS}`
-
-**Quando inativo:** rotear pra `confirm_creation` (comportamento manual existente).
-</step>
-
-</process>
-
-<success_criteria>
-- Fase validada contra o roadmap
-- Contexto anterior carregado (PROJECT.md, REQUIREMENTS.md, STATE.md, arquivos CONTEXT.md anteriores)
-- Questões já decididas não re-perguntadas (carregadas de fases anteriores)
-- Codebase varrida por ativos reutilizáveis, padrões e pontos de integração
-- Áreas cinzentas identificadas por análise inteligente com anotações de código e decisão anterior
-- Usuário selecionou quais áreas discutir
-- Cada área selecionada explorada até satisfação do usuário (com opções informadas por código e por decisões anteriores)
-- Expansão de escopo redirecionada para ideias adiadas
-- CONTEXT.md captura decisões reais, não visão vaga
-- CONTEXT.md inclui seção canonical_refs com caminhos completos de arquivos para cada spec/ADR/doc que agentes downstream precisam (OBRIGATÓRIO — nunca omitir)
-- CONTEXT.md inclui seção code_context com ativos e padrões reutilizáveis
-- Ideias adiadas preservadas para fases futuras
-- STATE.md atualizado com informações da sessão
-- Usuário sabe os próximos passos
-</success_criteria>
+<purpose>
+Extrair decisões de implementação que agentes downstream precisam. Analisar a fase para identificar áreas cinzentas, deixar o usuário escolher o que discutir, então fazer deep-dive em cada área selecionada até a satisfação.
+
+Você é um parceiro de pensamento, não um entrevistador. O usuário é o visionário — você é o construtor. Seu trabalho é capturar decisões que guiarão pesquisa e planejamento, não descobrir a implementação por conta própria.
+</purpose>
+
+<downstream_awareness>
+**CONTEXT.md alimenta:**
+
+1. **phase-researcher** — Lê CONTEXT.md para saber O QUE pesquisar
+   - "Usuário quer layout baseado em cards" → pesquisador investiga padrões de componentes de card
+   - "Scroll infinito decidido" → pesquisador investiga bibliotecas de virtualização
+
+2. **planner** — Lê CONTEXT.md para saber QUAIS decisões estão bloqueadas
+   - "Pull-to-refresh no mobile" → planejador inclui isso nas especificações de tarefas
+   - "Discrição do Claude: skeleton de carregamento" → planejador pode decidir a abordagem
+
+**Seu trabalho:** Capturar decisões claramente o suficiente para que agentes downstream possam agir nelas sem perguntar ao usuário novamente.
+
+**Não é seu trabalho:** Descobrir COMO implementar. Isso é o que pesquisa e planejamento fazem com as decisões que você captura.
+</downstream_awareness>
+
+<philosophy>
+**Usuário = visionário. Claude = construtor.**
+
+Usuário SABE: como imagina, visual/sensação, essencial vs nice-to-have, referências específicas.
+Usuário NÃO sabe (não pergunte): padrões da codebase (pesquisador lê), riscos técnicos (pesquisador), abordagem de implementação (planejador), métricas (inferidas).
+
+Pergunte sobre visão e escolhas; capture decisões pra agentes downstream.
+</philosophy>
+
+<scope_guardrail>
+**CRÍTICO: sem expansão de escopo.** Limite da fase vem do ROADMAP e é FIXO. Discussão clarifica COMO, nunca SE adicionar capacidades.
+
+| Permitido (clarifica) | Não permitido (expande) |
+|---|---|
+| "Como exibir posts?" (layout, densidade) | "Adicionar comentários?" (nova capacidade) |
+| "O que em estado vazio?" | "E busca/filtragem?" |
+| "Pull-to-refresh ou manual?" | "Incluir favoritos?" |
+
+**Heurística:** clarifica o que já está na fase, ou adiciona capacidade que merece fase própria?
+
+**Quando usuário sugere expansão:** "[X] seria nova capacidade — fase própria. Anoto pro backlog. De volta a [tópico]." Capture em "Ideias Adiadas". Não perca, não aja.
+</scope_guardrail>
+
+<supabase_detection>
+**Detecção de fase Supabase:** antes de identificar áreas cinzentas genéricas, verifique se a fase mexe em Supabase (DB/Auth/Realtime/Edge Functions/Storage/RLS/migrations).
+
+Sinais de fase Supabase no objetivo do ROADMAP.md ou nos REQs mapeados:
+- Menções a "Supabase", "Postgres", "RLS", "policy", "migration", "supabase/migrations/", "supabase/schemas/", "supabase/functions/"
+- Menções a "Auth Next.js", "@supabase/ssr", "magic link", "OAuth", "MFA"
+- Menções a "broadcast", "realtime", "presence", "postgres_changes"
+- Menções a "Edge Function", "Deno", "pgvector", "RAG", "pg_cron", "pgmq"
+- Menções a "bucket", "signed URL", "storage.objects"
+
+**Se for fase Supabase:** considere delegar a discussão para o agent `supabase-architect` em vez de gerar áreas cinzentas genéricas. O architect já tem template de perguntas Supabase-específicas (tier Free/Pro, branches, RLS strategy multi-tenant, schema design, topology realtime, custos de egress/branches).
+
+```
+Task(subagent_type=supabase-architect, prompt="Projete schema + RLS + topologia para esta fase Supabase: {phase_goal}. Retorne plano em formato Markdown estruturado para servir de base ao CONTEXT.md.")
+```
+
+Use o output do architect como base do `<decisions>` do CONTEXT.md em vez de fazer questionamento manual. **Para fases mistas** (parte Supabase, parte genérica) — use architect só para a parte Supabase, depois faça discussão padrão para o resto.
+</supabase_detection>
+
+<gray_area_identification>
+Áreas cinzentas são **decisões de implementação que o usuário se importa** — coisas que podem ir de múltiplas formas e mudariam o resultado.
+
+**Como identificar áreas cinzentas:**
+
+1. **Ler o objetivo da fase** do ROADMAP.md
+2. **Entender o domínio** — Que tipo de coisa está sendo construída?
+   - Algo que usuários VÊM → apresentação visual, interações, estados importam
+   - Algo que usuários CHAMAM → contratos de interface, respostas, erros importam
+   - Algo que usuários EXECUTAM → invocação, saída, modos de comportamento importam
+   - Algo que usuários LÊM → estrutura, tom, profundidade, fluxo importam
+   - Algo sendo ORGANIZADO → critérios, agrupamento, tratamento de exceções importam
+3. **Gerar áreas cinzentas específicas da fase** — Não categorias genéricas, mas decisões concretas para ESTA fase
+
+**Não use rótulos genéricos** (UI/UX/Comportamento). Gere áreas específicas. Exemplos: Auth → sessão, erros, multi-device, recuperação. Backups CLI → output, flags, progress, recovery. Foto biblioteca → agrupamento, duplicatas, nomenclatura, pastas. API docs → estrutura, exemplos, versionamento, interativos.
+
+**Pergunta-chave:** quais decisões mudariam o resultado que o usuário deveria opinar?
+
+**Claude trata sozinho (não perguntar):** detalhes técnicos, padrões de arquitetura, otimização, escopo (roadmap define).
+</gray_area_identification>
+
+<answer_validation>
+**IMPORTANTE: Validação de resposta** — Após cada chamada AskUserQuestion, verificar se a resposta está vazia ou contém apenas espaços em branco. Se sim:
+1. Tentar a pergunta novamente com os mesmos parâmetros
+2. Se ainda vazia, apresentar as opções como uma lista numerada em texto simples e pedir ao usuário que digite o número da sua escolha
+Nunca prosseguir com uma resposta vazia.
+
+**Modo texto (`workflow.text_mode: true` na config ou flag `--text`):**
+Quando o modo texto estiver ativo, **não use AskUserQuestion de forma alguma**. Em vez disso, apresente cada
+pergunta como uma lista numerada em texto simples e peça ao usuário que digite o número da sua escolha.
+Isso é necessário para sessões remotas do Claude Code (modo `/rc`) onde o App Claude
+não pode encaminhar seleções de menu TUI de volta ao host.
+
+Ativar modo texto:
+- Por sessão: passar flag `--text` para qualquer comando (ex: `/discutir-fase --text`)
+- Por projeto: `tools config-set workflow.text_mode true`
+
+O modo texto aplica-se a TODOS os workflows na sessão, não apenas ao discuss-phase.
+</answer_validation>
+
+<process>
+
+**Caminho expresso disponível:** Se você já tem um PRD ou documento de critérios de aceitação, use `/planejar-fase {fase} --prd caminho/para/prd.md` para pular esta discussão e ir direto ao planejamento.
+
+<step name="initialize" priority="first">
+Número da fase do argumento (obrigatório).
+
+```bash
+INIT=$(node "./.claude/framework/bin/tools.cjs" init phase-op "${PHASE}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+AGENT_SKILLS_ADVISOR=$(node "./.claude/framework/bin/tools.cjs" agent-skills advisor 2>/dev/null)
+```
+
+Analisar JSON para: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `has_verification`, `plan_count`, `roadmap_exists`, `planning_exists`.
+
+**Se `phase_found` for false:**
+```
+Fase [X] não encontrada no roadmap.
+
+Use /progresso ${WS} para ver as fases disponíveis.
+```
+Sair do workflow.
+
+**Se `phase_found` for true:** Continuar para check_existing.
+
+**Modo auto** — Se `--auto` estiver presente em ARGUMENTS:
+- Em `check_existing`: auto-selecionar "Pular" (se contexto existir) ou continuar sem prompt (se sem contexto/planos)
+- Em `present_gray_areas`: auto-selecionar TODAS as áreas cinzentas sem perguntar ao usuário
+- Em `discuss_areas`: para cada pergunta de discussão, escolher a opção recomendada (primeira opção, ou a marcada como "recomendada") sem usar AskUserQuestion
+- Logar cada escolha auto-selecionada inline para que o usuário possa revisar decisões no arquivo de contexto
+- Após a discussão concluir, avançar automaticamente para plan-phase (comportamento existente)
+</step>
+
+<step name="check_existing">
+Verificar se CONTEXT.md já existe usando `has_context` do init.
+
+```bash
+ls ${phase_dir}/*-CONTEXT.md 2>/dev/null || true
+```
+
+**Se existir:**
+
+**Se `--auto`:** Auto-selecionar "Atualizar" — carregar contexto existente e continuar para analyze_phase. Logar: `[auto] Contexto existe — atualizando com decisões auto-selecionadas.`
+
+**Caso contrário:** Usar AskUserQuestion:
+- header: "Contexto"
+- question: "Fase [X] já tem contexto. O que você quer fazer?"
+- options:
+  - "Atualizar" — Revisar e revisar contexto existente
+  - "Visualizar" — Me mostra o que há
+  - "Pular" — Usar contexto existente como está
+
+Se "Atualizar": Carregar existente, continuar para analyze_phase
+Se "Visualizar": Exibir CONTEXT.md, então oferecer atualizar/pular
+Se "Pular": Sair do workflow
+
+**Se não existir:**
+
+Verificar `has_plans` e `plan_count` do init. **Se `has_plans` for true:**
+
+**Se `--auto`:** Auto-selecionar "Continuar e replanejar depois". Logar: `[auto] Planos existem — continuando com captura de contexto, replanejará depois.`
+
+**Caso contrário:** Usar AskUserQuestion:
+- header: "Planos existem"
+- question: "Fase [X] já tem {plan_count} plano(s) criado(s) sem contexto do usuário. Suas decisões aqui não afetarão os planos existentes a menos que você replane."
+- options:
+  - "Continuar e replanejar depois" — Capturar contexto, então executar /planejar-fase {X} ${WS} para replanejar
+  - "Visualizar planos existentes" — Mostrar planos antes de decidir
+  - "Cancelar" — Pular discuss-phase
+
+Se "Continuar e replanejar depois": Continuar para analyze_phase.
+Se "Visualizar planos existentes": Exibir arquivos de plano, então oferecer "Continuar" / "Cancelar".
+Se "Cancelar": Sair do workflow.
+
+**Se `has_plans` for false:** Continuar para load_prior_context.
+</step>
+
+<step name="load_prior_context">
+Ler PROJECT.md (visão/princípios/inegociáveis), REQUIREMENTS.md (critérios/must-haves), STATE.md (progresso/flags). Encontrar CONTEXT.md anteriores (`find .planning/phases -name "*-CONTEXT.md" | sort`); pra cada um com número < fase atual, extrair `<decisions>` (preferências bloqueadas) e `<specifics>` (refs particulares).
+
+Construir contexto interno `<prior_decisions>` com seções "Nível de Projeto" + "Das Fases Anteriores".
+
+**Uso downstream:** `analyze_phase` pula áreas já decididas; `present_gray_areas` anota com refs ("Você escolheu X na Fase 5"); `discuss_areas` pré-preenche ou sinaliza conflitos. Sem contexto anterior → continuar (esperado pra fases iniciais).
+</step>
+
+<step name="cross_reference_todos">
+Verificar se alguma tarefa pendente é relevante ao escopo desta fase. Exibe itens do backlog que de outra forma poderiam ser perdidos.
+
+**Carregar e corresponder tarefas:**
+```bash
+TODO_MATCHES=$(node "./.claude/framework/bin/tools.cjs" todo match-phase "${PHASE_NUMBER}")
+```
+
+Analisar JSON para: `todo_count`, `matches[]` (cada um com `file`, `title`, `area`, `score`, `reasons`).
+
+**Se `todo_count` for 0 ou `matches` estiver vazio:** Pular silenciosamente — sem atraso no workflow.
+
+**Se correspondências encontradas:**
+
+Apresentar tarefas correspondentes ao usuário. Mostrar cada correspondência com seu título, área e por que correspondeu:
+
+```
+📋 Encontradas {N} tarefa(s) pendente(s) que podem ser relevantes para a Fase {X}:
+
+{Para cada correspondência:}
+- **{título}** (área: {área}, relevância: {score}) — correspondeu em {reasons}
+```
+
+Usar AskUserQuestion (multiSelect) perguntando quais tarefas incorporar ao escopo desta fase:
+
+```
+Quais dessas tarefas devem ser incorporadas ao escopo da Fase {X}?
+(Selecione as que se aplicam, ou nenhuma para pular)
+```
+
+**Para tarefas selecionadas (incorporadas):**
+- Armazenar internamente como `<folded_todos>` para inclusão na seção `<decisions>` do CONTEXT.md
+- Estes se tornam itens de escopo adicionais que agentes downstream (pesquisador, planejador) verão
+
+**Para tarefas não selecionadas (revisadas mas não incorporadas):**
+- Armazenar internamente como `<reviewed_todos>` para inclusão na seção `<deferred>` do CONTEXT.md
+- Isso evita que fases futuras re-exibam as mesmas tarefas como "perdidas"
+
+**Modo auto (`--auto`):** Incorporar todas as tarefas com score >= 0,4 automaticamente. Logar a seleção.
+</step>
+
+<step name="scout_codebase">
+Varredura leve do código existente para informar identificação de áreas cinzentas e discussão. Usa ~10% do contexto — aceitável para uma sessão interativa.
+
+**Passo 1: Verificar mapas de codebase existentes**
+```bash
+ls .planning/codebase/*.md 2>/dev/null || true
+```
+
+**Mapas de codebase existem (`.planning/codebase/*.md`):** ler CONVENTIONS/STRUCTURE/STACK conforme tipo da fase. Extrair: ativos reutilizáveis, padrões estabelecidos, pontos de integração.
+
+**Sem mapas:** grep direcionado por termos-chave do objetivo (`grep -rl "termo1\|termo2" src/ app/ --include='*.{ts,tsx,js,jsx}' | head -10`) + `ls src/{components,hooks,lib,utils}/`. Ler 3-5 arquivos mais relevantes.
+
+Construir `<codebase_context>` interno: ativos reutilizáveis, padrões, pontos de integração, opções criativas que a arquitetura habilita/restringe. Não escreve em arquivo — só sessão atual.
+</step>
+
+<step name="analyze_phase">
+Analisar a fase para identificar áreas cinzentas que valem a discussão. **Usar tanto `prior_decisions` quanto `codebase_context` para embasar a análise.**
+
+**Ler a descrição da fase do ROADMAP.md e determinar:**
+
+1. **Limite de domínio** — Qual capacidade esta fase está entregando? Declará-la claramente.
+
+1b. **Inicializar acumulador de refs canônicas** — Começar a construir a lista `<canonical_refs>` para CONTEXT.md. Isso se acumula ao longo de toda a discussão, não apenas neste passo.
+
+   **Fonte 1 (agora):** Copiar `Canonical refs:` do ROADMAP.md para esta fase. Expandir cada uma para um caminho relativo completo.
+   **Fonte 2 (agora):** Verificar REQUIREMENTS.md e PROJECT.md por quaisquer specs/ADRs referenciados para esta fase.
+   **Fonte 3 (scout_codebase):** Se código existente referencia docs (ex: comentários citando ADRs), adicionar esses.
+   **Fonte 4 (discuss_areas):** Quando o usuário disser "leia X", "verifique Y", ou referenciar qualquer doc/spec/ADR durante a discussão — adicionar imediatamente. Estes são frequentemente as refs MAIS importantes porque representam docs que o usuário especificamente quer seguidos.
+
+   Esta lista é OBRIGATÓRIA no CONTEXT.md. Cada ref deve ter um caminho relativo completo para que agentes downstream possam lê-la diretamente. Se não existirem docs externos, note isso explicitamente.
+
+2. **Verificar decisões anteriores** — Antes de gerar áreas cinzentas, verificar se alguma já foi decidida:
+   - Escanear `<prior_decisions>` por escolhas relevantes (ex: "Somente Ctrl+C, sem atalhos de tecla única")
+   - Estas estão **pré-respondidas** — não re-perguntar a menos que esta fase tenha necessidades conflitantes
+   - Notar decisões anteriores aplicáveis para uso na apresentação
+
+3. **Áreas cinzentas por categoria** — Para cada categoria relevante (UI, UX, Comportamento, Estados Vazios, Conteúdo), identificar 1-2 ambiguidades específicas que mudariam a implementação. **Anotar com contexto de código onde relevante** (ex: "Você já tem um componente Card" ou "Sem padrão existente para isso").
+
+4. **Avaliação de pulo** — Se não existirem áreas cinzentas significativas (infraestrutura pura, implementação clara, ou tudo já decidido em fases anteriores), a fase pode não precisar de discussão.
+
+**Detecção de Modo Advisor:**
+
+`ADVISOR_MODE = exists("./.claude/framework/USER-PROFILE.md")`. Se false, pular todos os passos advisor — workflow conversacional inalterado.
+
+Se true, resolver `calibration_tier` por prioridade: (1) `config.json > preferences.vendor_philosophy` (project), (2) USER-PROFILE.md Vendor Choices/Philosophy (global), (3) default `standard`. Mapeamento: `conservative`/`thorough-evaluator` → `full_maturity`; `opinionated` → `minimal_decisive`; `pragmatic-fast` ou outro/vazio → `standard`.
+
+`ADVISOR_MODEL=$(node "./.claude/framework/bin/tools.cjs" resolve-model advisor-researcher --raw)`
+
+**Produzir sua análise internamente, então apresentar ao usuário.**
+
+Exemplo de análise para fase "Feed de Posts" (com código e contexto anterior):
+```
+Domínio: Exibindo posts de usuários seguidos
+Existente: Componente Card (src/components/ui/Card.tsx), hook useInfiniteQuery, Tailwind CSS
+Decisões anteriores: "UI minimalista preferida" (Fase 2), "Sem paginação — sempre scroll infinito" (Fase 4)
+Áreas cinzentas:
+- UI: Estilo de layout (cards vs timeline vs grid) — Componente Card existe com variantes shadow/rounded
+- UI: Densidade de informação (posts completos vs prévias) — sem padrões de densidade existentes
+- Comportamento: Padrão de carregamento — JÁ DECIDIDO: scroll infinito (Fase 4)
+- Estado Vazio: O que mostra quando não há posts — Componente EmptyState existe em ui/
+- Conteúdo: Quais metadados exibir (hora, autor, contagem de reações)
+```
+</step>
+
+<step name="present_gray_areas">
+Apresentar o limite de domínio, decisões anteriores e áreas cinzentas ao usuário.
+
+**Primeiro, declarar o limite e quaisquer decisões anteriores que se aplicam:**
+```
+Fase [X]: [Nome]
+Domínio: [O que esta fase entrega — da sua análise]
+
+Vamos clarificar COMO implementar isso.
+(Novas capacidades pertencem a outras fases.)
+
+[Se decisões anteriores se aplicam:]
+**Carregando de fases anteriores:**
+- [Decisão da Fase N que se aplica aqui]
+- [Decisão da Fase M que se aplica aqui]
+```
+
+**Se `--auto`:** Auto-selecionar TODAS as áreas cinzentas. Logar: `[auto] Selecionadas todas as áreas cinzentas: [lista de nomes das áreas].` Pular o AskUserQuestion abaixo e continuar diretamente para discuss_areas com todas as áreas selecionadas.
+
+**Caso contrário, usar AskUserQuestion (multiSelect: true):**
+- header: "Discutir"
+- question: "Quais áreas você quer discutir para [nome da fase]?"
+- options: Gerar 3-4 áreas cinzentas específicas da fase, cada uma com:
+  - "[Área específica]" (rótulo) — concreto, não genérico
+  - [1-2 perguntas que isso cobre + anotação de contexto de código] (descrição)
+  - **Destacar a escolha recomendada com breve explicação do porquê**
+
+**Anotações de decisão anterior:** Quando uma área cinzenta já foi decidida em uma fase anterior, anotá-la:
+```
+☐ Atalhos de saída — Como os usuários devem sair?
+  (Você decidiu "Somente Ctrl+C, sem atalhos de tecla única" na Fase 5 — revisitar ou manter?)
+```
+
+**Anotações de contexto de código:** Quando o scout encontrou código existente relevante, anotar a descrição da área cinzenta:
+```
+☐ Estilo de layout — Cards vs lista vs timeline?
+  (Você já tem um componente Card com variantes shadow/rounded. Reutilizá-lo mantém o app consistente.)
+```
+
+**Combinando ambos:** Quando tanto decisões anteriores quanto contexto de código se aplicam:
+```
+☐ Comportamento de carregamento — Scroll infinito ou paginação?
+  (Você escolheu scroll infinito na Fase 4. Hook useInfiniteQuery já configurado.)
+```
+
+**NÃO incluir opção "pular" ou "você decide".** O usuário executou este comando para discutir — dar escolhas reais.
+
+**Exemplos por domínio:**
+- Feed de Posts: layout (cards/lista/timeline), carregamento (infinito/paginação), ordenação, metadados
+- Backup CLI: output (JSON/tabela/texto), flags (curtas/longas), progress (silencioso/bar/verbose), recovery (fail-fast/retry)
+- Foto biblioteca: agrupamento (data/local/face/evento), duplicatas (melhor/todos/prompt), nomenclatura, pastas
+
+Continuar para discuss_areas com áreas selecionadas (ou advisor_research se ADVISOR_MODE for true).
+</step>
+
+<step name="advisor_research">
+**Pesquisa Advisor** (somente quando ADVISOR_MODE for true)
+
+Após o usuário selecionar áreas cinzentas em present_gray_areas, criar agentes de pesquisa paralelos.
+
+1. Exibir status breve: "Pesquisando {N} áreas..."
+
+2. Para CADA área cinzenta selecionada pelo usuário, criar um Task() em paralelo:
+
+   Task(
+     prompt="First, read @./.claude/agents/advisor-researcher.md for your role and instructions.
+
+     <gray_area>{area_name}: {area_description from gray area identification}</gray_area>
+     <phase_context>{phase_goal and description from ROADMAP.md}</phase_context>
+     <project_context>{project name and brief description from PROJECT.md}</project_context>
+     <calibration_tier>{resolved calibration tier: full_maturity | standard | minimal_decisive}</calibration_tier>
+
+     Research this gray area and return a structured comparison table with rationale.
+     ${AGENT_SKILLS_ADVISOR}",
+     subagent_type="general-purpose",
+     model="{ADVISOR_MODEL}",
+     description="Research: {area_name}"
+   )
+
+   Todas as chamadas Task() criam simultaneamente — NÃO aguardar uma antes de iniciar a próxima.
+
+3. Após TODOS os agentes retornarem, SINTETIZAR resultados antes de apresentar:
+   Para o retorno de cada agente:
+   a. Analisar a tabela de comparação markdown e parágrafo de raciocínio
+   b. Verificar se todas as 5 colunas estão presentes (Option | Pros | Cons | Complexity | Recommendation) — preencher colunas ausentes em vez de mostrar tabela quebrada
+   c. Verificar contagem de opções contra o tier de calibração:
+      - full_maturity: 3-5 opções aceitável
+      - standard: 2-4 opções aceitável
+      - minimal_decisive: 1-2 opções aceitável
+      Se agente retornou demais, remover as menos viáveis. Se poucas demais, aceitar como está.
+   d. Reescrever parágrafo de raciocínio para incorporar contexto do projeto e contexto de discussão em andamento ao qual o agente não tinha acesso
+   e. Se agente retornou apenas 1 opção, converter de formato de tabela para recomendação direta: "Abordagem padrão para {área}: {opção}. {raciocínio}"
+
+4. Armazenar tabelas sintetizadas para uso em discuss_areas.
+
+**Se ADVISOR_MODE for false:** Pular este passo inteiramente — prosseguir diretamente de present_gray_areas para discuss_areas.
+</step>
+
+<step name="discuss_areas">
+Discutir cada área selecionada com o usuário. O fluxo depende do modo advisor.
+
+**Se ADVISOR_MODE for true:**
+
+Fluxo de discussão com tabela primeiro — apresentar tabelas de comparação baseadas em pesquisa, então capturar escolhas do usuário.
+
+**Para cada área selecionada:**
+
+1. **Apresentar a tabela de comparação sintetizada + parágrafo de raciocínio** (do passo advisor_research)
+
+2. **Usar AskUserQuestion:**
+   - header: "{area_name}"
+   - question: "Qual abordagem para {area_name}?"
+   - options: Extrair da coluna Option da tabela (AskUserQuestion adiciona "Outro" automaticamente)
+
+3. **Registrar a seleção do usuário:**
+   - Se o usuário escolher das opções da tabela → registrar como decisão bloqueada para essa área
+   - Se o usuário escolher "Outro" → receber seu input, refletir de volta para confirmação, registrar
+
+4. **Após registrar escolha, Claude decide se perguntas de acompanhamento são necessárias:**
+   - Se a escolha tem ambiguidade que afetaria o planejamento downstream → fazer 1-2 perguntas de acompanhamento direcionadas usando AskUserQuestion
+   - Se a escolha é clara e autocontida → mover para próxima área
+   - NÃO fazer as 4 perguntas padrão — a tabela já forneceu o contexto
+
+5. **Após todas as áreas processadas:**
+   - header: "Concluído"
+   - question: "Isso cobre [listar áreas]. Pronto para criar contexto?"
+   - options: "Criar contexto" / "Revisitar uma área"
+
+**Tratamento de expansão de escopo (modo advisor):**
+Se o usuário mencionar algo fora do domínio da fase:
+```
+"[Funcionalidade] parece uma nova capacidade — pertence à sua própria fase.
+Vou anotá-la como uma ideia adiada.
+
+De volta a [área atual]: [retornar à pergunta atual]"
+```
+
+Rastrear ideias adiadas internamente.
+
+---
+
+**Se ADVISOR_MODE for false:**
+
+Para cada área selecionada, conduzir um loop de discussão focado.
+
+**Modos opcionais (lidos de config + args):**
+
+- **`workflow.research_before_questions: true`** ou padrão off — antes de cada área, fazer 2-3 bullet de melhores práticas via web, apresentar com a pergunta. Ex: "OAuth 2.0 + PKCE é padrão atual pra SPAs; cookies httpOnly preferidos vs localStorage; passkey/WebAuthn em alta 2025-2026."
+- **`--text` ou `workflow.text_mode: true`** — substitui TODOS AskUserQuestion por listas numeradas em texto simples (necessário em sessões remotas Claude Code `/rc`).
+- **`--batch[=N]`** (default 4 quando ausente, range 2-5) — 1 turno agrupado com N perguntas numeradas em vez de N turnos de pergunta única. Após responder, refletir capturas e fazer follow-up mínimo.
+- **`--analyze`** — antes de cada pergunta (ou batch), fornecer mini-tabela de trade-offs (2-3 opções, prós/contras baseados na codebase + padrões), recomendação destacada, pitfalls.
+
+**Filosofia:** adaptativo, usuário escolhe o ritmo. Default: 4 turnos de pergunta única, depois verifica continuar. `--batch`: 1 turno agrupado, depois verifica.
+
+Cada resposta (ou conjunto de respostas, no modo batch) deve revelar a próxima pergunta ou próximo batch.
+
+**Modo auto (`--auto`):** Para cada área, Claude seleciona a opção recomendada (primeira opção, ou a explicitamente marcada como "recomendada") para cada pergunta sem usar AskUserQuestion. Logar cada escolha auto-selecionada:
+```
+[auto] [Área] — P: "[texto da pergunta]" → Selecionado: "[opção escolhida]" (padrão recomendado)
+```
+Após todas as áreas serem auto-resolvidas, pular o prompt "Explorar mais áreas cinzentas" e prosseguir diretamente para write_context.
+
+**Modo interativo (sem `--auto`):**
+
+**Para cada área:**
+
+1. **Anunciar a área:**
+   ```
+   Vamos falar sobre [Área].
+   ```
+
+2. **Fazer perguntas usando o ritmo selecionado:**
+
+   **Padrão (sem `--batch`): Fazer 4 perguntas usando AskUserQuestion**
+   - header: "[Área]" (máx 12 chars — abreviar se necessário)
+   - question: Decisão específica para esta área
+   - options: 2-3 escolhas concretas (AskUserQuestion adiciona "Outro" automaticamente), com a escolha recomendada destacada e breve explicação do porquê
+   - **Anotar opções com contexto de código** quando relevante:
+     ```
+     "Como os posts devem ser exibidos?"
+     - Cards (reutiliza o componente Card existente — consistente com Mensagens)
+     - Lista (mais simples, seria um novo padrão)
+     - Timeline (precisa de novo componente Timeline — nenhum existe ainda)
+     ```
+   - Incluir "Você decide" como opção quando razoável — captura discrição do Claude
+   - **Context7 para escolhas de biblioteca:** Quando uma área cinzenta envolve seleção de biblioteca (ex: "magic links" → consultar docs do next-auth) ou decisões de abordagem de API, usar ferramentas `mcp__context7__*` para buscar documentação atual e informar as opções. Não usar Context7 para cada pergunta — apenas quando conhecimento específico da biblioteca melhora as opções.
+
+   **Modo batch (`--batch`): Fazer 2-5 perguntas numeradas em um turno de texto simples**
+   - Agrupar perguntas intimamente relacionadas para a área atual em uma única mensagem
+   - Manter cada pergunta concreta e respondível em uma resposta
+   - Quando opções são úteis, incluir escolhas inline curtas por pergunta em vez de um AskUserQuestion separado para cada item
+   - Após a resposta do usuário, refletir de volta as decisões capturadas, notar itens não respondidos, e fazer apenas o mínimo de acompanhamento necessário antes de prosseguir
+   - Preservar adaptabilidade entre batches: usar o conjunto completo de respostas para decidir o próximo batch ou se a área está suficientemente clara
+
+3. **Após o conjunto atual de perguntas, verificar:**
+   - header: "[Área]" (máx 12 chars)
+   - question: "Mais perguntas sobre [área], ou mover para próxima? (Restantes: [listar outras áreas não visitadas])"
+   - options: "Mais perguntas" / "Próxima área"
+
+   Ao construir o texto da pergunta, listar as áreas não visitadas restantes para que o usuário saiba o que vem a seguir. Por exemplo: "Mais perguntas sobre Layout, ou mover para próxima? (Restantes: Comportamento de carregamento, Ordenação de conteúdo)"
+
+   Se "Mais perguntas" → fazer mais 4 perguntas únicas, ou mais um batch de 2-5 perguntas quando `--batch` estiver ativo, então verificar novamente
+   Se "Próxima área" → prosseguir para próxima área selecionada
+   Se "Outro" (texto livre) → interpretar intenção: frases de continuação ("mais", "continuar", "sim", "mais perguntas") mapeiam para "Mais perguntas"; frases de avanço ("feito", "continuar", "próximo", "pular") mapeiam para "Próxima área". Se ambíguo, perguntar: "Continuar com mais perguntas sobre [área], ou mover para a próxima área?"
+
+4. **Após todas as áreas inicialmente selecionadas concluírem:**
+   - Resumir o que foi capturado da discussão até agora
+   - AskUserQuestion:
+     - header: "Concluído"
+     - question: "Discutimos [listar áreas]. Quais áreas cinzentas permanecem pouco claras?"
+     - options: "Explorar mais áreas cinzentas" / "Estou pronto para o contexto"
+   - Se "Explorar mais áreas cinzentas":
+     - Identificar 2-4 áreas cinzentas adicionais com base no que foi aprendido
+     - Retornar à lógica de present_gray_areas com essas novas áreas
+     - Loop: discutir novas áreas, então solicitar novamente
+   - Se "Estou pronto para o contexto": Prosseguir para write_context
+
+**Acumulação de refs canônicas:** quando usuário referencia doc/spec/ADR (ex: "leia adr-014"), imediatamente: leia o doc, adicione ao acumulador com caminho relativo completo, use pra informar perguntas seguintes. Esses são frequentemente MAIS importantes que refs do ROADMAP — usuário quer que agentes downstream sigam. Nunca perca.
+
+**Design de perguntas:** opções concretas (não "Opção A"), cada resposta informa a próxima. Se usuário escolher "Outro" pra texto livre, faça acompanhamento em prompt simples (NÃO outro AskUserQuestion); reflita de volta e confirme.
+
+**Expansão de escopo:** ver `<scope_guardrail>` acima — anote como Ideia Adiada, retorne ao tópico.
+
+**Log interno por pergunta:** área, opções apresentadas, seleção do usuário, notas de acompanhamento. Usado pra gerar DISCUSSION-LOG.md no `write_context`.
+</step>
+
+<step name="write_context">
+Criar CONTEXT.md capturando as decisões tomadas.
+
+**Também gerar DISCUSSION-LOG.md** — uma trilha de auditoria completa do Q&A do discuss-phase.
+Este arquivo é apenas para referência humana (auditorias de software, revisões de conformidade). NÃO é
+consumido por agentes downstream (pesquisador, planejador, executor).
+
+**Encontrar ou criar diretório de fase:**
+
+Usar valores do init: `phase_dir`, `phase_slug`, `padded_phase`.
+
+Se `phase_dir` for null (fase existe no roadmap mas sem diretório):
+```bash
+mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"
+```
+
+**Localização do arquivo:** `${phase_dir}/${padded_phase}-CONTEXT.md`
+
+**Estruturar o conteúdo pelo que foi discutido:**
+
+```markdown
+# Fase [X]: [Nome] - Contexto
+
+**Coletado:** [data]
+**Status:** Pronto para planejamento
+
+<domain>
+## Limite da Fase
+
+[Declaração clara do que esta fase entrega — a âncora de escopo]
+
+</domain>
+
+<decisions>
+## Decisões de Implementação
+
+### [Categoria 1 que foi discutida]
+- **D-01:** [Decisão ou preferência capturada]
+- **D-02:** [Outra decisão se aplicável]
+
+### [Categoria 2 que foi discutida]
+- **D-03:** [Decisão ou preferência capturada]
+
+### Discrição do Claude
+[Áreas onde o usuário disse "você decide" — notar que Claude tem flexibilidade aqui]
+
+### Tarefas Incorporadas
+[Se alguma tarefa foi incorporada ao escopo do passo cross_reference_todos, listá-las aqui.
+Cada entrada deve incluir o título da tarefa, problema original e como se encaixa no escopo desta fase.
+Se nenhuma tarefa foi incorporada: omitir esta subseção inteiramente.]
+
+</decisions>
+
+<canonical_refs>
+## Referências Canônicas
+
+**Agentes downstream DEVEM ler estas antes de planejar ou implementar.**
+
+[Seção OBRIGATÓRIA. Escrever aqui a lista COMPLETA de refs canônicas acumuladas.
+Fontes: refs do ROADMAP.md + refs do REQUIREMENTS.md + docs referenciados pelo usuário durante
+a discussão + quaisquer docs descobertos durante a varredura da codebase. Agrupar por área de tópico.
+Cada entrada precisa de um caminho relativo completo — não apenas um nome.]
+
+### [Área de tópico 1]
+- `caminho/para/adr-ou-spec.md` — [O que decide/define que é relevante]
+- `caminho/para/doc.md` §N — [Referência de seção específica]
+
+### [Área de tópico 2]
+- `caminho/para/feature-doc.md` — [O que este doc define]
+
+[Se sem specs externas: "Sem specs externas — requisitos totalmente capturados nas decisões acima"]
+
+</canonical_refs>
+
+<code_context>
+## Insights de Código Existente
+
+### Ativos Reutilizáveis
+- [Componente/hook/utilitário]: [Como poderia ser usado nesta fase]
+
+### Padrões Estabelecidos
+- [Padrão]: [Como restringe/habilita esta fase]
+
+### Pontos de Integração
+- [Onde novo código se conecta ao sistema existente]
+
+</code_context>
+
+<specifics>
+## Ideias Específicas
+
+[Quaisquer referências particulares, exemplos, ou momentos "quero como X" da discussão]
+
+[Se nenhum: "Sem requisitos específicos — aberto a abordagens padrão"]
+
+</specifics>
+
+<deferred>
+## Ideias Adiadas
+
+[Ideias que surgiram mas pertencem a outras fases. Não as perder.]
+
+### Tarefas Revisadas (não incorporadas)
+[Se alguma tarefa foi revisada em cross_reference_todos mas não incorporada ao escopo,
+listá-las aqui para que fases futuras saibam que foram consideradas.
+Cada entrada: título da tarefa + motivo pelo qual foi adiada (fora do escopo, pertence à Fase Y, etc.)
+Se sem tarefas revisadas-mas-adiadas: omitir esta subseção inteiramente.]
+
+[Se nenhum: "Nenhum — discussão ficou dentro do escopo da fase"]
+
+</deferred>
+
+---
+
+*Fase: XX-nome*
+*Contexto coletado: [data]*
+```
+
+Escrever arquivo.
+</step>
+
+<step name="confirm_creation">
+Apresentar resumo e próximos passos:
+
+```
+Criado: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
+
+## Decisões Capturadas
+
+### [Categoria]
+- [Decisão-chave]
+
+### [Categoria]
+- [Decisão-chave]
+
+[Se ideias adiadas existirem:]
+## Anotado para Depois
+- [Ideia adiada] — fase futura
+
+---
+
+## ▶ Próximo Passo
+
+**Fase ${PHASE}: [Nome]** — [Objetivo do ROADMAP.md]
+
+`/planejar-fase ${PHASE} ${WS}`
+
+<sub>`/clear` primeiro → janela de contexto fresca</sub>
+
+---
+
+**Também disponível:**
+- `/planejar-fase ${PHASE} --skip-research ${WS}` — planejar sem pesquisa
+- `/fase-ui ${PHASE} ${WS}` — gerar contrato de design de UI antes do planejamento (se a fase tem trabalho de frontend)
+- Revisar/editar CONTEXT.md antes de continuar
+
+---
+```
+</step>
+
+<step name="git_commit">
+**Escrever DISCUSSION-LOG.md antes de commitar:**
+
+**Localização do arquivo:** `${phase_dir}/${padded_phase}-DISCUSSION-LOG.md`
+
+```markdown
+# Fase [X]: [Nome] - Log de Discussão
+
+> **Somente trilha de auditoria.** Não usar como entrada para agentes de planejamento, pesquisa ou execução.
+> Decisões são capturadas no CONTEXT.md — este log preserva as alternativas consideradas.
+
+**Data:** [data ISO]
+**Fase:** [número-fase]-[nome-fase]
+**Áreas discutidas:** [lista separada por vírgula]
+
+---
+
+[Para cada área cinzenta discutida:]
+
+## [Nome da Área]
+
+| Opção | Descrição | Selecionada |
+|-------|-----------|-------------|
+| [Opção 1] | [Descrição do AskUserQuestion] | |
+| [Opção 2] | [Descrição] | ✓ |
+| [Opção 3] | [Descrição] | |
+
+**Escolha do usuário:** [Opção selecionada ou resposta em texto livre]
+**Notas:** [Quaisquer esclarecimentos, contexto de acompanhamento, ou raciocínio fornecido pelo usuário]
+
+---
+
+[Repetir para cada área]
+
+## Discrição do Claude
+
+[Listar áreas onde o usuário disse "você decide" ou delegou ao Claude]
+
+## Ideias Adiadas
+
+[Ideias mencionadas durante a discussão que foram anotadas para fases futuras]
+```
+
+Escrever arquivo.
+
+Commitar contexto da fase e log de discussão:
+
+```bash
+node "./.claude/framework/bin/tools.cjs" commit "docs(${padded_phase}): capture phase context" --files "${phase_dir}/${padded_phase}-CONTEXT.md" "${phase_dir}/${padded_phase}-DISCUSSION-LOG.md"
+```
+
+Confirmar: "Commitado: docs(${padded_phase}): capturar contexto da fase"
+</step>
+
+<step name="update_state">
+Atualizar STATE.md com informações da sessão:
+
+```bash
+node "./.claude/framework/bin/tools.cjs" state record-session \
+  --stopped-at "Phase ${PHASE} context gathered" \
+  --resume-file "${phase_dir}/${padded_phase}-CONTEXT.md"
+```
+
+Commitar STATE.md:
+
+```bash
+node "./.claude/framework/bin/tools.cjs" commit "docs(state): record phase ${PHASE} context session" --files .planning/STATE.md
+```
+</step>
+
+<step name="auto_advance">
+**Detecção:** flag `--auto` em $ARGUMENTS, OR `workflow._auto_chain_active=true`, OR `workflow.auto_advance=true`.
+
+**Sync de cadeia:** se usuário invocou manualmente (sem `--auto`), zere `workflow._auto_chain_active` (mas NÃO toque `workflow.auto_advance` — preferência do usuário). Se `--auto` presente e cadeia não estava ativa, set `_auto_chain_active=true` (handle uso direto de `--auto` sem new-project).
+
+**Quando ativo:** dispare `Skill(skill="framework:planejar-fase", args="${PHASE} --auto ${WS}")` (use Skill, não Task aninhado — evita freeze de runtime, issue #686).
+
+**Roteamento de retorno do plan-phase:**
+- `FASE CONCLUÍDA` → cadeia completa. Próximo: `/discutir-fase ${NEXT_PHASE} --auto ${WS}` (após `/clear`)
+- `PLANEJAMENTO CONCLUÍDO` → execução parou. Continuar: `/executar-fase ${PHASE} ${WS}`
+- `PLANEJAMENTO INCONCLUSIVO / CHECKPOINT` → parou. Continuar: `/planejar-fase ${PHASE} ${WS}`
+- `LACUNAS ENCONTRADAS` → parou. Continuar: `/planejar-fase ${PHASE} --gaps ${WS}`
+
+**Quando inativo:** rotear pra `confirm_creation` (comportamento manual existente).
+</step>
+
+</process>
+
+<success_criteria>
+- Fase validada contra o roadmap
+- Contexto anterior carregado (PROJECT.md, REQUIREMENTS.md, STATE.md, arquivos CONTEXT.md anteriores)
+- Questões já decididas não re-perguntadas (carregadas de fases anteriores)
+- Codebase varrida por ativos reutilizáveis, padrões e pontos de integração
+- Áreas cinzentas identificadas por análise inteligente com anotações de código e decisão anterior
+- Usuário selecionou quais áreas discutir
+- Cada área selecionada explorada até satisfação do usuário (com opções informadas por código e por decisões anteriores)
+- Expansão de escopo redirecionada para ideias adiadas
+- CONTEXT.md captura decisões reais, não visão vaga
+- CONTEXT.md inclui seção canonical_refs com caminhos completos de arquivos para cada spec/ADR/doc que agentes downstream precisam (OBRIGATÓRIO — nunca omitir)
+- CONTEXT.md inclui seção code_context com ativos e padrões reutilizáveis
+- Ideias adiadas preservadas para fases futuras
+- STATE.md atualizado com informações da sessão
+- Usuário sabe os próximos passos
+</success_criteria>