Touch Map

Que fait Touch Map ?

Construisez une carte mentale de ce que ce changement doit toucher pour aboutir. N'écrivez pas de plan d'implémentation. N'écrivez pas de code. Ne chargez pas la compétence suivante dans un pipeline. Une compétence de workflow ultérieure séquence cette carte avec d'autres compétences.

La carte est le produit : les parties et fichiers nécessaires pour mener à bien le changement.

Quand l'utiliser

Chargez après que l'utilisateur a décidé quoi est le changement, et tout comment qu'il a déjà choisi.

• Exécuter pour : une nouvelle fonctionnalité, une correction de bug, une refonte qui déplace une limite.
• Ignorer : fautes de frappe, commentaires, formatage, fichiers de verrouillage uniquement, documentation sans code.
• Si l'intention est encore ouverte (« implémenter X » sans comportement choisi) : arrêtez. Demandez jusqu'à ce que le changement soit fixé. Ensuite, cartographiez. Ne cartographiez pas une fonctionnalité qui n'est pas encore choisie.

Barrières strictes

1. Pas de code et pas de compétence suivante. Cette compétence cartographie. Elle ne planifie pas de blocs. Elle n'implémente pas.
2. Affichez la carte et arrêtez. N'attendez pas d'approbation. L'utilisateur interrompt si la carte est erronée.
3. Ne lisez pas coupling.json. C'est une vérification ultérieure et distincte.
4. Ne parcourez pas tout le dépôt pour des utilitaires. Enregistrez la réutilisation que l'agent a réellement vue dans les domaines ciblés. Une compétence ultérieure gère la recherche complète.

Atlas persistant

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

Commité avec le dépôt. Grain de domaine uniquement. Les noms de fonctions n'ont pas leur place ici.

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

• id — nom court, un mot ou en kebab-case.
• owns — chemins de paquets ou de dossiers.
• talksTo — autres identifiants de domaine.

Écrivez ce fichier uniquement lorsqu'un fait au niveau du domaine a changé : un domaine ajouté, supprimé ou renommé ; les chemins owns ; ou un lien talksTo. Ajouter une fonction à l'intérieur d'un domaine existant ne doit pas modifier ce fichier.

Procédures

Procédure 1 : Confirmer l'intention fixée

1. Si le changement est déjà clair (bug nommé, fonction nommée, comportement nommé), continuez.
2. Si l'utilisateur choisit encore ce qu'il veut, arrêtez de cartographier. Demandez jusqu'à ce que l'intention soit fixée. Revenez ensuite ici.

Procédure 2 : Charger ou amorcer l'atlas

