mattpocock/wayfinder

Uma ideia vaga chegou, grande demais para uma única sessão de agente e envolta em névoa: o caminho daqui até o destino ainda não está visível. Wayfinding é sobre encontrar esse caminho, não investir contra o destino. Esta habilidade traça o caminho como um mapa compartilhado no rastreador de issues do repositório e, em seguida, trabalha seus tickets de decisão (perguntas cuja resolução é uma decisão, não fatias de uma construção a ser executada) um de cada vez até que a rota esteja clara.

O destino varia por esforço, e nomeá-lo é o primeiro ato de traçar: ele molda cada ticket. Pode ser uma especificação para entregar e iterar, uma decisão a ser tomada antes do planejamento começar, ou uma mudança feita no local, como uma migração de estrutura de dados. O mapa é independente de domínio: trabalho de engenharia, conteúdo de curso, qualquer coisa que se encaixe no formato.

Planeje, não execute

O Wayfinder é planejamento por padrão: cada ticket resolve uma decisão, e o mapa está pronto quando o caminho está claro, sem nada a ser decidido antes de alguém ir e fazer a coisa. A tentação de simplesmente fazer o trabalho geralmente é o sinal de que você atingiu a borda do mapa e é hora de passar adiante. Um esforço pode substituir isso em suas Notas, carregando a execução para dentro do próprio mapa, mas, na ausência disso, produza decisões, não entregas.

Referencie pelo nome

Cada mapa e ticket é uma issue, portanto, tem um nome: seu título. Em tudo que o humano lê (narração, as Decisões até agora do mapa), refira-se a ele por esse nome, nunca por um ID, número ou slug. Uma parede de #42, #43, #44 é ilegível; nomes são lidos rapidamente. O ID e a URL não desaparecem; um nome envolve seu link, mas eles andam dentro do nome, nunca o substituem.

O Mapa

O mapa é uma única issue no rastreador de issues deste repositório, rotulada como wayfinder:map, o artefato canônico. Seus tickets são issues filhas do mapa.

O mapa é um índice, não um armazenamento. Ele lista as decisões tomadas e aponta para os tickets que contêm seus detalhes; uma decisão vive em exatamente um lugar, seu ticket, então o mapa nunca a reafirma, apenas a resume e a vincula.

Onde o mapa, seus tickets filhos, bloqueios e consultas de fronteira residem fisicamente é específico do rastreador. O rastreador de issues deve ter sido fornecido a você. Caso contrário, diga ao usuário para executar /setup-matt-pocock-skills. Consulte a seção "Operações de wayfinding" do documento do rastreador para saber como este repositório as expressa. Se nenhum rastreador foi fornecido, use o rastreador markdown local como padrão.

O corpo do mapa

O mapa inteiro em baixa resolução, carregado uma vez por sessão. Tickets abertos não são listados: são issues filhas abertas, encontradas por consulta.

## Destino

<qual é a aparência de alcançar o fim deste mapa: a especificação, decisão ou mudança que este esforço está encontrando seu caminho. Uma ou duas linhas; cada sessão se orienta para ele antes de escolher um ticket.>

## Notas

<domínio; habilidades que cada sessão deve consultar; preferências permanentes para este esforço>

## Decisões até agora

<!-- o índice: uma linha por ticket fechado, suficiente para julgar relevância, então 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

<!-- veja "Névoa de guerra": névoa no escopo que você ainda não pode transformar em ticket; gradua-se conforme a fronteira avança -->

## Fora do escopo

<!-- veja "Fora do escopo": trabalho descartado além do destino; fechado, nunca gradua -->

Tickets

Cada ticket é uma issue filha do mapa; o ID da issue no rastreador é sua identidade. Seu corpo é a pergunta, dimensionada para uma sessão de agente de 100K tokens:

## Pergunta

<a decisão ou investigação que este ticket resolve>

Cada ticket carrega um rótulo wayfinder:<tipo>, um entre research, prototype, grilling, task (veja Tipos de Ticket).

Uma sessão reivindica um ticket atribuindo-o ao desenvolvedor que está conduzindo o mapa, primeiro, antes de qualquer trabalho, para que sessões concorrentes o ignorem. Esse responsável é a reivindicação: um ticket aberto e não atribuído não é reivindicado.

