ask-navigator

Ask Navigator

O Ask-navigator é o navegador do shipyard: ele pega um esforço envolto em névoa — o caminho daqui até o destino ainda não é visível — e o traça como um mapa de tickets de decisão no rastreador de issues do repositório, depois trabalha a fronteira um ticket por sessão até que a rota esteja clara. Ele produz decisões, nunca entregáveis: quando o caminho está claro, ele faz a transição, não constrói. A entrega pertence ao /oh-my-claudecode:launch.

O contrato de função. O capitão (o humano) assina o destino (W1) e o mapa (W2); o navegador redige todo o resto e nunca responde a uma pergunta que pertence ao capitão — uma sessão de interrogatório na qual o agente responde às suas próprias perguntas quebrou a função, não apenas o processo. Fatos são trabalho do navegador; decisões são do capitão.

Teste de névoa. Um esforço tem névoa quando qualquer resposta for 'não':

1. P1 — O destino pode ser declarado em uma frase: a especificação, decisão ou mudança para a qual este esforço está encontrando o caminho?
2. P2 — As três primeiras decisões podem ser declaradas com precisão agora, mesmo que nenhuma delas possa ser respondida ainda?

Ambos 'sim' → nenhum mapa é necessário; execute /oh-my-claudecode:launch (seu portão de névoa envia esforços para cá apenas quando uma resposta é 'não'). Qualquer 'não' → trace primeiro. O ask-navigator também pode ser acessado diretamente: invoque-o com uma ideia vaga, com perguntas residuais deixadas pelo portão de névoa do launch, ou sem argumento para continuar o mapa aberto.

Lar do mapa

O mapa é uma única issue rotulada navigator:map no rastreador de issues do repositório; seus tickets de decisão são issues filhas do mapa. O rastreador deve ter sido registrado pelo /oh-my-claudecode:drydock; se nenhum foi registrado, pergunte uma vez (GitHub / GitLab / markdown local) e lembre a resposta dentro das Notas do mapa.

• Com suporte de rastreador (GitHub, GitLab ou rastreador registrado): uma issue de mapa, issues filhas por ticket, relacionamentos nativos de bloqueio/sub-issue. Sessões concorrentes e a interface do próprio rastreador renderizam a fronteira — o mapa vive onde os humanos já olham. Crie o rótulo navigator:map se o rastreador ainda não o tiver; os tipos de ticket ficam no corpo do ticket, não em rótulos.
• Fallback para markdown local: .omc/wayfinder/<slug-do-mapa>/map.md mais decisions/NN-<slug>.md, um arquivo por ticket, numerados em ordem de dependência. O modo local não tem garantia de reivindicação concorrente: é de motorista único por convenção, declarado uma vez nas Notas do mapa.

O mapa é um índice, não um armazenamento: uma decisão vive em exatamente um lugar — seu ticket. O mapa resume cada resolução em uma linha e um link; nunca reafirma o detalhe.

Idioma do documento

O texto do mapa e dos tickets segue o mesmo contrato de idioma do documento que /oh-my-claudecode:drydock: leia documentLanguage do frontmatter do CONTEXT.md quando presente; se o estaleiro não estiver estabelecido, pergunte sobre o idioma uma vez durante o traçado (W2) e registre a tag resolvida nas Notas do mapa para que a execução posterior do launch a herde. Caminhos, rótulos, comandos de barra, o rótulo navigator:map, nomes de tipos de ticket (research, loft, grilling, task), HITL/AFK e blockedBy são tokens estáveis e permanecem byte por byte estáveis em todos os idiomas.

Traçar o mapa

Invocado com uma ideia vaga (ou perguntas residuais do launch). Traçar é trabalho de uma sessão; não resolve nada manualmente.