1. Si .agent/domain-map.json existe, lisez-le.
2. S'il est manquant, construisez un premier atlas uniquement au grain du domaine :
   • Préférez packages/* (ou les dossiers de paquets du dépôt).
   • Sinon, utilisez les dossiers de zone de premier niveau sous src/ (ou la racine source principale).
   • Définissez talksTo à partir des arêtes d'import entre ces chemins owns.
   • Ne mettez pas de noms de fonctions dans l'atlas.
3. Créez .agent/ si nécessaire. Écrivez le fichier. Affichez le nouvel atlas dans le même tour. Continuez. N'attendez pas.

Procédure 3 : Zoomer sur ce changement

1. Choisissez le(s) domaine(s) ciblé(s) à partir de l'atlas et de l'intention fixée.
2. Partez des modules qui appartiennent clairement au changement.
3. Lisez ces fichiers. Suivez les imports uniquement tant que la liste des « fichiers à toucher » change encore.
4. Arrêtez lorsqu'un fichier nouvellement ouvert ne modifie pas la carte. Ne lisez pas un paquet en entier par souci d'exhaustivité.
5. Nommez les parties comme modules plus fonctions et types existants que le changement utilisera ou à côté desquels il se trouvera. Les fichiers sont des pointeurs, pas la carte.
6. Notez la réutilisation réellement vue dans ces fichiers (chemin + symbole). Ne parcourez pas tout l'espace de travail pour des aides.

Procédure 4 : Choisir le chemin s'il en existe plus d'un

S'il n'existe qu'un seul chemin honnête, énoncez-le en une ligne.

S'il existe plus d'un chemin, choisissez-en un. Arrêtez-vous à la première étape de l'échelle qui décide :

1. Réutiliser quelque chose qui existe plutôt que d'écrire un nouveau module.
2. Rester dans le(s) domaine(s) ciblé(s). N'ouvrez pas un nouveau domaine.
3. N'ajoutez pas de paquet, de couche ou d'API publique si un changement interne fonctionne.
4. Ensuite, le moins de fichiers.

Nommez le gagnant et quelle étape a décidé. Le moins de fichiers est le départage, pas la règle entière. Ne fourrez pas un nouveau comportement dans un fichier godillot pour gagner sur le nombre de fichiers.

Procédure 5 : Mettre à jour l'atlas (niveau domaine uniquement)

1. Si ce changement ajoute, supprime ou renomme un domaine, ou modifie owns / talksTo, corrigez .agent/domain-map.json dans ce même travail.
2. Si rien n'a changé au grain du domaine, laissez le fichier tranquille.

Procédure 6 : Afficher la carte par changement

Affichez ces six sections, dans cet ordre. N'écrivez pas de fichier markdown par tâche.

1. Domaine(s) ciblé(s) — depuis l'atlas.
2. Parties — modules, plus fonctions et types existants en jeu. Incluez la réutilisation vue (chemin + symbole).
3. Comment ils parlent — uniquement les arêtes que ce changement utilise (appels, types, données). Pas un graphe d'appels complet. Ajoutez un diagramme Mermaid uniquement si ces arêtes sont difficiles à voir en listes.
4. Fichiers à toucher — la liste finale. C'est le produit autonome.
5. Ne touchera pas — explicite. Empêche les modifications parasites.
6. Choix du chemin — une ligne s'il n'y avait qu'un seul chemin. S'il y en avait plusieurs, le gagnant et l'étape de l'échelle.

Procédure 7 : Arrêter

1. Après la procédure 6, arrêtez.
2. N'écrivez pas de code. Ne chargez pas une autre compétence depuis celle-ci.

Arbre de décision

• Intention non fixée → Procédure 1, puis arrêtez de cartographier jusqu'à ce qu'elle le soit.
• Intention fixée, changement de comportement → Procédure 2 → 3 → 4 → 5 → 6 → 7.
• Faute de frappe / commentaire / format / fichier de verrouillage / documentation uniquement → cette compétence ne s'applique pas.
• Fichier d'atlas manquant → Procédure 2 étape 2 (amorçage), puis continuez.
• Un chemin vs plusieurs chemins → Procédure 4.

Drapeaux rouges

Signal	Ce que ça signifie	Faites plutôt
Cartographier avant que l'utilisateur ait choisi la fonctionnalité	L'intention n'est pas fixée	Procédure 1. Interrogez d'abord.
Ouvrir chaque fichier dans owns	Tournée, pas une carte	Procédure 3 : arrêtez quand la liste de fichiers est stable.
Chercher isRecord dans tout le monorepo	La recherche complète est une autre compétence	Enregistrez uniquement la réutilisation déjà vue.
Lire coupling.json	Mauvais fichier	Laissez cette vérification pour plus tard.
Attendre un « ça va ? » sur la carte	La barrière est afficher-et-arrêter	Affichez les six sections et arrêtez.
Commencer à coder après la carte	Cette compétence ne fait que cartographier	Procédure 7. Pas de code.
Charger la compétence de pipeline suivante depuis ici	Laisse la composition au workflow	Arrêtez. Laissez la compétence de workflow séquencer.
Écrire .agent/touch-maps/<task>.md	Déchets de tâche obsolètes	Chat (ou session) uniquement. Le seul fichier persistant est l'atlas.
Modifier l'atlas parce qu'une aide a été ajoutée	Grain de fonction dans l'atlas	Laissez l'atlas. Mettez l'aide dans la section 2.
Choisir le chemin avec le moins de fichiers en premier	Piège du fichier godillot	Suivez l'échelle complète.

Gestion des erreurs

• Pas à l'intérieur d'un dépôt git : cartographiez ce changement dans les six sections. Ignorez le fichier d'atlas. Dites-le en une ligne.
• Le JSON de l'atlas est invalide : ne devinez pas. Signalez l'erreur d'analyse. Reconstruisez à partir de la procédure 2 étape 2 uniquement si l'utilisateur est d'accord, ou corrigez le JSON si l'intention est évidente (virgule traînante, crochet manquant).
• Le domaine ciblé n'est pas clair : choisissez le plus petit ensemble de domaines qui peut posséder le changement. Exprimez le doute dans le choix du chemin. N'inventez pas un nouveau domaine pour un bug d'un seul fichier.
• L'utilisateur interrompt en disant que la carte est erronée : corrigez les six sections. Relancez la procédure 4 si le chemin a changé. Ensuite, arrêtez.