aurumiles/Handoff

Que fait Handoff ?

Ferme une session de travail en écrivant sur disque un fichier que la session suivante lira pour reprendre exactement là où nous nous sommes arrêtés. On l'utilise à la place de /compact, jamais ensemble.

Pourquoi pas /compact

/compact pour écrire le résumé relit toute la conversation, puis remplace l'historique par ce résumé. Le préfixe change, donc le cache déjà construit meurt, et à partir de là chaque tour le reconstruit au-dessus d'un résumé de quarante tours. Cela n'achète pas d'économie, cela achète de la continuité et la fait payer.

Un fichier handoff fait le contraire sur trois fronts :

1. Coûte moins cher. Le fichier fait quelques centaines de tokens en écriture et autant en lecture, et la nouvelle session repart avec un préfixe petit et propre.
2. L'utilisateur choisit ce qui survit. /compact décide tout seul et jette la chose la plus précieuse, à savoir les pistes déjà essayées qui n'ont pas fonctionné. Aucun résumé automatique ne les conserve.
3. Reste sur le disque. La troisième session sur le même travail sait ce qu'ont fait la première et la seconde. Un compact vit et meurt dans sa session.

Procédure

1. Reconstruis toi-même, ne demande pas ce que tu peux voir. Ce qui a été touché, ce qui a été essayé, ce qui a échoué et pourquoi, quelles décisions ont été prises, où on s'est arrêté : tout cela se trouve dans la conversation. Dans un dépôt git, ajoute git status --short et git log --oneline -5.

2. Demande seulement les deux trous que tu ne peux pas déduire. Ce sont l'objectif (ce qu'on construit et pourquoi, pas ce qu'on a fait aujourd'hui) et la prochaine étape souhaitée, qui n'est pas toujours la prochaine étape évidente. S'ils manquent, demande-les en une seule question, avec ton hypothèse déjà incluse, pour qu'il suffise de répondre « oui ». Tout le reste ne se demande pas : si une section est vide, écris aucun et passe à la suite, sans inventer des problèmes résolus qui n'existent pas.

3. Décide où l'écrire. Dans un dépôt de code : docs/handoff/{YYYY-MM-DD}-{slug}.md. Dans un coffre ou un dossier de notes (comme ce projet lui-même, il-tuo-os) : un dossier handoffs/ dans le projet auquel le travail appartient. Le {slug} est deux ou trois mots sur le travail, pas sur la date. Si un handoff avec le même slug existe déjà, ne l'écrase pas : le nouveau fichier incrémente un champ seq et place le précédent dans prev, ainsi la chaîne se lit à rebours.

4. Écris le fichier avec ce frontmatter — type: handoff, date, status, seq, prev, tags — et ces sections, dans cet ordre :

• Objectif : ce qu'on construit et pourquoi, deux ou trois lignes, raison incluse.
• Où nous en sommes : l'état réel maintenant. Ce qui fonctionne, ce qui est à moitié fait, ce qui n'est pas commencé.
• Ce que nous avons essayé qui N'a PAS fonctionné : la section la plus importante du fichier. Chaque piste abandonnée avec le motif. Cela sert à empêcher la session suivante de la réessayer depuis le début.
• Problèmes rencontrés et comment nous les avons résolus : seulement ceux qui se reproduiraient. Symptôme, cause, correction.
• Décisions prises : ce qui a été choisi et ce qui a été écarté, avec une ligne expliquant pourquoi. Une décision sans l'alternative écartée sera rediscutée à zéro la semaine suivante.
• Fichiers touchés : chemins, avec une ligne sur ce qui a changé dans chacun.
• Où nous voulons aller : la prochaine étape, écrite à l'impératif. Puis la suivante, si elle est déjà claire.
• À savoir avant de toucher quoi que ce soit : pièges, commandes à lancer d'une certaine manière, choses qui semblent cassées mais ne le sont pas. S'il n'y en a pas, aucun.

5. Termine en affichant dans le chat la ligne de reprise, prête à être collée dans une nouvelle session : Lis {chemin} et reprends à partir de "Où nous voulons aller". Plus une ligne pour dire qu'à ce stade on peut faire /clear et que la reprise ne coûtera que ce fichier.

Quand NE PAS l'utiliser

Une compétence qu'on utilise toujours est une compétence qu'on utilise au hasard.

• Changement de tâche sans continuité → /clear, aucun handoff n'est nécessaire.
• On a pris une mauvaise piste dans les derniers tours → /rewind, qui revient à un point que le cache connaît déjà.
• On reprend bientôt et sans mises à jour entre-temps → /rename plus /resume.
• Le travail continue un autre jour ou une autre semaine → cette compétence.

Cette compétence ne lance pas /clear à la place de l'utilisateur : elle le suggère seulement.