Merge pull request #456 from raifdmueller/feat/system-use-cases-in-workflow

feat: add System Use Cases and Supplementary Specs to workflow

Author: rdmueller

docs/changelog.adoc

@@ -2,6 +2,12 @@
 
 A chronological record of all semantic anchors added to the catalog. Community contributors are credited with thanks.
 
+== 2026-05-03
+
+*Workflow improvements:*
+
+* *Specification workflow restructured* — Step 4 now builds the spec in layers: Persona Use Cases (Cockburn Fully Dressed, User Goal level), System Use Cases (technical interfaces: API, CLI, events, file formats), and Supplementary Specifications (Entity Model, State Machines, Interface Contracts, Validation Rules). Aligned with Martinelli's AIUP distinction between Business and System Use Case Specifications.
+
 == 2026-05-02
 
 *New anchors:*

docs/spec-driven-workflow.adoc

@@ -205,6 +205,10 @@ Write a PRD based on our discussion. Save it as src/docs/specs/prd.adoc.
 
 === Step 4: Create Detailed Specification
 
+Step 4 builds the specification in layers: from scope discovery (Actor-Goal List) through persona-level use cases to technical system specifications and supplementary models.
+
+==== Step 4a: Discover Scope with the Actor-Goal List
+
 Start by discovering scope with an ⚓ link:#/anchor/cockburn-use-cases[*Actor-Goal List*]:
 
 [source]
@@ -216,11 +220,14 @@ 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:
+==== Step 4b: Persona Use Cases
+
+Generate use cases at User Goal level from the Actor-Goal List.
+These describe what actors want to achieve and how the system responds -- in prose, at a level that stakeholders can review.
 
 [source]
 ----
-Create a detailed specification from the PRD and Actor-Goal List.
+Create Persona Use Cases 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
@@ -257,6 +264,50 @@ These criteria become the foundation for TDD later.
 
 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.
 
+==== Step 4c: System Use Cases
+
+Derive System Use Cases from the Persona Use Cases.
+Where Persona Use Cases describe what actors want, System Use Cases describe what the system does at its technical boundaries -- API endpoints, CLI commands, events, file formats.
+
+[source]
+----
+Derive System Use Cases from the Persona Use Cases.
+For each system interface (API endpoint, CLI command, event, file format):
+- Trigger and Preconditions (technical: HTTP method, auth token, system state)
+- Input: format, validation rules, constraints
+- Processing: steps the system performs (reference Business Rules)
+- Output: response format, status codes, payload schema
+- Error responses: codes, messages, recovery hints
+- Non-functional: performance budget, rate limits, timeouts
+Use EARS syntax (When/While/If/Shall) for individual requirements
+where applicable. Save as src/docs/specs/system-use-cases.adoc.
+----
+
+System Use Cases bridge the gap between stakeholder-facing Persona Use Cases and implementation.
+They are the input the AI needs to generate correct API handlers, CLI parsers, and event processors without guessing at technical details.
+
+Simon Martinelli's https://unifiedprocess.ai/[AI Unified Process] calls this the move from Business Use Cases to System Use Case Specifications -- the same distinction at a different granularity.
+
+==== Step 4d: Supplementary Specifications
+
+Not every requirement fits into a use case.
+Create supplementary specifications as needed based on the project type:
+
+[source]
+----
+Based on the Use Cases, create supplementary specifications:
+- Entity Model: entities, attributes, relationships, constraints (as PlantUML ERD)
+- State Machines: for entities with lifecycle behavior (as PlantUML state diagrams)
+- Interface Contracts: DTOs and schemas at system boundaries
+- Validation Rules: cross-cutting rules not tied to a single use case
+Save in src/docs/specs/.
+----
+
+Which supplementary specs you need depends on the project.
+A CLI tool may only need an Entity Model.
+A web application typically needs all four.
+The AI will ask if something is missing during implementation -- that feedback loop (Step 8) catches gaps early.
+
 == Phase 2: Architecture
 
 === Step 5: Create arc42 Architecture Documentation
@@ -480,9 +531,17 @@ The essential one-liners for each phase, with the Semantic Anchors they activate
 |`Write a PRD based on our discussion. Save as src/docs/specs/prd.adoc. Follow Strunk & White.`
 |link:#/anchor/plain-english-strunk-white[Strunk & White]
 
