feat(socratic-recovery): derive quality scenarios instead of blanket [OPEN]

docs/brownfield-workflow.adoc

@@ -126,6 +126,12 @@ Process:
                  Operations
      - State precisely what cannot be answered, and why.
 
+   Quality (the Q4 branch) is not wholly team knowledge. Where the code
+   shows measurable behaviour — a timeout, a truncation limit, a budget,
+   a retry policy, the threats and test concept from Q3.8 — write it as
+   an [ANSWERED] quality scenario with file:line. Never invent a target
+   number. Only the quality-goal ranking (Q4.9) is [OPEN].
+
 5. Output two files in AsciiDoc:
 
    QUESTION_TREE.adoc

docs/brownfield-workflow.de.adoc

@@ -124,6 +124,12 @@ Process:
                  Operations
      - State precisely what cannot be answered, and why.
 
+   Quality (the Q4 branch) is not wholly team knowledge. Where the code
+   shows measurable behaviour — a timeout, a truncation limit, a budget,
+   a retry policy, the threats and test concept from Q3.8 — write it as
+   an [ANSWERED] quality scenario with file:line. Never invent a target
+   number. Only the quality-goal ranking (Q4.9) is [OPEN].
+
 5. Output two files in AsciiDoc:
 
    QUESTION_TREE.adoc

skill/socratic-code-theory-recovery/prompts/phase-1-question-tree.md

@@ -55,6 +55,12 @@ Process:
                  Operations
      - State precisely what cannot be answered, and why.
 
+   Quality (the Q4 branch) is not wholly team knowledge. Where the code
+   shows measurable behaviour — a timeout, a truncation limit, a budget,
+   a retry policy, the threats and test concept from Q3.8 — write it as
+   an [ANSWERED] quality scenario with file:line. Never invent a target
+   number. Only the quality-goal ranking (Q4.9) is [OPEN].
+
 5. Output two files in AsciiDoc:
 
    QUESTION_TREE.adoc

skill/socratic-code-theory-recovery/prompts/phase-2-synthesize.md

@@ -39,6 +39,13 @@ Produce four artifacts:
 3. docs/arc42/arc42-[context-name].adoc — Architecture
    - All 12 arc42 chapters. Mark chapters with no content as
      "No information from Phase 1" rather than fabricating content.
+   - Chapter 10 (Quality Requirements) is an exception: synthesize it
+     from the [ANSWERED] Q4 quality scenarios plus the Q4.9 ranking. It
+     is never just an [OPEN] pointer. Reuse evidence already in Q3.8 —
+     Security scenarios cite the STRIDE T-IDs, Maintainability scenarios
+     the test concept. Only the goal ranking stays [OPEN]; "No
+     information" is legitimate here only if Q4 produced no answered
+     scenario at all.
    - Source: Q3 branch of QUESTION_TREE.adoc
    - Anchor: arc42 (Starke / Hruschka)
 

skill/socratic-code-theory-recovery/references/arc42.md

