amadeus-grilling

Was macht amadeus-grilling?

Zweck

Unklarheiten in der Planung und im Design systematisch durch Fragen beseitigen.

Bis zum gemeinsamen Verständnis die Zweige des Designbaums der Reihe nach durchgehen. Voneinander abhängige Entscheidungen nacheinander lösen, indem die Abhängigkeiten aufgelöst werden.

Grundhaltung

Fragen präzise stellen. Aber nicht das Stellen von Fragen an sich zum Ziel machen.

Nur die Punkte erfragen, die für den Fortschritt der Benutzerentscheidung zwingend notwendig sind. Fakten, die aus der Codebasis, den .amadeus/-Artefakten, vorhandenen Dokumenten oder bisherigen Gesprächen beantwortet werden können, selbst recherchieren – nicht fragen.

Wie Fragen gestellt werden

Fragen einzeln stellen. Mehrere Fragen gleichzeitig zu stellen, macht es schwierig zu erkennen, welche Entscheidung zuerst getroffen werden muss.

Jede Frage enthält:

• Was entschieden werden muss.
• Warum diese Entscheidung jetzt notwendig ist.
• Empfohlene Antwort.
• Grund für die Empfehlung.

Nach dem Stellen einer Frage auf die Antwort des Benutzers warten. Vor Erhalt der Antwort nicht zur nächsten Frage übergehen.

Empfohlene Antwort

Zu jeder Frage muss eine empfohlene Antwort gegeben werden.

Die Empfehlung basiert auf den aktuellen Artefakten, Design-Grenzen, Implementierungsrisiken und Auswirkungen auf nachfolgende Arbeiten. Wenn keine Empfehlung möglich ist, den Grund und die fehlenden Informationen für die Entscheidung angeben.

Recherche priorisieren

Wenn eine Frage durch Recherche in der Codebasis oder den Artefakten beantwortet werden kann, zuerst dort nachsehen.

Beispiele für Recherche-Quellen:

• .amadeus/
• README.md
• AGENTS.md
• AMADEUS.md
• Vorhandene Skills
• Vorhandene Intent-Artefakte
• Vorhandene Domäne, Glossar, Entscheidungen, Rückverfolgbarkeit

Erst wenn nach der Recherche immer noch eine menschliche Entscheidung nötig ist, wird gefragt.

Grilling Decision Trail

Wenn während guided oder refine Fragen und Antworten auftreten, die die Bedeutung von Artefakten oder nachfolgende Entscheidungen beeinflussen, wird der endgültige Entscheidungsprozess als Grilling Decision Trail aufgezeichnet.

Der Grilling Decision Trail ist kein Rohprotokoll. Nicht bestätigte Aussagen, zwischenzeitlich verworfene Vorschläge, reine Ausführungsgenehmigungen, leichte Bestätigungen der Arbeitsreihenfolge, Bestätigungen von Befehlsausführungen oder vorübergehende Arbeitsbedingungen werden nicht aufgezeichnet.

Aufgezeichnet werden Entscheidungen dieser Art:

• Umfang (Scope).
• Erfolgskriterien.
• Ausgeschlossene Bereiche.
• Abhängigkeiten.
• Begriffsdefinitionen.
• Abgegrenzte Kontexte (Bounded Contexts).
• Aufteilungsstrategie.
• Zustandsbewertungen.
• Zielorte für Änderungen.
• Supersede-Entscheidungen.

amadeus-grilling definiert die Kriterien, die Aufzeichnungsstruktur, den Status und die Nummerierung. Die tatsächliche Erstellung oder Aktualisierung von grillings.md und grillings/Gxxx-*.md erfolgt durch die Phase-Skill, die das Grilling aufgerufen hat.

In den Runden, in denen gefragt wird, werden keine Artefakte aktualisiert. In der Runde nach Erhalt der Benutzerantwort interpretiert die Phase-Skill die Antwort innerhalb ihrer Artefaktgrenzen und aktualisiert den Grilling Decision Trail mit denselben Änderungen, die auch in den Phase-Artefakten vorgenommen werden.

Die Platzierung erfolgt direkt im Stammverzeichnis des betroffenen Artefakt-Sets.

<Ziel-Stammverzeichnis>/
  grillings.md
  grillings/
    G001-<thema>.md

Das Ziel-Stammverzeichnis ist:

.amadeus/discoveries/<discovery-id>/
.amadeus/event-storming/<event-storming-id>/
.amadeus/intents/<intent-id>-<slug>/
.amadeus/intents/<intent-id>-<slug>/event-storming/<event-storming-id>/

Die Steuerungsebene (Steering Layer) wird von dieser Aufzeichnung ausgenommen, da die aktuelle .amadeus/-Struktur vermischt ist.

Entscheidungen, die sich nur auf die Gesamtdomäne oder gemeinsame Begriffe auswirken, erhalten in der aktuellen Struktur keinen eigenen Grilling Decision Trail. Falls nötig, werden sie als Grundlage in .amadeus/domain-map.md, .amadeus/context-map.md, .amadeus/glossary.md oder als Entscheidung des betroffenen Intents festgehalten.