-|Specification
-|`Create a detailed spec with Use Cases (Trigger, Main Flow, Alternative Flows, Postconditions, Business Rules), Activity Diagrams (all paths), and Gherkin acceptance criteria.`
-|link:#/anchor/gherkin[Gherkin]
+|Persona Use Cases
+|`Create Persona Use Cases in Cockburn's Fully Dressed format (Actor, Trigger, Main Flow, Extensions, Postconditions, Business Rules). Add Activity Diagrams and Gherkin acceptance criteria.`
+|link:#/anchor/cockburn-use-cases[Cockburn], link:#/anchor/gherkin[Gherkin]
+
+|System Use Cases
+|`Derive System Use Cases from Persona Use Cases. For each interface: input/validation, processing, output/status codes, error responses. EARS syntax where applicable.`
+|link:#/anchor/ears-requirements[EARS]
+
+|Supplementary Specs
+|`Create Entity Model (PlantUML ERD), State Machines, Interface Contracts (DTOs), Validation Rules as needed.`
+|{empty}--
 
 |Architecture
 |`Create arc42 docs with PlantUML C4 diagrams based on the spec. Save in src/docs/arc42/.`

docs/spec-driven-workflow.de.adoc

@@ -215,6 +215,10 @@ Write a PRD based on our discussion. Save it as src/docs/specs/prd.adoc.
 
 === Schritt 4: Detaillierte Spezifikation erstellen
 
+Schritt 4 baut die Spezifikation in Schichten auf: von der Scope-Ermittlung (Actor-Goal-Liste) über Use Cases auf Persona-Ebene bis zu technischen System-Spezifikationen und ergänzenden Modellen.
+
+==== Schritt 4a: Scope mit der Actor-Goal-Liste ermitteln
+
 Zuerst den Scope mit einer ⚓ link:#/anchor/cockburn-use-cases[*Actor-Goal-Liste*] entdecken:
 
 [source]
@@ -226,11 +230,14 @@ 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:
+==== Schritt 4b: Persona Use Cases
+
+Use Cases auf User-Goal-Ebene aus der Actor-Goal-Liste generieren.
+Diese beschreiben, was Akteure erreichen wollen und wie das System reagiert — in Prosa, auf einem Abstraktionsniveau, das Stakeholder reviewen können.
 
 [source]
 ----
-Create a detailed specification from the PRD and Actor-Goal List.
+Create Persona Use Cases 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
@@ -267,6 +274,50 @@ Diese Kriterien werden später die Grundlage für TDD.
 
 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.
 
+==== Schritt 4c: System Use Cases
+
+System Use Cases aus den Persona Use Cases ableiten.
+Wo Persona Use Cases beschreiben, was Akteure wollen, beschreiben System Use Cases, was das System an seinen technischen Schnittstellen tut — API-Endpunkte, CLI-Befehle, Events, Dateiformate.
+
+[source]
+----
+Derive System Use Cases from the Persona Use Cases.
+For each system interface (API endpoint, CLI command, event, file format):
+- Trigger and Preconditions (technical: HTTP method, auth token, system state)
+- Input: format, validation rules, constraints
+- Processing: steps the system performs (reference Business Rules)
+- Output: response format, status codes, payload schema
+- Error responses: codes, messages, recovery hints
+- Non-functional: performance budget, rate limits, timeouts
+Use EARS syntax (When/While/If/Shall) for individual requirements
+where applicable. Save as src/docs/specs/system-use-cases.adoc.
+----
+
+System Use Cases schließen die Lücke zwischen stakeholder-orientierten Persona Use Cases und der Implementierung.
+Sie sind der Input, den die KI braucht, um korrekte API-Handler, CLI-Parser und Event-Prozessoren zu generieren, ohne technische Details zu erraten.
+
+Simon Martinellis https://unifiedprocess.ai/[AI Unified Process] nennt das den Übergang von Business Use Cases zu System Use Case Specifications — dieselbe Unterscheidung auf anderer Granularitätsebene.
+
+==== Schritt 4d: Ergänzende Spezifikationen
+
+Nicht jede Anforderung passt in einen Use Case.
+Ergänzende Spezifikationen je nach Projekttyp erstellen:
+
+[source]
+----
+Based on the Use Cases, create supplementary specifications:
+- Entity Model: entities, attributes, relationships, constraints (as PlantUML ERD)
+- State Machines: for entities with lifecycle behavior (as PlantUML state diagrams)
+- Interface Contracts: DTOs and schemas at system boundaries
+- Validation Rules: cross-cutting rules not tied to a single use case
+Save in src/docs/specs/.
+----
+
+Welche ergänzenden Specs man braucht, hängt vom Projekt ab.
+Ein CLI-Tool braucht vielleicht nur ein Entity Model.
+Eine Webanwendung braucht typischerweise alle vier.
+Die KI fragt nach, wenn etwas fehlt — der Feedback-Loop (Schritt 8) fängt Lücken früh auf.
+
 == Phase 2: Architektur
 
 === Schritt 5: arc42-Architekturdokumentation erstellen
