Touch Map

O que Touch Map faz?

Construa um mapa mental do que esta mudança deve tocar para ser concluída. Não escreva um plano de implementação. Não escreva código. Não carregue a próxima skill em uma pipeline. Uma skill de workflow posterior sequencia este mapa com outras skills.

O mapa é o produto final: as partes e os arquivos necessários para levar a mudança adiante.

Quando Usar

Carregue após o usuário ter decidido o que é a mudança e qualquer como que já escolheu.

• Execute para: uma nova funcionalidade, uma correção de bug, uma refatoração que move um limite.
• Pule: erros de digitação, comentários, formatação, apenas lockfile, docs sem código.
• Se a intenção ainda está em aberto ("implemente X" sem comportamento escolhido): pare. Pergunte até que a mudança esteja definida. Depois mapeie. Não mapeie uma funcionalidade que ainda não foi escolhida.

Portões Rígidos

1. Nenhum código e nenhuma próxima skill. Esta skill mapeia. Ela não planeja blocos. Ela não implementa.
2. Mostre o mapa e pare. Não aguarde aprovação. O usuário interrompe se o mapa estiver errado.
3. Não leia coupling.json. Essa é uma verificação separada posterior.
4. Não vasculhe todo o repositório em busca de utilitários. Registre a reutilização que o agente realmente viu no(s) domínio(s) atingido(s). Uma skill posterior é responsável pela busca completa.

Atlas Persistente

Caminho: <repo>/.agent/domain-map.json

Commitado com o repositório. Apenas no grão de domínio. Nomes de funções não pertencem aqui.

{
  "version": 1,
  "domains": [
    {
      "id": "auth",
      "owns": ["packages/auth", "packages/auth-ui"],
      "talksTo": ["users", "sessions"]
    }
  ]
}

• id — nome curto, uma palavra ou kebab-case.
• owns — caminhos de pacotes ou pastas.
• talksTo — outros ids de domínio.

Escreva este arquivo apenas quando um fato em nível de domínio mudou: um domínio adicionado, removido ou renomeado; caminhos owns; ou um link talksTo. Adicionar uma função dentro de um domínio existente não deve editar este arquivo.

Procedimentos

Procedimento 1: Confirmar intenção definida

1. Se a mudança já está clara (bug nomeado, função nomeada, comportamento nomeado), continue.
2. Se o usuário ainda está escolhendo o que quer, pare de mapear. Pergunte até que a intenção esteja definida. Depois retorne aqui.

Procedimento 2: Carregar ou inicializar o atlas

