Anwendungsteil 2. Diagnose von Spezifikationsdefekten

Status: Empfehlung. Die Injektion eines kontrollierten Defekts in die Spezifikation ist eine Lehrtechnik, die dem Mutation Testing (Mutationsprüfung) nahe steht. Konkrete Defektklassen (cycle, priority_conflict, hidden_out_of_scope) werden in Projekten angewendet, sind jedoch nicht standardisiert. Die Stagnationsmetriken (ask_storm, stage_regress) sind noch experimentell.

Die ingenieurwissenschaftliche Bezeichnung für diese Technik ist die kontrolliert defekte Spezifikation: Sie führen absichtlich einen Defekt ein, um die Diagnose zu überprüfen. Im Text wird gelegentlich die Kurzbezeichnung "vergiftete Spezifikation" verwendet, doch sie darf die Hauptregel nicht verschleiern: eine Mutation, ein Symptom, ein Wiederherstellungskriterium.

Dieses Kapitel setzt zwei grundlegende Ideen des ersten Bandes fort: negative Anforderungen aus Teil 7 und Antipatterns aus Teil 20. Der Unterschied besteht darin, dass der Defekt nun absichtlich eingeführt und im Voraus begrenzt wird. Versuchen Sie hier nicht, den gesamten Triage-Prozess zu überprüfen: Das Mindestmaß für den Lernzweck ist das Poisoned/Fixed-Paar und eine Wiederherstellungszeile in validation.md.

Vor dem Lesen

• Fundierung aus dem ersten Band: Teil 7 liefert negative Anforderungen, Teil 20 — SDD-Antipatterns.
• Lokaler Lernfall: appointment_latency, da der Prioritätskonflikt ohne externe Infrastruktur sichtbar ist.
• Vorbereitung für capstone/: Poisoned/Fixed-Paar für high_memory_usage und eine Wiederherstellungszeile in validation.md.
• Hauptbegriff für den ersten Durchgang: kontrollierter Defekt.
• Zurückzustellen: Metriken ask_storm, stage_regress, vollständiger Rücklauf und automatische Zyklussuche.

Die Grenze zu benachbarten Techniken ist einfach. Dieses Kapitel behandelt einen manuell eingeführten Defekt und ein Stagnationssymptom. Kapitel 4 — ein minimales Gegenbeispiel zu formalem Then. Kapitel 5 — viele deterministische Mutanten zur Prüfung des Validators. Kapitel 8 — offizielles Protokoll für Streit, Beweise und Präzedenzfälle.

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

Ziel

Nach diesem Kapitel werden Sie in der Lage sein, die Triage-Spezifikation für Vorfälle absichtlich zu beschädigen, den Stagnationspunkt von Qwen Code zu identifizieren und die Spezifikation in einen stabilen, reproduzierbaren Zustand zu bringen.

Der Lernwert liegt nicht darin, sofort eine einwandfreie Triage zu erhalten. Das Ziel ist es, kontrolliert einen Fehler zu erzeugen, seine Spuren zu lesen und die Ursache in den Anforderungen zu beheben. Das Ergebnis wird eine funktionierende Technik sein:

• ein Defekt pro Iteration;
• messbare Stagnationsdiagnose;
• formale Auflösung von Widersprüchen;
• Rücklauf des vollständigen SDD-Zyklus Specify → Plan → Tasks → Implement.

Minimales Lernszenario

Lernfall

Vorfall appointment_latency: Die Spezifikation erfordert gleichzeitig "P0 innerhalb von 30 Sekunden eskalieren" und "vor jeder Eskalation auf manuelle Bestätigung warten". Ein Prioritätskonflikt muss festgehalten und durch eine Ausnahmeregel behoben werden.

Vorbereitung

• book2/examples/templates/validation.md — Formular zur Dokumentation 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 innerhalb von 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 Eskalation sofort erlaubt, aber human_audit_required=true.
REQ-LAT-03: Für P1-P3 bleibt die vorherige human approval blockierend.

Diese Zeilen können in die Lern-Dateien poisoned-spec.md und fixed-spec.md für den lokalen Fall appointment_latency eingefügt werden. Wenn die Endbewertung nach high_memory_usage erfolgt, übertragen Sie in capstone/ nur die Defektklasse und die Wiederherstellungszeile aus dem Block unten. Ändern Sie nur jeweils einen Defekt: Hier ist das der Prioritätskonflikt.

Schritte

