Touch Map

¿Qué hace Touch Map?

Construye un mapa mental de lo que este cambio debe tocar para completarse. No escribas un plan de implementación. No escribas código. No cargues la siguiente habilidad en una tubería. Una habilidad de flujo de trabajo posterior secuencia este mapa con otras habilidades.

El mapa es el producto: las partes y archivos requeridos para llevar el cambio a término.

Cuándo Usarlo

Cárgalo después de que el usuario haya decidido qué es el cambio y cualquier cómo que ya hayan elegido.

• Ejecutar para: una nueva función, una corrección de errores, una refactorización que mueve un límite.
• Saltar: errores tipográficos, comentarios, formato, solo lockfile, documentación sin código.
• Si la intención aún está abierta ("implementa X" sin comportamiento elegido): detente. Pregunta hasta que el cambio esté definido. Luego mapea. No mapees una función que aún no ha sido elegida.

Puertas Duras

1. Sin código y sin siguiente habilidad. Esta habilidad mapea. No planifica bloques. No implementa.
2. Muestra el mapa y detente. No esperes aprobación. El usuario interrumpe si el mapa está mal.
3. No leas coupling.json. Eso es una verificación separada posterior.
4. No busques en todo el repositorio utilidades. Registra la reutilización que el agente realmente vio en los dominios afectados. Una habilidad posterior se encarga de la búsqueda completa.

Atlas Persistente

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

Comprometido con el repositorio. Solo a nivel de dominio. Los nombres de funciones no pertenecen aquí.

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

• id — nombre corto, una palabra o en kebab-case.
• owns — rutas de paquetes o carpetas.
• talksTo — otros ids de dominio.

Escribe este archivo solo cuando un hecho a nivel de dominio haya cambiado: se haya agregado, eliminado o renombrado un dominio; rutas owns; o un enlace talksTo. Agregar una función dentro de un dominio existente no debe editar este archivo.

Procedimientos

Procedimiento 1: Confirmar intención definida

1. Si el cambio ya está claro (error nombrado, función nombrada, comportamiento nombrado), continúa.
2. Si el usuario aún está eligiendo lo que quiere, detén el mapeo. Pregunta hasta que la intención esté definida. Luego regresa aquí.

Procedimiento 2: Cargar o iniciar el atlas

