ll-skills 1.0.0

package/hooks/ll-skills-check-update.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+'use strict';
+
+// Hook SessionStart do ll-skills. Instalado em <configDir>/hooks/ pelo bin/install.js.
+//
+// Modo leitor (sem argumentos, foreground, sem rede):
+//   lê o cache da execução anterior e, se houver versão mais nova registrada para a
+//   versão instalada agora, emite um systemMessage curto. Depois dispara o modo worker
+//   em background e sai.
+//
+// Modo worker (--worker, background, com rede):
+//   consulta a versão publicada (`npm view ll-skills version`); se o pacote ainda não
+//   está no registro e a instalação veio de `npx github:`, cai para `git ls-remote` e
+//   compara o SHA. Regrava o cache.
+//
+// Regra de ouro: nunca atrasar o início da sessão, nada em stderr, nada fora do
+// próprio cache. Qualquer falha termina em silêncio com exit 0.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn, execFileSync } = require('child_process');
+
+const PKG_NAME = 'll-skills';
+const REPO_URL = 'https://github.com/allangdy/ll-skills.git';
+const CONFIG_DIR = path.dirname(__dirname); // <configDir>/hooks/<este arquivo>
+const STATE_DIR = path.join(CONFIG_DIR, 'll-skills');
+const CACHE_DIR = path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'll-skills');
+const CACHE_FILE = path.join(CACHE_DIR, 'update-check.json');
+const CHECK_INTERVAL = 6 * 60 * 60; // segundos entre consultas de rede
+const NET_TIMEOUT = 10000;
+
+function readText(file) {
+  try {
+    return fs.readFileSync(file, 'utf8').trim();
+  } catch {
+    return null;
+  }
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function parseSemver(v) {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(String(v || ''));
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+function semverNewer(candidate, current) {
+  const a = parseSemver(candidate);
+  const b = parseSemver(current);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] > b[i]) return true;
+    if (a[i] < b[i]) return false;
+  }
+  return false;
+}
+
+function writeCache(obj) {
+  fs.mkdirSync(CACHE_DIR, { recursive: true });
+  const tmp = `${CACHE_FILE}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(obj) + '\n');
+  fs.renameSync(tmp, CACHE_FILE);
+}
+
+function npmLatest() {
+  try {
+    const out = execFileSync('npm', ['view', PKG_NAME, 'version'], {
+      timeout: NET_TIMEOUT,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf8',
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0', npm_config_update_notifier: 'false' },
+    }).trim();
+    return parseSemver(out) ? out : null;
+  } catch {
+    return null;
+  }
+}
+
+function gitRemoteSha() {
+  try {
+    const out = execFileSync('git', ['ls-remote', REPO_URL, 'HEAD'], {
+      timeout: NET_TIMEOUT,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf8',
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    });
+    const sha = out.split(/\s/)[0];
+    return /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+  } catch {
+    return null;
+  }
+}
+
+function worker(installed) {
+  const now = Math.floor(Date.now() / 1000);
+  const cache = { checked: now, installed, latest: null, update_available: false, method: null };
+
+  const latest = npmLatest();
+  if (latest) {
+    cache.latest = latest;
+    cache.method = 'npm';
+    cache.update_available = semverNewer(latest, installed);
+    writeCache(cache);
+    return;
+  }
+
+  // Pacote ainda não publicado: só há referência remota confiável se a instalação veio do GitHub.
+  const info = readJson(path.join(STATE_DIR, 'install.json'));
+  if (info && info.source === 'github' && info.sha) {
+    const remote = gitRemoteSha();
+    if (remote) {
+      cache.method = 'git';
+      cache.latest = remote.slice(0, 7);
+      cache.update_available = !remote.startsWith(info.sha);
+    }
+  }
+  writeCache(cache);
+}
+
+function reader(installed) {
+  const cache = readJson(CACHE_FILE);
+  if (cache && cache.update_available && cache.installed === installed && cache.latest) {
+    process.stdout.write(
+      JSON.stringify({
+        systemMessage: `ll-skills desatualizado (instalado ${installed}, disponível ${cache.latest}) — rode /ll-atualizar`,
+      }) + '\n'
+    );
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  const checked = cache && Number.isFinite(cache.checked) ? cache.checked : 0;
+  if (now - checked >= CHECK_INTERVAL) {
+    const child = spawn(process.execPath, [__filename, '--worker'], { detached: true, stdio: 'ignore' });
+    child.unref();
+  }
+}
+
+function main() {
+  const installed = readText(path.join(STATE_DIR, 'VERSION'));
+  if (!installed) return;
+  if (process.argv[2] === '--worker') worker(installed);
+  else reader(installed);
+}
+
+try {
+  main();
+} catch {
+  /* silêncio */
+}
+process.exit(0);

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "ll-skills",
+  "version": "1.0.0",
+  "description": "Pipeline de desenvolvimento orientado a evidência para Claude Code: pesquisa de mercado, premortem, POCs desarmadoras, spec por entrevista e verificação de entrega",
+  "bin": {
+    "ll-skills": "bin/install.js"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "agents",
+    "hooks",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "bash scripts/smoke-test.sh"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "commonjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/allangdy/ll-skills.git"
+  },
+  "homepage": "https://github.com/allangdy/ll-skills#readme",
+  "bugs": {
+    "url": "https://github.com/allangdy/ll-skills/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "skills",
+    "agents"
+  ],
+  "author": "allangdy",
+  "license": "MIT"
+}

package/skills/ll-atualizar/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: ll-atualizar
+description: Atualiza o ll-skills para a última versão publicada, mostrando o changelog do que mudou antes de aplicar. Use quando o pedido for "atualizar o ll-skills", "atualiza as skills", "ll-skills desatualizado", "tem versão nova do ll-skills?" ou quando o aviso de sessão disser que o ll-skills está desatualizado.
+---
+
+# Atualizar o ll-skills
+
+O ll-skills é distribuído como pacote npm e instalado por `npx ll-skills@latest`, que copia
+as skills `ll-*` para `~/.claude/skills/` e grava a versão instalada. Este fluxo compara a
+versão instalada com a publicada, mostra o que mudou entre elas e aplica a atualização
+rodando o instalador de novo.
+
+Toda mutação acontece pelo instalador. Nada em `~/.claude/skills/ll-*`, `~/.claude/ll-skills/`
+ou `~/.claude/settings.json` é editado à mão.
+
+## 1. Versão instalada
+
+```bash
+cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/ll-skills/VERSION"
+```
+
+Se o arquivo não existir, o ll-skills não está instalado por este mecanismo. Diga isso,
+indique `npx ll-skills@latest` e pare.
+
+## 2. Versão publicada
+
+```bash
+npm view ll-skills version
+```
+
+Sem rede, ou se o npm devolver `E404` (pacote ainda não publicado): diga que não deu para
+consultar o registro e pare — não adivinhe.
+
+**Se as versões coincidirem**: diga que o ll-skills já está na última versão, cite a
+versão, e encerre. Nada mais a fazer.
+
+## 3. Changelog
+
+```bash
+curl -sf https://raw.githubusercontent.com/allangdy/ll-skills/main/CHANGELOG.md
+```
+
+O arquivo segue Keep a Changelog: uma seção `## [x.y.z] - data` por versão, da mais nova
+para a mais antiga. Mostre apenas as seções com versão maior que a instalada e menor ou
+igual à publicada, do mais antigo ao mais recente. Se a chamada falhar, siga para a
+atualização avisando que o changelog não pôde ser carregado.
+
+## 4. Aplicar
+
+```bash
+npx --yes ll-skills@latest
+```
+
+O instalador sobrescreve as skills, poda arquivos órfãos da versão anterior, atualiza o
+hook de aviso e regrava `VERSION`. Se falhar, mostre a saída de erro e pare — não tente
+contornar copiando arquivos à mão.
+
+## 5. Confirmar e encerrar
+
+Releia `VERSION` e confirme que agora bate com a versão publicada. Reporte:
+
+- versão antiga → versão nova
+- resumo do changelog aplicado
+- que a sessão atual ainda carrega as skills antigas: skills novas ou renomeadas só
+  aparecem depois de reiniciar o Claude Code (conteúdo alterado de uma skill que já
+  existia é lido na próxima invocação)
+
+Se `VERSION` não mudou, diga isso claramente em vez de declarar sucesso.

package/skills/ll-decidir-antes/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: ll-decidir-antes
+description: Prepara uma implementação longa (horas ou dias de agente autônomo) decidindo tudo o que importa antes do código — levanta evidência com subagentes, entrevista o usuário via AskUserQuestion sobre as decisões irreversíveis em ordem de impacto, e consolida SPEC.md + PROGRESS.md com protocolo anti-drift embutido, prontos para handoff. Use quando o pedido for criar uma spec antes de implementar, fazer perguntas antes de começar, preparar uma tarefa longa para um agente, conduzir uma entrevista de decisões ou montar um handoff para implementação autônoma.
+---
+
+# decidir-antes
+
+Dado "quero implementar X", esta skill conduz: (1) levantamento de evidência, (2) construção da fila de decisões, (3) entrevista via AskUserQuestion, (4) escrita de `SPEC.md` + `PROGRESS.md`, (5) handoff. Ela NÃO implementa nada — o entregável é a spec que sustenta um implementador autônomo por horas ou dias sem drift, e a instrução de partida que o dispara.
+
+Artefatos, por padrão em `docs/spec-<slug>/`:
+
+| Arquivo | Papel | Mutabilidade |
+|---|---|---|
+| `mapas/*.md` | evidência condensada dos subagentes | escritos uma vez |
+| `FILA.md` | inventário de decisões + fila da entrevista | vivo durante a entrevista |
+| `SPEC.md` | contrato de implementação, ordenado por precedência | append-only após aprovação |
+| `PROGRESS.md` | estado do implementador | mutável, do implementador |
+| `decisoes/` | ambiguidades da execução aguardando o humano | criadas pelo implementador |
+
+Na primeira interação, confirme com o usuário em uma única troca: o corte de escopo do trabalho (o que está dentro e fora) e o local dos artefatos. Depois disso, os pontos de contato com o humano são as perguntas da entrevista e o handoff — nada entre eles.
+
+## Fase 1 — Evidência
+
+Nenhuma pergunta sem lastro. Antes de formular qualquer decisão:
+
+- **Os artefatos das etapas anteriores vêm primeiro**, antes de mapear qualquer coisa nova. Procure no repo e leia direto, sem subagente — já são evidência condensada e citável: `docs/README.md` (o índice do dossiê, com o **Estado da decisão** no topo) e `docs/decisoes-em-aberto.md` da pesquisa de mercado; `docs/premortem/premortem.md` e `docs/premortem/placar.md`; SPECs anteriores e suas decisões `DEC-NNN`. Eles se citam pelo caminho e pela seção, como os mapas se citam por `arquivo:linha`. Nada disso existir é normal — a skill roda sozinha; o que não pode é existir e ser remapeado do zero.
+- Delegue o mapeamento a subagentes — um por material (código atual, protótipo/design, documentos do pedido). A sessão principal lê apenas os mapas condensados que eles produzem, nunca os fontes inteiros: sessões que abrem tudo morrem por estouro de contexto antes de decidir qualquer coisa. Fontes abertos na sessão principal só sob demanda, no trecho exato que uma pergunta exigir.
+- Cada mapa registra fatos com `arquivo:linha` — é essa citação que as perguntas vão carregar.
+- O lastro tem dois tipos: **interno** (os mapas do projeto) e **externo** — decisões que dependem de conhecimento de fora do projeto (escolha de tecnologia ou biblioteca, padrão de mercado, limites e preços de API) exigem pesquisa web por subagente antes da pergunta. Recomendação de memória ou opinião não sustenta pergunta.
+- Leia `referencias/protocolo-entrevista.md` agora: ele traz o brief-modelo dos mapeadores e pesquisadores, o formato dos itens da fila e o protocolo de pergunta das fases 2 e 3.
+
+## Fase 2 — Fila de decisões
+
+Construa `FILA.md`: um item por coisa decidível pelo usuário (não por detalhe), com evidência dos dois lados, camada/impacto, dependências e status `PENDENTE`. Divergências entre o que existe e o que foi pedido entram nas duas direções — adição e subtração são ambas decisões do dono, nunca descarte silencioso.
+
+Antes de classificar, aplique a herança dos artefatos anteriores:
+
+- Decisão **já tomada** neles **não vira pergunta**: entra na spec como contrato herdado, com a fonte citada (`docs/README.md` §Estado da decisão, `docs/premortem/placar.md`, `DEC-014` da spec anterior). Não re-litigar atravessa as skills, não só a entrevista — re-perguntar o que o dono já fechou queima a confiança na fila inteira. Só volta a ser pergunta se a evidência nova a contradiz, e aí a pergunta é essa: a contradição, com os dois registros lado a lado.
+- Falha **CONFIRMADA** no placar do premortem entra como **restrição de desenho**, não como risco a discutir: as opções que a ignoram não são oferecidas, e a rota de saída quantificada no placar vira o custo declarado das que sobram.
+- **Pendência com dono** nesses artefatos vira item da fila apenas se o dono for o usuário; dono implementador ou agente vira pendência da spec, com o marco em que fecha.
+
+Classificação de cada item — o coração da skill:
+
+- **Vira PERGUNTA** (one-way door) se qualquer um valer: mudar depois exige reescrever mais de um módulo; a resposta condiciona ou redesenha outras decisões da fila; é preferência do usuário que nenhuma evidência revela.
+- **Vira ASSUNÇÃO** (two-way door) caso contrário: decida você, com o default mais barato de reverter, e registre com porquê. Assunções entram na spec marcadas — são o único tipo de decisão que o implementador pode escalar por evidência contrária.
+
+Ordene a fila: primeiro a pergunta que re-precifica todas as outras (sequenciamento, big-bang vs incremental, corte de escopo); depois por impacto estrutural descendente; dentro do nível, o que desbloqueia ou poda mais itens.
+
+Marque em cada PERGUNTA o lastro: `interno` (os mapas bastam) ou `externo` (exige pesquisa web). As externas disparam subagentes de pesquisa em background já nesta fase — a entrevista segue com as internas e nunca bloqueia esperando pesquisa; cada pergunta externa entra na fila quando o comparativo dela chegar.
+
+## Fase 3 — Entrevista
+
+Siga o protocolo de `referencias/protocolo-entrevista.md`. O núcleo inviolável:
+
+- AskUserQuestion, cabeçalho "PERGUNTA N/M". Impacto ALTO: uma decisão por chamada. Impacto baixo: até 4 por chamada, sempre uma decisão por pergunta.
+- Toda pergunta carrega a evidência dos dois lados (com `arquivo:linha`), sua análise honesta com posição própria, e opções com custo/consequência; a recomendada vem primeiro com "(Recomendada)" no label — ela informa, o usuário decide.
+- Registre a resposta em `FILA.md` imediatamente (literal, com data) e re-avalie a fila após CADA resposta: respostas desdobram itens novos, decidem outros "por regra" e podam perguntas sem objeto. Commit por bloco quando em repo git.
+- Sem resposta = `PENDENTE`. Você não decide nenhuma one-way door sozinho — nem as "óbvias". Decisão contra a sua recomendação: registro fiel com as consequências, sem re-litigar.
+- 3 a 5 decisões ALTO por sessão de perguntas; ao atingir o limite, ofereça pausa. A fila vive no arquivo, não na conversa: qualquer sessão retoma do próximo `PENDENTE` sem re-derivar nada.
+
+A entrevista termina quando a fila zera os `PENDENTE` — por resposta, por regra ou por delegação explícita do usuário ("você decide" vira assunção registrada).
+
+## Fase 4 — SPEC.md + PROGRESS.md
+
+Leia `referencias/template-spec.md` e escreva os dois arquivos a partir dele. Regras que nascem nesta fase:
+
+- Critério de aceite sem comando de verificação executável não entra como critério — entra como pendência com dono nomeado e marco. Requisito sem verificação é requisito que vaza.
+- Decisão que cita um entregável nomeia o entregável (arquivo, rota, migração, tela); pendência tem dono e marco. Referência vaga hoje é re-pergunta garantida na semana 2 da execução.
+- A spec é curta e densa: detalhe fino fica nos mapas e entra por referência de caminho. O protocolo de execução (seção 7) vai completo no SPEC.md — o implementador não conhece esta skill; a spec é tudo o que ele tem.
+
+## Fase 5 — Handoff
+
+Apresente ao usuário: contagem de decisões (perguntadas / assumidas / herdadas / contra a recomendação), riscos aceitos conscientemente, pendências com dono, e a instrução de partida do implementador:
+
+<instrucao-de-partida>
+Implemente <caminho>/SPEC.md até o fim.
+
+Leia a spec inteira antes de qualquer código. Ela é autossuficiente e as decisões da seção 3 são contrato — nada é re-decidido. A seção 7 é o seu protocolo de operação e prevalece sobre instruções genéricas de sessão. Estado vive em PROGRESS.md e no git, não na conversa. Trabalhe um marco por vez até todos estarem `passes: true` com os comandos de verificação passando. Antes de delegar trabalho a subagentes, invoque a skill `ll-orquestrar` (ll-skills) pela ferramenta Skill — ela rege decomposição, briefs, roteamento de modelos e verificação. Se ela não existir no seu ambiente: delegue apenas subtarefas grandes e genuinamente independentes, com brief autossuficiente (objetivo, contrato de saída, limites), e verifique resultados com evidência. Suas liberdades estão na seção 5b; use seu melhor julgamento dentro delas. Tudo fora delas: escale conforme a seção 7. Ao final, a entrega é auditada pela skill `ll-verificar-entrega` — o VERIFICACAO.md dela, não o seu relato, é o que fecha o trabalho.
+</instrucao-de-partida>
+
+Rota preferida: dispare o agente **`ll-implementador`** do ll-skills (ele parte com a `ll-orquestrar` pré-carregada) com a instrução acima. Qualquer sessão ou agente com a instrução também serve — a spec é autossuficiente. Você entrega a spec e para aqui; quando o implementador declarar pronto, o caminho é `ll-verificar-entrega`.

package/skills/ll-decidir-antes/referencias/protocolo-entrevista.md

@@ -0,0 +1,112 @@
+# Protocolo — evidência, fila e entrevista
+
+Leitor: o agente que conduz a skill `ll-decidir-antes`, nas fases 1 a 3. O objetivo final destas fases é que nenhuma one-way door chegue à spec sem resposta do usuário, e nenhuma two-way door vire pergunta.
+
+## 1. Brief-modelo do subagente mapeador
+
+Um subagente por material. Subagentes não veem esta conversa: o brief carrega tudo. Adapte:
+
+<brief-mapeador>
+Você mapeia <material> para uma entrevista de decisões que precede uma implementação longa. Cada afirmação sua pode virar a evidência de um lado de uma decisão apresentada ao dono do projeto — precisão de citação importa mais que prosa.
+
+Contexto: o pedido é "<pedido do usuário, resumido>". O mapa alimenta a construção de um inventário de decisões; outro agente fará as perguntas.
+
+Material: <caminhos exatos; nada além deles>.
+
+Instruções: percorra o material inteiro. Para cada capacidade, comportamento, contrato ou estrutura relevante ao pedido, registre o fato com `arquivo:linha` (ou tela/rota, para protótipos). Cubra tudo o que encontrar e rotule cada achado com confiança (alta/média/baixa) — a filtragem é do orquestrador, não sua.
+
+Contrato de saída: escreva `<raiz>/mapas/<nome>.md` com seções por área do sistema; fatos em bullets no formato `arquivo:linha — fato`; seção final "Lacunas e incertezas" com o que você não conseguiu confirmar. Responda ao orquestrador só com o caminho do mapa e 3 linhas de sumário.
+
+Limites: não proponha decisões nem soluções; o mapa cabe em ~200 linhas — condense, não transcreva.
+
+Sucesso: o orquestrador consegue citar seu mapa numa pergunta ao dono sem reabrir o fonte.
+</brief-mapeador>
+
+Quando o material é visual (protótipo, site), o mapeador navega e captura telas por conta própria e as descreve no mapa — screenshots ficam com ele, nunca voltam à sessão principal.
+
+## 2. FILA.md — esqueleto
+
+<esqueleto-fila>
+# Fila de decisões — <pedido> (<data>)
+
+## Estado
+- Fase: <1 evidência | 2 fila | 3 entrevista | 4 spec> — <última ação> / <próximo passo concreto>
+- Entrevista: <d> DECIDIDAS · <a> ASSUMIDAS · <p> PENDENTES · próxima: Q-NNN
+- Notas de retomada: <o que uma sessão nova precisa saber para continuar>
+
+## Sumário executivo
+<escrito no fechamento da entrevista — ver §6>
+
+## Ordem da entrevista
+Q-003 (kickoff) → Q-001 → Q-007 → ...
+
+## Itens
+### Q-001 — <título decidível, não descritivo>
+- **Classe:** PERGUNTA | ASSUNÇÃO · **Camada:** dominio|contrato|arquitetura|ui · **Impacto:** ALTO|MÉDIO|BAIXO
+- **Lastro:** interno | externo — pesquisa: <em andamento | `mapas/pesquisa-<tema>.md`>
+- **Lado A (pedido/protótipo):** <evidência com arquivo:linha ou tela>
+- **Lado B (sistema atual):** <evidência com arquivo:linha, ou "inexistente">
+- **Depende de:** Q-x · **Condiciona:** Q-y, Q-z
+- **Status:** PENDENTE
+  → DECIDIDA — <resposta literal do usuário> (<data>) [contra a recomendação — registro fiel; NÃO re-litigar] [risco aceito: <qual>]
+  → ASSUMIDA — <default> porque <porquê em 1 linha>
+  → DECIDIDA POR REGRA — segue Q-x (<data>)
+  → HERDADA — <decisão fechada em etapa anterior> (fonte: <artefato §seção>) — contrato, não pergunta
+</esqueleto-fila>
+
+O bloco Estado é atualizado a cada checkpoint. O git é o registro durável, não a conversa: commit por bloco de respostas (`docs(spec): fila — decisões Q-x..Q-y (bloco N)`).
+
+## 3. Classificação e ordenação
+
+O teste de classe está no SKILL.md (fase 2). Refinamentos:
+
+- Em dúvida entre PERGUNTA e ASSUNÇÃO, olhe o fan-out: item que condiciona 3+ outros é pergunta mesmo que pareça reversível — a resposta redesenha a fila.
+- A pergunta de kickoff vem antes de tudo quando existir: sequenciamento (big-bang vs incremental), corte de escopo (mínimo vs completo). Ela muda o PREÇO de todas as opções seguintes — as descrições de custo das perguntas posteriores citam a resposta dela.
+- Ordem dentro da fila: domínio/identidade/schema → contratos (API, permissões, vocabulário transversal) → navegação/estados globais → item local por tela ou módulo. Dentro de cada nível, primeiro o que desbloqueia ou poda mais itens (use Depende/Condiciona).
+Lastro externo — decisões que dependem de conhecimento de fora do projeto (qual framework, qual biblioteca, padrão de mercado, limites e preços de API):
+
+- Ao classificar o item, marque `Lastro: externo` e dispare imediatamente um subagente de pesquisa web em background (um por tema; para comparativos disputados, um por opção e um consolidador). A entrevista segue com os itens internos — nunca trava esperando pesquisa, e a pergunta externa entra na fila quando o comparativo chegar.
+- A pergunta externa só é feita quando a recomendação puder ser sustentada: cada opção com seus trade-offs reais e fontes, e a "(Recomendada)" com justificativa rastreável ao arquivo de pesquisa — nunca de memória ou opinião.
+
+<brief-pesquisador>
+Você pesquisa <tema> para sustentar uma decisão que será apresentada ao dono do projeto. Contexto: <pedido + restrições relevantes do projeto, ex.: stack atual, orçamento>. Instruções: levante as opções viáveis (<lista, se já conhecida>) com trade-offs reais — maturidade, limites, preço, encaixe com <restrição> — cobrindo prós e contras de todas e rotulando cada afirmação com a fonte (URL) e confiança. Contrato de saída: escreva `<raiz>/mapas/pesquisa-<tema>.md` com uma seção por opção, tabela comparativa final com pontuação justificada, e sua recomendação com porquê. Limites: sem decisão final — quem decide é o dono; ~150 linhas. Sucesso: o orquestrador monta a pergunta e as descrições de custo citando só o seu arquivo.
+</brief-pesquisador>
+
+## 4. Anatomia da chamada AskUserQuestion
+
+Texto da pergunta — autossuficiente; o usuário decide lendo só a pergunta:
+
+1. Cabeçalho: `PERGUNTA N/M — <título> (impacto ALTO|MÉDIO|BAIXO)`. M é o total corrente da fila; quando desdobramentos criarem itens, M cresce — anuncie ("éramos 14, a resposta de Q-005 criou 2 itens: agora 16").
+2. O que está em jogo, em 1–3 frases.
+3. Evidência dos dois lados, citada do item (`arquivo:linha`, tela do protótipo).
+4. Contexto novo de decisões anteriores da própria bateria, quando condicionarem esta ("com Q-003 = big-bang, migrações saem sem backfill — isso barateia a opção 1").
+5. "Minha análise honesta: ..." — sua posição própria e o porquê, antes das opções.
+
+Opções — 2 a 4, mutuamente exclusivas:
+
+- A recomendada vem PRIMEIRA, com "(Recomendada)" no label. Label ≤ ~5 palavras; a description diz a consequência e o custo concretos ("migração dos grants + deploy ordenado — barato sob big-bang"), nunca só o nome da alternativa.
+- Menu canônico quando a decisão compara algo novo com o existente: Adotar / Adaptar: \<como\> / Manter o atual / Cortar do escopo.
+- Opção de escape quando fizer sentido: "Tanto faz — decida na implementação" (vira ASSUMIDA com as alternativas registradas); em ação destrutiva ou externa: "Não — eu mesmo executo".
+- `multiSelect` só para inventário de fatos independentes e combináveis (quais claims são reais, quais integrações entram) — nunca para alternativas excludentes.
+
+Lotes: impacto ALTO = 1 pergunta por chamada, sempre — você nunca agrupa itens ALTO por conta própria (o usuário pode responder em lote se quiser). Impacto baixo (ui-local, config) = até 4 perguntas por chamada, cada uma com uma única decisão. Fundir duas decisões numa pergunta destrói a rastreabilidade da resposta.
+
+Fadiga: 3–5 decisões ALTO por sessão de perguntas; no limite, ofereça pausa com o Estado da fila atualizado — a retomada é barata porque a fila vive no arquivo.
+
+## 5. Depois de cada resposta
+
+1. **Registre imediatamente** no item: resposta literal, data. Contra a recomendação: marque "contra a recomendação — registro fiel; NÃO re-litigar" e anote as consequências que você apresentou. Risco aceito conscientemente: marque no item e liste no sumário.
+2. **Nomeie o que a resposta cita.** Se a decisão referencia um entregável ("o CTA", "a tela de billing", "a coluna nova"), o registro nomeia arquivo/rota/migração/tela. Referência que ainda não existe e não tem nome: pergunte qual/onde na sequência, antes de registrar — decisão com referência órfã é re-pergunta garantida na execução.
+3. **Pendência descoberta** (algo a fazer que não é decisão): registre com dono proposto (humano ou implementador) e marco em que fecha. Pendência sem dono não existe — ela some.
+4. **Re-avalie a fila**: remova perguntas que ficaram sem objeto; decida itens "por regra" de resposta anterior (registre `DECIDIDA POR REGRA — segue Q-x`); desdobramentos viram itens novos — inclusive "nascidos DECIDIDOS" quando a resposta livre já os fecha.
+5. **Commit por bloco** (3–6 respostas ou fechamento de nível).
+
+Casos especiais:
+
+- **Resposta livre ("Other") é redesenho de primeira classe**: registre verbatim e trate como redirecionamento — pode criar itens, matar itens, ou redirecionar o processo (pedido de pesquisa, de opinião sem viés). Pedido de arbitragem sem viés (copy, naming): subagentes juízes cegos, um por alternativa, sem saber a autoria; re-apresente a MESMA pergunta numerada com o veredito ("PERGUNTA 6/16 (retomada)").
+- **"Não entendi"** ou contra-pergunta: reformule e re-pergunte com contexto melhor — a falha foi da pergunta, não do usuário. Nunca siga com uma resposta que você intuiu.
+- **Delegação** ("você decide"): vira ASSUMIDA com default e porquê — entra na spec como assunção, escalável por evidência contrária.
+
+## 6. Fechamento da entrevista
+
+Com zero `PENDENTE`, escreva o Sumário executivo no topo da FILA.md: contagens (por classe, camada, impacto), decisões herdadas de etapas anteriores com a fonte de cada uma, decisões contra a recomendação, respostas livres registradas verbatim, riscos aceitos conscientemente, pendências com dono, e a linha "Consumo: este arquivo alimenta SPEC.md; em conflito, SPEC.md prevalece". Commit de fechamento. Siga para a fase 4 do SKILL.md.