Merge pull request #454 from raifdmueller/add-socratic-theory-recovery-contract

feat: add Socratic Code Theory Recovery contract + Cockburn Use Cases anchor

Author: rdmueller

docs/anchors/cockburn-use-cases.adoc

@@ -0,0 +1,57 @@
+= Cockburn Use Cases
+:categories: requirements-engineering
+:roles: business-analyst, software-architect, product-owner, software-developer
+:related: gherkin, bdd-given-when-then, ears-requirements, arc42, iso-25010
+:proponents: Alistair Cockburn
+:tags: use-cases, requirements, goal-levels, fully-dressed, actor-goal-list
+:tier: 3
+
+[%collapsible]
+====
+Full Name:: Cockburn Use Cases (Writing Effective Use Cases)
+
+Also known as:: Fully Dressed Use Cases, Goal-Level Use Cases, Cockburn Format
+
+[discrete]
+== *Core Concepts*:
+
+Fully Dressed Format::
+A structured textual template for describing system behavior from the actor's perspective. Each use case includes: Primary Actor, Stakeholders & Interests, Preconditions, Trigger, Main Success Scenario (numbered steps), Extensions (alternative/failure paths with step references), Postconditions (success guarantee and minimal guarantee), and Technology & Data Variations.
+
+Goal Levels::
+Three abstraction levels that organise use cases into a hierarchy:
++
+* *Summary* (Kite/Cloud) — business-process-level goals spanning multiple user sessions. Example: "Manage customer lifecycle."
+* *User Goal* (Sea Level) — the sweet spot: one actor, one sitting, one measurable outcome. Example: "Place an order." Most use cases live here.
+* *Subfunction* (Fish/Clam) — steps that support a user goal but are not goals in themselves. Example: "Authenticate user." Extract only when reused across multiple user-goal use cases.
+
+Scope::
+Defines the system boundary — what is inside the "design scope" and what is an external actor. Cockburn uses icons (a box for the system, a person for actors) to make the boundary visual. Getting scope right prevents use cases from being either too vague (organisational scope) or too detailed (component scope).
+
+Actor-Goal List::
+The discovery technique: list every actor and every goal they have against the system. This produces a candidate use case list before writing any prose. The goal level test: "Does the actor go home happy if this goal is achieved?" filters out subfunctions masquerading as user goals.
+
+What Cockburn does *not* prescribe::
+Cockburn's format is deliberately *prose-based and notation-agnostic*. It does not mandate Activity Diagrams, Gherkin, EARS, or any formal syntax. Those are complementary representations that can be layered on top — Activity Diagrams for visual flow, Gherkin for executable acceptance criteria, EARS for structured requirement statements.
+
+Key Proponents:: Alistair Cockburn (_Writing Effective Use Cases_, Addison-Wesley, 2001). The book remains the canonical reference; Cockburn also contributed to the Agile Manifesto and Crystal methodologies.
+
+[discrete]
+== *When to Use*:
+
+* Discovering what a system needs to do before deciding how to build it — the Actor-Goal List is a fast, structured brainstorm
+* Structuring requirements conversations with stakeholders who think in scenarios, not features
+* Decomposing a large system into manageable behavioural units at the right granularity (goal-level test)
+* Brownfield theory recovery: reconstructing what a system does by writing use cases from observed behaviour
+* Feeding downstream artifacts: each use case becomes a natural unit for Activity Diagrams, Gherkin scenarios, and test plans
+* Complementing arc42: use cases populate Section 6 (Runtime View) and inform Section 3 (Context and Scope)
+
+[discrete]
+== *Related Anchors*:
+
+* <<gherkin,Gherkin>> - Executable acceptance criteria that can be derived from each extension path in a use case
+* <<bdd-given-when-then,BDD Given/When/Then>> - Formalises the scenario steps that Cockburn describes in prose
+* <<ears-requirements,EARS Requirements>> - Structured syntax for individual requirement statements; complements Cockburn's scenario-level structure
+* <<arc42,arc42>> - Use cases feed Section 6 (Runtime View) and inform Section 3 (Context and Scope)
+* <<iso-25010,ISO 25010>> - Quality goals that use case extensions should address (error handling, performance, security)
+====

docs/anchors/cockburn-use-cases.de.adoc