O bloqueio usa a relação de dependência nativa do rastreador: essencial porque renderiza a fronteira visualmente na própria interface do rastreador, para que o humano veja o que é possível pegar sem abrir o mapa. Apenas um rastreador que não possui bloqueio nativo recorre a uma convenção no corpo. Um ticket está desbloqueado quando todos os tickets que o bloqueiam estão fechados; a fronteira são as issues filhas abertas, desbloqueadas e não reivindicadas, a borda do conhecido.

A resposta não faz parte do corpo; ela é registrada na resolução (veja Trabalhe no mapa). Os ativos criados ao resolver um ticket são vinculados a partir da issue, não colados nela.

Tipos de Ticket

Cada ticket é HITL (humano no loop, trabalhado com um humano que fala por si mesmo) ou AFK, conduzido apenas pelo agente. Um ticket HITL só é resolvido por meio dessa troca ao vivo; o agente nunca substitui o lado humano (um agente de investigação que responde suas próprias perguntas quebrou isso).

• Pesquisa (AFK): Leitura de documentação, APIs de terceiros ou recursos locais, como bases de conhecimento, para descobrir um fato do qual uma decisão depende. Resolvido por um subagente que chama a ferramenta Skill com "research". Use quando o conhecimento fora do diretório de trabalho atual for necessário.
• Protótipo (HITL): Aumente a fidelidade da discussão criando um artefato barato, aproximado e concreto para reagir (um esboço, uma versão inicial, um stub ou código de UI/lógica) chamando a ferramenta Skill com "prototype". Vincule o protótipo como um ativo. Use quando "como deveria parecer" ou "como deveria se comportar" for a pergunta-chave.
• Investigação (HITL): Conversa. O caso padrão. Sempre chame a ferramenta Skill duas vezes, para "grilling" e "domain-modeling".
• Tarefa (HITL ou AFK): Trabalho manual que deve acontecer antes que uma decisão possa ser tomada: nada a decidir, prototipar ou pesquisar, mas a discussão está bloqueada até que seja concluída. Inscrever-se em um serviço para que sua API possa ser julgada, provisionar acesso, mover dados para que sua forma possa ser vista. Este é o único tipo que faz em vez de decidir, e ganha seu lugar ao desbloquear uma decisão, não ao entregar o destino. O agente o conduz sozinho onde puder (AFK); caso contrário, entrega ao humano uma lista de verificação precisa (HITL). Resolvido quando o trabalho é concluído; a resposta registra o que foi feito e quaisquer fatos resultantes (localização de credenciais, novas URLs, contagens de linhas) dos quais tickets posteriores dependem.

Névoa de guerra

O mapa é deliberadamente incompleto: não mapeie o que você ainda não pode ver. Além dos tickets ativos está a névoa de guerra: a visão turva de decisões e investigações que você sabe que estão por vir, mas ainda não consegue fixar, porque dependem de perguntas ainda abertas. Resolver um ticket limpa a névoa à sua frente, graduando o que agora é especificável em novos tickets, um de cada vez, até que o caminho para o destino esteja claro e nenhum ticket restante.

A seção Ainda não especificado do mapa é onde essa visão turva é registrada: a pergunta suspeita, a área a ser revisitada posteriormente. É a fronteira não descoberta em direção ao destino: tudo aqui está no escopo, apenas não está nítido o suficiente para ser transformado em ticket. Escreva tão vagamente ou tão completamente quanto a visão permitir; ele funciona como um sinalizador para colaboradores que estão lendo para onde o esforço está indo.

Névoa ou ticket? O teste é se você pode afirmar 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 e você não possa agir ainda.
• Ainda não especificado quando você ainda não consegue formulá-la com tanta nitidez. Não pré-corte a névoa em pedaços do tamanho de tickets: ela é mais grosseira que um ticket, e um pedaço pode se graduar em vários tickets, ou nenhum, quando a fronteira o alcançar.

Ainda não especificado exclui o que já foi decidido (Decisões até agora), o que já é um ticket ativo e o que está fora do escopo (a próxima seção).

Fora do escopo