1. Schreiben Sie in poisoned-spec.md zwei widersprüchliche Regeln mit gleicher priority. Erwartung: Der Defekt ist in den Daten sichtbar, nicht im Kommentar versteckt.
2. Notieren Sie vor dem Analysestart das erwartete Symptom: z.B. priority_conflict=true && escalation_path_resolved=false.
3. Führen Sie ein manuelles Review oder einen Plan Mode-Abfrage an Qwen Code durch, ohne Dateien zu ändern. Erwartung: Das Modell weist auf den Konflikt hin oder verliert genau an der strittigen Stelle den Faden.

1. Fügen Sie in fixed-spec.md p0_time_critical_override hinzu und verlagern Sie die manuelle Prüfung in einen Post-Faktum-Audit.
2. Dokumentieren Sie in validation.md zwei Fakten: Der ursprüngliche Konflikt wurde gefunden, der korrigierte Pfad behält human_audit_required=true.
3. Vergleichen Sie das Ergebnis mit dem lauffähigen Analogon 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 die Wiederherstellungszeile: priority_conflict=false && escalation_path_resolved=P0 && audit_required=true.

Wie dies in capstone/ übernommen wird

Ü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 die Wiederherstellungszeile hinzu. Übertragen Sie keine lange Plan Mode-Spur: Für die Bewertung zählen Defektklasse, Patch und der Fakt, dass der Konflikt nicht mehr reproduzierbar ist.

Minimaler Fragment (dasselbe priority_conflict von appointment_latency auf den Hauptbewertungsfall high_memory_usage übertragen: Es stehen sich die Erlaubnis für restart_pod und die Anforderung human approval mit gleicher Priorität gegenüber):

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

Reviewfähige Spur