1. Se .agent/domain-map.json existir, leia-o.
2. Se estiver faltando, construa um primeiro atlas apenas no grão de domínio:
   • Prefira packages/* (ou as pastas de pacotes do repositório).
   • Caso contrário, use pastas de área de nível superior sob src/ (ou a raiz de código principal).
   • Defina talksTo a partir das arestas de importação entre esses caminhos owns.
   • Não coloque nomes de funções no atlas.
3. Crie .agent/ se necessário. Escreva o arquivo. Mostre o novo atlas na mesma rodada. Continue. Não aguarde.

Procedimento 3: Focar nesta mudança

1. Escolha o(s) domínio(s) atingido(s) a partir do atlas e da intenção definida.
2. Comece pelos módulos que claramente pertencem à mudança.
3. Leia esses arquivos. Siga as importações apenas enquanto a lista de "arquivos a tocar" ainda estiver mudando.
4. Pare quando um arquivo recém-aberto não alterar o mapa. Não leia um pacote por completo.
5. Nomeie as partes como módulos mais funções e tipos existentes que a mudança usará ou ficará ao lado. Arquivos são ponteiros, não o mapa.
6. Observe a reutilização realmente vista nesses arquivos (caminho + símbolo). Não faça grep em todo o espaço de trabalho por auxiliares.

Procedimento 4: Escolher o caminho se houver mais de um

Se houver apenas um caminho honesto, declare-o em uma linha.

Se houver mais de um caminho, escolha um. Pare no primeiro degrau da escada que decidir:

1. Reutilizar algo que existe em vez de escrever um novo módulo.
2. Permanecer dentro do(s) domínio(s) atingido(s). Não abrir um novo domínio.
3. Não adicionar um pacote, camada ou API pública se uma alteração interna funcionar.
4. Então, o menor número de arquivos.

Nomeie o vencedor e qual degrau o decidiu. Menor número de arquivos é o desempate, não a regra inteira. Não enfie novo comportamento em um arquivo god para vencer na contagem de arquivos.

Procedimento 5: Atualizar o atlas (apenas nível de domínio)

1. Se esta mudança adicionar, remover ou renomear um domínio, ou alterar owns / talksTo, corrija .agent/domain-map.json neste mesmo trabalho.
2. Se nada no grão de domínio mudou, deixe o arquivo como está.

Procedimento 6: Mostrar o mapa por mudança

Mostre estas seis seções, nesta ordem. Não escreva um arquivo markdown por tarefa.

1. Domínio(s) atingido(s) — do atlas.
2. Partes — módulos, mais funções e tipos existentes em jogo. Inclua reutilização vista (caminho + símbolo).
3. Como se comunicam — apenas as arestas que esta mudança usa (chamadas, tipos, dados). Não um grafo de chamadas completo. Adicione um diagrama Mermaid apenas se essas arestas forem difíceis de ver em marcadores.
4. Arquivos a tocar — a lista final. Este é o produto independente.
5. Não tocará — explícito. Impede edições por impulso.
6. Escolha de caminho — uma linha se houver apenas um caminho. Se houver vários, o vencedor e o degrau da escada.

Procedimento 7: Parar

1. Após o Procedimento 6, pare.
2. Não escreva código. Não carregue outra skill a partir desta.

Árvore de Decisão

• Intenção não definida → Procedimento 1, depois pare de mapear até que esteja.
• Intenção definida, mudança de comportamento → Procedimento 2 → 3 → 4 → 5 → 6 → 7.
• Erro de digitação / comentário / formato / lockfile / apenas docs → esta skill não se aplica.
• Arquivo de atlas ausente → Procedimento 2 passo 2 (inicialização), depois continue.
• Um caminho vs. vários caminhos → Procedimento 4.

Bandeiras Vermelhas

Sinal	O que significa	Faça em vez disso
Mapear antes de o usuário escolher a funcionalidade	Intenção não definida	Procedimento 1. Pressione primeiro.
Abrir todos os arquivos em owns	Tour, não um mapa	Procedimento 3: pare quando a lista de arquivos estiver estável.
Fazer grep no monorepo por isRecord	Busca completa é uma skill diferente	Registre apenas a reutilização já vista.
Ler coupling.json	Arquivo errado	Deixe essa verificação para depois.
Esperar por "parece bom?" no mapa	Portão é mostrar e parar	Mostre as seis seções e pare.
Começar a codificar após o mapa	Esta skill apenas mapeia	Procedimento 7. Nenhum código.
Carregar a próxima skill da pipeline a partir daqui	Deixa a composição para o workflow	Pare. Deixe a skill de workflow sequenciar.
Escrever .agent/touch-maps/<task>.md	Lixo de tarefa obsoleto	Apenas chat (ou sessão). O arquivo de atlas é a única persistência.
Editar o atlas porque um auxiliar foi adicionado	Grão de função no atlas	Deixe o atlas em paz. Coloque o auxiliar na seção 2.
Escolher o caminho com menos arquivos primeiro	Armadilha do arquivo god	Execute a escada completa.

Tratamento de Erros

• Não está dentro de um repositório git: mapeie esta mudança nas seis seções. Pule o arquivo de atlas. Diga isso em uma linha.
• JSON do atlas inválido: não adivinhe. Relate o erro de análise. Reconstrua a partir do Procedimento 2 passo 2 apenas se o usuário concordar, ou corrija o JSON se a intenção for óbvia (vírgula sobressalente, colchete faltando).
• Domínio atingido incerto: escolha o menor conjunto de domínios que pode ser dono da mudança. Declare a dúvida na Escolha de caminho. Não invente um novo domínio para um bug de um arquivo.
• Usuário interrompe dizendo que o mapa está errado: corrija as seis seções. Reexecute o Procedimento 4 se o caminho mudou. Depois pare.