Anwendungsteil 2. Diagnose von Spezifikationsfehlern

Status: Empfehlung. Die Injektion eines kontrollierten Defekts in die Spezifikation ist eine Lehrmethode, die dem Mutationstest (mutation testing) nahe kommt. Konkrete Fehlerklassen (cycle, priority_conflict, hidden_out_of_scope) werden in Projekten angewendet, sind aber nicht vereinheitlicht. Festlauf-Metriken (ask_storm, stage_regress) sind Forschungsfront.

Die ingenieurtechnische Bezeichnung der Methode lautet kontrolliert defekte Spezifikation: Sie fügen absichtlich einen Defekt ein, um die Diagnose zu prüfen. Im Text wird manchmal der kurze, prägnante Ausdruck „vergiftete Spezifikation" verwendet, der aber die Hauptregel nicht verdecken darf: eine Mutation, ein Symptom, ein Wiederherstellungskriterium.

Dieses Kapitel setzt zwei Grundideen des ersten Bandes fort: negative Anforderungen aus Teil 7 und Antimuster aus Teil 20. Der Unterschied besteht darin, dass der Defekt nun absichtlich eingeführt und von vornherein begrenzt wird. Versuchen Sie hier nicht, den gesamten Triage-Prozess zu prüfen: das Lehrminimum ist ein poisoned/fixed-Paar und eine Wiederherstellungszeile in validation.md.

Vor dem Lesen

• Bezug aus dem ersten Band: Teil 7 liefert negative Anforderungen, Teil 20 die SDD-Antimuster.
• Lokaler Lernfall: appointment_latency, da der Prioritätskonflikt ohne externe Infrastruktur sichtbar ist.
• Spur für capstone/: ein poisoned/fixed-Paar für high_memory_usage und eine Wiederherstellungszeile in validation.md.
• Hauptbegriff des ersten Durchgangs: kontrollierter Defekt.
• Was zurückzustellen ist: Metriken ask_storm, stage_regress, der vollständige Rückwärtsdurchlauf und die automatische Zyklussuche.

Die Grenze zu benachbarten Techniken ist einfach. Dieses Kapitel behandelt einen manuell eingefügten Defekt und ein Festlauf-Symptom. Kapitel 4 behandelt ein minimales Gegenbeispiel zu einem formalen Then. Kapitel 5 behandelt viele deterministische Mutanten zur Prüfung des Validierers. Kapitel 8 behandelt das offizielle Protokoll für Streit, Beweise und Präzedenzfälle.

Das Szenario des Kapitels ist der Anstieg der Latenz der Route appointments-api, der Agentenseite auf Hono JSX, die bereits in Teil 11 des ersten Bandes erschienen ist. Dieselbe Domäne, nur unter Stress. Der Katalog klassischer Fehler, auf die sich die Mutationen stützen, befindet sich in Teil 20. SDD-Antimuster.

Ziel

Nach diesem Kapitel können Sie die Spezifikation der Incident-Triage absichtlich beschädigen, den Festlauf-Punkt von Qwen Code identifizieren und die Spezifikation in einen stabilen, reproduzierbaren Zustand bringen.

Der Lernwert liegt nicht darin, sofort eine tadellose Triage zu erhalten. Das Ziel ist zu lernen, kontrolliert Fehler zu erzeugen, deren Spuren zu lesen und die Grundursache in den Anforderungen zu beheben. Das Ergebnis wird eine funktionierende Technik sein:

• ein Defekt pro Iteration;
• messbare Diagnose einer Sackgasse;
• formale Auflösung von Widersprüchen;
• Rückwärtsdurchlauf der vollständigen SDD-Schleife Specify → Plan → Tasks → Implement.

Minimales Lernszenario

Lernfall

Incident appointment_latency: Die Spezifikation verlangt gleichzeitig „P0 in 30 Sekunden eskalieren" und „vor jeder Eskalation auf manuelle Bestätigung warten". Es gilt, einen Prioritätskonflikt zu fixieren und ihn mit einer Ausnahmeregel zu beheben.

Vorbereitung

• book2/examples/templates/validation.md — Formular zum Festhalten der Prüfung.
• Zwei kurze Dateien oder Abschnitte: poisoned-spec.md und fixed-spec.md.
• Ein erwartetes Symptom: ask_storm, stage_regress oder phase_context_loss.

