Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -297,6 +297,7 @@ The AgentSkill enables AI agents (Claude Code, Codex, Cursor, etc.) to recognize
**Checklist for new anchors:**
- [ ] Add anchor to `docs/anchors/<name>.adoc`
- [ ] Update `skill/semantic-anchor-translator/references/catalog.md` with the new entry
- [ ] Research documented criticism and edition drift; if found, add a `== Criticism` / `== Current Status` section (EN + DE) with named, fetch-verified linked sources (see CONTRIBUTING and issue #603)

**Future (Post-Phase 3):**
1. User creates GitHub Issue via template
Expand Down
10 changes: 10 additions & 0 deletions CONTRIBUTING.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,15 @@ Each anchor is stored as an AsciiDoc file with metadata attributes:
* `:tags:` - Keywords for search (optional but recommended)
* `:related:` - Related anchor IDs (optional)

*Criticism and Current Status (research required, include when found):*

The catalog is a lexicon, not a list of endorsements — inclusion means the term works as a precise pointer, not that we recommend the practice. For every new anchor, research whether documented criticism or drift exists, and add the finding as a section:

* `== Criticism` — the method itself is contested. Only named, citable critique (critic + linked source), never vibes like "nobody uses this anymore". The section reports the discourse; it does not adjudicate. Where the discourse names alternatives, name them too.
* `== Current Status` — the method stands, but the training-data prior and the present have drifted apart: a newer edition exists (name the edition the prior likely points to), a successor emerged, or adoption faded.

Verify every linked source by actually fetching it before committing. If the research finds nothing citable, omit both sections — an empty section is noise. See https://github.com/LLM-Coding/Semantic-Anchors/issues/603[#603] for the full-catalog triage behind this convention.

== Counter-Examples

These are *NOT* semantic anchors:
Expand Down Expand Up @@ -262,6 +271,7 @@ For *new semantic anchors*:
. All required metadata attributes present (`:categories:`, `:roles:`, `:proponents:`)
. AsciiDoc format correct (`[%collapsible]` block, proper attribute syntax)
. Anchor tested with LLM prompt (see <<testing-anchor,Testing Your Semantic Anchor>>)
. Documented criticism / edition drift researched — and captured in a _Criticism_ or _Current Status_ section with named, fetch-verified sources where found

For *code changes*:

Expand Down
14 changes: 14 additions & 0 deletions docs/anchors/_template.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,18 @@ Key Proponents:: Author Name ("Book Title"), Another Author

* <<related-anchor-1,Related Anchor Name>>
* <<related-anchor-2,Another Related Anchor>>

// Research documented criticism and edition drift for every new anchor (see
// CONTRIBUTING "Criticism and Current Status"). Include the sections below
// only when the research finds citable sources — delete them otherwise.

[discrete]
== Criticism:

* Named critic, https://example.org["Linked, fetch-verified source"] (year) — what the critique says; name the alternative the discourse proposes, if any

[discrete]
== Current Status:

* Newer edition / successor / adoption shift, with linked source — and which version the training-data prior most plausibly serves
====
7 changes: 7 additions & 0 deletions docs/anchors/blooms-taxonomy.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -59,4 +59,11 @@ Key Proponents:: Benjamin Bloom et al. ("Taxonomy of Educational Objectives", 19
* <<feynman-technique,Feynman Technique>> — explaining-it-back is a concrete check at the Understand level; Bloom names the levels above it
* <<socratic-method,Socratic Method>> — questioning drives learners up the levels; Bloom labels where they are
* <<diataxis-framework,Diátaxis Framework>> — documentation types map loosely to cognitive levels (tutorial → Apply, explanation → Understand)

[discrete]
== *Current Status*:

* Two versions circulate: the original 1956 framework (Bloom et al.) uses *nouns* — Knowledge, Comprehension, Application, Analysis, Synthesis, Evaluation — while the 2001 revision described above uses *verbs* and puts Create at the top. The standard citable summary of the differences is Krathwohl, https://people.ucsc.edu/~ktellez/blooms_taxonomy.pdf["A Revision of Bloom's Taxonomy: An Overview"] (Theory Into Practice 41(4), 2002)
* An LLM's training-data prior plausibly *blends both versions* — material on each is abundant, and many secondary sources mix the level names — so an unqualified "Bloom's Taxonomy" can anchor to either category set
* Name the version explicitly: "revised Bloom's taxonomy (Anderson/Krathwohl 2001)" or "original Bloom's taxonomy (1956)"
====
7 changes: 7 additions & 0 deletions docs/anchors/blooms-taxonomy.de.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -59,4 +59,11 @@ Key Proponents:: Benjamin Bloom et al. („Taxonomy of Educational Objectives",
* <<feynman-technique,Feynman Technique>> — Zurückerklären ist ein konkreter Check auf der Understand-Stufe; Bloom benennt die Stufen darüber
* <<socratic-method,Socratic Method>> — Fragen treiben Lernende die Stufen hinauf; Bloom etikettiert, wo sie stehen
* <<diataxis-framework,Diátaxis Framework>> — Doku-Typen bilden grob auf kognitive Stufen ab (Tutorial → Apply, Explanation → Understand)

[discrete]
== *Aktueller Stand*:

* Zwei Versionen sind im Umlauf: Das Original von 1956 (Bloom et al.) verwendet *Substantive* — Knowledge, Comprehension, Application, Analysis, Synthesis, Evaluation — die oben beschriebene Revision von 2001 dagegen *Verben*, mit Create an der Spitze. Die zitierfähige Standardübersicht der Unterschiede ist Krathwohl, https://people.ucsc.edu/~ktellez/blooms_taxonomy.pdf["A Revision of Bloom's Taxonomy: An Overview"] (Theory Into Practice 41(4), 2002)
* Der Trainingsdaten-Prior eines LLM *vermischt plausibel beide Versionen* — Material zu beiden ist reichlich vorhanden, und viele Sekundärquellen mischen die Stufennamen — ein unqualifiziertes „Bloom's Taxonomy" kann also auf beide Kategoriesätze ankern
* Nenne die Version explizit: „revidierte Bloom-Taxonomie (Anderson/Krathwohl 2001)" oder „Original-Taxonomie (1956)"
====
7 changes: 7 additions & 0 deletions docs/anchors/cockburn-use-cases.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -59,4 +59,11 @@ Key Proponents:: Alistair Cockburn (_Writing Effective Use Cases_, Addison-Wesle
== *Further Reading*:

* link:#/training-data-vs-practice[Anchors and Training Data] - why this anchor reflects Cockburn's craft rather than Jacobson's later Use-Case 2.0/3.0, and what that reveals about how anchors depend on training data.

[discrete]
== *Current Status*:

* _Writing Effective Use Cases_ (2001) never had a second edition and remains the canonical craft text — and the densest, most reliably activated LLM prior for use-case writing
* Jacobson's successor exists and works as an anchor of its own: https://www.ivarjacobson.com/publications/white-papers/use-case-20-e-book[Use-Case 2.0] (Jacobson, Spence & Bittner, free ebook, 2011) adapts use cases to iterative delivery via *use-case slices*
* https://www.ivarjacobson.com/publications/books/use-case-30-ebook[Use Case 3.0] (de Mendonca & Jacobson, v1.0, 2024) *does* exist — but it is too young to be an anchor: LLMs hold no dense prior for it (see _Further Reading_ above), so supply its definition in the prompt if you want 3.0 semantics. Jacobson and Cockburn realigned their craft in https://queue.acm.org/detail.cfm?id=3631182["Use Cases are Essential"] (ACM Queue, 2023)
====
7 changes: 7 additions & 0 deletions docs/anchors/cockburn-use-cases.de.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -59,4 +59,11 @@ Schlüsselvertreter:: Alistair Cockburn (_Writing Effective Use Cases_, Addison-
== *Weiterführend*:

* link:#/training-data-vs-practice[Anchors and Training Data] - warum dieser Anker Cockburns Handwerk abbildet und nicht Jacobsons spätere Use-Case 2.0/3.0, und was das über die Abhängigkeit von Ankern von den Trainingsdaten verrät.

[discrete]
== *Aktueller Stand*:

* _Writing Effective Use Cases_ (2001) hat nie eine zweite Auflage bekommen und bleibt der kanonische Handwerkstext — und der dichteste, am zuverlässigsten aktivierte LLM-Prior für das Schreiben von Use Cases
* Jacobsons Nachfolger existiert und trägt als eigener Anker: https://www.ivarjacobson.com/publications/white-papers/use-case-20-e-book[Use-Case 2.0] (Jacobson, Spence & Bittner, freies Ebook, 2011) passt Use Cases über *Use-Case Slices* an iterative Lieferung an
* https://www.ivarjacobson.com/publications/books/use-case-30-ebook[Use Case 3.0] (de Mendonca & Jacobson, v1.0, 2024) existiert *tatsächlich* — ist aber zu jung für einen Anker: LLMs halten dafür keinen dichten Prior (siehe _Weiterführend_ oben); wer 3.0-Semantik will, liefert die Definition im Prompt mit. Jacobson und Cockburn haben ihr Handwerk in https://queue.acm.org/detail.cfm?id=3631182["Use Cases are Essential"] (ACM Queue, 2023) neu zusammengeführt
====
7 changes: 7 additions & 0 deletions docs/anchors/effective-go.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -43,4 +43,11 @@ Key Proponent:: The Go Authors (https://go.dev/doc/effective_go)
* Explaining Go idioms that differ from other languages (e.g. error handling, interfaces)
* Prompting an LLM to produce idiomatic, production-quality Go code

[discrete]
== *Current Status*:

* Dated by its own admission — https://go.dev/doc/effective_go[the document] opens with: "This document was written for Go's release in 2009 and is not actively updated. While it remains a good guide for using the core language, it does not cover significant changes to the language (generics), ecosystem (modules), or libraries added since." The Go team has deliberately frozen it (https://go.dev/issue/28782[golang/go #28782], still open)
* It predates the entire modern toolchain era — modules (2018/19) and generics (Go 1.18, 2022) — so its guidance is *silent* on these topics rather than wrong about the core language
* Modern complements: the curated https://go.dev/wiki/CodeReviewComments[Go Code Review Comments] (self-described "supplement to Effective Go") and Google's maintained https://google.github.io/styleguide/go/[Go Style series] (Guide, Decisions, Best Practices)

====
7 changes: 7 additions & 0 deletions docs/anchors/effective-go.de.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -43,4 +43,11 @@ Schlüsselvertreter:: The Go Authors (https://go.dev/doc/effective_go)
* Erklärung von Go-Idiomen, die sich von anderen Sprachen unterscheiden (z.B. Fehlerbehandlung, Interfaces)
* LLM-Prompting für idiomatischen, produktionsreifen Go-Code

[discrete]
== *Aktueller Stand*:

* Nach eigener Auskunft veraltet — https://go.dev/doc/effective_go[das Dokument] beginnt mit dem Hinweis: "This document was written for Go's release in 2009 and is not actively updated. While it remains a good guide for using the core language, it does not cover significant changes to the language (generics), ecosystem (modules), or libraries added since." Das Go-Team hat es bewusst eingefroren (https://go.dev/issue/28782[golang/go #28782], weiterhin offen)
* Es stammt aus der Zeit vor der gesamten modernen Toolchain-Ära — Modules (2018/19) und Generics (Go 1.18, 2022) — seine Ratschläge *schweigen* zu diesen Themen, statt beim Sprachkern falsch zu liegen
* Moderne Ergänzungen: die kuratierten https://go.dev/wiki/CodeReviewComments[Go Code Review Comments] (Selbstbeschreibung: "supplement to Effective Go") und Googles gepflegte https://google.github.io/styleguide/go/[Go-Style-Reihe] (Guide, Decisions, Best Practices)

====
2 changes: 1 addition & 1 deletion docs/anchors/gutes-deutsch-wolf-schneider.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ Key Proponents:: Wolf Schneider ("Deutsch für Profis", 1982; "Deutsch! Das Hand
[discrete]
== *Criticism*:

* Descriptive linguists (e.g. Anatol Stefanowitsch in the https://scilogs.spektrum.de/sprachlog/sprachkritik/[Sprachlog "Sprachkritik" series]) criticise Schneider's tradition of Sprachkritik for presenting personal style preferences as objective norms of German and for framing language change as decline
* Descriptive linguists reject the Sprachkritik tradition Schneider stands for presenting personal style preferences as objective norms of German and reading language change as decline; Anatol Stefanowitsch (Sprachlog) called Schneider the "Sprachpapst" and https://www.sprachlog.de/2012/12/07/sprachbrocken-49-2012/["oberster Sprachnörgler der deutschsprachigen Journaille"] (2012)
* Schneider's polemics beyond craft advice are contested: his campaign against anglicisms ("Speak German!", 2008) and his co-initiation of the 2019 appeal "Schluss mit dem Gender-Unfug!" drew https://www.wz.de/panorama/mit-vollgas-in-die-vergangenheit-kritik-an-gender-unfug-aufruf_aid-37331153[broad criticism from academic linguists] — on these points his norms diverge from current usage
* The core craft rules (short sentences, verbs over nouns, concrete words) remain largely uncontested in journalism training; the criticism targets the claim of general validity, not the toolbox — the English-language parallel is the linguists' critique of <<plain-english-strunk-white,Strunk & White>>
====
2 changes: 1 addition & 1 deletion docs/anchors/gutes-deutsch-wolf-schneider.de.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ Schlüsselvertreter:: Wolf Schneider ("Deutsch für Profis", 1982; "Deutsch! Das
[discrete]
== *Kritik*:

* Deskriptive Linguisten (z. B. Anatol Stefanowitsch in der https://scilogs.spektrum.de/sprachlog/sprachkritik/[Sprachlog-Reihe "Sprachkritik"]) kritisieren Schneiders Tradition der Sprachkritik dafür, persönliche Stilvorlieben als objektive Normen des Deutschen auszugeben und Sprachwandel als Verfall zu deuten
* Deskriptive Linguisten lehnen die Sprachkritik-Tradition ab, für die Schneider steht — persönliche Stilvorlieben als objektive Normen des Deutschen auszugeben und Sprachwandel als Verfall zu deuten; Anatol Stefanowitsch (Sprachlog) nannte Schneider den „Sprachpapst" und https://www.sprachlog.de/2012/12/07/sprachbrocken-49-2012/[„obersten Sprachnörgler der deutschsprachigen Journaille"] (2012)
* Schneiders Polemiken jenseits der Handwerksregeln sind umstritten: seine Kampagne gegen Anglizismen ("Speak German!", 2008) und seine Mitinitiierung des Aufrufs "Schluss mit dem Gender-Unfug!" (2019) stießen auf https://www.wz.de/panorama/mit-vollgas-in-die-vergangenheit-kritik-an-gender-unfug-aufruf_aid-37331153[breite Kritik aus der akademischen Linguistik] — in diesen Punkten weichen seine Normen vom heutigen Sprachgebrauch ab
* Die handwerklichen Kernregeln (kurze Sätze, Verben statt Substantive, konkrete Wörter) sind in der Journalistenausbildung weitgehend unbestritten; die Kritik richtet sich gegen den Anspruch allgemeiner Gültigkeit, nicht gegen den Werkzeugkasten — die englischsprachige Parallele ist die Linguisten-Kritik an <<plain-english-strunk-white,Strunk & White>>
====
7 changes: 7 additions & 0 deletions docs/anchors/iso-25010.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -53,4 +53,11 @@ Key Proponents:: ISO/IEC JTC 1/SC 7 (replaces ISO/IEC 9126)
* <<atam,ATAM>>
* <<arc42,arc42 Architecture Documentation>>
* <<adr-according-to-nygard,ADR according to Nygard>>

[discrete]
== *Current Status*:

* The eight-characteristic model described above is the 2011 edition — which ISO has withdrawn. The current edition, https://www.iso.org/standard/78176.html[ISO/IEC 25010:2023], expands the model to *nine* characteristics: *Safety* is new, Usability was renamed to *Interaction Capability*, Portability to *Flexibility* (free change summary: https://quality.arc42.org/articles/iso-25010-update-2023[arc42 Quality Model])
* Most published material still describes the 2011 model — as of mid-2026 even the English Wikipedia article — so an LLM's training-data prior for "ISO 25010" most plausibly serves the older eight-characteristic edition
* Name the edition explicitly ("ISO/IEC 25010:2023") whenever the distinction matters; the bare term will usually resolve to the 2011 model
====
7 changes: 7 additions & 0 deletions docs/anchors/iso-25010.de.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -52,4 +52,11 @@ Schlüsselvertreter:: ISO/IEC JTC 1/SC 7 (ersetzt ISO/IEC 9126)
* <<atam,ATAM>>
* <<arc42,arc42 Architekturdokumentation>>
* <<adr-according-to-nygard,ADR nach Nygard>>

[discrete]
== *Aktueller Stand*:

* Das oben beschriebene Acht-Merkmale-Modell ist die Ausgabe von 2011 — die ISO inzwischen zurückgezogen hat. Die aktuelle Ausgabe https://www.iso.org/standard/78176.html[ISO/IEC 25010:2023] erweitert das Modell auf *neun* Merkmale: *Safety* ist neu, Usability wurde in *Interaction Capability* umbenannt, Portability in *Flexibility* (frei lesbare Änderungsübersicht: https://quality.arc42.org/articles/iso-25010-update-2023[arc42 Quality Model])
* Der Großteil des veröffentlichten Materials beschreibt weiterhin das 2011er Modell — Mitte 2026 sogar noch der englische Wikipedia-Artikel — der Trainingsdaten-Prior eines LLM für „ISO 25010" bedient also höchstwahrscheinlich die ältere Acht-Merkmale-Ausgabe
* Nenne die Ausgabe explizit („ISO/IEC 25010:2023"), wann immer der Unterschied zählt; der bloße Begriff löst meist zum 2011er Modell auf
====
7 changes: 7 additions & 0 deletions docs/anchors/madr.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -47,4 +47,11 @@ Reference:: https://adr.github.io/madr/
* Organizations using Markdown-based documentation workflows
* When LLM assistance is needed to generate consistent decision records
* Complementing arc42 Section 9 (Architecture Decisions)

[discrete]
== *Current Status*:

* The current release is https://adr.github.io/madr/[MADR 4.0.0] (September 2024). The name changed twice along the way: MADR 3.x (2022) renamed "Markdown *Architectural* Decision Records" to "Markdown *Any* Decision Records"; 4.0 renamed it back, while keeping the template usable for any decision
* An LLM's training-data prior most plausibly reproduces the 2.x-era format (2018–2022, the longest-lived and most widely copied variant): inline `* Status:` / `* Deciders:` / `* Date:` bullets and split "Positive/Negative Consequences" sections — rather than the current YAML front matter with `decision-makers`, the merged "Consequences" section, and the "Confirmation" element introduced in 3.x/4.x
* When the exact format matters, point the model at the https://github.com/adr/madr/tree/4.0.0/template[current template] or paste it into the prompt — the anchor name reliably evokes the concept, but not the current field set
====
7 changes: 7 additions & 0 deletions docs/anchors/madr.de.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -46,4 +46,11 @@ Referenz:: https://adr.github.io/madr/
* Organisationen mit Markdown-basierten Dokumentations-Workflows
* Wenn LLM-Unterstützung zur Generierung konsistenter Entscheidungsaufzeichnungen benötigt wird
* Ergänzung zu arc42 Abschnitt 9 (Architekturentscheidungen)

[discrete]
== *Aktueller Stand*:

* Die aktuelle Version ist https://adr.github.io/madr/[MADR 4.0.0] (September 2024). Der Name änderte sich unterwegs zweimal: MADR 3.x (2022) benannte „Markdown *Architectural* Decision Records" in „Markdown *Any* Decision Records" um; 4.0 benannte zurück — das Template bleibt für beliebige Entscheidungen nutzbar
* Der Trainingsdaten-Prior eines LLM reproduziert höchstwahrscheinlich das Format der 2.x-Ära (2018–2022, die langlebigste und meistkopierte Variante): Inline-Bullets `* Status:` / `* Deciders:` / `* Date:` und getrennte „Positive/Negative Consequences"-Abschnitte — statt des aktuellen YAML-Front-Matter mit `decision-makers`, dem zusammengelegten „Consequences"-Abschnitt und dem in 3.x/4.x eingeführten „Confirmation"-Element
* Wenn das exakte Format zählt: dem Modell das https://github.com/adr/madr/tree/4.0.0/template[aktuelle Template] zeigen oder in den Prompt einfügen — der Ankername aktiviert zuverlässig das Konzept, aber nicht den aktuellen Feldsatz
====
9 changes: 8 additions & 1 deletion docs/anchors/owasp-top-10.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ A09 – Security Logging and Monitoring Failures:: Insufficient logging, detecti
A10 – Server-Side Request Forgery (SSRF):: Server fetches remote resources from attacker-controlled URLs without validation


Key Proponent:: OWASP Foundation (https://owasp.org/Top10/, first published 2003, current edition 2021)
Key Proponent:: OWASP Foundation (https://owasp.org/Top10/, first published 2003; the list above is the 2021 edition)

[discrete]
== *When to Use*:
Expand All @@ -53,4 +53,11 @@ Key Proponent:: OWASP Foundation (https://owasp.org/Top10/, first published 2003

* <<regulated-environment,Regulated Environment>>
* <<iec-61508-sil-levels,IEC 61508 SIL Levels>>

[discrete]
== *Current Status*:

* The list above is the *2021* edition. The current released edition is https://owasp.org/Top10/2025/[OWASP Top 10:2025] (RC November 2025, finalized around the turn of 2025/26): it adds *Software Supply Chain Failures* (A03) and *Mishandling of Exceptional Conditions* (A10), folds SSRF into Broken Access Control, and re-ranks several categories (https://owasp.org/Top10/2025/0x00_2025-Introduction/[what changed])
* An LLM's training-data prior for "OWASP Top 10" most plausibly serves the 2021 edition — it was current for over four years and dominates tutorials, courses, and blog material; models with earlier cutoffs may even blend in 2017
* Name the edition explicitly in prompts ("OWASP Top 10:2025" vs ":2021") — bare category IDs are ambiguous across editions: A03 means Injection in 2021 but Software Supply Chain Failures in 2025
====
Loading
Loading