zflow

Un ensemble de compétences pour Agent de développement logiciel, conçu pour les ingénieurs de stockage distribué.

Qu'est-ce que zflow ?

Ce pack de compétences (skill) pour agents IA est spécialement conçu pour les ingénieurs en stockage distribué. Il fournit un cadre structuré pour documenter et gérer les cycles de changement logiciel, de la planification à la validation. Le cœur du pack est le concept de "Stage", un document central qui relie tous les artefacts produits lors d'un cycle de modification (missions, spécifications, contrats de tâches, décisions architecturales, résultats de tests). Il définit un cycle de vie clair pour chaque Stage (création, remplissage, finalisation, vérification) avec des modèles, des listes de vérification et des règles d'interaction entre les compétences (par exemple, comment les contrats de tâches délégués s'intègrent ou comment les ADR sont obligatoires). L'objectif est d'améliorer la traçabilité, la reproductibilité et la communication au sein des équipes de développement de systèmes complexes, en capturant non seulement ce qui a été fait, mais aussi pourquoi et quels écarts ont eu lieu.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add 13eholder/zflow

Installed? Explore more Productivité et collaboration skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Stage

Présentation

Stage est un document de liaison d'un cycle de modifications logicielles. Il ne remplace aucun artefact produit par d'autres compétences, mais enregistre ce que chaque compétence a produit, les relations entre ces produits et l'histoire complète de ce cycle de modifications.

Stage répond à quatre questions :

  1. Qu'allions-nous faire ? (MISSION + documents normatifs)
  2. Comment le travail d'implémentation a-t-il été délégué en toute sécurité ? (Index direct des contrats de tâches)
  3. Qu'avons-nous réellement accompli ? (Documents descriptifs + ADR)
  4. Pourquoi y a-t-il des écarts ? (Écarts entre le normatif et le descriptif + résumé des enseignements)
                          STAGE.md
                   (Couche de liaison / Index + Narration)
                          |
    +--------+--------+----+----+------------+--------+--------+
    |        |             |    |            |        |        |
  MISSION   Documents     Plan   Contrats de   Documents  Vérification
  (Objectif) normatifs   (plan+todo) tâches    descriptifs (Preuve)
                                                |
                                              ADR
                                      (Obligatoire, au moins un par Stage)

Quand l'utiliser

La création d'un Stage est entièrement décidée par l'utilisateur. Un Stage n'est créé que sur demande explicite de l'utilisateur, sans déclenchement automatique.

L'utilisateur initie généralement ainsi :

  • "Créer un Stage" / "Démarrer un Stage"
  • "Créer un Stage pour ce cycle de travail"
  • "Finaliser le Stage" / "Sceller le Stage"
  • Après la sortie du plan /plan, l'utilisateur répond "oui" à la question "Un document Stage est-il nécessaire ?"

Cas d'usage typiques (à titre indicatif pour l'utilisateur, pas de règle de déclenchement) :

  • Changement couvrant plusieurs tâches, formant un tout logique
  • Nouvelle fonctionnalité couvrant plusieurs modules
  • Refactorisation modifiant la structure interne mais pas le comportement
  • Chaîne de correction complète d'un défaut en production
  • Tout changement nécessitant d'enregistrer une décision architecturale

Ne se déclenche pas automatiquement :

  • Une tâche unique et isolée ou un changement mécanique ne crée pas automatiquement de Stage
  • Une mise à jour purement documentaire ne crée pas automatiquement de Stage
  • L'agent ne juge pas par lui-même en fonction du nombre de tâches ou de l'étendue multi-module ; la confirmation de l'utilisateur est nécessaire

Même si delegated-task-contract a besoin d'un Stage parent, il ne doit pas déclencher automatiquement la création du Stage ; s'il n'y a pas encore de Stage, il doit s'arrêter et demander explicitement à l'utilisateur. L'appartenance au répertoire, l'index unidirectionnel, la synchronisation d'état et le contrôle de verrouillage de la finalisation suivent tous les règles d'intégration Stage et Contrat de Tâche.

Types de Stage