Minimales poisoned/fixed-Paar für den ersten Durchgang:

poisoned:

REQ-LAT-01: latency_p95 >= 2s und severity=P0 erfordern Eskalation in 30 Sekunden. priority=100
REQ-LAT-02: jede Eskalation erfordert vorherige human approval. priority=100

fixed:
REQ-LAT-01: für severity=P0 gilt p0_time_critical_override.
REQ-LAT-02: bei p0_time_critical_override ist die Eskalation sofort zulässig, aber human_audit_required=true.
REQ-LAT-03: für P1-P3 bleibt die vorherige human approval blockierend.

Diese Zeilen können in die Lerndateien poisoned-spec.md und fixed-spec.md für den lokalen Fall appointment_latency abgelegt werden. Wenn die abschließende Bewertung nach high_memory_usage erfolgt, übertragen Sie in capstone/ nur die Fehlerklasse und die Wiederherstellungszeile aus dem folgenden Block. Ändern Sie immer nur einen Defekt zur Zeit: hier ist es der Prioritätskonflikt.

Schritte

1. Notieren Sie in poisoned-spec.md zwei sich widersprechende Regeln mit derselben priority. Erwartung: Der Defekt ist in den Daten sichtbar, nicht in einem Kommentar versteckt.
2. Halten Sie vor dem Start der Analyse das erwartete Symptom fest: zum Beispiel priority_conflict=true && escalation_path_resolved=false.
3. Führen Sie ein manuelles Review oder eine Plan Mode-Anfrage an Qwen Code ohne Dateiänderungen durch. Erwartung: Das Modell weist auf den Konflikt hin oder verliert den Faden genau an der strittigen Stelle.

1. Fügen Sie in fixed-spec.md p0_time_critical_override hinzu und verlagern Sie die manuelle Prüfung in ein nachträgliches Audit.
2. Halten Sie in validation.md zwei Fakten fest: der ursprüngliche Konflikt wurde gefunden, der korrigierte Pfad erhält human_audit_required=true.
3. Vergleichen Sie das Ergebnis mit dem lauffähigen Analogon zu Spec CI aus [examples/spec-ci/](examples/spec-ci/README.md), wenn Sie die Form der Anforderungen und des Plans automatisch prüfen möchten.

Kontrollfakt

Die Korrektur ändert die prüfbare Regel, nicht nur die Erklärung. In validation.md steht eine Wiederherstellungszeile: priority_conflict=false && escalation_path_resolved=P0 && audit_required=true.

Wie dies in capstone/ gelangt

Übertragen Sie in capstone/poisoned-spec.md genau einen Defekt und in capstone/fixed-spec.md genau eine Korrektur. Fügen Sie in capstone/validation.md eine Wiederherstellungszeile hinzu. Übertragen Sie nicht die lange Plan Mode-Spur: für die Bewertung zählen die Fehlerklasse, der Patch und die Tatsache, dass der Konflikt nicht mehr reproduzierbar ist.

Minimaler Ausschnitt (dieselbe Klasse priority_conflict, vom Lernfall appointment_latency auf den zentralen Bewertungsfall high_memory_usage übertragen: im Konflikt stehen die Erlaubnis zu restart_pod und die Anforderung human approval mit gleicher Priorität):

- defect_class: priority_conflict
- poisoned: memory_percent >= 90 in 10 Minuten erlaubt restart_pod, aber jeder restart_pod erfordert vorherige human approval mit derselben Priorität.
- fixed: restart_pod ist als pre-approved action nur für stateless pods zulässig, und der erste Produktionslauf erfordert human_review_for_first_run=true.
- validation: priority_conflict=false && action=restart_pod && human_review_for_first_run=true

Reviewbare Spur