1. Execute a auditoria, adie as conclusões. Execute a auditoria /oh-my-claudecode:drydock --check no modo somente relatório: as conclusões nunca bloqueiam o traçado (um mapa produz decisões, não aterrissagens em slots), mas são registradas textualmente nas Notas do mapa — o portão do estaleiro do launch cobrará essa dívida quando o esforço finalmente entrar em entrega. Se o estaleiro não estiver estabelecido (sem CONTEXT.md, sem docs/adr/), ofereça /oh-my-claudecode:drydock uma vez; se o capitão recusar, prossiga no modo somente rastreador e adie todo sedimento (veja Sedimento).
2. W1 — nomeie o destino. Chame a ferramenta Skill com "deep-interview" e defina para o que este mapa está encontrando o caminho: a especificação, decisão ou mudança. O destino fixa o escopo, portanto é resolvido primeiro. W1 é uma assinatura do capitão: apresente a declaração de destino e obtenha confirmação explícita. Se o capitão não puder declarar um destino mesmo com a ajuda da entrevista, isso não é um erro — apresente os melhores candidatos classificados e deixe o capitão escolher um para traçar ou estacionar o esforço.
3. Mapeie a fronteira. Entreviste novamente com "deep-interview", em largura: espalhe-se por todo o espaço em vez de aprofundar em qualquer tópico, revelando as decisões em aberto e os primeiros passos que podem ser dados agora. Se isso não revelar névoa — o caminho para o destino já está claro e a jornada cabe em uma sessão — nenhum mapa é necessário: pare e recomende /oh-my-claudecode:launch.
4. W2 — assine o mapa. Apresente o mapa proposto: destino, tickets iniciais com tipos e arestas de bloqueio, e o esboço da névoa. W2 é uma assinatura do capitão: granularidade errada aqui desperdiça todas as sessões posteriores. Itere até ser assinado.
5. Crie o mapa e os tickets. Rotule o mapa como navigator:map; crie tickets filhos; conecte arestas de bloqueio em uma segunda passagem (as issues precisam de IDs antes de poderem referenciar umas às outras). Tudo que ainda não for nítido o suficiente para virar ticket permanece em Ainda não especificado.
6. Dispare os subagentes de pesquisa. Para cada ticket research recém-criado, gere um subagente em segundo plano para resolvê-lo em paralelo (veja Tipos de ticket), capturando descobertas onde o ticket puder vinculá-las.
7. Pare com o ponteiro de fechamento da sessão: o link do mapa, quantos tickets estão na fronteira, e "na próxima sessão, execute /oh-my-claudecode:ask-navigator para trabalhar a próxima decisão."

Trabalhar o mapa

Invocado com um mapa (link ou número) ou sem argumento (retomar o mapa aberto). Um ticket é opcional: sem um, pegue o próximo ticket da fronteira, não um que o capitão precise escolher.

1. Carregue o mapa: a visão de baixa resolução, nunca o corpo de cada ticket. Amplie para o corpo completo de um ticket sob demanda.
2. Reivindique antes de trabalhar: atribua o ticket ao capitão (rastreador) ou defina Claimed-by (local) primeiro, para que sessões concorrentes o ignorem. Um ticket aberto e não reivindicado não está reivindicado. Se a atribuição não for possível (permissões, sem identificador), registre a reivindicação em um comentário do ticket.
3. Resolva-o de acordo com seu tipo (veja Tipos de ticket). Amplie conforme necessário; chame a ferramenta Skill com "deep-interview" sempre que a resolução precisar da contribuição do capitão.
4. Registre a resolução: publique a resposta como um comentário/seção de resolução, feche o ticket (como concluído; um ticket considerado além do destino fecha como não planejado) e acrescente uma linha às Decisões até agora do mapa — [<título do ticket>](link): <resumo de uma linha>.
5. Avançar a fronteira: promova qualquer névoa que a resposta tornou especificável (remova-a de Ainda não especificado, crie os novos tickets, conecte arestas); se a resposta revelar que um ticket está além do destino, feche-o e deixe uma linha em Fora do escopo; atualize ou exclua tickets que a decisão invalidou.
6. Sedimento (veja Sedimento).
7. Pare após um ticket. Uma resolução por sessão é a cadência — é o orçamento da janela de contexto, não uma política. O ponteiro de fechamento da sessão nomeia o que acabou de ser resolvido e o que está agora na fronteira.

Tipos de ticket

Cada ticket é HITL (trabalhado com o capitão, que fala por si mesmo) ou AFK (conduzido apenas pelo navegador). Um ticket HITL só se resolve por meio de troca ao vivo; o agente nunca substitui o lado do capitão.

Tipo	Modo	Resolvido por	Usar quando
research	AFK	Subagente em segundo plano: investigue fontes primárias (documentos oficiais, código-fonte, especificações), deixe um arquivo Markdown citado em docs/research/<slug-do-ticket>.md (ou a convenção de notas existente do repositório, quando houver), e vincule-o ao ticket	Uma decisão depende de conhecimento fora do diretório de trabalho atual
loft	HITL	Chame a ferramenta Skill com "loft": um artefato descartável responde à pergunta do ticket — um módulo de lógica pura em um shell clicável, ou variantes de interface estruturalmente diferentes em uma única rota; o capitão reage, a resposta é incorporada na resolução, o artefato permanece em um branch loft/<nome>	A pergunta é precisa, mas a prosa não pode resolvê-la — precisa ser vista ou clicada, não descrita
grilling	HITL	Chame a ferramenta Skill com "deep-interview"; o capitão decide cada rodada	A conversa é a resolução — o caso padrão
task	HITL ou AFK	O navegador conduz sozinho onde puder; caso contrário, entrega ao capitão uma lista de verificação precisa	Trabalho manual que desbloqueia uma decisão (inscrever-se em um serviço, provisionar acesso, mover dados para que sua forma possa ser vista) — ganha seu lugar ao desbloquear uma decisão, não ao entregar o destino

A resposta nunca faz parte do corpo do ticket; é registrada na resolução. Ativos criados durante a resolução são vinculados ao ticket, não colados nele.

