amadeus-grilling

Que fait amadeus-grilling ?

Objectif

Éliminer l'ambiguïté des plans et des conceptions une par une, grâce à des questions.

Parcourir les branches de l'arbre de conception dans l'ordre, jusqu'à parvenir à une compréhension partagée. Les décisions interdépendantes sont résolues une par une, en démêlant leurs dépendances.

Attitude fondamentale

Les questions doivent être posées avec rigueur. Cependant, l'objectif n'est pas d'augmenter le nombre de questions pour lui-même.

Ne demander que les points sur lesquels l'utilisateur doit nécessairement se prononcer pour avancer. Les réponses pouvant être obtenues à partir de la base de code, des artefacts .amadeus/, de la documentation existante ou des conversations précédentes doivent être vérifiées par vous-même, sans poser de question.

Comment poser les questions

Poser les questions une par une. Poser plusieurs questions à la fois rend difficile de savoir par quelle décision commencer.

Chaque question doit inclure :

• Ce que l'on souhaite décider.
• Pourquoi cette décision est nécessaire maintenant.
• Une réponse recommandée.
• La raison de cette recommandation.

Après avoir posé une question, attendre la réponse de l'utilisateur. Ne pas passer à la question suivante avant d'avoir reçu la réponse.

Réponse recommandée

Chaque question doit obligatoirement être accompagnée d'une réponse recommandée.

La réponse recommandée doit être formulée en tenant compte des artefacts actuels, des limites de conception, des risques de mise en œuvre et de l'impact sur les travaux ultérieurs. Si une recommandation n'est pas possible, en indiquer la raison ainsi que les informations manquantes nécessaires à la décision.

Priorité à la recherche

Si une question peut être répondue en consultant la base de code ou les artefacts, il faut d'abord les consulter.

Exemples d'éléments à consulter :

• .amadeus/
• README.md
• AGENTS.md
• AMADEUS.md
• Les compétences existantes
• Les artefacts d'Intention existants
• Les domaines, glossaires, décisions et traçabilités existants

Ne poser une question que si, après ces vérifications, un jugement humain est encore nécessaire.

Grilling Decision Trail

Lorsqu'une question et une réponse, dans le cadre d'un guided ou refine, affectent le sens d'un artefact ou une décision ultérieure, le processus de décision validé est enregistré en tant que Grilling Decision Trail.

La Grilling Decision Trail n'est pas un journal brut. Les propos non validés, les propositions rejetées en cours de route, les simples autorisations d'exécution, les confirmations légères d'ordre de travail, les confirmations d'exécution de commandes, ou les commodités temporaires d'exécution ne sont pas enregistrés.

Les décisions à enregistrer sont les suivantes :

• Périmètre.
• Conditions de succès.
• Hors périmètre.
• Dépendances.
• Terminologie.
• Contexte borné.
• Stratégie de partitionnement.
• Évaluation d'état.
• Cible de mise à jour.
• Décision de remplacement (supersede).

amadeus-grilling définit les critères d'enregistrement, la structure, l'état et la numérotation. La création ou la mise à jour effective de grillings.md et de grillings/Gxxx-*.md est effectuée par la compétence de phase qui a appelé le grillage.

Ne pas mettre à jour les artefacts dans le tour où une question est posée. Dans le tour suivant la réception de la réponse de l'utilisateur, la compétence de phase interprète la réponse dans les limites de ses propres artefacts, et met à jour la Grilling Decision Trail en même temps que les autres modifications de la phase.

L'emplacement se trouve directement sous la racine de l'ensemble d'artefacts cible.

<racine cible>/
  grillings.md
  grillings/
    G001-<sujet>.md

La racine cible est la suivante :

.amadeus/discoveries/<id-de-la-découverte>/
.amadeus/event-storming/<id-du-event-storming>/
.amadeus/intents/<id-de-l-intention>-<slug>/
.amadeus/intents/<id-de-l-intention>-<slug>/event-storming/<id-du-event-storming>/

La couche de pilotage (Steering layer) est exclue de cette cible d'enregistrement en raison du mélange actuel de structures sous .amadeus/.

Les décisions qui ne concernent que le domaine global ou la terminologie partagée ne donnent pas lieu à la création d'une nouvelle Grilling Decision Trail dédiée dans la structure actuelle. Si nécessaire, elles sont conservées comme justification dans .amadeus/domain-map.md, .amadeus/context-map.md, ou .amadeus/glossary.md, ou dans la décision de l'Intention cible.