@@ -0,0 +1,57 @@
+= Cockburn Use Cases
+:categories: requirements-engineering
+:roles: business-analyst, software-architect, product-owner, software-developer
+:related: gherkin, bdd-given-when-then, ears-requirements, arc42, iso-25010
+:proponents: Alistair Cockburn
+:tags: use-cases, anforderungen, goal-levels, fully-dressed, actor-goal-liste
+:tier: 3
+
+[%collapsible]
+====
+Vollständiger Name:: Cockburn Use Cases (Writing Effective Use Cases)
+
+Auch bekannt als:: Fully Dressed Use Cases, Goal-Level Use Cases, Cockburn-Format
+
+[discrete]
+== *Kernkonzepte*:
+
+Fully Dressed Format::
+Ein strukturiertes textuelles Template zur Beschreibung von Systemverhalten aus Sicht des Akteurs. Jeder Use Case enthält: Primary Actor, Stakeholders & Interests, Vorbedingungen, Trigger, Main Success Scenario (nummerierte Schritte), Extensions (alternative/Fehlerpfade mit Schrittverweisen), Nachbedingungen (Success Guarantee und Minimal Guarantee) sowie Technology & Data Variations.
+
+Goal Levels::
+Drei Abstraktionsebenen, die Use Cases hierarchisch organisieren:
++
+* *Summary* (Kite/Cloud) — Geschäftsprozessziele über mehrere Sitzungen. Beispiel: "Kundenlebenszyklus verwalten."
+* *User Goal* (Sea Level) — der Idealfall: ein Akteur, eine Sitzung, ein messbares Ergebnis. Beispiel: "Bestellung aufgeben." Die meisten Use Cases leben hier.
+* *Subfunction* (Fish/Clam) — Schritte, die ein User Goal unterstützen, aber selbst keine eigenständigen Ziele sind. Beispiel: "Benutzer authentifizieren." Nur extrahieren, wenn sie in mehreren User-Goal-Use-Cases wiederverwendet werden.
+
+Scope::
+Definiert die Systemgrenze — was innerhalb des "Design Scope" liegt und was externer Akteur ist. Cockburn verwendet Ikonen (ein Kasten für das System, eine Person für Akteure), um die Grenze visuell zu machen. Den richtigen Scope zu treffen verhindert, dass Use Cases entweder zu vage (organisatorischer Scope) oder zu detailliert (Komponenten-Scope) werden.
+
+Actor-Goal-Liste::
+Die Discovery-Technik: jeden Akteur und jedes Ziel auflisten, das er gegenüber dem System hat. Das ergibt eine Kandidatenliste für Use Cases, bevor Prosa geschrieben wird. Der Goal-Level-Test: "Geht der Akteur zufrieden nach Hause, wenn dieses Ziel erreicht ist?" filtert Subfunctions heraus, die sich als User Goals tarnen.
+
+Was Cockburn *nicht* vorschreibt::
+Cockburns Format ist bewusst *prosabasiert und notationsagnostisch*. Es verlangt keine Activity-Diagramme, kein Gherkin, kein EARS und keine formale Syntax. Das sind komplementäre Darstellungsformen, die darauf aufbauen können — Activity-Diagramme für visuellen Fluss, Gherkin für ausführbare Akzeptanzkriterien, EARS für strukturierte Anforderungsformulierungen.
+
+Schlüsselvertreter:: Alistair Cockburn (_Writing Effective Use Cases_, Addison-Wesley, 2001). Das Buch bleibt die kanonische Referenz; Cockburn ist auch Mitunterzeichner des Agilen Manifests und Begründer der Crystal-Methodologien.
+
+[discrete]
+== *Wann zu verwenden*:
+
+* Herausfinden was ein System tun muss, bevor entschieden wird wie es gebaut wird — die Actor-Goal-Liste ist ein schneller, strukturierter Brainstorm
+* Requirements-Gespräche mit Stakeholdern strukturieren, die in Szenarien denken, nicht in Features
+* Ein großes System in handhabbare Verhaltenseinheiten auf der richtigen Granularität zerlegen (Goal-Level-Test)
+* Brownfield-Theorie-Rekonstruktion: aus beobachtetem Verhalten Use Cases schreiben
+* Downstream-Artefakte befüttern: jeder Use Case wird zur natürlichen Einheit für Activity-Diagramme, Gherkin-Szenarien und Testpläne
+* arc42 ergänzen: Use Cases füllen Abschnitt 6 (Laufzeitsicht) und informieren Abschnitt 3 (Kontextabgrenzung)
+
+[discrete]
+== *Verwandte Anker*:
+
+* <<gherkin,Gherkin>> - Ausführbare Akzeptanzkriterien, die aus jedem Extension-Pfad eines Use Cases abgeleitet werden können
+* <<bdd-given-when-then,BDD Given/When/Then>> - Formalisiert die Szenario-Schritte, die Cockburn in Prosa beschreibt
+* <<ears-requirements,EARS Requirements>> - Strukturierte Syntax für einzelne Anforderungsformulierungen; ergänzt Cockburns szenariobasierte Struktur
+* <<arc42,arc42>> - Use Cases füllen Abschnitt 6 (Laufzeitsicht) und informieren Abschnitt 3 (Kontextabgrenzung)
+* <<iso-25010,ISO 25010>> - Qualitätsziele, die Use-Case-Extensions adressieren sollten (Fehlerbehandlung, Performance, Sicherheit)
+====