grillings.md dient nur als Index. Details der Sitzungen stehen in grillings/Gxxx-*.md.

grillings.md hat mindestens diese Struktur:

# Grillings

## Liste

| ID | Thema | Zielobjekt | Status | Wichtigste getroffene Entscheidungen | Zielort | Details |
|---|---|---|---|---|---|---|
| G001 | Ideation Scope | Intent | completed | Der Zielumfang wird auf den Admin-Bereich beschränkt | [scope.md](scope.md) | [G001](grillings/G001-ideation-scope.md) |

Die Sitzungsdatei heißt G001-<thema>.md. <thema> wird nur aus englischen Kleinbuchstaben, Ziffern und Bindestrichen gebildet.

Der Sitzungsstatus ist einer von:

• active
• completed
• superseded

Der Status einzelner Entscheidungen ist einer von:

• active
• superseded

Die Sitzungsdatei enthält: Übersicht, Getroffene Entscheidungen und Fragenprotokoll. Die Übersicht muss den Zielort der gesamten Sitzung angeben. Die Zielorte in der Übersicht und bei einzelnen Entscheidungen verweisen auf Artefakte innerhalb des Ziel-Stammverzeichnisses. Bei Discovery und Event Storming ist ein Verweis auf die übergeordnete Markdown-Datei mit derselben ID (../<id>.md) von <id>/grillings aus erlaubt. Nur wenn der Grilling Decision Trail der Gesamtdomäne auf .amadeus/glossary.md verweist, ist ein Verweis auf gemeinsame Begriffe (../glossary.md) erlaubt. Jeder Fragenprotokolleintrag muss enthalten: Was bestätigt werden soll, Warum eine Bestätigung nötig ist, Empfohlene Antwort, Grund für die Empfehlung und Benutzerantwort. Jeder Fragenprotokolleintrag muss auf die ID der getroffenen Entscheidung verweisen. Jede einzelne Entscheidung muss ihren Zielort angeben. Bei superseded-Entscheidungen muss der Ersatzort angegeben werden.

Bei scaffold-only wird nicht gefragt, daher wird kein Grilling Decision Trail erstellt. Bei repair wird der Grilling Decision Trail grundsätzlich nicht aktualisiert. Wenn jedoch die bestehende grillings.md oder grillings/Gxxx-*.md selbst beschädigt ist, darf sie als Strukturreparatur korrigiert werden.

Übergabe bei langanhaltenden Diskussionen

Wenn das Grilling sich hinzieht und es sicherer ist, in einer anderen Gesprächseinheit fortzufahren, wird handoff als Betriebshilfe verwendet.

handoff ist kein Artefakt des Amadeus DLC. Das erstellte Übergabedokument wird im temporären Verzeichnis des Betriebssystems abgelegt und nicht unter .amadeus/.

Getroffene Entscheidungen bleiben im Grilling Decision Trail. handoff enthält nur die Verweise, die zum Wiederaufsetzen in der nächsten Gesprächseinheit nötig sind.

handoff enthält mindestens:

• Den Ziel-Workspace und das Ziel-Artefakt-Set.
• Die zu konsultierenden grillings.md und grillings/Gxxx-*.md.
• Eine Zusammenfassung der bereits getroffenen Entscheidungen.
• Die noch unbeantworteten Fragen und die nächste zu klärende Frage.
• Die empfohlene Skill für die nächste Gesprächseinheit.

Inhalte, die bereits in vorhandenen Artefakten dokumentiert sind, nicht in handoff duplizieren. Wenn Artefakte, PRs, Issues, Diffs oder Testergebnisse existieren, werden diese per Pfad oder URL referenziert.

Einsatzmöglichkeiten bei Amadeus

Kommt in folgenden Situationen zum Einsatz:

• Klärung von Zweck, Akteuren, Einschränkungen und Domänenbereichen der Steuerungsebene.
• Klärung von Zweck, Abhängigkeiten, Erfolgskriterien und Umfang eines Intents.
• Klärung von Zielbereich, Ausschlussbereichen, Machbarkeit, Team, erstem Mock und Übergabe an Inception bei Ideation.
• Klärung von Begriffen, Konzepten, abgegrenzten Kontexten, DDD-Modellen und Vertragsbedeutungen.
• Klärung der Granularität oder von Ausnahmegründen bei Units, Bolts und Specs.

Verbotenes

• Mehrere Fragen gleichzeitig stellen.
• Fragen zu Dingen, die durch Lesen vorhandener Artefakte geklärt werden können.
• Fragen ohne empfohlene Antwort stellen.
• In der Fragerunde Artefakte aktualisieren, ohne die Antwort abzuwarten.
• Eine Benutzerantwort als endgültig festlegen, die mit vorhandenen Artefakten im Widerspruch steht. Bei Widersprüchen den Widerspruch zuerst erklären und bestätigen lassen.