@@ -15,7 +15,7 @@ arc42 is a 12-chapter template for documenting software architecture (Gernot Sta
 | Q3.7 | Deployment View | Which hardware/infrastructure runs the system? Deployment topology, environments, mapping building blocks to infrastructure. |
 | Q3.8 | Crosscutting Concepts | Domain models, architecture/design patterns used, persistence, UI, communication, plausibility checks, exception/error handling, logging, security, internationalisation, configurability? |
 | Q3.9 | Architecture Decisions | Why was each significant decision made? Each becomes a Nygard ADR — see [nygard-adrs.md](nygard-adrs.md). |
-| Q3.10 | Quality Requirements | Quality tree, quality scenarios (when/where/who/measurement). Connects to Q4 (ISO 25010). |
+| Q3.10 | Quality Requirements | Quality tree and quality scenarios. Synthesized from the `[ANSWERED]` Q4 scenarios plus the `Q4.9` ranking — never just an `[OPEN]` pointer. The Q4 branch derives the scenarios; see [iso-25010.md](iso-25010.md). |
 | Q3.11 | Risks and Technical Debt | Known technical risks, debt items, and their mitigation status. Overlaps with Q5. |
 | Q3.12 | Glossary | Domain terminology — terms the team uses with project-specific meaning. |
 

skill/socratic-code-theory-recovery/references/examples.md

@@ -162,6 +162,19 @@ Mechanisms are visible but the target is not. Specifically:
 Answers affect whether Q3.11 (Risks) flags absent audit logging as debt.
 ```
 
+### Q4.2.scenario: What time-behaviour scenario does the code enforce?
+
+```
+[ANSWERED]
+Evidence: src/integration/InventoryClient.java:34 (Duration.ofSeconds(3)), src/config/HttpClientConfig.java:19
+Performance scenario: when OrderService reserves inventory, the call to
+the Inventory service is bounded by a 3-second timeout; on timeout the
+order fails with 409 Conflict rather than hanging. The 3-second value is
+a literal in the code — a measurable, code-derived target. This is an
+[ANSWERED] quality scenario, not an [OPEN] one: the threshold did not
+have to be invented or asked of the team. It belongs in arc42 Chapter 10.
+```
+
 ## Q5 — Risks and Technical Debt
 
 ### Q5.1.TestDebt: What test debt exists?

skill/socratic-code-theory-recovery/references/iso-25010.md

@@ -34,6 +34,19 @@ The full 25010 standard also defines a Quality-in-Use model: Effectiveness, Effi
 
 **Rule of thumb**: the *mechanism* is in the code; the *target* and *priority* are in stakeholders' heads. Most Q4 leaves split into `[ANSWERED]` mechanism + `[OPEN]` target.
 
+## Write quality scenarios, not just mechanisms
+
+arc42 Chapter 10 needs *quality scenarios* — a measurable stimulus and response — not a bare list of mechanisms. Turn each derived mechanism into a scenario:
+
+- If the code carries a **literal threshold** (a timeout constant, a truncation limit, a batch size, an auto-compact size), the scenario is fully `[ANSWERED]`: state the stimulus, the response, and the number, and cite `file:line`.
+- If the code carries only a **mechanism with no number** (retry exists, but no stated SLO), write the scenario's stimulus and response from the code and mark the *target value* `[OPEN]`.
+
+Never invent a threshold to fill a scenario. "Derive scenarios" means reading measurable behaviour out of the code — not guessing plausible numbers.
+
+Reuse evidence already gathered: Security scenarios trace to the STRIDE threat catalogue in `Q3.8` (the T-IDs); Maintainability scenarios trace to the `Q3.8` test concept (coverage, layering). Do not re-derive or discard that evidence.
+
+arc42 Chapter 10 (`Q3.10`) is synthesized from the `[ANSWERED]` Q4 scenarios plus the `Q4.9` ranking. It is never just an `[OPEN]` pointer — it is empty only if Q4 genuinely produced no answered scenario, which a real codebase will not.
+
 ## Quality goal *priority* is the highest-value open question
 
 The single most useful question for the team is "which 3-5 quality characteristics are top priority, and what is the rank order?" This shapes every architecture trade-off and is the input to arc42 Q3.1 and to ADR Pugh matrices. This is the fixed node `Q4.9`; its leaf is almost always `[OPEN]`, with Ask role *Architect + Product Owner*.

website/public/data/contracts.json

@@ -155,8 +155,8 @@
       "adr-according-to-nygard",
       "mental-model-according-to-naur"
     ],
-    "template": "Recover a program's \"theory\" (Naur 1985) from source code through recursive question refinement.\n\n- Start with 5 root questions: Q1 Problem/Users, Q2 Specification, Q3 Architecture, Q4 Quality Goals, Q5 Risks.\n\n- The second level of the tree is FIXED, not free. Every run emits exactly these nodes, in this order, even when a node's only leaf is [OPEN] or [ANSWERED: not applicable]:\n  - Q1.1-Q1.6: product identity, primary users, channels, why-built, success metrics, segment priority\n  - Q2.1-Q2.6: actors, use-case catalog, per-interface system specs, data/entity model, acceptance criteria, cross-cutting business rules\n  - Q3.1-Q3.12: the twelve arc42 chapters, in arc42 order\n  - Q4.1-Q4.8: the eight ISO/IEC 25010 characteristics; plus Q4.9: which characteristic has priority\n  - Q5.1-Q5.5: technical debt, security risks, operational risks, dependency/supply-chain risks, scaling/performance risks\n\n- Below the fixed second level, decompose freely and code-driven; stop when a leaf is small enough to answer from one piece of code evidence, or to pose as one precise stakeholder question. Third-level depth varies between runs — expected.\n\n- Q-IDs are stable: Q3.7 is always Deployment View, in every run, so trees from different runs can be diffed node-by-node.\n\n- Each leaf is [ANSWERED] (with file:line evidence) or [OPEN] (with Category, Ask role, and why it is unanswerable from code).\n\n- Open Questions are the handoff document: always emit one section per role (Product Owner, Architect, Developer, Domain Expert, Operations), even when a section is empty (\"No open questions for this role\").\n\n- Two-phase workflow: Phase 1 builds the tree; the team answers the Open Questions; Phase 2 synthesizes documentation from the answered tree.",
-    "templateDe": "Die \"Theorie\" eines Programms (Naur 1985) aus dem Quellcode durch rekursive Fragenverfeinerung rekonstruieren.\n\n- Mit 5 Wurzelfragen starten: Q1 Problem/Nutzer, Q2 Spezifikation, Q3 Architektur, Q4 Qualitätsziele, Q5 Risiken.\n\n- Die zweite Baumebene ist FIX, nicht frei. Jeder Lauf erzeugt genau diese Knoten, in dieser Reihenfolge, auch wenn ein Knoten nur ein [OPEN]- oder [ANSWERED: not applicable]-Blatt hat:\n  - Q1.1-Q1.6: Produktidentität, primäre Nutzer, Kanäle, Warum-gebaut, Erfolgsmetriken, Segmentpriorität\n  - Q2.1-Q2.6: Akteure, Use-Case-Katalog, System-Specs pro Schnittstelle, Daten-/Entity-Modell, Akzeptanzkriterien, übergreifende Geschäftsregeln\n  - Q3.1-Q3.12: die zwölf arc42-Kapitel, in arc42-Reihenfolge\n  - Q4.1-Q4.8: die acht ISO/IEC-25010-Merkmale; plus Q4.9: welches Merkmal Priorität hat\n  - Q5.1-Q5.5: technische Schuld, Sicherheitsrisiken, Betriebsrisiken, Abhängigkeits-/Supply-Chain-Risiken, Skalierungs-/Performance-Risiken\n\n- Unterhalb der fixen zweiten Ebene frei und code-getrieben zerlegen; stoppen, wenn ein Blatt aus einem Stück Code-Evidenz oder einem Stakeholder-Fakt beantwortbar ist. Die Tiefe der dritten Ebene variiert zwischen Läufen — erwartet.\n\n- Q-IDs sind stabil: Q3.7 ist in jedem Lauf die Verteilungssicht, sodass Bäume verschiedener Läufe Knoten für Knoten verglichen werden können.\n\n- Jedes Blatt ist [ANSWERED] (mit file:line-Evidenz) oder [OPEN] (mit Kategorie, zuständiger Rolle und Begründung, warum es aus dem Code nicht beantwortbar ist).\n\n- Offene Fragen sind das Übergabedokument: immer einen Abschnitt pro Rolle erzeugen (Product Owner, Architekt, Entwickler, Domänenexperte, Operations), auch wenn ein Abschnitt leer ist (\"Keine offenen Fragen für diese Rolle\").\n\n- Zwei-Phasen-Workflow: Phase 1 baut den Baum; das Team beantwortet die offenen Fragen; Phase 2 synthetisiert Dokumentation aus dem beantworteten Baum.",
+    "template": "Recover a program's \"theory\" (Naur 1985) from source code through recursive question refinement.\n\n- Start with 5 root questions: Q1 Problem/Users, Q2 Specification, Q3 Architecture, Q4 Quality Goals, Q5 Risks.\n\n- The second level of the tree is FIXED, not free. Every run emits exactly these nodes, in this order, even when a node's only leaf is [OPEN] or [ANSWERED: not applicable]:\n  - Q1.1-Q1.6: product identity, primary users, channels, why-built, success metrics, segment priority\n  - Q2.1-Q2.6: actors, use-case catalog, per-interface system specs, data/entity model, acceptance criteria, cross-cutting business rules\n  - Q3.1-Q3.12: the twelve arc42 chapters, in arc42 order\n  - Q4.1-Q4.8: the eight ISO/IEC 25010 characteristics; plus Q4.9: which characteristic has priority\n  - Q5.1-Q5.5: technical debt, security risks, operational risks, dependency/supply-chain risks, scaling/performance risks\n\n- Below the fixed second level, decompose freely and code-driven; stop when a leaf is small enough to answer from one piece of code evidence, or to pose as one precise stakeholder question. Third-level depth varies between runs — expected.\n\n- Q-IDs are stable: Q3.7 is always Deployment View, in every run, so trees from different runs can be diffed node-by-node.\n\n- Each leaf is [ANSWERED] (with file:line evidence) or [OPEN] (with Category, Ask role, and why it is unanswerable from code).\n\n- Quality is not wholly team knowledge. Derive quality scenarios for the Q4 branch and arc42 Chapter 10 from measurable code behaviour — literal thresholds, timeouts, budgets, the threat catalogue and test concept from Q3.8 — as [ANSWERED] with file:line; never invent target numbers. Only the quality-goal ranking (Q4.9) is [OPEN]. arc42 Chapter 10 carries the derivable scenarios, never just an [OPEN] pointer.\n\n- Open Questions are the handoff document: always emit one section per role (Product Owner, Architect, Developer, Domain Expert, Operations), even when a section is empty (\"No open questions for this role\").\n\n- Two-phase workflow: Phase 1 builds the tree; the team answers the Open Questions; Phase 2 synthesizes documentation from the answered tree.",
+    "templateDe": "Die \"Theorie\" eines Programms (Naur 1985) aus dem Quellcode durch rekursive Fragenverfeinerung rekonstruieren.\n\n- Mit 5 Wurzelfragen starten: Q1 Problem/Nutzer, Q2 Spezifikation, Q3 Architektur, Q4 Qualitätsziele, Q5 Risiken.\n\n- Die zweite Baumebene ist FIX, nicht frei. Jeder Lauf erzeugt genau diese Knoten, in dieser Reihenfolge, auch wenn ein Knoten nur ein [OPEN]- oder [ANSWERED: not applicable]-Blatt hat:\n  - Q1.1-Q1.6: Produktidentität, primäre Nutzer, Kanäle, Warum-gebaut, Erfolgsmetriken, Segmentpriorität\n  - Q2.1-Q2.6: Akteure, Use-Case-Katalog, System-Specs pro Schnittstelle, Daten-/Entity-Modell, Akzeptanzkriterien, übergreifende Geschäftsregeln\n  - Q3.1-Q3.12: die zwölf arc42-Kapitel, in arc42-Reihenfolge\n  - Q4.1-Q4.8: die acht ISO/IEC-25010-Merkmale; plus Q4.9: welches Merkmal Priorität hat\n  - Q5.1-Q5.5: technische Schuld, Sicherheitsrisiken, Betriebsrisiken, Abhängigkeits-/Supply-Chain-Risiken, Skalierungs-/Performance-Risiken\n\n- Unterhalb der fixen zweiten Ebene frei und code-getrieben zerlegen; stoppen, wenn ein Blatt klein genug ist, um aus einem Stück Code-Evidenz beantwortet oder als eine präzise Stakeholder-Frage gestellt zu werden. Die Tiefe der dritten Ebene variiert zwischen Läufen — erwartet.\n\n- Q-IDs sind stabil: Q3.7 ist in jedem Lauf die Verteilungssicht, sodass Bäume verschiedener Läufe Knoten für Knoten verglichen werden können.\n\n- Jedes Blatt ist [ANSWERED] (mit file:line-Evidenz) oder [OPEN] (mit Kategorie, zuständiger Rolle und Begründung, warum es aus dem Code nicht beantwortbar ist).\n\n- Qualität ist nicht vollständig Team-Wissen. Qualitätsszenarien für den Q4-Ast und arc42-Kapitel 10 aus messbarem Code-Verhalten ableiten — literale Schwellwerte, Timeouts, Budgets, den Threat-Katalog und das Test-Konzept aus Q3.8 — als [ANSWERED] mit file:line; Zielwerte nie erfinden. Nur das Qualitätsziel-Ranking (Q4.9) ist [OPEN]. arc42-Kapitel 10 trägt die ableitbaren Szenarien, nie nur einen [OPEN]-Verweis.\n\n- Offene Fragen sind das Übergabedokument: immer einen Abschnitt pro Rolle erzeugen (Product Owner, Architekt, Entwickler, Domänenexperte, Operations), auch wenn ein Abschnitt leer ist (\"Keine offenen Fragen für diese Rolle\").\n\n- Zwei-Phasen-Workflow: Phase 1 baut den Baum; das Team beantwortet die offenen Fragen; Phase 2 synthetisiert Dokumentation aus dem beantworteten Baum.",
     "category": "documentation"
   },
   {