docs/changelog.adoc

@@ -2,6 +2,16 @@
 
 A chronological record of all semantic anchors added to the catalog. Community contributors are credited with thanks.
 
+== 2026-05-02
+
+*New anchors:*
+
+* *Cockburn Use Cases* — Alistair Cockburn's structured textual use case format with Goal Levels (Summary, User Goal, Subfunction) and Actor-Goal List discovery technique
+
+*New contracts:*
+
+* *Socratic Code Theory Recovery* — Recover a program's "theory" (Naur 1985) from source code through recursive question refinement; composes Socratic Method, arc42, ISO 25010, Nygard ADRs, Mental Model (Naur)
+
 == 2026-04-20
 
 *New anchors:*

docs/spec-driven-workflow.adoc

@@ -205,36 +205,57 @@ Write a PRD based on our discussion. Save it as src/docs/specs/prd.adoc.
 
 === Step 4: Create Detailed Specification
 
-From the PRD, generate a full specification:
+Start by discovering scope with an ⚓ link:#/anchor/cockburn-use-cases[*Actor-Goal List*]:
 
 [source]
 ----
-Create a detailed specification from the PRD. Include:
-- Use Cases (Trigger, Main Flow, Alternative Flows, Postconditions, Business Rules)
-- Activity Diagrams for all flows (not just the happy path)
-- Acceptance criteria in Gherkin format
+Create an Actor-Goal List from the PRD.
+For each actor, list every goal they have against the system.
+Apply the Goal Level test: "Does the actor go home happy if this goal
+is achieved?" — if yes, it's a User Goal. If not, it's a Subfunction
+(extract only when reused). Save as src/docs/specs/actor-goal-list.adoc.
+----
+
+Then generate the full specification from the Actor-Goal List:
+
+[source]
+----
+Create a detailed specification from the PRD and Actor-Goal List.
+For each User Goal, write a Use Case in Cockburn's Fully Dressed format:
+- Primary Actor and Stakeholders & Interests
+- Trigger, Preconditions
+- Main Success Scenario (numbered steps)
+- Extensions (alternative/failure paths, referencing step numbers)
+- Postconditions (Success Guarantee and Minimal Guarantee)
+- Business Rules (BR-001, BR-002, ...)
+Then add for each Use Case:
+- Activity Diagram covering all flows (not just the happy path)
+- Acceptance criteria in Gherkin format (Given/When/Then)
 Save as .adoc files in src/docs/specs/.
 ----
 
-Each Use Case must define four elements:
+Each Use Case in ⚓ link:#/anchor/cockburn-use-cases[*Cockburn's Fully Dressed format*] defines:
 
+* *Primary Actor*: Who initiates the use case and has the goal.
+* *Stakeholders & Interests*: Who else cares about the outcome and what they need from it.
 * *Trigger*: The specific event that starts the use case ("User clicks Submit", "System receives webhook").
 Without a trigger, neither the AI nor a tester knows when the use case begins.