A névoa sempre se acumula em direção ao destino. O destino fixa o escopo, portanto, trabalho além dele está fora do escopo: não é névoa e não pertence a Ainda não especificado. Ele ganha sua própria seção Fora do escopo no mapa: trabalho que você conscientemente descartou deste esforço. O escopo, não a nitidez, o coloca aqui.

Trabalho fora do escopo nunca gradua (a fronteira para no destino), então ele retorna apenas se o destino for redesenhado, e então como um novo esforço, não uma retomada.

Descartar algo como fora do escopo é um ato de definição de escopo, não um passo na rota. Quando um ticket que já existe acaba ficando além do destino (mal escopado durante o mapeamento ou exposto por uma resolução), feche-o (um ticket fechado está inequivocamente fora da fronteira) e deixe uma linha na seção Fora do escopo: o resumo mais o motivo de estar fora do escopo, vinculando o ticket fechado. Ele permanece fora de Decisões até agora, que registra a rota realmente percorrida; um limite de escopo não é um passo nela.

Invocação

Dois modos. De qualquer forma, nunca resolva mais de um ticket por sessão, com exceção de tickets de pesquisa.

Traçar o mapa

O usuário invoca com uma ideia vaga.

1. Nomeie o destino. Chame a ferramenta Skill duas vezes, para "grilling" e "domain-modeling", para definir para onde este mapa está encontrando seu caminho: a especificação, decisão ou mudança. O destino fixa o escopo, então é definido primeiro.
2. Mapeie a fronteira. Investigue novamente, em largura desta vez: espalhe-se por todo o espaço em vez de se aprofundar em qualquer tópico, identificando as decisões abertas e os primeiros passos possíveis agora. Se isso não revelar névoa (o caminho para o destino já está claro, toda a jornada é pequena o suficiente para uma sessão), você não precisa de um mapa. Pare e pergunte ao usuário como ele gostaria de prosseguir.
3. Crie o mapa (rótulo wayfinder:map): Destino e Notas preenchidos, Decisões até agora vazias, a névoa esboçada em Ainda não especificado.
4. Crie os tickets que você pode especificar agora como issues filhas do mapa, depois conecte as arestas de bloqueio em uma segunda passagem (as issues precisam de IDs antes de poderem referenciar umas às outras). A conexão as ordena na fronteira e nas bloqueadas; tudo que você ainda não pode especificar permanece na névoa: a seção Ainda não especificado.
5. Dispare os subagentes de pesquisa. Para cada ticket de research que você acabou de criar, inicie um subagente que chame a ferramenta Skill com "research" para resolvê-lo em paralelo, capturando suas descobertas em um branch research/<nome> descartável com um ponteiro de contexto do ticket.
6. Pare: traçar é trabalho de uma sessão; ela não resolve nada manualmente.

Trabalhe no mapa

O usuário invoca com um mapa (URL ou número). Um ticket é opcional: sem um, você escolhe a próxima decisão, não o usuário.

1. Carregue o mapa: a visão de baixa resolução, não o corpo de cada ticket.
2. Escolha o ticket. Se o usuário nomeou um, use-o. Caso contrário, pegue o primeiro ticket da fronteira em ordem. Reivindique-o: atribua-o a si mesmo antes de qualquer trabalho.
3. Resolva-o. Amplie conforme necessário: busque o corpo completo de qualquer ticket relacionado ou fechado sob demanda; chame a ferramenta Skill para as habilidades que o bloco ## Notas nomeia. Em caso de dúvida, chame a ferramenta Skill duas vezes, para "grilling" e "domain-modeling".
4. Registre a resolução: publique a resposta como um comentário de resolução, feche a issue e anexe um ponteiro de contexto às Decisões até agora do mapa.
5. Adicione tickets recém-surgidos (crie e conecte); graduate qualquer névoa que a resposta tornou especificável, limpando cada pedaço graduado de Ainda não especificado para que viva apenas como seu novo ticket. Se a resposta revelar que um ticket (este ou outro) está além do destino, descarte-o como fora do escopo em vez de resolvê-lo na rota. Se a decisão invalidar outras partes do mapa, atualize ou exclua esses tickets.

O usuário pode executar tickets desbloqueados em paralelo, então espere que outras sessões estejam editando o rastreador simultaneamente.