Im Lernpaket bewahren Sie das Paar poisoned-spec.md / fixed-spec.md und den Eintrag in validation.md auf. Ausgaben out/* sind nicht nötig, wenn sie nur durch ein lokales Projektskript erzeugt wurden.

Schlüsselideen

Führen Sie in jede Iteration genau eine Art von Defekt ein. Unter „Defekt" ist hier eine von drei kontrollierten Mutationen der Spezifikation zu verstehen:

• Zyklus — zirkuläre Abhängigkeit zwischen Zuständen (zum Beispiel WAIT_APPROVAL → VALIDATE_ESCALATION → WAIT_APPROVAL);
• Prioritätskonflikt — zwei Regeln mit derselben Priorität, die zu sich gegenseitig ausschließenden Aktionen führen (etwa „P0 in 30 Sekunden eskalieren" und „auf manuelle Bestätigung warten");

• versteckte Grenzüberschreitung (hidden out-of-scope) — eine Aktion, die eine Anforderung erzwingt, obwohl sie in constraints verboten ist (zum Beispiel ein Jira-Ticket in einem Abnahmetest bei Jira-Verbot in den Einschränkungen).

Wenn Sie gleichzeitig eine rekursive Abhängigkeit, eine strittige Eskalationsregel und eine verbotene Integration hinzufügen, zeigt die Qwen Code-Spur ein allgemeines Chaos. Zu verstehen, welches Element das Verhalten gebrochen hat, wird unmöglich.

Halten Sie die Mutation in minimalem Radius: ein geändertes Spezifikationsfragment, ein erwartetes Symptom und ein Wiederherstellungskriterium.

Lokalisieren Sie das Festlaufen des Modells anhand von Chat-Metriken, nicht durch das Gefühl einer „seltsamen" Antwort. Wir führen drei diagnostische Merkmale ein:

• ask_storm — wiederholte Rückfragen ohne neue Daten;
• stage_regress — Rückkehr zu derselben Aufgabe oder Stufe;
• phase_context_loss — Verlust des Phasenkontexts, zum Beispiel das Vermischen von Plan und Implement.

Diese Merkmale sind besonders nützlich, wenn Qwen Code formal weiter antwortet, aber faktisch keine Lösung voranbringt: erneut den Eigentümer fragt, denselben Plan neu erstellt oder ein Werkzeug vorschlägt, das in der Spezifikation nicht erlaubt war. Eine praktische Kontrollzeile kann so aussehen: ask_storm >= 4 || stage_regress >= 2 || phase_context_loss=true. Nach dem Auslösen analysieren Sie die Sitzung als diagnostisches Artefakt, nicht als gescheiterten Dialog.

> Wie diese Metriken im Lerndurchgang zu zählen sind. Dies sind Heuristiken, keine CI-Metriken: im ersten Durchgang genügt eine handschriftliche Notiz in validation.md. > > - ask_storm: jede neue Nachricht des Agenten, die Daten anfordert, die in vorherigen Nachrichten der aktuellen Sitzung bereits genannt wurden. Zählt +1. Wird zurückgesetzt, sobald Sie mindestens ein neues Feld zu requirements.md oder clarifications.md hinzugefügt haben. > - stage_regress: Rückkehr der aktuellen SDD-Phase (specify/plan/tasks/implement) auf die vorherige ohne expliziten Eintrag des Grundes in validation.md. Zählt +1 pro Rückschritt. > - phase_context_loss: genau dann wahr, wenn der Agent in einer neuen Phase auf eine Regel verweist, die im aktuellen requirements.md oder plan.md fehlt. >

> Für den vollen Track werden diese Zähler über einen Parser für das Transkript der Qwen Code-Sitzung automatisiert (qwen --output-format json + Aggregator-Skript). Das Lehrminimum zählt sie mit dem Auge zum Zeitpunkt der Sitzung.

Formulieren Sie den Defekt als explizite widersprüchliche Anforderungen mit Prioritäten, nicht als Kommentar in YAML. Vergleichen Sie die beiden Wege.

Schlecht:

# TODO: P0 müssen in 30 s eskaliert werden, aber human approval ist obligatorisch —
# unklar, was gewinnt, klären wir später.
rules:
  - id: escalate_p0
    when: severity == "P0"
    then: { escalation: critical_phone }

Problem: Der Defekt sitzt im Kommentar. Linter und JSON Schema prüfen ihn nicht, und Qwen Code kann # TODO zwar lesen, ist aber nicht verpflichtet, einen Kommentar als ausführbaren Vertrag zu betrachten. Daher bleibt der Konflikt außerhalb der formalen Prüfung.

Gut:

rules:
  - id: escalate_p0
    when: severity == "P0"
    then: { escalation: critical_phone }
    priority: 100
  - id: human_approval_required
    when: severity == "P0"
    then: { require_human_approval: true }
    priority: 100   # absichtlicher Konflikt auf derselben Priorität

Nun fängt check_rule_priority.py (siehe unten als [project script]) die Kollision anhand von priority ab, nicht anhand des menschlichen Gedächtnisses.

Übersetzen Sie strittige Anforderungen in Given/When/Then und JSON Schema. Natürliche Sprache vermittelt Absichten gut, hält aber die Grenzen zulässigen Verhaltens schlecht fest. Die Formulierung „für kritische Incidents ist schnelle Eskalation nötig" lässt der Modell Raum für Vermutungen. Das Szenario Given severity=P0 and owner_unresponsive=true / When escalation_deadline expires / Then use critical_phone and record human_audit_required definiert einen prüfbaren Zweig.

JSON Schema schließt die zweite Hälfte des Problems. Es beschreibt nicht nur den gewünschten Pfad, sondern verbietet unzulässige Zustände. Zum Beispiel das Fehlen von auto_escalation_channel bei P0 oder die Nutzung einer Integration aus der Liste forbidden_integrations. Eine solche Kombination entspricht dem SDD-Ansatz: die Spezifikation muss Erfolgskriterien, Einschränkungen und prüfbare Abnahmetests im gesamten Entwicklungszyklus enthalten. GitHub Spec Kit Quickstart beschreibt diese Phasen als Sequenz Specify → Plan → Tasks → Implement.

Lösen Sie den Konflikt durch eine formale Strategie. Die Strategie umfasst drei Teile:

• Eine Ausnahmeregel (Override) bestimmt, welche Anforderung am Zeitdruck gewinnt (zum Beispiel time_critical_override über manual_gate_for_noncritical);
• eine einzige Quelle der Wahrheit beseitigt die Diskrepanz zwischen Spezifikationstext, Schema und Test — wenn Prioritäten in YAML deklariert sind, verweisen Sie aus Abnahmetests und JSON Schema auf dieselbe Hierarchie und führen keine parallele Auslegung ein;
• eine Prüfinvariante hält die Sicherheit des Übergangs fest: vor der Eskalation halten Sie severity, deadline und owner_state fest, nach der Eskalation channel, audit_record und reason_code. Andernfalls kann das System den Konflikt formal „lösen", aber die Rückverfolgbarkeit verlieren.

Schließen Sie das Refactoring mit einem Rückwärtsdurchlauf des gesamten Zyklus Specify → Plan → Tasks → Implement ab. Andernfalls bleibt die Korrektur eine lokale Vermutung. Worauf in der Spur zu achten ist:

• Wenn nach dem Patch Plan stabil ist, aber Tasks inkompatible Aktionen erzeugen — der Defekt ist von den Regeln in die Zerlegung gewandert;
• wenn Implement durchläuft, aber Abnahmetests fehlschlagen — die Grenze zulässigen Verhaltens ist unvollständig beschrieben oder das Schema deckt die operationelle Wirkung nicht ab.

Betrachten Sie nur das wiederholbare Ergebnis als zuverlässig: dasselbe Incident-Log, dieselbe Spezifikation, zwei aufeinanderfolgende Durchläufe ohne neue ask_storm, stage_regress und Prioritätskonflikte.

Beispiele und Anwendung

Betrachten wir ein Szenario, das von den vorherigen Fällen abweicht: ein scharfer Anstieg der Latenz von appointments-api in der Produktion. In der vergifteten Version der Spezifikation sind gleichzeitig zwei Anforderungen gesetzt: „alle P0 werden in 30 Sekunden eskaliert" und „jede Eskalation erfordert manuelle Bestätigung (human approval)".

Was geschieht. Ist der Verantwortliche nicht erreichbar, gerät Qwen Code in die Schleife ESCALATE_EVENT → CHECK_OWNER → WAIT_APPROVAL → VALIDATE_ESCALATION → ESCALATE_EVENT. Die Deadline verlangt Handeln. Die manuelle Barriere verbietet Handeln. Eine Austrittsregel ist nicht definiert. Der diagnostische Lauf kann so gestaltet werden:

> [project script] — die folgenden Befehle beschreiben die erwarteten Prüfungen der vergifteten Spezifikationsschleife; ein nahes lauffähiges Analogon des einfachen Spezifikations-Gateways (Spec CI) siehe examples/spec-ci/README.md.

qwen -p "Analysiere im Planungsmodus @specs/appointment-latency-poisoned.yaml.

Suche Zyklen, Prioritätskonflikte und versteckte Grenzüberschreitungen (hidden_out_of_scope). Dateien nicht ändern." \
  --approval-mode plan \
  --output-format json \
  > out/appointment-latency-plan-review.json

python3 scripts/spec_ci/find_spec_loops.py \
  --spec specs/appointment-latency-poisoned.yaml \
  --out out/appointment-loop.dot

Kontrollzeile für das Fehlschlagen: cycle_count > 0 && ask_storm >= 4 && escalation_path_resolved=false.

flowchart TD
    Specify[Specify]
    Plan[Plan]
    Tasks[Tasks]
    WaitApproval[WAIT_APPROVAL]
    Deadlock[Sackgasse nach Priorität]
    Specify -->|SDD| Plan
    Specify -->|SDD| Tasks
    Plan -->|SDD| WaitApproval
    Tasks -->|SDD| WaitApproval
    WaitApproval -->|SDD-Rückwärtskante| Deadlock
    Deadlock -->|Prioritätsblockade| Specify
    classDef danger fill:#ffcccc,stroke:#b00020,stroke-width:2px,color:#5a0000
    class Deadlock danger

Beginnen Sie die Korrektur nicht mit der Entfernung der manuellen Bestätigung, sondern mit der Klärung ihres Geltungsbereichs. Für P0 führen Sie eine Ausnahmeregel ein, bei der die Reaktionszeit wichtiger ist als die vorherige manuelle Bestätigung. Verlagern Sie die manuelle Prüfung in ein nachträgliches Audit.

Für P1–P3 belassen Sie die manuelle Barriere blockierend — dort besteht nicht dasselbe Zeitrisko. Ein minimaler Patch kann so aussehen:

rules:
  - id: p0_time_critical_override
    when: severity == "P0" && owner_unresponsive == true
    then:
      escalation: critical_phone
      human_audit_required: true
    priority: 100

  - id: human_gate_noncritical
    when: severity in ["P1", "P2", "P3"]
    then:
      require_human_approval: true
    priority: 10

Danach sichern Sie die strittige Stelle mit einem Schema ab. Dies ist nötig, damit das Modell nicht zu einer versteckten Abstimmung über einen benachbarten Schritt zurückkehrt. Im JSON Schema verlangen Sie einen Auto-Eskalationskanal für P0 bei nicht erreichbarem Eigentümer und erhalten gleichzeitig den obligatorischen Audit-Trail. So legen Sie nicht nur fest „was zu tun ist", sondern auch „was nicht als erfolgreicher Abschluss gelten darf":

{
  "if": {
    "properties": {
      "severity": { "const": "P0" },
      "owner_unresponsive": { "const": true }
    },
    "required": ["severity", "owner_unresponsive"]
  },
  "then": {
    "required": ["auto_escalation_channel", "human_audit_required", "reason_code"],
    "properties": {
      "auto_escalation_channel": { "const": "critical_phone" },

"human_audit_required": { "const": true },
      "reason_code": { "const": "time_critical_override" }
    }
  }
}

Die abschließende Prüfung muss die gesamte Schleife durchlaufen, nicht nur das neue Schema:

> [project script] — lint_spec.py und check_rule_priority.py sind in Ihrem Projekt zu implementieren; ein lauffähiges Analogon einfacher Schema- und Coverage-Gateways siehe examples/spec-ci/README.md.

python3 scripts/spec_ci/lint_spec.py \
  --spec specs/appointment-latency-fixed.yaml \
  --atomicity

python3 scripts/spec_ci/check_rule_priority.py \
  --spec specs/appointment-latency-fixed.yaml \
  --expect-json-schema

qwen -p "Lies @specs/appointment-latency-fixed.yaml und @validation.md.
Führe ein Replay der Phasen specify/plan/tasks/implement als Review durch: was besteht,
was bleibt ungeprüft, welche Fakten erfordern Skripte." \
  --approval-mode plan \
  --output-format json \
  > out/appointment-latency-replay-review.json

Erfolgreiche Wiederherstellungszeile: priority_conflict=false && cycle_count==0 && escalation_path_resolved=P0 && audit_required=true.

Fazit

Eine vergiftete Spezifikation ist nur dann nützlich, wenn ihr Kern von vornherein begrenzt ist: ein Defekt, ein messbares Symptom, ein formaler Patch und ein vollständiger Rückwärtsdurchlauf.

Zyklen, Prioritätskonflikte und versteckte Grenzüberschreitungen verwandeln sich von zufälligen Fehlschlägen von Qwen Code in steuerbare Labormutationen, wenn zwei Bedingungen erfüllt sind. Erstens: Sie lesen die Spur über ask_storm, stage_regress, phase_context_loss. Zweitens: Sie prüfen die Korrektur über Given/When/Then, JSON Schema, Ausnahmeregeln und Invarianten vor/nach der Eskalation.

Nach einem solchen Training hört die Spezifikation auf, eine Sammlung von Wünschen zu sein, und wird zu einem stabilen Vertrag. Der Vertrag kann reproduzierbar gebrochen, repariert und vor erneutem Fehlschlag geschützt werden. Im nächsten Kapitel fassen wir diese Regeln in constitution.md als erstes Projekt-Referendum zusammen.

Artefakte und Fertigkeitskriterien

| fixed-spec.md (oder korrigiertes YAML) | der Patch ändert die prüfbare Regel, nicht nur die Erklärung im Text | | Wiederherstellungszeile in validation.md | erläutert, welcher konkrete Fakt nach der Korrektur nicht mehr reproduzierbar ist |

Der vollständige Track ergänzt out/appointment-latency-plan-review.json mit der Qwen Code-Diagnose, ein JSON-Schema-Fragment, das die Rückkehr zur versteckten manuellen Bestätigung verbietet, sowie out/appointment-latency-replay-review.json nach dem Rückwärtsdurchlauf. Betrachten Sie ihn als fertig, wenn das lauffähige Analogon zu Spec CI lokal einen behebbaren Fehlschlag und ein Bestehen zeigt und das Replay Specify → Plan → Tasks → Implement den ursprünglichen Konflikt nicht zurückbringt.

Praxis

1. Kopieren Sie eine bestehende Feature-Spezifikation und führen Sie genau einen Defekt ein: Prioritätskonflikt, Zyklus oder versteckte Grenzüberschreitung. *Erwartung: Es entstehen zwei Versionen — poisoned-spec.md und fixed-spec.md, die sich in genau einer Mutation unterscheiden; Sie können die Fehlerklasse mit einem Wort benennen, bevor der Agent gestartet wird.*

1. Beschreiben Sie das erwartete Fehlschlagsymptom vor dem Start des Agenten: was soll sich aufhängen, was soll mehrdeutig werden, welcher Fakt soll fehlschlagen. *Erwartung: Das Symptom ist konkret notiert (ask_storm nach der dritten Rückfrage, stage_regress von plan → specify, Fehlschlag von Then in validation.md), nicht als „der Agent wird es nicht schaffen".*
2. Beheben Sie den Defekt so, dass der Patch die Anforderung, den Plan und die Prüfung ändert, nicht nur die Erklärung im Text. *Erwartung: Der Diff berührt mindestens einen von requirements.md, plan.md, validation.md; der Rückwärtsdurchlauf Specify → Plan → Tasks → Implement bringt den ursprünglichen Konflikt nicht zurück.*

Kontrollfragen

1. Warum darf man in eine vergiftete Spezifikation nicht mehrere Defekte gleichzeitig einführen?
2. Worin unterscheidet sich ein Prioritätskonflikt von einer versteckten Grenzüberschreitung?
3. Was beweist ein vollständiger Rückwärtsdurchlauf Specify → Plan → Tasks → Implement?
4. Sie haben den Defekt „Eskalationszyklus" eingeführt, aber Qwen Code gab „keine Rückfragen nötig" aus und ging an die Implementierung. Was sagt dies über Ihre Spezifikation aus und welcher nächste Diagnoseschritt folgt?