-* *Main Flow*: The numbered steps of the happy path, each describing observable system behavior.
-* *Alternative Flows*: Named branches (A1, A2, ...) for error handling, validation failures, and edge cases.
-* *Postconditions*: The guaranteed system state after successful completion.
+* *Main Success Scenario*: The numbered steps of the happy path, each describing observable system behavior.
+* *Extensions*: Named branches (3a, 4b, ...) for error handling, validation failures, and edge cases — referencing the step they branch from.
+* *Postconditions*: The guaranteed system state after successful completion (Success Guarantee) and the minimum guarantee even when the use case fails (Minimal Guarantee).
 Postconditions are what your tests assert.
 * *Business Rules*: Numbered rules (BR-001, BR-002, ...) that capture validation constraints, calculation logic, or domain invariants.
 Business rules make implicit knowledge explicit.
 Without them, the AI invents its own validation logic -- or skips it entirely.
 
-This structure follows Alistair Cockburn's Use Case format, which LLMs recognize reliably.
 The more precise the use case, the less the AI has to guess during implementation.
+Cockburn's format is deliberately prose-based — it does not prescribe any specific notation.
+Activity Diagrams and Gherkin are complementary representations we layer on top:
 
 ⚓ link:#/anchor/gherkin[*Gherkin*] (Given/When/Then) provides acceptance criteria that are both human-readable and machine-testable.
 These criteria become the foundation for TDD later.
 
-Activity Diagrams are an important part of the specification because they define flows, error paths, and edge cases in a way the AI can follow during implementation.
+Activity Diagrams define flows, error paths, and edge cases visually — the AI can follow them during implementation to cover all branches, not just the happy path.
 
 == Phase 2: Architecture
 

docs/spec-driven-workflow.de.adoc

@@ -215,36 +215,57 @@ Write a PRD based on our discussion. Save it as src/docs/specs/prd.adoc.
 
 === Schritt 4: Detaillierte Spezifikation erstellen
 
-Aus dem PRD eine vollständige Spezifikation generieren:
+Zuerst den Scope mit einer ⚓ link:#/anchor/cockburn-use-cases[*Actor-Goal-Liste*] entdecken:
 
 [source]
 ----
-Create a detailed specification from the PRD. Include:
-- Use Cases (Trigger, Main Flow, Alternative Flows, Postconditions, Business Rules)
-- Activity Diagrams for all flows (not just the happy path)
-- Acceptance criteria in Gherkin format
+Create an Actor-Goal List from the PRD.
+For each actor, list every goal they have against the system.
+Apply the Goal Level test: "Does the actor go home happy if this goal
+is achieved?" — if yes, it's a User Goal. If not, it's a Subfunction
+(extract only when reused). Save as src/docs/specs/actor-goal-list.adoc.
+----
+
+Dann aus der Actor-Goal-Liste die vollständige Spezifikation generieren:
+
+[source]
+----
+Create a detailed specification from the PRD and Actor-Goal List.
+For each User Goal, write a Use Case in Cockburn's Fully Dressed format:
+- Primary Actor and Stakeholders & Interests
+- Trigger, Preconditions
+- Main Success Scenario (numbered steps)
+- Extensions (alternative/failure paths, referencing step numbers)
+- Postconditions (Success Guarantee and Minimal Guarantee)
+- Business Rules (BR-001, BR-002, ...)
+Then add for each Use Case:
+- Activity Diagram covering all flows (not just the happy path)
+- Acceptance criteria in Gherkin format (Given/When/Then)
 Save as .adoc files in src/docs/specs/.
 ----
 
-Jeder Use Case muss fünf Elemente definieren:
+Jeder Use Case in ⚓ link:#/anchor/cockburn-use-cases[*Cockburns Fully Dressed Format*] definiert:
 
+* *Primary Actor*: Wer den Use Case initiiert und das Ziel hat.
+* *Stakeholders & Interests*: Wer noch am Ergebnis beteiligt ist und was sie davon brauchen.
 * *Trigger*: Das spezifische Ereignis, das den Use Case auslöst ("Benutzer klickt auf Absenden", "System empfängt Webhook").
 Ohne Trigger weiß weder die KI noch ein Tester, wann der Use Case beginnt.