@@ -497,9 +548,17 @@ Die wichtigsten Einzeiler pro Phase mit den Semantic Anchors, die sie aktivieren
 |`Write a PRD based on our discussion. Save as src/docs/specs/prd.adoc. Follow Strunk & White.`
 |link:#/anchor/plain-english-strunk-white[Strunk & White]
 
-|Spezifikation
-|`Create a detailed spec with Use Cases (Trigger, Main Flow, Alternative Flows, Postconditions, Business Rules), Activity Diagrams (all paths), and Gherkin acceptance criteria.`
-|link:#/anchor/gherkin[Gherkin]
+|Persona Use Cases
+|`Create Persona Use Cases in Cockburn's Fully Dressed format (Actor, Trigger, Main Flow, Extensions, Postconditions, Business Rules). Add Activity Diagrams and Gherkin acceptance criteria.`
+|link:#/anchor/cockburn-use-cases[Cockburn], link:#/anchor/gherkin[Gherkin]
+
+|System Use Cases
+|`Derive System Use Cases from Persona Use Cases. For each interface: input/validation, processing, output/status codes, error responses. EARS syntax where applicable.`
+|link:#/anchor/ears-requirements[EARS]
+
+|Ergänzende Specs
+|`Create Entity Model (PlantUML ERD), State Machines, Interface Contracts (DTOs), Validation Rules as needed.`
+|{empty}--
 
 |Architektur
 |`Create arc42 docs with PlantUML C4 diagrams based on the spec. Save in src/docs/arc42/.`

website/public/data/contracts.json

@@ -6,8 +6,8 @@
     "description": "What we mean when we say 'spec'",
     "descriptionDe": "Was wir meinen, wenn wir 'Spec' sagen",
     "anchors": ["cockburn-use-cases", "gherkin", "bdd-given-when-then", "ears-requirements"],
-    "template": "When we talk about a \"specification\" or \"spec\", we mean:\n- Use Cases in Cockburn's Fully Dressed format (Primary Actor, Trigger, Main Success Scenario, Extensions, Postconditions) at User Goal level, with Business Rules (BR-IDs)\n- Activity Diagrams for all flows (not just the happy path)\n- Acceptance criteria in Gherkin format (Given/When/Then)\n- Individual requirements in EARS syntax where applicable (When/While/If/Shall)",
-    "templateDe": "Wenn wir von einer \"Spezifikation\" oder \"Spec\" sprechen, meinen wir:\n- Use Cases im Cockburn Fully Dressed Format (Primary Actor, Trigger, Main Success Scenario, Extensions, Nachbedingungen) auf User-Goal-Ebene, mit Geschäftsregeln (BR-IDs)\n- Activity Diagrams für alle Abläufe (nicht nur der Happy Path)\n- Akzeptanzkriterien im Gherkin-Format (Given/When/Then)\n- Einzelanforderungen in EARS-Syntax wo passend (When/While/If/Shall)",
+    "template": "When we talk about a \"specification\" or \"spec\", we mean:\n- Persona Use Cases in Cockburn's Fully Dressed format (Primary Actor, Trigger, Main Success Scenario, Extensions, Postconditions) at User Goal level, with Business Rules (BR-IDs)\n- System Use Cases for each technical interface (API endpoint, CLI command, event, file format): input/validation, processing, output/status codes, error responses\n- Activity Diagrams for all flows (not just the happy path)\n- Acceptance criteria in Gherkin format (Given/When/Then)\n- Individual requirements in EARS syntax where applicable (When/While/If/Shall)\n- Supplementary Specifications as needed: Entity Model, State Machines, Interface Contracts, Validation Rules",
+    "templateDe": "Wenn wir von einer \"Spezifikation\" oder \"Spec\" sprechen, meinen wir:\n- Persona Use Cases im Cockburn Fully Dressed Format (Primary Actor, Trigger, Main Success Scenario, Extensions, Nachbedingungen) auf User-Goal-Ebene, mit Geschäftsregeln (BR-IDs)\n- System Use Cases für jede technische Schnittstelle (API-Endpunkt, CLI-Befehl, Event, Dateiformat): Input/Validierung, Verarbeitung, Output/Statuscodes, Fehlerantworten\n- Activity Diagrams für alle Abläufe (nicht nur der Happy Path)\n- Akzeptanzkriterien im Gherkin-Format (Given/When/Then)\n- Einzelanforderungen in EARS-Syntax wo passend (When/While/If/Shall)\n- Ergänzende Spezifikationen nach Bedarf: Entity Model, State Machines, Interface Contracts, Validierungsregeln",
     "category": "requirements"
   },
   {