Behalten Sie im Lernpaket das Paar poisoned-spec.md / fixed-spec.md und den Eintrag in validation.md. Ausgaben out/* sind nicht erforderlich, wenn sie nur durch ein lokales Projektscript erzeugt wurden.

Schlüsselideen

Führen Sie in jede Iteration genau einen Defekttyp ein. Unter "Defekt" versteht man hier eine der drei kontrollierten Mutationen der Spezifikation:

• Zyklus — zyklische Abhängigkeit zwischen Zuständen (z.B. WAIT_APPROVAL → VALIDATE_ESCALATION → WAIT_APPROVAL);
• Prioritätskonflikt — zwei Regeln mit gleicher Priorität, die zu sich gegenseitig ausschließenden Aktionen führen (z.B. "P0 innerhalb von 30 Sekunden eskalieren" und "auf manuelle Bestätigung warten");

• versteckter Grenzüberschritt (hidden out-of-scope) — eine Aktion, die eine Anforderung erzwingt, obwohl sie in constraints verboten ist (z.B. Jira-Ticket im Akzeptanztest bei Verbot von Jira in den Einschränkungen).

Wenn gleichzeitig eine rekursive Abhängigkeit, eine strittige Eskalationsregel und eine verbotene Integration hinzugefügt werden, zeigt die Spur von Qwen Code allgemeines Chaos. Es wird unmöglich sein zu erkennen, welches Element das Verhalten beschädigt hat.

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

Lokalisieren Sie die Stagnation des Modells durch Chat-Metriken, nicht durch den Eindruck eines "seltsamen" Antworts. Führen wir drei diagnostische Merkmale ein:

• ask_storm — wiederholte klärende Anfragen ohne Auftauchen neuer Daten;
• stage_regress — Rückkehr zu derselben Aufgabe oder Phase;
• phase_context_loss — Verlust des Phasenkontexts, z.B. Vermischung von Plan und Implement.

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

> Wie man diese Metriken im Lerndurchgang zählt. Es sind Heuristiken, keine CI-Metriken: Für den ersten Durchgang genügt ein Bleistiftstrich in validation.md. > > - ask_storm: Jede neue Agenten-Nachricht, die Daten anfordert, die bereits in vorherigen Nachrichten der aktuellen Sitzung genannt wurden. Zählt +1. Wird zurückgesetzt, wenn Sie mindestens ein neues Feld in requirements.md oder clarifications.md hinzugefügt haben. > - stage_regress: Rückkehr der aktuellen SDD-Phase (specify/plan/tasks/implement) auf die vorherige ohne explizite Aufzeichnung des Grunds in validation.md. Zählt +1 pro Rückschritt. > - phase_context_loss: Trifft genau dann zu, wenn der Agent in einer neuen Phase auf eine Regel verweist, die im aktuellen requirements.md oder plan.md nicht vorhanden ist. >

> Für den vollständigen Track werden diese Zähler durch einen Parser der Qwen Code-Sitzungstranskription automatisiert (qwen --output-format json + Aggregatorskript). Der Lernmindeststandard zählt sie manuell während der Sitzung.

Definieren Sie den Defekt durch explizite widersprüchliche Anforderungen mit Prioritäten, nicht durch einen Kommentar in YAML. Vergleichen Sie zwei Wege.

Schlecht:

# TODO: P0 müssen innerhalb von 30s 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 lesen, muss aber den Kommentar nicht als ausführbaren Vertrag 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 gleicher Priorität

Jetzt erfasst check_rule_priority.py (siehe unten als [project script]) die Kollision nach priority, nicht nach menschlichem Gedächtnis.

Überführen Sie strittige Anforderungen in Given/When/Then und JSON Schema. Natürliche Sprache vermittelt Absicht gut, hält aber Grenzen des zulässigen Verhaltens schlecht fest. Die Formulierung "für kritische Vorfälle ist eine schnelle Eskalation erforderlich" lässt dem 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 ab. Es beschreibt nicht nur den gewünschten Pfad, sondern verbietet unzulässige Zustände. Zum Beispiel fehlendes auto_escalation_channel bei P0 oder Verwendung einer Integration aus der Liste forbidden_integrations. Diese Verbindung entspricht dem SDD-Ansatz: Die Spezifikation sollte Erfolgskriterien, Einschränkungen und prüfbare Akzeptanztests im vollständigen Entwicklungszyklus umfassen. GitHub Spec Kit Quickstart beschreibt diese Phasen als Sequenz Specify → Plan → Tasks → Implement.

Lösen Sie den Konflikt nach einer formalen Strategie. Die Strategie umfasst drei Teile:

• Ausnahmeregel (override) bestimmt, welche Anforderung am Rand der Zeit gewinnt (z.B. time_critical_override über manual_gate_for_noncritical);
• einzige Quelle der Wahrheit beseitigt Abweichungen zwischen Spezifikationstext, Schema und Test — wenn Prioritäten in YAML deklariert sind, verweisen Sie aus Akzeptanztests und JSON Schema auf dieselbe Hierarchie, statt eine parallele Auslegung einzuführen;
• Prüfinvariante sichert die Sicherheit des Übergangs: Vor der Eskalation erfassen Sie severity, deadline und owner_state, 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 Refactorings mit dem Rücklauf des vollständigen Zyklus Specify → Plan → Tasks → Implement ab. Andernfalls bleibt die Korrektur eine lokale Vermutung. Was in der Spur zu suchen ist:

• wenn sich nach dem Patch der Plan stabilisiert, aber Tasks unvereinbare Aktionen erzeugen — ist der Defekt aus den Regeln in die Dekomposition gewandert;
• wenn Implement besteht, aber Akzeptanztests fehlschlagen — ist die Grenze des zulässigen Verhaltens unvollständig beschrieben oder das Schema deckt den operationellen Effekt nicht ab.

Betrachten Sie nur ein wiederholbares Ergebnis als zuverlässig: derselbe Vorfallsjournal, dieselbe Spezifikation, zwei aufeinanderfolgende Durchläufe ohne neue ask_storm, stage_regress und Prioritätskonflikte.

Beispiele und Anwendung

Nehmen wir ein Szenario, das sich von vorherigen Fällen unterscheidet: plötzlicher Latenzanstieg von appointments-api in Production. In der vergifteten Version der Spezifikation sind gleichzeitig zwei Anforderungen gesetzt: "alle P0 werden innerhalb von 30 Sekunden eskaliert" und "jede Eskalation erfordert manuelle Bestätigung (human approval)".

Was passiert. Wenn der Verantwortliche nicht erreichbar ist, gerät Qwen Code in eine Schleife ESCALATE_EVENT → CHECK_OWNER → WAIT_APPROVAL → VALIDATE_ESCALATION → ESCALATE_EVENT. Die Frist erfordert Handlung. Die manuelle Barriere verbietet Handlung. Die Ausstiegsregel ist nicht definiert. Der Diagnoselauf kann so strukturiert werden:

> [project script] — Die Befehle unten beschreiben die erwarteten Prüfungen des vergifteten Spezifikationszyklus; ein naher lauffähiger Analogon des grundlegenden Spezifikations-Gateways (Spec CI) siehe in examples/spec-ci/README.md.

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

Finde Zyklen, Prioritätskonflikte und versteckte Grenzüberschreitungen (hidden_out_of_scope). Ändere Dateien nicht." \
  --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 Scheitern: cycle_count > 0 && ask_storm >= 4 && escalation_path_resolved=false.

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

Beginnen Sie die Korrektur nicht mit dem Entfernen der manuellen Bestätigung, sondern mit der Präzisierung ihres Geltungsbereichs. Für P0 führen Sie eine Ausnahmeregel ein, in der die Reaktionszeit wichtiger ist als die vorherige manuelle Bestätigung. Verlagern Sie die manuelle Prüfung in einen Post-Faktum-Audit.

Für P1–P3 lassen Sie die manuelle Barriere blockierend — dort besteht kein vergleichbares Zeitrisiko. Der minimale 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

Dann sichern Sie die strittige Stelle mit einem Schema. Dies ist nötig, damit das Modell nicht zu einer versteckten Einigung über einen benachbarten Schritt zurückkehrt. Im JSON Schema fordern Sie einen Auto-Eskalationskanal für P0 bei nicht erreichbarem Eigentümer und behalten gleichzeitig die obligatorische Audit-Spur. So definieren Sie nicht nur "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 finale Prüfung muss den gesamten Zyklus durchlaufen, nicht nur das neue Schema:

> [project script] — lint_spec.py und check_rule_priority.py müssen in Ihrem Projekt implementiert werden; lauffähiges Analogon einfacher Schema- und Abdeckungs-Gateways siehe in 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.
Mache einen Replay der Phasen specify/plan/tasks/implement als Review: 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.

Zusammenfassung

Eine vergiftete Spezifikation ist nur dann nützlich, wenn ihr Gift im Voraus begrenzt ist: ein Defekt, ein messbares Symptom, ein formaler Patch und ein vollständiger Rücklauf.

Zyklen, Prioritätskonflikte und versteckte Grenzüberschreitungen verwandeln sich aus zufälligen Qwen Code-Versagensfällen in kontrollierbare Labor-Mutationen unter zwei Bedingungen. Erstens — Sie lesen die Spur durch ask_storm, stage_regress, phase_context_loss. Zweitens — Sie prüfen die Korrektur durch Given/When/Then, JSON Schema, Ausnahmeregeln und Invarianten vor/nach der Eskalation.

Nach diesem 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 Versagen geschützt werden. Im nächsten Kapitel fassen wir diese Regeln in constitution.md als erstes projektweites Referendum zusammen.

Artefakte und Fertigstellungskriterien

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

Der vollständige Track ergänzt out/appointment-latency-plan-review.json mit Qwen Code-Diagnose, JSON Schema-Fragment, das die Rückkehr zu versteckter manueller Bestätigung verbietet, und out/appointment-latency-replay-review.json nach dem Rücklauf. Betrachten Sie ihn als fertig, wenn das lauffähige Spec CI-Analogon lokal einen behebbaren Fehler und ein Bestehen zeigt, und der 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 versteckter Grenzüberschritt. *Erwartung: Es entstehen zwei Versionen — poisoned-spec.md und fixed-spec.md, die sich genau in einer Mutation unterscheiden; Sie können die Defektklasse vor dem Agentenstart in einem Wort benennen.*

1. Beschreiben Sie das erwartete Versagens-Symptom vor dem Agentenstart: was sollte sich schleifen, was sollte mehrdeutig werden, welcher Fakt sollte scheitern. *Erwartung: Symptom ist konkret aufgezeichnet (ask_storm nach dem dritten Klärungsversuch, stage_regress mit plan → specify, Scheitern von Then in validation.md), nicht als "Agent schafft es nicht".*
2. Beheben Sie den Defekt so, dass der Patch Anforderung, Plan und Prüfung ändert, nicht nur die Erklärung im Text. *Erwartung: Diff betrifft mindestens eine von requirements.md, plan.md, validation.md; Rücklauf 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 einem versteckten Grenzüberschritt?
3. Was beweist der vollständige Rücklauf Specify → Plan → Tasks → Implement?
4. Sie führten den Defekt "Eskalationszyklus" ein, aber Qwen Code gab "keine Klärungen erforderlich" aus und begann mit der Implementierung. Was sagt dies über Ihre Spezifikation aus und welcher ist der nächste Diagnoseschritt?