-* *Hauptablauf (Main Flow)*: Die nummerierten Schritte des Happy Path, jeder beschreibt beobachtbares Systemverhalten.
-* *Alternativabläufe (Alternative Flows)*: Benannte Verzweigungen (A1, A2, ...) für Fehlerbehandlung, Validierungsfehler und Randfälle.
-* *Nachbedingungen (Postconditions)*: Der garantierte Systemzustand nach erfolgreicher Ausführung.
+* *Main Success Scenario*: Die nummerierten Schritte des Happy Path, jeder beschreibt beobachtbares Systemverhalten.
+* *Extensions*: Benannte Verzweigungen (3a, 4b, ...) für Fehlerbehandlung, Validierungsfehler und Randfälle — mit Verweis auf den Schritt, von dem sie abzweigen.
+* *Nachbedingungen (Postconditions)*: Der garantierte Systemzustand nach erfolgreicher Ausführung (Success Guarantee) und die minimale Garantie auch bei Fehlschlag (Minimal Guarantee).
 Nachbedingungen sind das, was die Tests prüfen.
 * *Geschäftsregeln (Business Rules)*: Nummerierte Regeln (BR-001, BR-002, ...) für Validierungslogik, Berechnungen oder Domäneninvarianten.
 Geschäftsregeln machen implizites Wissen explizit.
 Ohne sie erfindet die KI eigene Validierungslogik -- oder lässt sie komplett weg.
 
-Diese Struktur folgt dem Use-Case-Format von Alistair Cockburn, das LLMs zuverlässig erkennen.
 Je präziser der Use Case, desto weniger muss die KI bei der Implementierung raten.
+Cockburns Format ist bewusst prosabasiert — es schreibt keine bestimmte Notation vor.
+Activity-Diagramme und Gherkin sind komplementäre Darstellungsformen, die wir darauf aufsetzen:
 
 ⚓ link:#/anchor/gherkin[*Gherkin*] (Given/When/Then) liefert Akzeptanzkriterien, die sowohl für Menschen lesbar als auch maschinell testbar sind.
 Diese Kriterien werden später die Grundlage für TDD.
 
-Activity Diagrams sind ein wichtiger Teil der Spezifikation, weil sie Abläufe, Fehlerpfade und Randfälle so definieren, dass die KI ihnen bei der Implementierung folgen kann.
+Activity Diagrams definieren Abläufe, Fehlerpfade und Randfälle visuell — die KI kann ihnen bei der Implementierung folgen, um alle Zweige abzudecken, nicht nur den Happy Path.
 
 == Phase 2: Architektur
 

skill/semantic-anchor-translator/references/catalog.md

@@ -386,6 +386,11 @@ Source: https://github.com/LLM-Coding/Semantic-Anchors
 
 ## Requirements Engineering
 
+### Cockburn Use Cases
+- **Also known as:** Fully Dressed Use Cases, Goal-Level Use Cases
+- **Proponents:** Alistair Cockburn
+- **Core:** Structured textual use case format — Primary Actor, Stakeholders & Interests, Preconditions, Trigger, Main Success Scenario, Extensions, Postconditions; three Goal Levels (Summary/Kite, User Goal/Sea Level, Subfunction/Fish); Actor-Goal List as discovery technique; deliberately prose-based and notation-agnostic — does NOT prescribe Activity Diagrams, Gherkin, or EARS, which are complementary representations
+
 ### INVEST
 - **Proponents:** Bill Wake
 - **Core:** Independent, Negotiable, Valuable, Estimable, Small, Testable — criteria for well-formed user stories

website/public/data/anchors.json

@@ -223,6 +223,38 @@
     "filePath": "docs/anchors/clean-architecture.adoc",
     "tier": 3
   },
+  {
+    "id": "cockburn-use-cases",
+    "title": "Cockburn Use Cases",
+    "categories": [
+      "requirements-engineering"
+    ],
+    "roles": [
+      "business-analyst",
+      "software-architect",
+      "product-owner",
+      "software-developer"
+    ],
+    "related": [
+      "gherkin",
+      "bdd-given-when-then",
+      "ears-requirements",
+      "arc42",
+      "iso-25010"
+    ],
+    "proponents": [
+      "Alistair Cockburn"
+    ],
+    "tags": [
+      "use-cases",
+      "requirements",
+      "goal-levels",
+      "fully-dressed",
+      "actor-goal-list"
+    ],
+    "filePath": "docs/anchors/cockburn-use-cases.adoc",
+    "tier": 3
+  },
   {
     "id": "code-smells",
     "title": "Code Smells",

website/public/data/categories.json

@@ -139,6 +139,7 @@
     "id": "requirements-engineering",
     "name": "Requirements Engineering",
     "anchors": [
+      "cockburn-use-cases",
       "ears-requirements",
       "invest",
       "moscow",