m1nga/iteration-close

iteration-close — distiller, supprimer, vérifier la reprise, répéter l'amorçage, ensemencer la suite

Un produit qui itère indéfiniment accumule deux dettes silencieuses, et ce skill les rembourse toutes les deux à chaque frontière d'itération — en toute sécurité (rien n'est perdu) mais impitoyablement (rien de mort n'est gardé) :

• Les fichiers morts traînent et pourrissent en doubles vérités — un arbre déprécié reste pendant des semaines ; un manuel continue d'affirmer qu'un composant « n'est pas construit » longtemps après avoir été livré.
• La connaissance qui ne vit que dans une fenêtre de chat meurt avec elle — des pipelines entiers fonctionnels sont morts dans des blocs-notes ; des décisions durement acquises meurent avec la session. Gardez la leçon, pas l'artefact.

Il est générique : il fonctionne sur n'importe quel dépôt en lisant les conventions de ce dépôt, et là où une convention est absente, il crée le minimum plutôt que de présumer ou de générer une erreur. « Une nouvelle fenêtre ou une nouvelle machine peut continuer » est un ESPOIR jusqu'à ce qu'il soit TESTÉ ; être à jour (pull) est toujours sûr, mais publier (push) est un choix délibéré. Répondez dans la langue de l'utilisateur.

Deux façons de l'exécuter

• Fermeture complète (par défaut) : les cinq phases, dans l'ordre. Utilisez-la quand une itération/tranche est terminée et que l'utilisateur souhaite la clôturer de bout en bout.
• Suppression seule (nettoyage autonome) : lorsque l'utilisateur demande seulement de nettoyer les fichiers anciens/morts/obsolètes, exécutez la Phase 2 seule — n'imposez PAS la fermeture complète en cinq actes. Les conditions préalables s'appliquent toujours : exécutez l'Étape 0 (orientation), les vérifications de refus fermé, et une vérification ponctuelle de la Phase 1 limitée à l'inventaire des suppressions — tout élément dont la leçon ou la décision ne vit que dans le chat est d'abord distillé dans un fichier suivi, ou reste hors de l'inventaire. Chaque règle de la Phase 2 s'applique inchangée, y compris la porte d'approbation explicite et la règle de quarantaine.

Étape 0 — s'orienter sur CE dépôt (découvrir, sinon planifier pour créer)

Lisez le document d'entrée qui existe — CLAUDE.md / AGENTS.md / README / un index docs/ — et découvrez six choses. Utilisez ce que vous trouvez ; là où quelque chose est absent, notez-le comme un trou que cette fermeture comblera (chaque phase ci-dessous explique comment), n'inventez jamais un chemin qui n'existe pas.

1. Enregistrement des leçons/décisions — où ce dépôt archive-t-il les décisions ? (CHANGELOG, docs/adr/, DECISIONS.md, ou un registre spécifique au dépôt.) Si aucun, la Phase 1 crée un seul DECISIONS.md.
2. Commande de téléversement confirmée — une étape de push délibérée (bin/sync, make deploy, une discipline documentée git push) ? Si oui, c'est LE canal de téléversement ; ne le contournez jamais. Si aucun, la Phase 3a utilise git push simple après un diffstat + confirmation.
3. Commande d'amorçage — comment un clone frais prend-il vie ? (bin/bootstrap, bin/sync-setup, install.sh, make setup, une installation via gestionnaire de paquets.) Si aucun, la Phase 4 en crée un.
4. Commande de test — à partir de la configuration CI, des scripts package.json, d'un Makefile, ou de la valeur par défaut du langage (pytest / go test / cargo test / npm test). Si rien n'est détectable, le dépôt n'a pas encore de suite exécutable : traitez cela comme un état explicite ci-dessous — ne le lisez jamais comme « vert », ne REFUSEZ jamais un dépôt qui n'en a légitimement pas.
5. Compétence de porte / validation — une compétence de validation produit ou de pré-construction ? Si oui, sa liste de vérification « après-construction » est votre porte de pré-fermeture. (Les portes spécifiques au produit vivent dans le dépôt produit ; ce skill reste générique et s'en remet à elles.)
6. Répertoires de données / récupération / quarantaine déclarés — répertoires que le document d'entrée nomme comme contenant des données réelles, du matériel de récupération ou des fichiers en quarantaine. Ceux-ci sont exemptés de toute règle « les répertoires en forme d'archive ne doivent pas exister » ci-dessous et ne doivent jamais apparaître dans un inventaire de suppression.

Refuser de s'exécuter (fermé en cas d'échec)

Ne fermez pas en milieu d'itération — vous perdez la peau ET la chair. REFUSEZ (dans les deux modes d'exécution) si : le répertoire n'est pas un dépôt git (arrêtez et dites-le — exécuter git init est la décision de l'utilisateur) ; la suite de tests existe et ÉCHOUE réellement (une suite absente n'est pas une suite qui échoue — voir Étape 0.4) ; une porte adverse, si le dépôt en a une, est en attente ou CHANGEMENTS-REQUIS ; ou un autre agent/voie a du travail non commité en milieu de tranche dans des chemins que vous toucheriez. Dites ce qui bloque et arrêtez.

Lors d'une fermeture complète, exécutez les phases DANS L'ORDRE. Chacune a un test de sortie ; ne passez jamais au-delà d'une sortie échouée.

Phase 1 — DISTILLER (porte de récupération : rien ne meurt avant que sa leçon ne soit archivée)

1. Balayez les décisions nées dans le chat de cette itération vers le registre de décisions du dépôt (Étape 0.1), chacune avec son statut et sa source. Si le dépôt n'archive encore les décisions nulle part, créer le registre fait partie de cette phase — un seul DECISIONS.md à la racine du dépôt suffit. Une décision qui n'existe que dans une fenêtre de chat n'existe pas ; ne laissez pas de décisions distillées sans domicile suivi.
2. Nouvelles invariants/règles découvertes cette itération → vers le fichier de contrats du dépôt, ou à défaut le registre de décisions — idéalement chacune sous forme de test. Si aucun n'existe, créez le registre de décisions et mettez-les là. Supprimez l'artefact, gardez l'invariant.
3. Vérification des capacités uniquement session : cette itération a-t-elle dépendu de quoi que ce soit qui ne vit QUE dans une invite, un bloc-notes ou la mémoire de quelqu'un ? Promouvez-le dans le dépôt (code / compétence / doc) ou enregistrez son exclusion délibérée. Nommez chacun explicitement — c'est là que les pipelines meurent.
4. Si la STRUCTURE a changé, mettez à jour — ou, si aucune n'existe et que la structure est maintenant non triviale, créez — une courte note d'architecture/système pour qu'elle décrive toujours la réalité. Mettez à jour tout tableau de bord (par exemple un document de progression) si le dépôt en a un.

TEST DE SORTIE : grep les décisions et invariants clés de cette itération dans le dépôt — chacun trouvable dans un fichier suivi. Tout trouvable uniquement dans le chat = Phase 1 pas terminée.

Phase 2 — SUPPRIMER (suppression impitoyable ; l'historique git est le SEUL archive)

1. Construisez un inventaire de suppression avec preuves, une ligne chacun : chemin | pourquoi mort | qu'est-ce qui le remplace. Couvrez les modules/spécifications remplacés, les répertoires morts/vides, les résidus de développement (fichiers temporaires, déchets de type mktemp, lignes de test dans des magasins de forme réelle), les docs de planification/TODO terminés, et les DOCS OBSOLÈTES — effectuez une passe de contradiction docs vs code ; un doc qui affirme ce que le code contredit est pire qu'aucun. Marquez chaque ligne SUIVI ou NON SUIVI (git ls-files --error-unmatch <chemin>), car les deux ont des sorts différents (règles 3 et 4).
2. Présentez l'inventaire COMPLET à l'utilisateur et attendez un oui explicite avant de supprimer quoi que ce soit. L'approbation partielle est acceptable — agissez uniquement sur les lignes approuvées. L'agent n'appuie jamais seul sur des boutons irréversibles ; « l'utilisateur a demandé un nettoyage » autorise la construction de la liste, pas son exécution.
3. Fichiers suivis : git rm seulement. PAS de répertoires _archive/, PAS de .bak, PAS de renommages old-/legacy-, PAS de cadavres commentés. Récupération = historique git, à un git revert — c'est l'archive ; un commit de point de contrôle avant la suppression le rend à toute épreuve.
4. Fichiers non suivis ou gitignorés : JAMAIS rm directement — l'historique git ne peut pas récupérer ce qui n'a jamais été commité. C'est la ligne de sécurité des données. Déplacez-les plutôt dans le répertoire de quarantaine déclaré du dépôt (Étape 0.6). Si aucun n'est déclaré, créez-en un maintenant : .iteration-quarantine/ à la racine du dépôt, ajouté à .gitignore, déclaré dans le document d'entrée avec une ligne (« quarantaine pour fichiers non suivis en attente de suppression — vidé manuellement par l'utilisateur »). Vider la quarantaine est l'acte de l'utilisateur — proposez-le lors d'une future fermeture, avec son propre oui explicite ; jamais en silence.
5. Ne supprimez jamais les DONNÉES réelles du produit comme s'il s'agissait de résidus de développement. L'état des utilisateurs/clients, les sessions sauvegardées, les archives réelles de contenu utilisateur ressemblent à du fouillis mais sont l'âme du produit. Lorsqu'un répertoire pourrait être l'un ou l'autre, traitez-le comme des données et conservez-le ; vérifiez avant tout git rm.
6. Committez les suppressions en groupes thématiques ; chaque message dit POURQUOI + ce qui les remplace.
7. Vérifications post-suppression (toutes celles qui s'appliquent doivent passer) : si le dépôt a une suite de tests, elle est verte ; le grep de références pendantes pour chaque module/symbole supprimé est vide (une importation d'un fichier supprimé plante au démarrage — une vraie cicatrice) ; le document d'entrée et les docs de compétences ne référencent aucun chemin supprimé.

TEST DE SORTIE : git status propre, aucun répertoire en forme d'archive n'existe — sauf les répertoires que le document d'entrée déclare comme données, récupération ou quarantaine (Étape 0.6) — grep de références pendantes vide, et la suite de tests verte si elle existe.

Phase 3 — DEUX CANAUX DE PRÉPARATION (besoins différents ; vérifiez séparément)

Téléverser et être-continuable ne sont PAS le même problème. Les confondre, c'est ainsi qu'un dépôt est « poussé vers le cloud » alors que son état réel vit encore dans un journal de chat. Vérifiez chacun séparément.

3a. Téléversement cloud confirmé (le problème de TRANSPORT)

1. Scan de secrets sur les fichiers SUIVIS uniquement (sk-ant / ghp_ / gho_ / github_pat / AKIA / xox[baprs] / consumer_secret / access_token / Bearer / BEGIN PRIVATE KEY / formes .env). Tout résultat → arrêtez, nettoyez, re-scanner.
2. Vérifiez git remote. S'il n'y a PAS de remote, le téléversement en a besoin d'un que l'UTILISATEUR fournit — ajouter un remote est un changement de configuration, donc confirmez-le avec l'utilisateur ou enregistrez « pas encore de remote — publication différée » et passez à 3b plutôt que de générer une erreur sur une commande git nue.
3. Avec un remote : montrez git log @{u}..HEAD --oneline + diffstat (utilisez « tous les commits locaux » quand il n'y a pas encore d'amont) — exactement ce qui quittera cette machine.
4. Téléversez via la commande de téléversement confirmée du dépôt (Étape 0.2) après que l'utilisateur a confirmé ; si le dépôt n'en a pas, git push après le diffstat et un oui. Ne poussez jamais automatiquement.

3b. Reprise sans contexte (le problème de COMPLÉTUDE DES CONNAISSANCES) — la sonde de démarrage à froid

1. Obtenez UN lecteur vraiment sans contexte sur le dépôt — dans Claude Code : générez un sous-agent frais (outil Task) ; dans Codex : exécutez un codex exec frais ou une nouvelle session sans contexte antérieur ; sur tout harnais nu : ouvrez une nouvelle session et collez UNIQUEMENT le chemin du dépôt plus les questions, jamais cette conversation. Donnez-lui seulement le chemin du dépôt et : « Lisez ce dépôt à froid à partir de son document d'entrée. Puis répondez : (1) quel est ce produit, en une phrase ; (2) où en est le travail (fait / prochain) ; (3) que feriez-vous ensuite et pourquoi ; (4) nommez trois choses que vous ne devez jamais faire ici. »
2. Notez ses réponses par rapport aux docs canoniques du dépôt. Si le dépôt n'a pas de document d'entrée/canonique du tout, en créer un minimal (le produit en une phrase, état actuel fait/prochain, trois jamais-faire) fait partie de cette fermeture — c'est l'artefact que la sonde évalue. N'exécutez pas la sonde contre rien.
3. Chaque réponse fausse ou manquante est un BUG DE DOC DE REPRISE, pas la faute de la sonde. Corrigez (ou créez) le doc, réexécutez avec un NOUVEAU lecteur frais. Bouclez jusqu'à ce qu'un lecteur à froid obtienne 4/4, limité à 3 tours — si cela échoue encore après 3, listez les lacunes restantes et remettez la décision à l'utilisateur.

TEST DE SORTIE : la sonde passe 4/4. Alors seulement « toute nouvelle fenêtre / machine peut continuer » est un fait testé.

Phase 4 — AMORÇAGE EN UNE COMMANDE (répété, pas supposé)

1. Assurez-vous que l'amorçage du dépôt (Étape 0.3) existe et est à jour — idempotent, sûr à réexécuter : vérifiez les versions de la chaîne d'outils ; câblez la synchronisation/config ; installez les dépendances ; exécutez la suite de tests si elle existe ; affichez le statut actuel + les NOMS de tous les secrets locaux manquants (jamais les valeurs, par exemple « config.local.json absent — nécessaire uniquement pour la publication en direct ») ; sortez non nul en cas d'échec avec une raison en une ligne. Si aucun amorçage n'existe encore, cette itération est celle pour en créer un.
2. RÉPÉTEZ-LE : clonez le dépôt dans un répertoire temporaire (à partir de l'URL d'origine, ou du chemin du dépôt local quand il n'y a pas encore de remote) et exécutez l'amorçage là. Il doit se terminer en vert avec ZÉRO étapes manuelles. Supprimez le clone de répétition après.
3. L'histoire de la nouvelle machine doit être une ligne et VRAIE après cette répétition : git clone <origin-url> <dir> && cd <dir> && <commande d'amorçage>. Si aucun remote n'existe encore, notez que cette ligne n'est pas encore vraie tant que l'utilisateur n'en a pas défini un — ne la publiez pas comme si elle fonctionnait.

TEST DE SORTIE : le clone de répétition s'amorce en vert, sans intervention humaine.

Phase 5 — FERMETURE + ENSEMENCEMENT (continuité)

1. Taguez l'itération : git tag iter-<N>-<slug> (annoté, résumé en une ligne). N = 1 + le nombre de tags iter-* existants (git tag --list "iter-*") ; la première fermeture est iter-1.
2. Mettez à jour le tableau de bord / journal avec une ligne, si le dépôt en a un : ce qui a été distillé, combien de fichiers supprimés, sonde 4/4, amorçage répété.
3. Émettez LA GRAINE DE LA PROCHAINE ITÉRATION dans le chat : les questions ouvertes que cette itération a soulevées + une invite de lancement prête à coller pour la prochaine tranche (objectif, critères d'acceptation, et un rappel d'exécuter la porte de validation du dépôt avant de construire, si elle en a une).

Itération majeure — quand la STRUCTURE elle-même est remplacée (mêmes règles, peau plus grande)

Une refonte structurelle — nouvelle architecture, nouvel arbre de modules, même « l'ancienne approche était erronée » — reste une ITÉRATION d'un seul organisme, pas un redémarrage. Elle garde son historique git, ses décisions, ses leçons ; seule la peau est nouvelle. Les redémarrages saignent : chaque fois qu'un projet renaît dans un nouveau dépôt, du matériel de niveau leçon est laissé derrière. Donc :

• Développez la nouvelle structure DANS CE DÉPÔT aux côtés de l'ancienne (modèle étranglement) : le nouvel arbre gagne d'abord les tests et la propriété ; l'ancien arbre meurt dans la Phase 2 seulement une fois que rien ne le référence.
• Ouvrir un NOUVEAU dépôt est l'exception coûteuse, pas la valeur par défaut — cela nécessite une décision enregistrée indiquant POURQUOI cet historique doit être abandonné, approuvée avant tout déplacement de fichier.
• Mêmes cinq phases ; l'inventaire de suppression est juste plus grand et la sonde de démarrage à froid importe davantage — les docs de la nouvelle structure n'ont jamais rencontré d'étranger.
• Si le nom du produit ou la commande d'entrée change, l'histoire en une ligne de la Phase 4 est mise à jour dans la MÊME itération. Deux noms vivants est un bogue de double vérité.

Garde-fous (non négociables)

• L'ordre des phases est le mécanisme de sécurité : NE supprimez JAMAIS (Phase 2) avant que distiller (Phase 1) ne soit terminé — en mode suppression seule, la vérification ponctuelle de la Phase 1 sur l'inventaire est cette porte.
• L'inventaire de suppression complet est montré à l'utilisateur, et RIEN n'est supprimé sans son oui explicite. L'agent n'appuie jamais seul sur des boutons irréversibles.
• Les fichiers non suivis ou gitignorés sont mis en quarantaine, jamais rm — l'historique git ne peut pas les récupérer.
• La suppression nécessite des preuves de remplacement, pas des impressions. Vraiment incertain ? Gardez-le UNE itération de plus et enregistrez le doute dans le registre de décisions.

Philosophie opérationnelle (le « pourquoi » derrière les règles)

• Une dépense de temps ici = économie de temps ailleurs. La distillerie, la répétition d'amorçage et la sonde de reprise à froid prennent du temps de session. C'est le but. Si une fermeture prend 60 secondes, vous ne faites probablement qu'appuyer sur un bouton ; la valeur est dans la friction — la découverte que le bootstrap ne fonctionne pas, qu'un doc ment, qu'une décision vit encore dans votre dernier chat.
• L'historique git est la seule archive. Pas de dossiers _archive, pas de branches mortes « de sauvegarde », pas de fichiers renommés old-. L'historique git a des outils de parcours, des blâmes, des revert — chaque autre format pourrit. Faites confiance à git ; formez l'équipe à s'y fier.
• La sonde de reprise à froid trouve les trous que les humains normalisent. Les gens qui vivent dans un codebase lissent ses aspérités dans leur tête. Un lecteur sans contexte frais ne le fait pas — il tombe dans chaque trou que vous avez appris à enjamber. Gardez l'investissement dans ce choc cognitif.
• La suppression donne de l'oxygène. Garder du code mort « juste au cas où » est plus coûteux que de le récupérer depuis git. Le code mort est un bruit de signal dans chaque recherche, tue le moral, et — pire — fait croire aux nouveaux arrivants que deux chemins également valides existent. Supprimer la branche est la réponse.
• Le mode suppression seule existe pour les humains. Parfois, l'utilisateur veut juste nettoyer. Ne les forcez pas à un rituel complet quand ils ont ouvert une session pour une chose rapide. Mais ne laissez pas non plus des décisions mourir dans le chat — la vérification ponctuelle de la Phase 1 sur l'inventaire est la porte de sécurité minimale.