Corpo do mapa

## Destino

<como é chegar ao fim deste mapa: a especificação, decisão ou mudança para a qual este esforço está encontrando o caminho. Uma ou duas linhas; toda sessão se orienta por ele antes de escolher um ticket.>

## Notas

<domínio; skills que toda sessão deve consultar; preferências permanentes; conclusões adiadas do drydock --check (textualmente); tag documentLanguage resolvida; ressalvas do modo de rastreador para modo local>

## Decisões até agora

<!-- o índice: uma linha por ticket fechado, suficiente para julgar relevância, depois amplie o link para o detalhe que o ticket contém -->

- [<título do ticket fechado>](link): <resumo de uma linha da resposta>

## Ainda não especificado

<!-- névoa dentro do escopo que você ainda não pode transformar em ticket; é promovida à medida que a fronteira avança -->

## Fora do escopo

<!-- trabalho considerado além do destino; fechado, nunca é promovido -->

Névoa ou ticket? O teste é se você pode declarar a pergunta com precisão agora, não se pode respondê-la agora. Ticket quando a pergunta já está nítida, mesmo que esteja bloqueada. Ainda não especificado quando você não consegue formulá-la com essa nitidez — não pré-corte a névoa em pedaços do tamanho de tickets; um bloco pode se transformar em vários tickets ou em nenhum. Fora do escopo é um ato de escopo, não um passo na rota: escopo, não nitidez, coloca o trabalho lá, e ele só retorna se o destino for redesenhado.

Sedimento

As resoluções aterrissam na trilha de papel do shipyard no momento em que se estabelecem — os mesmos slots que a Fase 1 do launch usa:

• um termo que as resoluções estabeleceram ou afinaram → glossário do CONTEXT.md (uma entrada: definição, limite, ambiguidade resolvida)
• uma decisão passando no teste ADR (difícil de reverter, surpreendente sem contexto, uma troca real) → docs/adr/NNNN-<slug>.md
• uma regra de negócio ou fato de contexto → docs/business/ (um artigo por pergunta de negócio)

Quando o estaleiro não está estabelecido (o capitão recusou o drydock no momento do traçado), adie, não pule: registre cada aterrissagem pendente como uma linha nas Notas do mapa sob um cabeçalho Sedimento adiado. A execução posterior do /oh-my-claudecode:launch trata as superfícies não estabelecidas como conclusões, e as linhas adiadas dizem exatamente o que aterrissar primeiro.

Saída — entregue, não construa

O mapa está concluído quando não há tickets abertos restantes e Ainda não especificado está vazio. Então:

1. Consolide Decisões até agora em um resumo de missão: objetivo, limite de escopo, não-objetivos — escrevível agora porque o caminho está claro. Escreva-o em .omc/wayfinder/<slug-do-mapa>/brief.md para que a transferência passe um ponteiro, não conteúdo.
2. Recomende: "O caminho está claro. Execute /oh-my-claudecode:launch com o resumo em .omc/wayfinder/<slug-do-mapa>/brief.md." O mapa permanece como o diário de bordo do esforço; o portão do estaleiro do launch é dono de todas as verificações a partir daí.
3. A entrada padrão é a Fase 1 do launch (a trilha de papel já está meio cheia; sua fronteira se limpa rapidamente). Somente quando as decisões já soarem como uma especificação, uma especificação pode ser redigida e o launch iniciado na Fase 2 com o caminho da especificação.

Escopo e não-objetivos

• Sem daemon, sem modo, sem comportamento sempre ativo, sem máquina de estado em tempo de execução: o mapa são issues comuns de rastreador ou arquivos do repositório.
• Solicitações recebidas que chegam como névoa são responsabilidade do porto para rotear: uma issue difusa entregue pelo /oh-my-claudecode:harbor é traçada como qualquer ideia vaga, com o tópico original e quaisquer links de decisão assinados como material.
• Nunca muta o ciclo de vida da Equipe, status de tarefas ou estado de tempo de execução; nunca publica tickets de entrega — tickets de construção de fatia vertical pertencem ao C3 do launch, e o navegador não deve pré-cortar névoa neles.
• Nunca executa uma decisão além de registrá-la. A única exceção é um ticket task, que faz apenas o que desbloqueia uma decisão.
• As Decisões até agora do mapa são um índice; uma decisão vive em exatamente um lugar, seu ticket.

Definição de conclusão

Uma sessão de traçado termina com um mapa assinado pelo capitão e tickets de pesquisa disparados. Uma sessão de trabalho termina com exatamente uma resolução registrada, a fronteira avançada e o ponteiro de fechamento da sessão emitido. O esforço termina quando o caminho está claro e o resumo de missão está nas mãos do capitão com /oh-my-claudecode:launch recomendado — toda decisão que o navegador tomou em nome do capitão pode ser respondida com um ponteiro para onde foi registrada.