1. Si existe .agent/domain-map.json, léelo.
2. Si falta, construye un primer atlas solo a nivel de dominio:
   • Prefiere packages/* (o las carpetas de paquetes del repositorio).
   • En otro caso, usa carpetas de área de nivel superior bajo src/ (o la raíz fuente principal).
   • Establece talksTo a partir de aristas de importación entre esas rutas owns.
   • No pongas nombres de funciones en el atlas.
3. Crea .agent/ si es necesario. Escribe el archivo. Muestra el nuevo atlas en el mismo turno. Continúa. No esperes.

Procedimiento 3: Enfocarse en este cambio

1. Elige los dominios afectados del atlas y la intención definida.
2. Comienza desde los módulos que claramente pertenecen al cambio.
3. Lee esos archivos. Sigue las importaciones solo mientras la lista de "archivos a tocar" siga cambiando.
4. Detente cuando un archivo recién abierto no cambie el mapa. No leas un paquete por completitud.
5. Nombra las partes como módulos más funciones y tipos existentes que el cambio usará o junto a los que se ubicará. Los archivos son punteros, no el mapa.
6. Anota la reutilización realmente vista en esos archivos (ruta + símbolo). No hagas grep en todo el espacio de trabajo en busca de ayudantes.

Procedimiento 4: Elegir la ruta si existe más de una

Si solo existe una ruta honesta, indícala en una línea.

Si existe más de una ruta, elige una. Detente en el primer escalón de la escalera que decida:

1. Reutilizar algo que existe sobre escribir un nuevo módulo.
2. Permanecer dentro de los dominios afectados. No abras un nuevo dominio.
3. No agregues un paquete, capa o API pública si un cambio interno funciona.
4. Luego, la menor cantidad de archivos.

Nombra al ganador y qué escalón lo decidió. La menor cantidad de archivos es el desempate, no la regla completa. No metas nuevo comportamiento en un archivo gigante para ganar en conteo de archivos.

Procedimiento 5: Actualizar el atlas (solo a nivel de dominio)

1. Si este cambio agrega, elimina o renombra un dominio, o cambia owns / talksTo, modifica .agent/domain-map.json en este mismo trabajo.
2. Si nada a nivel de dominio cambió, deja el archivo en paz.

Procedimiento 6: Mostrar el mapa por cambio

Muestra estas seis secciones, en este orden. No escribas un archivo markdown por tarea.

1. Dominio(s) afectado(s) — del atlas.
2. Partes — módulos, más funciones y tipos existentes en juego. Incluye la reutilización vista (ruta + símbolo).
3. Cómo se comunican — solo las aristas que este cambio usa (llamadas, tipos, datos). No un grafo de llamadas completo. Agrega un diagrama Mermaid solo si esas aristas son difíciles de ver en viñetas.
4. Archivos a tocar — la lista final. Este es el producto independiente.
5. No se tocarán — explícito. Detiene ediciones de paso.
6. Elección de ruta — una línea si había una sola ruta. Si había varias, el ganador y el escalón de la escalera.

Procedimiento 7: Detenerse

1. Después del Procedimiento 6, detente.
2. No escribas código. No cargues otra habilidad desde esta.

Árbol de Decisión

• Intención no definida → Procedimiento 1, luego detén el mapeo hasta que lo esté.
• Intención definida, cambio de comportamiento → Procedimiento 2 → 3 → 4 → 5 → 6 → 7.
• Error tipográfico / comentario / formato / lockfile / solo documentación → esta habilidad no aplica.
• Archivo de atlas faltante → Procedimiento 2 paso 2 (iniciar), luego continúa.
• Una ruta vs muchas rutas → Procedimiento 4.

Banderas Rojas

Señal	Qué significa	Haz en su lugar
Mapear antes de que el usuario elija la función	La intención no está definida	Procedimiento 1. Pregunta primero.
Abrir cada archivo en owns	Recorrido, no un mapa	Procedimiento 3: detente cuando la lista de archivos sea estable.
Hacer grep en el monorepo por isRecord	Búsqueda completa es una habilidad diferente	Registra solo la reutilización ya vista.
Leer coupling.json	Archivo incorrecto	Deja esa verificación para después.
Esperar "¿se ve bien?" en el mapa	La puerta es mostrar y detenerse	Muestra las seis secciones y detente.
Comenzar a codificar después del mapa	Esta habilidad solo mapea	Procedimiento 7. Sin código.
Cargar la siguiente habilidad de la tubería desde aquí	Deja la composición al flujo de trabajo	Detente. Deja que la habilidad de flujo de trabajo secuencie.
Escribir .agent/touch-maps/<task>.md	Basura de tarea obsoleta	Solo en el chat (o sesión). El archivo atlas es la única persistencia.
Editar el atlas porque se agregó un ayudante	Grano de función en el atlas	Deja el atlas. Pon el ayudante en la sección 2.
Elegir la ruta con menos archivos primero	Trampa del archivo gigante	Ejecuta toda la escalera.

Manejo de Errores

• No está dentro de un repositorio git: mapea este cambio en las seis secciones. Omite el archivo atlas. Dilo en una línea.
• El JSON del atlas no es válido: no adivines. Reporta el error de análisis. Reconstruye desde el Procedimiento 2 paso 2 solo si el usuario está de acuerdo, o arregla el JSON si la intención es obvia (coma final, corchete faltante).
• El dominio afectado no está claro: elige el conjunto más pequeño de dominios que pueda ser dueño del cambio. Indica la duda en la elección de ruta. No inventes un nuevo dominio para un error de un solo archivo.
• El usuario interrumpe que el mapa está mal: corrige las seis secciones. Vuelve a ejecutar el Procedimiento 4 si la ruta cambió. Luego detente.