grillings.md ne contient que l'index. Les détails des sessions se trouvent dans grillings/Gxxx-*.md.

grillings.md a la structure minimale suivante :

# Grillings

## Liste

| ID | Sujet | Cible | État | Décision principale | Cible de mise à jour | Détails |
|---|---|---|---|---|---|---|
| G001 | Ideation Scope | Intent | complet | Limiter le périmètre à l'écran d'administration | [scope.md](scope.md) | [G001](grillings/G001-ideation-scope.md) |

Le nom du fichier de session doit être G001-<sujet>.md. <sujet> doit être écrit uniquement en minuscules anglaises, chiffres et traits d'union.

L'état d'une session est l'un des suivants :

• active
• complet
• remplacé (superseded)

L'état d'une décision individuelle est l'un des suivants :

• active
• remplacée (superseded)

Le fichier de session doit contenir les éléments suivants : Résumé, Décisions validées, et Enregistrement des questions. Le Résumé doit obligatoirement mentionner la cible de mise à jour de l'ensemble de la session. La cible de mise à jour, dans le Résumé et dans les décisions individuelles, fait référence aux artefacts au sein de la racine cible. Pour les Découvertes (Discovery) et les Event Storming, il est permis de référencer le Markdown parent de même ID depuis <id>/grillings avec ../<id>.md. Cependant, seule la référence à ../glossary.md depuis une Grilling Decision Trail sous le domaine global est autorisée, en tant que mise à jour de la terminologie partagée. Chaque enregistrement de question doit obligatoirement inclure : Ce que l'on souhaite confirmer, Pourquoi la confirmation est nécessaire, Réponse recommandée, Raison de la recommandation, et Réponse de l'utilisateur. Chaque enregistrement de question doit obligatoirement faire référence à l'ID de la décision validée. Chaque décision individuelle doit obligatoirement mentionner sa cible de mise à jour. Les décisions individuelles remplacées (superseded) doivent obligatoirement indiquer leur remplacement.

En mode scaffold-only, aucune question n'est posée, donc aucune Grilling Decision Trail n'est créée. En mode repair, la Grilling Decision Trail n'est pas mise à jour en principe. Cependant, si les fichiers grillings.md ou grillings/Gxxx-*.md existants sont eux-mêmes corrompus, ils peuvent être réparés structurellement.

Transmission des discussions longues

Si le grillage s'éternise et qu'il est plus sûr de le poursuivre dans une autre unité de conversation, utiliser handoff comme aide opérationnelle.

handoff n'est pas un artefact d'Amadeus DLC. Le document de transmission créé doit être placé dans un répertoire temporaire du système d'exploitation, et non sous .amadeus/.

Les décisions validées sont conservées dans la Grilling Decision Trail. handoff ne doit contenir que les références nécessaires pour reprendre la discussion dans l'unité de conversation suivante.

handoff doit inclure au moins les éléments suivants :

• L'espace de travail cible et l'ensemble d'artefacts cible.
• Les grillings.md et grillings/Gxxx-*.md à consulter.
• Un résumé des décisions déjà validées.
• Les questions restées sans réponse et la prochaine question à poser.
• La compétence recommandée pour l'unité de conversation suivante.

Ne pas dupliquer dans handoff le contenu déjà présent dans les artefacts existants. Si des artefacts, PR, Issues, diffs ou résultats de validation existent, les référencer par leur chemin ou URL.

Contexte d'utilisation dans Amadeus

Cette compétence est utilisée dans les situations suivantes :

• Confirmer l'objectif, les acteurs, les contraintes et le domaine de la couche de pilotage.
• Confirmer l'objectif, les dépendances, les conditions de succès et le périmètre d'une Intention.
• Confirmer la cible, le hors périmètre, la faisabilité, l'organisation, l'ébauche initiale et la transmission à l'Inception d'une Idéation.
• Confirmer le sens de la terminologie, des concepts, des contextes bornés, des modèles DDD et des contrats.
• Confirmer la granularité ou les raisons d'exception des Unités, Bolts et Spécifications.

Interdictions

• Ne pas poser plusieurs questions à la fois.
• Ne pas poser de questions dont la réponse peut être trouvée en lisant les artefacts existants.
• Ne pas poser de question sans réponse recommandée.
• Ne pas mettre à jour les artefacts dans le tour où une question est posée, sans avoir reçu la réponse.
• Ne pas valider une réponse utilisateur en contradiction avec les artefacts existants. En cas de contradiction, expliquer d'abord la contradiction et la confirmer.