TypeMotivationCritères de succèsNormatif vs DescriptifAccent documentaire
featAjouter une nouvelle capacitéNouveau comportement apparaît et est conforme aux spécificationsLes écarts sont normaux, doivent être enregistrésspec + api-contract + api-doc
optAméliorer un comportement existantLes métriques atteignent les valeurs ciblesEnregistrer brièvement la comparaison des résultats d'optimisationBaseline de performance + Résultats d'optimisation
debugCorriger un comportement erronéLe problème ne se reproduit pas + les tests de régression couvrent le chemin de la cause racineNormatif = Descriptif (la correction est l'objectif)Phénomène + Cause racine + Stratégie de correction + Mesures préventives
refactorModifier la structure interne, le comportement reste inchangéTous les comportements existants restent inchangés, les tests de régression sont tous vertsNormatif = Descriptif est une exigence stricteConception architecturale + Description du changement de structure

Cycle de vie d'un Stage

/plan sortie                 Pendant l'implémentation          Implémentation terminée        Lors de l'exécution /ship
     |                          |                            |                      |
     v                          v                            v                      v
  Créer le squelette      Maintenir la doc & Index     Finaliser STAGE.md        Vérifier l'existence
  (MISSION +              des contrats                   (Contrôle final,       du Stage
   chemins des doc.       (État, écarts,                Doc. descriptive,       (pré-lancement
   normatives,            résumé des preuves)           ADR, analyse des        liste de contrôle
   lien du plan                                             écarts,                blocage)
   d'implémentation)                                        résultats de vérification,
                                                             résumé des
                                                             enseignements)

Création (phase de squelette)

Après que /plan a produit tasks/plan.md et tasks/todo.md, l'agent demande à l'utilisateur s'il a besoin d'un document Stage. Après confirmation de l'utilisateur :

  1. Créer le répertoire stages/<stage-id>/ (stage-id est un titre court en kebab-case)
  2. Créer le squelette STAGE.md, pré-rempli avec :
    • Type (feat | opt | debug | refactor)
    • Statut défini sur draft
    • Décideur
    • MISSION (extrait de la spec)
    • Chemins des documents normatifs (marqués comme TODO)
    • Liens vers le plan d'implémentation (insérer tasks/plan.md et tasks/todo.md)
    • Table d'index direct des contrats de tâches (vide initialement)
    • Documents descriptifs (marqués comme TODO — à remplir après l'implémentation)
    • ADR (marqués comme TODO — au moins un par Stage, à remplir après l'implémentation)
    • Résultats de vérification (marqués comme TODO)
  3. Ajouter une ligne dans stages/INDEX.md

Remplissage (phase de construction)

Pendant l'implémentation :

  • Les tâches normales terminées ne nécessitent pas de modification de STAGE.md ; cependant, la synchronisation est obligatoire lors du premier enregistrement d'un contrat, d'un changement d'état ou d'un retour de déviation / preuve.
  • Lorsque des documents normatifs (spec, api-contract) sont produits, mettre à jour les liens correspondants et supprimer la marque TODO.
  • Les contrats ne sont indexés que par l'index direct de STAGE.md ; n'ajoutez pas de champ Stage ou de lien retour dans le contrat.
  • Les déviations de contrat non none sont synchronisées dans le tableau "Écarts normatif vs descriptif", sans attendre la finalisation pour les écrire de mémoire.

Finalisation (après implémentation)

Une fois toutes les tâches terminées et la vérification réussie, l'agent rappelle à l'utilisateur de finaliser. Après confirmation de l'utilisateur :

  1. Vérifier task-contract/ contre la table d'index pour s'assurer qu'il n'y a pas d'omission, de lien mort ou de dérive d'état.
  2. Confirmer que tous les statuts du corps des contrats sont COMPLETED ou CANCELLED ; tout DRAFT, READY ou BLOCKED_BY_ARCHITECTURE empêche la finalisation.
  3. Remplir les liens vers les documents descriptifs (api-doc, ADR).
  4. Remplir le tableau des écarts normatif vs descriptif (y compris la colonne "Mise à jour rétroactive du document normatif ?"), en incluant toute déviation significative signalée par les contrats.
  5. Remplir les résultats de vérification et lier les Preuves requises des contrats.
  6. Distiller le résumé des enseignements ("À faire la prochaine fois" et "À éviter la prochaine fois").
  7. Changer le statut en done.
  8. Mettre à jour la ligne correspondante dans stages/INDEX.md.

Vérification (avant publication)

La liste de contrôle pré-lancement de /ship inclut :

  • "☐ Les changements majeurs ont-ils un document Stage correspondant ?" — Si un Stage a été créé pour ce cycle de travail, c'est un élément bloquant.

Modèle de Stage

Voici le modèle standard pour stages/<stage-id>/STAGE.md :

# Stage : [Titre court]

**Type**: feat | opt | debug | refactor
**Dates**: AAAA-MM-JJ — AAAA-MM-JJ
**Statut**: draft | in-progress | done | abandoned | superseded | split
**Décideur**: @nom_utilisateur

---

## MISSION (Objectif de ce cycle)

<!-- feat / opt / refactor utilisent le format MISSION standard -->

- **Objectif**: [Décrire en une phrase ce que ce cycle doit accomplir]
- **Utilisateurs**: [Qui en bénéficiera]
- **Critères de succès**: [Comment savoir si c'est fait — conditions spécifiques et vérifiables]
- **Contraintes**: [Limitations contraignantes — techniques, de ressources, de temps]
- **Non fait**: [Éléments explicitement exclus et pourquoi]

<!-- Le type debug remplace par la structure suivante : -->
<!--
- **Phénomène**: [Ce que l'utilisateur a fait, ce qu'il a vu, ce qu'il aurait dû voir]
- **Impact**: [Périmètre d'impact, durée, risque d'intégrité des données]
- **Hypothèse de cause racine**: [Première évaluation — mise à jour après confirmation de la cause racine lors de l'implémentation]
- **Stratégie de correction**: [Solution d'arrêt d'urgence + Correction de la cause racine + Mesures préventives]
- **Critères de succès**: [Le problème ne se reproduit pas, les tests de régression couvrent le chemin de la cause racine, les problèmes similaires ont une vérification statique]
-->

→ Voir [MISSION.md](./MISSION.md)

---

## Documents normatifs (Comment nous prévoyions de faire)

| Document | Compétence source | Description |
|----------|-------------------|-------------|
| [spec/xxx.md](./spec/xxx.md) | spec-driven-dev | Spécifications fonctionnelles |
| [design/api-contract.md](./design/api-contract.md) | api-and-interface | Contrat d'API |
| [design/xxx.md](./design/xxx.md) | — | [Description complémentaire] |

> Remplir avant le début de l'implémentation. Si un type de document n'est pas concerné par ce cycle, supprimer la ligne correspondante.

---

## Plan d'implémentation

| Document | Compétence source | Description |
|----------|-------------------|-------------|
| [tasks/plan.md](./tasks/plan.md) | planning-and-task | Plan technique |
| [tasks/todo.md](./tasks/todo.md) | planning-and-task | Liste des tâches atomiques |

---

## Contrats de tâches (Limites de délégation d'exécution)

> Indexe uniquement les délégations en écriture nécessitant le contrôle `delegated-task-contract`. Le corps du contrat, le statut et les preuves requises sont basés sur le fichier correspondant ; ce tableau ne conserve que les liens directs et les résumés, et n'écrit pas de lien retour du Stage vers le contrat.

| Tâche | Contrat | Statut | Déviation / Preuve |
|-------|---------|--------|--------------------|
| [ID de tâche] | [ID de tâche](./task-contract/TASK-XXX.md) | DRAFT \| READY \| BLOCKED_BY_ARCHITECTURE \| COMPLETED \| CANCELLED | [Blocage, déviation, preuve ou raison d'annulation ; sinon écrire `—`] |

> Conserver l'en-tête du tableau et supprimer la ligne d'exemple s'il n'y a pas encore de contrat. Synchroniser ce tableau lors du premier enregistrement d'un contrat et à chaque changement de statut, de déviation ou de preuve.

---

## Documents descriptifs (À quoi cela ressemble en réalité)

> Remplir cette section après l'implémentation.

| Document | Compétence source | Description |
|----------|-------------------|-------------|
| [docs/api/xxx.md](./docs/api/xxx.md) | documentation-and-adrs | Documentation réelle de l'API |
| [docs/adr/XXX-titre.md](./docs/adr/XXX-titre.md) | documentation-and-adrs | Enregistrement de décision architecturale (obligatoire, au moins un par Stage) |

### ADR (Obligatoire)

Chaque Stage **doit** produire au moins un ADR. Les ADR enregistrent les décisions architecturales clés et leur contexte.

| ADR | Décision | Alternatives |
|-----|----------|--------------|
| [ADR-XXX](./docs/adr/XXX.md) | [Décrire la décision en une phrase] | [Solutions rejetées et raisons] |

**Exigences de contenu des ADR :**
- Enregistrer "Pourquoi A a été choisi plutôt que B"
- Lister les alternatives considérées et rejetées, avec les raisons du rejet
- Décrire les contraintes et les conséquences de la décision
- Si la décision est liée à un ADR existant, le référencer explicitement

**Centrage des ADR par type de Stage :**

| Type de Stage | Contenu typique de l'ADR |
|---------------|--------------------------|
| **feat** | Pourquoi cette architecture / framework / protocole a été choisi ; compromis de conception du modèle de données |
| **opt** | Pourquoi cette stratégie d'optimisation a été choisie ; pourquoi d'autres solutions n'ont pas été retenues (ex : cache vs optimisation d'index) |
| **debug** | Pourquoi la cause racine s'est produite ; pourquoi cette solution de correction a été choisie ; conception des mesures préventives |
| **refactor** | Pourquoi cette nouvelle structure a été choisie ; pourquoi certains cas limites n'ont pas été unifiés ; comparaison entre l'ancienne et la nouvelle structure |

---

## Écarts normatif vs descriptif

> Remplir après l'implémentation. Enregistrer tout écart significatif entre le plan et la réalité.

Lorsque le rapport `Required Evidence` d'un contrat signale une déviation non `none`, synchroniser cette déviation dans ce tableau tout en validant le contrat ; ne pas laisser la trace uniquement dans le contrat.

| Écart | Normatif (Plan) | Descriptif (Résultat) | Raison | Mise à jour rétroactive du document normatif ? |
|-------|-----------------|-----------------------|--------|-----------------------------------------------|
| [Brève description] | [Ce qui était prévu] | [Ce qui a été fait] | [Pourquoi l'écart] | Oui / Non |

**Explication de la colonne "Mise à jour rétroactive du document normatif ?" :**
- **Oui** : L'écart est considéré comme une direction de conception correcte, les spécifications ou le contrat d'API ont été modifiés a posteriori pour correspondre au résultat réel.
- **Non** : L'écart est un compromis temporaire ou un pis-aller, le document normatif reste inchangé pour référence lors des prochains Stages.
- Les lignes marquées "Non" sont candidates pour le backlog du prochain cycle.

---

## Résultats de vérification

| Élément de vérification | Statut | Preuve |
|-------------------------|--------|--------|
| [Critère d'acceptation 1] | ✅ / ❌ | [Rapport de test, données de performance, capture d'écran, etc.] |
| [Critère d'acceptation 2] | ✅ / ❌ | [Preuve] |
| Aucune régression | ✅ / ❌ | Lien vers l'exécution CI |

→ Voir [VERIFY.md](./VERIFY.md)

---

## Résumé des enseignements

> Remplir lors de la finalisation. Pas plus de deux phrases.

- **À faire la prochaine fois** : [Ce qui a été bien fait dans ce cycle — digne d'être réutilisé dans d'autres Stages]
- **À éviter la prochaine fois** : [Ce qui a été mal fait dans ce cycle — à éviter, à surveiller ou à améliorer]

---

## Liens

- **Stage précédent**: [STAGE-XXX](../stage-XXX/STAGE.md) (ou "Aucun")
- **Planification du prochain cycle**: [Brève description, ou "Aucun"]

Ajouts incrémentaux (après finalisation)

Après la finalisation d'un Stage (statut passé à done), si de petits problèmes doivent être corrigés sans constituer un nouveau Stage, une section d'ajout incrémental peut être ajoutée à la fin de STAGE.md :

---

## Ajout incrémental 1 (2026-07-28)

- **Changement**: [Décrire brièvement ce qui a été corrigé]
- **Raison**: [Pourquoi cette correction était-elle nécessaire après la finalisation ?]
- **Périmètre d'impact**: [Quels fichiers / modules]

Lors de l'ajout d'incréments :

  • Le statut du Stage reste done, ne revient pas à in-progress
  • Les entrées incrémentales sont ajoutées par ordre chronologique
  • Si la correction implique une nouvelle décision ADR, l'ajouter au tableau ADR des documents descriptifs et la marquer [Ajout incrémental 1]
  • Lorsque le nombre d'ajouts incrémentaux atteint 3 ou plus, envisager la création d'un nouveau Stage plutôt que de continuer à ajouter.

INDEX.md

stages/INDEX.md est le point d'entrée de navigation pour tous les Stages. Il est maintenu lors de la création et de la finalisation de chaque Stage.

# Index des Stages

| ID | Titre | Type | Statut | Modules concernés | Dates |
|----|-------|------|--------|-------------------|-------|
| 001 | raft-election-optimization | opt | done | consensus, rpc | 2026-07-15 — 2026-07-17 |
| 002 | wal-checksum-verification | feat | done | storage, wal | 2026-07-18 — 2026-07-20 |
| 003 | replica-sync-refactor | refactor | done | replication, net | 2026-07-22 — 2026-07-23 |
| 004 | multi-az-placement | feat | abandoned | placement, scheduler | 2026-07-23 |

Règles de maintenance :

  • Ajouter une ligne lors de la création d'un Stage, avec le statut draft
  • Mettre à jour le statut en done lors de la finalisation d'un Stage
  • Mettre à jour le statut lorsque le Stage passe à abandoned, superseded ou split
  • La colonne Modules concernés répertorie les modules/répertoires de premier niveau affectés, pour une recherche par module.

Modèle des statuts

StatutSignificationQuand l'utiliser
draftSquelette créé, implémentation pas encore commencéeAprès la création du Stage
in-progressEn cours d'implémentationPendant l'implémentation (optionnel)
doneTerminé comme prévu, finaliséToutes les tâches terminées, vérification réussie, résumé des enseignements écrit
abandonedAbandonné en cours de routeMauvaise direction, demande annulée, interrompu par une priorité plus élevée
supersededRemplacé par un autre StageLe périmètre du Stage-B a englobé celui du Stage-A
splitDivisé en plusieurs Stages plus petitsStage trop grand, divisé en sous-Stages indépendants

Traitement de abandoned :

  • Mettre à jour la section MISSION, ajouter un paragraphe "Raison de l'abandon"
  • Conserver au moins un ADR dans le tableau ADR, enregistrant "Pourquoi ne pas continuer ?"
  • Remplir le résumé des enseignements normalement — les leçons de l'abandon sont souvent plus précieuses que celles du succès.
  • Les parties de code/documentation déjà terminées dans le Stage abandonné doivent-elles être annulées ? La décision appartient au décideur et doit être enregistrée dans l'ADR.
  • Dans la section Liens, remplacer le champ "Planification du prochain cycle" par "Aucun (abandonné)".

Traitement de superseded :

  • Mettre à jour la section MISSION, ajouter un paragraphe "Remplacé par quel Stage et pourquoi"
  • Dans la section Liens, ajouter "Remplacé par : STAGE-XXX"
  • Changer le statut en superseded
  • Ne pas ajouter d'incréments au Stage remplacé ; tout travail ultérieur est transféré vers le Stage de remplacement.

Traitement de split :

  • Mettre à jour la section MISSION, ajouter un paragraphe "Divisé en quels sous-Stages et pourquoi"
  • Dans la section Liens, ajouter "Divisé en : STAGE-XXX, STAGE-YYY"
  • Changer le statut en split
  • Le Stage original ne reçoit plus d'incréments ; tout travail est transféré vers les sous-Stages.

Structure du répertoire

stages/
  INDEX.md                      ← Index, une ligne par Stage
  001-raft-election-optimization/
    STAGE.md                    ← Document de liaison du Stage
    MISSION.md                  ← Description détaillée de l'objectif (optionnelle, recommandée pour les projets complexes)
    spec/                       ← Normatif : spécifications fonctionnelles
    design/                     ← Normatif : contrat de protocole, disposition des données
    tasks/
      plan.md                   ← Plan d'implémentation
      todo.md                   ← Liste des tâches
    task-contract/              ← Limites de délégation d'exécution, au même niveau que tasks/spec
      TASK-001.md
      TASK-002.md
    docs/
      protocol/                 ← Descriptif : documentation du protocole, interfaces RPC
      adr/                      ← Descriptif : enregistrements de décisions architecturales (obligatoire)
    verify/                     ← Preuves de vérification
      fault-injection-report.md
      consistency-check.txt
      perf-before-after.json
  002-wal-checksum/
    ...
    ...

Hormis le chemin d'appartenance des contrats de tâches, la structure du répertoire est un modèle recommandé. La contrainte principale est : STAGE.md doit exister, chaque Stage doit contenir au moins un ADR ; s'il existe des contrats de tâches, ils doivent se trouver dans le répertoire task-contract/ de ce Stage et être indexés directement par STAGE.md.

Interactions avec d'autres compétences

CompétenceMode d'interaction
spec-driven-developmentLa MISSION du Stage est extraite de l'Objectif de la spec.
planning-and-task-breakdownAprès la sortie de /plan, l'agent demande si un squelette de Stage doit être créé.
delegated-task-contractLes contrats sont sauvegardés dans le répertoire task-contract/ du Stage en cours ; STAGE.md indexe unidirectionnellement leur statut, leurs déviations et leurs preuves, le contrat n'indexe pas le Stage en retour.
api-and-interface-designLes contrats de protocole (gRPC/protobuf) dans les documents normatifs et les documents d'interface dans les documents descriptifs sont tous liés au Stage.
failure-injection-testingLorsque la tolérance aux pannes et la récupération après sinistre sont concernées, le plan d'injection de défauts et le rapport d'expérience de chaos sont liés aux documents descriptifs du Stage.
consistency-and-durability-verificationLorsque le stockage ou la réplication d'état sont concernés, le rapport de vérification de la cohérence/durabilité est lié aux résultats de vérification du Stage.
processus d'implémentation natif de l'agentLorsque toutes les tâches sont terminées et vérifiées, l'agent rappelle de finaliser le Stage.
documentation-and-adrsL'ADR est un résultat obligatoire du Stage ; chaque Stage doit en avoir au moins un.
shipping-and-launch/ship vérifie l'existence du Stage (si un Stage a été créé pour ce cycle, c'est bloquant).

Excuses de rationalisation courantes

Excuse de rationalisationRéalité
"Ce changement est trop petit pour avoir besoin d'un Stage."Si le changement est si petit qu'il n'a pas besoin d'un Stage, alors il n'a probablement pas besoin d'un ADR non plus. Mais l'utilisateur a déjà décidé de créer un Stage — faites confiance à son jugement.
"Les besoins sont trop simples, le normatif et le descriptif ne devraient pas diverger."Les écarts sont omniprésents — même le changement le plus simple peut dévier du plan lors de l'implémentation. La valeur fondamentale de Stage est précisément d'enregistrer ces écarts.
"Écrivons d'abord le code, le Stage sera complété après."Un Stage avant la finalisation est un répertoire vivant, il n'a pas besoin d'être écrit en une seule fois. Mais le compléter après coup signifie que l'analyse des écarts dépend de la mémoire — et la mémoire n'est pas fiable.
"Celui-ci n'a pas besoin d'ADR."Chaque Stage a au moins une décision qui mérite d'être enregistrée — ne serait-ce que "Nous avons choisi l'implémentation la plus simple car les contraintes actuelles ne permettaient pas une solution plus complexe."
"C'est déjà abandoned, le résumé des enseignements n'a pas de sens."Les leçons de l'abandon sont souvent plus précieuses que celles du succès. Enregistrer "Pourquoi abandonner" est au moins aussi important que d'enregistrer "Pourquoi réussir".
"Marquer 'Non' dans le tableau des écarts suffit, aucune explication n'est nécessaire."Chaque ligne du tableau des écarts est une entrée pour les décisions futures. Les lignes marquées "Non" disent à la personne suivante : "Il y a une dette technique ici, et elle a été laissée intentionnellement."
"INDEX.md peut être complété plus tard."La valeur d'INDEX.md augmente avec le nombre de Stages — au premier Stage on ne le sent pas, au dixième c'est une nécessité. Maintenez-le dès le début.

Drapeaux rouges

  • Un STAGE.md a été créé mais la MISSION est vide — la valeur du squelette réside dans la MISSION, un Stage sans objectif n'est qu'un espace réservé.
  • Les documents descriptifs contiennent une documentation API mais pas d'ADR correspondant — viole la règle "au moins un ADR par Stage".
  • Le tableau des écarts est vide alors que l'utilisateur a mentionné des écarts lors de l'implémentation — les écarts n'ont pas été capturés.
  • Le résumé des enseignements est "Aucun" ou "Tout s'est bien passé" — chaque Stage a des leçons, si on n'en trouve pas, c'est que la réflexion n'est pas assez profonde.
  • Un Stage abandoned n'a pas de "Raison de l'abandon" — l'information la plus précieuse est perdue.
  • Une ligne dans INDEX.md reste longtemps en statut draft — soit avancer l'implémentation, soit la marquer comme abandoned, ne laissez pas le squelette pourrir.
  • La section des ajouts incrémentaux cumule 3+ entrées sans envisager de diviser en un nouveau Stage — cela indique que l'estimation du périmètre de ce cycle était erronée, il faut réfléchir plutôt que de continuer à ajouter.
  • Le champ Décideur est vide — en travail collaboratif, cela casse la chaîne de traçabilité des décisions.
  • Des fichiers dans task-contract/ ne sont pas indexés par STAGE.md, ou des liens d'index pointent vers des contrats inexistants.
  • Le statut, la déviation ou la preuve d'un contrat ont changé, mais le tableau du Stage conserve encore l'ancien résumé.
  • Un contrat contient un lien retour vers STAGE.md, ce qui entraîne une maintenance bidirectionnelle de la relation d'appartenance.
  • Il reste des contrats en statut DRAFT, READY ou BLOCKED_BY_ARCHITECTURE alors que le Stage est marqué done.

Vérification

Après la création du squelette du Stage :

  • stages/<stage-id>/STAGE.md existe
  • Le type de Stage (feat | opt | debug | refactor) est renseigné
  • Le statut est draft
  • Le décideur est renseigné
  • La MISSION est renseignée (format standard ou debug, selon le type)
  • Les liens du plan d'implémentation pointent vers tasks/plan.md et tasks/todo.md
  • La section "Contrats de tâches (Limites de délégation d'exécution)" et le tableau d'index direct vide sont créés
  • La ligne correspondante a été ajoutée dans stages/INDEX.md

Après la finalisation du Stage :

  • Les liens vers les documents descriptifs sont remplis
  • Au moins un ADR est lié dans le tableau des documents descriptifs
  • Le tableau des écarts normatif vs descriptif est rempli (si aucun écart, écrire explicitement "Aucun écart" et expliquer brièvement pourquoi)
  • Chaque ligne du tableau des écarts est marquée "Mise à jour rétroactive du document normatif ?"
  • Le tableau des résultats de vérification est rempli, chaque élément a un statut et une preuve
  • Chaque contrat dans task-contract/ est indexé directement, et le contrat ne contient pas de champ Stage ni de lien retour
  • Le statut de l'image miroir de l'index correspond au corps du contrat, tous les contrats sont COMPLETED ou CANCELLED
  • Les déviations, les preuves d'achèvement et les raisons d'annulation des contrats sont synchronisées dans le résumé correspondant ou la section des écarts
  • Le résumé des enseignements est rempli (deux phrases, pas vagues)
  • Le statut est passé à done (ou autre état final)
  • Le statut de la ligne correspondante dans stages/INDEX.md a été mis à jour en conséquence

Skills associés