Refactored "Cockburn Use Cases" to "Use Cases" #582
Conversation
….0/3.0 concepts, and updated associated references, anchors, and translations.
WalkthroughDas PR migriert systematisch den spezifischen ChangesUse Cases Anchor Migration
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@website/public/sitemap.xml`:
- Around line 1324-1330: ANCHOR_ALIASES in
website/src/components/contracts-page.js contains a stale mapping
'cockburn-use-cases' that no longer exists in website/public/data/anchors.json
and is missing an alias for 'use-cases'; remove the 'cockburn-use-cases' key
from ANCHOR_ALIASES and add an entry mapping 'use-cases' to the appropriate
anchor label (e.g., ['Cockburn']) so that anchor lookups align with anchors.json
and links resolve correctly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 76850e30-2f09-458b-8092-7379e4333e7e
📒 Files selected for processing (17)
docs/all-anchors.adocdocs/anchors/cockburn-use-cases.adocdocs/anchors/cockburn-use-cases.de.adocdocs/anchors/use-cases.adocdocs/anchors/use-cases.de.adocdocs/brownfield-workflow.adocdocs/brownfield-workflow.de.adocdocs/spec-driven-workflow.adocdocs/spec-driven-workflow.de.adocskill/semantic-anchor-translator/references/catalog.mdwebsite/public/data/anchors.jsonwebsite/public/data/categories.jsonwebsite/public/data/contracts.jsonwebsite/public/data/metadata.jsonwebsite/public/data/roles.jsonwebsite/public/llms.txtwebsite/public/sitemap.xml
💤 Files with no reviewable changes (2)
- docs/anchors/cockburn-use-cases.adoc
- docs/anchors/cockburn-use-cases.de.adoc
| <!-- Anchor: Use Cases --> | ||
| <url> | ||
| <loc>https://llm-coding.github.io/Semantic-Anchors/anchor/use-cases</loc> | ||
| <lastmod>2026-06-08</lastmod> | ||
| <changefreq>monthly</changefreq> | ||
| <priority>0.6</priority> | ||
| </url> |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Prüfe, ob cockburn-use-cases noch in anchors.json existiert
echo "=== Suche nach cockburn-use-cases in anchors.json ==="
jq '.[] | select(.id == "cockburn-use-cases") | .id' website/public/data/anchors.json
echo ""
echo "=== Alias-Mapping in contracts-page.js ==="
rg -n "cockburn-use-cases" website/src/components/contracts-page.js
echo ""
echo "=== Prüfe, ob 'use-cases' bereits in ANCHOR_ALIASES enthalten ist ==="
rg -n "'use-cases'" website/src/components/contracts-page.jsRepository: LLM-Coding/Semantic-Anchors
Length of output: 281
Alias-Migration für contracts-page.js ergänzen/bereinigen: website/public/data/anchors.json enthält keinen Eintrag mehr für cockburn-use-cases, aber website/src/components/contracts-page.js hat noch immer 'cockburn-use-cases': ['Cockburn']. Gleichzeitig ist in contracts-page.js kein Alias für 'use-cases' vorhanden. ⇒ ANCHOR_ALIASES entsprechend an anchors.json anpassen (stale Alias-Zuordnungen entfernen und use-cases ergänzen), damit Links nicht ins Leere führen.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@website/public/sitemap.xml` around lines 1324 - 1330, ANCHOR_ALIASES in
website/src/components/contracts-page.js contains a stale mapping
'cockburn-use-cases' that no longer exists in website/public/data/anchors.json
and is missing an alias for 'use-cases'; remove the 'cockburn-use-cases' key
from ANCHOR_ALIASES and add an entry mapping 'use-cases' to the appropriate
anchor label (e.g., ['Cockburn']) so that anchor lookups align with anchors.json
and links resolve correctly.
JensGrote
left a comment
JensGrote
left a comment
There was a problem hiding this comment.
Review: PR #582 – Refactored "Cockburn Use Cases" to "Use Cases"
(German version below)
Appreciation
Thank you @simasch for this contribution! The historical correction regarding Jacobson as the inventor of use cases and the integration of Use-Case 2.0/3.0 (especially slices) is a valuable improvement to the catalog. We appreciate you taking the time to research this properly and bring the anchor up to date with current literature.
That said, we have a few process and scope concerns that we'd like to address before merging.
Quality Criteria Assessment
| Criterion | Old (Cockburn Use Cases) | New (Use Cases) | Verdict |
|---|---|---|---|
| Precise | ✅ Clear: Cockburn's template | ✅ Broader but still well-bounded: Jacobson + Cockburn + UC 2.0/3.0 | OK |
| Rich | ✅ Goal Levels, Fully Dressed, Actor-Goal List | ✅✅ Additionally: Use-Case Slices, Origin/Evolution, UC 2.0/3.0, agile scaling | Improved |
| Consistent | ✅ | ✅ Clear attribution of who contributed what | OK |
| Attributable | ✅ Cockburn 2001 | ✅✅ Jacobson 1987/1992, Cockburn 2001, Spence/Bittner 2011, de Mendonca 2024 | Improved |
Content Assessment
Strengths:
- Historical correction – Jacobson correctly identified as the inventor of use cases (OOPSLA 1987). Cockburn appropriately positioned as the one who codified the writing template. The old anchor was misleading by listing Cockburn as sole proponent.
- Use-Case Slices – The central concept from UC 2.0/3.0 was completely missing in the old anchor. For agile teams this is the crucial bridge (slices → backlog items).
- Direct reference – Link to Jacobson/Spence/de Mendonca 2024 PDF provided.
- Extended "When to Use" – New entry about slicing for incremental delivery is highly practice-relevant.
Issues:
-
⚠️ Breaking change without alias handling – The ID changes fromcockburn-use-cases→use-cases. As CodeRabbit correctly identified:ANCHOR_ALIASESincontracts-page.jsstill contains the old key. This breaks existing links and references. -
⚠️ Scope creep – Theall-anchors.adocdiff includes ~15 new anchor includes (aida-model, blooms-taxonomy, inverted-pyramid-style, dry, law-of-demeter, postels-law, site-reliability-engineering, systemic-consulting, luhmann-system-theory, simon-constructivism, first-principles-thinking, event-storming, conways-law, fallacies-of-distributed-computing, quality-attribute-scenario, goodharts-law, meaningful-human-control) plus the removal of the entire "Workflow" section. This is significantly more than a single-anchor refactoring – it is a catalog restructure. The PR title suggests only the Use Case rename. -
⚠️ Regeneratedllms.txt(+1304 lines) – The file was obviously fully regenerated. Unclear whether the new anchors (from point 2) are included or whether this is a rebase artifact. Makes review difficult because you cannot separate the intentional content diff from generated noise. -
❌ No LLM Activation Test – CONTRIBUTING.md explicitly requires one. The anchor name changes to a more generic term – "Use Cases" alone may trigger UML diagram thinking or generic requirements lists rather than the rich Cockburn/Jacobson framework. A quick test would clarify whether "Use Cases" is precise enough as a standalone trigger.
-
⚠️ Regeneratedsitemap.xml(+287/-207) – Also fully regenerated, likely because the ~15 new anchors produce new URLs. Confirms scope creep.
Process Assessment
| Criterion | Met? |
|---|---|
| Issue discussed first? | ❌ No prior issue found |
| Conventional Commits? | Not verified |
| PR title accurate? | |
| LLM Activation Test? | ❌ Missing |
| Single Responsibility (1 PR = 1 change)? | ❌ At least 2 topics mixed |
Regarding the missing issue: Per CONTRIBUTING.md, changes to existing anchors should be proposed via the "📝 Improve Existing Anchor" issue template first. A rename from "Cockburn Use Cases" to "Use Cases" with significant content restructuring and a reattribution of the concept's origin is exactly the kind of change that benefits from community discussion before implementation. The question of whether "Use Cases" is a sufficiently precise trigger name (vs. "Cockburn Use Cases" or "Use Cases (Jacobson/Cockburn)") deserves its own deliberation.
Recommendation
Request Changes:
- Open an issue first to discuss the rename rationale and the precision question (is "Use Cases" alone rich enough or too generic as a trigger?).
- Split the PR: Use-Case refactoring (content is good!) as its own PR. Catalog reorganization (new includes, Workflow section removal) as a separate PR.
- Fix alias/redirect:
cockburn-use-cases→use-casesincontracts-page.js. - Add LLM Activation Test: Brief comparison of "Use Cases" vs. "Cockburn Use Cases" as trigger.
- Adjust PR title if not split.
Deutsche Version
Anerkennung
Vielen Dank @simasch für diese Contribution! Die historische Korrektur bezüglich Jacobson als Erfinder der Use Cases und die Integration von Use-Case 2.0/3.0 (insbesondere Slices) ist eine wertvolle Verbesserung des Katalogs. Wir schätzen es, dass du dir die Zeit genommen hast, das sauber zu recherchieren und den Anker auf den aktuellen Stand der Literatur zu bringen.
Allerdings haben wir einige Prozess- und Scope-Anmerkungen, die wir vor dem Merge klären möchten.
Bewertung nach Qualitätskriterien
| Kriterium | Alt (Cockburn Use Cases) | Neu (Use Cases) | Bewertung |
|---|---|---|---|
| Precise | ✅ Klar: Cockburns Template | ✅ Breiter aber weiterhin klar abgegrenzt: Jacobson + Cockburn + UC 2.0/3.0 | OK |
| Rich | ✅ Goal Levels, Fully Dressed, Actor-Goal List | ✅✅ Zusätzlich: Use-Case Slices, Entstehungsgeschichte, UC 2.0/3.0, agiles Scaling | Verbessert |
| Consistent | ✅ | ✅ Klare Zuordnung wer was beigetragen hat | OK |
| Attributable | ✅ Cockburn 2001 | ✅✅ Jacobson 1987/1992, Cockburn 2001, Spence/Bittner 2011, de Mendonca 2024 | Verbessert |
Inhaltliche Bewertung
Stärken:
- Historische Korrektur – Jacobson korrekt als Erfinder der Use Cases identifiziert (OOPSLA 1987). Cockburn angemessen als derjenige positioniert, der das Schreibtemplate kodifiziert hat. Der alte Anker war irreführend, weil er Cockburn als einzigen Urheber nannte.
- Use-Case Slices – Das zentrale Konzept aus UC 2.0/3.0 fehlte im alten Anker komplett. Für agile Teams ist das die entscheidende Brücke (Slices → Backlog Items).
- Direkte Referenz – Link zum Jacobson/Spence/de Mendonca 2024 PDF vorhanden.
- Erweitertes "When to Use" – Neuer Punkt zum Slicing für inkrementelle Lieferung ist hochgradig praxisrelevant.
Probleme:
-
⚠️ Breaking Change ohne Alias-Handling – Die ID ändert sich voncockburn-use-cases→use-cases. Wie CodeRabbit korrekt erkannt hat:ANCHOR_ALIASESincontracts-page.jsenthält noch den alten Key. Das bricht bestehende Links und Referenzen. -
⚠️ Scope Creep – Das Diff vonall-anchors.adocenthält ~15 neue Anker-Includes (aida-model, blooms-taxonomy, inverted-pyramid-style, dry, law-of-demeter, postels-law, site-reliability-engineering, systemic-consulting, luhmann-system-theory, simon-constructivism, first-principles-thinking, event-storming, conways-law, fallacies-of-distributed-computing, quality-attribute-scenario, goodharts-law, meaningful-human-control) plus die Entfernung der gesamten "Workflow"-Sektion. Das ist deutlich mehr als ein Einzel-Anker-Refactoring – es ist ein Katalog-Umbau. Der PR-Titel suggeriert nur die Use-Case-Umbenennung. -
⚠️ Vollständig neu generiertellms.txt(+1304 Zeilen) – Die Datei wurde offensichtlich komplett neu erzeugt. Unklar ob die neuen Anker (aus Punkt 2) hier mit eingeflossen sind oder ob es ein Rebase-Artefakt ist. Macht das Review schwierig, weil man den inhaltlichen Diff nicht vom generierten Rauschen trennen kann. -
❌ Kein LLM Activation Test – Die CONTRIBUTING.md fordert diesen explizit. Der Anker-Name wird generischer – "Use Cases" allein könnte bei LLMs eher UML-Diagramm-Assoziationen oder generische Anforderungslisten triggern statt das reiche Cockburn/Jacobson-Framework. Ein kurzer Test würde klären ob "Use Cases" als alleiniger Trigger präzise genug ist.
-
⚠️ Vollständig neu generiertesitemap.xml(+287/-207) – Auch hier wurde die Datei komplett neu erzeugt, wahrscheinlich weil die ~15 neuen Anker neue URLs produzieren. Bestätigt den Scope Creep.
Prozess-Bewertung
| Kriterium | Erfüllt? |
|---|---|
| Issue vorher diskutiert? | ❌ Kein vorheriges Issue gefunden |
| Conventional Commits? | Nicht verifiziert |
| PR-Titel korrekt? | |
| LLM Activation Test? | ❌ Fehlt |
| Single Responsibility (1 PR = 1 Änderung)? | ❌ Mindestens 2 Themen vermischt |
Zum fehlenden Issue: Gemäß CONTRIBUTING.md sollen Änderungen an bestehenden Ankern zuerst über das "📝 Improve Existing Anchor"-Issue-Template vorgeschlagen werden. Eine Umbenennung von "Cockburn Use Cases" zu "Use Cases" mit signifikanter inhaltlicher Umstrukturierung und Neuattribuierung des Konzeptursprungs ist genau die Art von Änderung, die von einer Community-Diskussion vor der Implementierung profitiert. Die Frage, ob "Use Cases" ein ausreichend präziser Trigger-Name ist (vs. "Cockburn Use Cases" oder "Use Cases (Jacobson/Cockburn)"), verdient eine eigene Diskussion.
Empfehlung
Request Changes:
- Zuerst ein Issue öffnen um die Umbenennung und die Präzisionsfrage zu diskutieren (ist "Use Cases" allein reichhaltig genug oder zu generisch als Trigger?).
- PR aufteilen: Use-Case-Refactoring (inhaltlich gut!) als eigenen PR. Katalog-Reorganisation (neue Includes, Workflow-Sektion-Entfernung) als separaten PR.
- Alias/Redirect fixen:
cockburn-use-cases→use-casesincontracts-page.js. - LLM Activation Test ergänzen: Kurzer Vergleich von "Use Cases" vs. "Cockburn Use Cases" als Trigger.
- PR-Titel anpassen falls nicht aufgeteilt.
Review of #582 — "Cockburn Use Cases" → "Use Cases"Thanks a lot for this, @simasch — and especially for the historical correction. You're factually right: Ivar Jacobson invented use cases (OOPSLA 1987, OOSE 1992); Cockburn (2001) codified how to write them well. That correction is genuinely valuable and I want to keep it. That said, after reviewing against our anchor-quality criteria I'd like to keep the correction but not take the rename. Here's the reasoning, because it's specific to what this catalog is. Why the rename weakens the anchorA Semantic Anchor only works if the term is already a dense, pre-computed prior in an LLM's training data — naming it activates rich, consistent knowledge without us supplying it. Our four criteria (CONTRIBUTING.adoc) are Precise, Rich, Consistent, Attributable. Measured against them:
The generic name scores worse on 3 of 4. Our own CONTRIBUTING example for Attributable is literally "Hexagonal Architecture (Cockburn, 2005)" — the precise, named form is the model we follow. The two names activate different concept fields
Our anchor's body, and the way it's consumed (the Specification contract and the spec-driven-workflow ask for "Cockburn's Fully Dressed format", "Actor-Goal List", goal levels), lives entirely in the Cockburn column. Renaming to the generic term — or to Jacobson — would make the trigger pull in diagrams/RUP that our content doesn't cover. That's a name↔content mismatch. On Use-Case 2.0 / 3.0This is the cleanest signal: to verify the 3.0 citation I had to look it up — the 2024 IJI eBook is real and good, but it is not strongly anchored in current training data (try "What concepts do you associate with 'Use-Case 3.0'?" — activation is thin). Use-Case 2.0/3.0 and "slices" also belong to Jacobson's lineage, i.e. the column our content doesn't use. Leaning the anchor on 2.0/3.0 puts its weight exactly where it fails our criteria. Worth saying: 2.0/3.0 didn't replace Cockburn's craft — it added a delivery/scaling layer (slices) on top. So the right home for it isn't this anchor at all. What I'd propose instead
Minor (only relevant if we did rename anyway)For completeness, the current diff would also leave a few dangling references: the Would you be up for reshaping this into "Origin note on the Cockburn anchor + (optionally) a Use-Case 2.0/3.0 contract"? Happy to help draft either. Really do appreciate the attention to getting the attribution right — that part is going in. 🙏 |
|
As I'm using use cases day by day with my customers I wouldn't distinguish between Cockburn and Jacobson. The extensions Cockburn made are not used in practice. But finally it's your decision. |
|
Please read this paper by Jacobson and Cockburn. There is no more difference: https://www.ivarjacobson.com/publications/use-case-foundation |
|
Your PR uncovered something important: how densely a concept sits in the LLM's training data — and, secondarily, the knowledge cutoff — decides how well we can communicate with it through a single term. That's a genuinely valuable insight. You're right on the facts: the invention is Jacobson's, not Cockburn's, and the technique has since evolved into v2.0 (2011) and v3.0 (2024). But those newer additions are barely represented in the training data. A semantic anchor is, by definition, a term that triggers a rich, already-present concept in the model. "Cockburn Use Cases" and "fully dressed use cases" do that reliably — and even a bare "use case" leans toward the Cockburn-style definition. v2.0 and v3.0 don't fire that way yet; ask an LLM "what do you associate with 'Use-Case 3.0'?" and you get very little. (Telling detail: v2.0 is from 2011, long before any cutoff, and is still thin — so it's density, more than recency, that drives this.) That gap is exactly the interesting part — it's why real-world practice and the anchor have drifted apart. The literature the models trained on peaked in the Cockburn era; practice moved on, the training data hasn't caught up. So the key distinction: the anchor popup describes the definition the term triggers in the LLM — it is not a state-of-the-art definition of the term. That's why I'll keep the anchor as "Cockburn Use Cases" (the most precise trigger, and our Specification contract already builds on it) and not fold the rename / v2.0 / v3.0 additions into it. But your point is too good to lose — I'm turning it into a short article on the site about exactly this drift between training knowledge and practice, and linking it from the anchor. I'd like to credit you as the practitioner who prompted it, and I'll share the draft with you before it goes live. Thanks for pushing on this — it sharpened the whole model. 🙏 |
A website article on how a semantic anchor's strength depends on how densely the concept sits in an LLM's training data, with a reproducible A-E experiment across Claude Haiku 4.5, Sonnet 4.6 and Opus 4.8. Wired into render-docs, the router and the main nav (EN), and linked from the Cockburn Use Cases anchor popup (EN + DE). Prompted by the discussion in #582. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…actice docs: add "Anchors and Training Data" article (from #582 discussion)
|
Danke für Deinen Input! Ich habe viel über den aktuellen Stand von Use Cases aber vor allem auch viel Details über die Wirkweise von Semantischen Ankern gelernt. Übrigens: selbst Fable-5 mit knowledge cutoff anfang des Jahres kennt nicht die V3. |
4 participants
Integrated Use Case version 3.0
Summary by CodeRabbit