diff --git a/.github/ISSUE_TEMPLATE/propose-anchor.yml b/.github/ISSUE_TEMPLATE/propose-anchor.yml index 6e4131b..d09585e 100644 --- a/.github/ISSUE_TEMPLATE/propose-anchor.yml +++ b/.github/ISSUE_TEMPLATE/propose-anchor.yml @@ -11,12 +11,33 @@ body: Thank you for proposing a new semantic anchor! Here's the workflow: 1. **You provide a term or concept** that you believe would make a good semantic anchor - 2. **GitHub Copilot validates** whether it meets the quality criteria (precise, rich, consistent, attributable) - 3. **If accepted**: Copilot enriches this issue with detailed information (proponents, categories, related concepts) - 4. **If rejected**: Copilot explains why it doesn't meet the criteria - 5. **After enrichment**: Copilot is assigned to create the anchor file and submit a PR + 2. **The review agent validates** whether it meets the quality criteria (see below) + 3. **If accepted**: The agent enriches this issue with detailed information (proponents, categories, related concepts) and assigns a quality tier + 4. **If rejected**: The agent explains why it doesn't meet the criteria + 5. **After enrichment**: The agent creates the anchor file and submits a PR - **Just provide the term below - Copilot handles the rest!** + ### Quality Criteria + + A semantic anchor must be **precise**, **rich**, **consistent**, and **attributable**. + + ### Tier Rating (★) + + The review agent assigns one of three tiers based on how reliably the anchor improves LLM communication: + + - **★★★ Self-standing**: Saying the anchor name alone reliably activates the correct behavior in the LLM. Clear, actionable, deterministic output. Examples: arc42, SOLID, Gherkin, MECE, Chain of Thought. + - **★★☆ Needs qualification**: The concept is known but requires a qualifier for reliable results. The anchor documentation must specify the recommended qualified form. Examples: "ADR according to Nygard", "3-point Pugh Matrix". + - **★☆☆ Descriptive only**: The term describes a concept but does not give the LLM clear instructions. These are **rejected** unless the proposer can demonstrate a concrete, actionable prompt pattern. + + ### Rejection Criteria + + The review agent **rejects** proposals that are: + - Pure philosophy without actionable instructions (e.g., "TIMTOWTDI") + - Personality/assessment frameworks without LLM utility (e.g., "MBTI") + - Fully covered by an existing anchor (e.g., "Rubber Duck Debugging" ≈ Socratic Method) + - Too vague to produce consistent LLM output (e.g., "Keep it simple") + - Not an established concept (invented by the proposer) + + **Just provide the term below - the review agent handles the rest!** - type: input id: term diff --git a/docs/anchors/_template.adoc b/docs/anchors/_template.adoc index 8b3e0e5..a3b561b 100644 --- a/docs/anchors/_template.adoc +++ b/docs/anchors/_template.adoc @@ -4,6 +4,7 @@ :related: related-anchor-1, related-anchor-2 :proponents: Author Name, Another Author :tags: tag1, tag2, tag3 +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/adr-according-to-nygard.adoc b/docs/anchors/adr-according-to-nygard.adoc index 049030a..1ab0bd4 100644 --- a/docs/anchors/adr-according-to-nygard.adoc +++ b/docs/anchors/adr-according-to-nygard.adoc @@ -1,6 +1,7 @@ = ADR according to Nygard :categories: software-architecture :roles: software-architect, software-developer, team-lead +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/arc42.adoc b/docs/anchors/arc42.adoc index 8cee715..e9dc324 100644 --- a/docs/anchors/arc42.adoc +++ b/docs/anchors/arc42.adoc @@ -2,6 +2,7 @@ :categories: software-architecture :roles: software-architect, technical-writer, team-lead :proponents: Gernot Starke, Peter Hruschka +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/atam.adoc b/docs/anchors/atam.adoc index 0f9615b..8e2c78c 100644 --- a/docs/anchors/atam.adoc +++ b/docs/anchors/atam.adoc @@ -4,6 +4,7 @@ :related: arc42, adr-according-to-nygard :proponents: Rick Kazman, Mark Klein, Paul Clements :tags: architecture evaluation, quality attributes, tradeoffs, utility tree, SEI, risk analysis +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/bdd-given-when-then.adoc b/docs/anchors/bdd-given-when-then.adoc index 135d0d8..8188f14 100644 --- a/docs/anchors/bdd-given-when-then.adoc +++ b/docs/anchors/bdd-given-when-then.adoc @@ -4,6 +4,7 @@ :proponents: Dan North :related: tdd-london-school, tdd-chicago-school, user-story-mapping :tags: bdd, gherkin, cucumber, specification-by-example, three-amigos, given-when-then, living-documentation +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/bem-methodology.adoc b/docs/anchors/bem-methodology.adoc index 4f2f262..3de9388 100644 --- a/docs/anchors/bem-methodology.adoc +++ b/docs/anchors/bem-methodology.adoc @@ -2,6 +2,7 @@ :categories: development-workflow :roles: software-developer, ux-designer :proponents: Yandex development team +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/bluf.adoc b/docs/anchors/bluf.adoc index 50f51a1..fd7a453 100644 --- a/docs/anchors/bluf.adoc +++ b/docs/anchors/bluf.adoc @@ -2,6 +2,7 @@ :categories: communication-presentation :roles: business-analyst, team-lead, technical-writer, consultant :proponents: US Military (Army writing standards), adopted broadly in business and government +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/c4-diagrams.adoc b/docs/anchors/c4-diagrams.adoc index 5d0a841..2dd4f55 100644 --- a/docs/anchors/c4-diagrams.adoc +++ b/docs/anchors/c4-diagrams.adoc @@ -1,6 +1,7 @@ = C4-Diagrams :categories: software-architecture :roles: software-architect, technical-writer, team-lead, consultant +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/chain-of-thought.adoc b/docs/anchors/chain-of-thought.adoc index cf8e35c..8b9df90 100644 --- a/docs/anchors/chain-of-thought.adoc +++ b/docs/anchors/chain-of-thought.adoc @@ -2,6 +2,7 @@ :categories: problem-solving :roles: software-developer, data-scientist, business-analyst :proponents: Wei et al. (Google Research, 2022), "Chain-of-Thought Prompting Elicits Reasoning in Large Language Models" +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/chatham-house-rule.adoc b/docs/anchors/chatham-house-rule.adoc deleted file mode 100644 index 42d1aa4..0000000 --- a/docs/anchors/chatham-house-rule.adoc +++ /dev/null @@ -1,71 +0,0 @@ -= Chatham House Rule -:categories: communication-presentation -:roles: team-lead, consultant, business-analyst, product-owner -:proponents: Chatham House (Royal Institute of International Affairs) -:tags: communication, confidentiality, meetings, open-discussion, trust - -[%collapsible] -==== -Full Name:: Chatham House Rule - -[discrete] -== *Core Concepts*: - -Information Sharing:: Participants are free to use information received, but neither the identity nor the affiliation of the speaker(s) may be revealed - -Confidentiality of Source:: "When a meeting, or part thereof, is held under the Chatham House Rule, participants are free to use the information received, but neither the identity nor the affiliation of the speaker(s), nor that of any other participant, may be revealed" - -Open Discussion:: Encourages frank and honest dialogue by removing attribution concerns - -Trust Building:: Creates psychological safety for participants to express controversial or sensitive views - -Knowledge Transfer:: Allows insights to be shared widely while protecting individual sources - -Single Rule Format:: Unlike other frameworks, it's a single, clearly defined rule - -Attribution Separation:: Distinguishes between "what was said" (shareable) and "who said it" (protected) - -Context Independence:: Applies equally to small meetings, large conferences, or online discussions - -Key Origin:: Established by Chatham House (Royal Institute of International Affairs) in London, 1927 - -Historical Context:: Originally created to enable diplomats and government officials to discuss international affairs candidly; now widely adopted across business, academia, and technology sectors - -[discrete] -== *When to Use*: - -* Strategic planning sessions where sensitive business information is discussed -* Retrospectives where team members need to speak candidly about problems -* Cross-organizational meetings where participants represent competing interests -* Executive briefings on sensitive topics -* Security discussions involving vulnerabilities or incidents -* Research interviews where anonymity encourages honesty -* Board meetings discussing confidential matters -* Community forums where psychological safety is needed - -[discrete] -== *Common Misunderstandings*: - -* ❌ "Everything is off the record" - Information CAN be shared, just not attributed -* ❌ "Nothing can be quoted" - The content is shareable, but without attribution -* ❌ "Conversations are confidential" - The rule protects identity, not information -* ✓ "You can use the insights, just don't say who said them" - Correct understanding - -[discrete] -== *Related Concepts*: - -* Psychological safety in teams -* Non-disclosure agreements (NDAs) - more restrictive than Chatham House Rule -* Off-the-record conversations -* Anonymous feedback systems - -[discrete] -== *Example Invocation*: - -[quote] -____ -This retrospective will be conducted under the Chatham House Rule. -You may share the insights we generate, but don't attribute comments -to specific team members. -____ -==== diff --git a/docs/anchors/chatham-house-rule.de.adoc b/docs/anchors/chatham-house-rule.de.adoc deleted file mode 100644 index e16fdda..0000000 --- a/docs/anchors/chatham-house-rule.de.adoc +++ /dev/null @@ -1,71 +0,0 @@ -= Chatham House Rule -:categories: communication-presentation -:roles: team-lead, consultant, business-analyst, product-owner -:proponents: Chatham House (Royal Institute of International Affairs) -:tags: kommunikation, vertraulichkeit, meetings, offene-diskussion, vertrauen - -[%collapsible] -==== -Vollständiger Name:: Chatham House Rule (Chatham-House-Regel) - -[discrete] -== *Kernkonzepte*: - -Informationsweitergabe:: Teilnehmer dürfen erhaltene Informationen frei verwenden, aber weder die Identität noch die Zugehörigkeit des Sprechers/der Sprecher darf offengelegt werden - -Vertraulichkeit der Quelle:: "Wenn ein Meeting oder ein Teil davon unter der Chatham House Rule stattfindet, dürfen die Teilnehmer die erhaltenen Informationen verwenden, aber weder die Identität noch die Zugehörigkeit des Sprechers/der Sprecher oder eines anderen Teilnehmers darf offengelegt werden" - -Offene Diskussion:: Fördert ehrlichen und direkten Dialog, indem Zuordnungsbedenken beseitigt werden - -Vertrauensbildung:: Schafft psychologische Sicherheit für Teilnehmer, um kontroverse oder sensible Ansichten zu äußern - -Wissenstransfer:: Ermöglicht die breite Weitergabe von Erkenntnissen bei gleichzeitigem Schutz individueller Quellen - -Einzelnes-Regel-Format:: Anders als andere Frameworks besteht es aus einer einzigen, klar definierten Regel - -Trennung der Attribution:: Unterscheidet zwischen "was gesagt wurde" (teilbar) und "wer es sagte" (geschützt) - -Kontextunabhängigkeit:: Gilt gleichermaßen für kleine Meetings, große Konferenzen oder Online-Diskussionen - -Ursprung:: Etabliert von Chatham House (Royal Institute of International Affairs) in London, 1927 - -Historischer Kontext:: Ursprünglich geschaffen, um Diplomaten und Regierungsbeamten die offene Diskussion internationaler Angelegenheiten zu ermöglichen; heute weit verbreitet in Wirtschaft, Wissenschaft und Technologiesektor - -[discrete] -== *Wann zu verwenden*: - -* Strategieplanungssitzungen, in denen sensible Geschäftsinformationen besprochen werden -* Retrospektiven, in denen Teammitglieder offen über Probleme sprechen müssen -* Organisationsübergreifende Meetings, bei denen Teilnehmer konkurrierende Interessen vertreten -* Executive Briefings zu sensiblen Themen -* Sicherheitsdiskussionen über Schwachstellen oder Vorfälle -* Forschungsinterviews, bei denen Anonymität Ehrlichkeit fördert -* Vorstandssitzungen zur Diskussion vertraulicher Angelegenheiten -* Community-Foren, bei denen psychologische Sicherheit benötigt wird - -[discrete] -== *Häufige Missverständnisse*: - -* ❌ "Alles ist vertraulich" - Informationen KÖNNEN geteilt werden, nur nicht zugeordnet -* ❌ "Nichts darf zitiert werden" - Der Inhalt ist teilbar, nur nicht mit Attribution -* ❌ "Gespräche sind geheim" - Die Regel schützt Identität, nicht Information -* ✓ "Sie können die Erkenntnisse nutzen, sagen Sie nur nicht, wer sie geäußert hat" - Korrekte Interpretation - -[discrete] -== *Verwandte Konzepte*: - -* Psychologische Sicherheit in Teams -* Geheimhaltungsvereinbarungen (NDAs) - restriktiver als die Chatham House Rule -* Off-the-Record-Gespräche -* Anonyme Feedback-Systeme - -[discrete] -== *Beispielhafte Anwendung*: - -[quote] -____ -Diese Retrospektive wird unter der Chatham House Rule durchgeführt. -Sie dürfen die generierten Erkenntnisse teilen, aber ordnen Sie -Kommentare nicht spezifischen Teammitgliedern zu. -____ -==== diff --git a/docs/anchors/clean-architecture.adoc b/docs/anchors/clean-architecture.adoc index 3507105..69e055b 100644 --- a/docs/anchors/clean-architecture.adoc +++ b/docs/anchors/clean-architecture.adoc @@ -1,6 +1,7 @@ = Clean Architecture :categories: software-architecture :roles: software-architect, software-developer +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/control-chart-shewhart.adoc b/docs/anchors/control-chart-shewhart.adoc index 1fd2b2d..90ed276 100644 --- a/docs/anchors/control-chart-shewhart.adoc +++ b/docs/anchors/control-chart-shewhart.adoc @@ -1,6 +1,8 @@ = Control Chart (Shewhart) :categories: statistical-methods :roles: data-scientist, devops-engineer, team-lead +:tier: 3 +:parent-anchor: spc [%collapsible] ==== diff --git a/docs/anchors/conventional-commits.adoc b/docs/anchors/conventional-commits.adoc index b442f18..c5b2fec 100644 --- a/docs/anchors/conventional-commits.adoc +++ b/docs/anchors/conventional-commits.adoc @@ -2,6 +2,7 @@ :categories: development-workflow :roles: software-developer, devops-engineer :proponents: Benjamin E. Coe, James J. Womack, Steve Mao +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/cqrs.adoc b/docs/anchors/cqrs.adoc index efbe959..7988506 100644 --- a/docs/anchors/cqrs.adoc +++ b/docs/anchors/cqrs.adoc @@ -4,6 +4,7 @@ :proponents: Greg Young, Bertrand Meyer, Udi Dahan :related: domain-driven-design, hexagonal-architecture, fowler-patterns :tags: cqrs, cqs, architecture, commands, queries, read-write-separation +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/cynefin-framework.adoc b/docs/anchors/cynefin-framework.adoc index a76ae1d..52e6c6a 100644 --- a/docs/anchors/cynefin-framework.adoc +++ b/docs/anchors/cynefin-framework.adoc @@ -4,6 +4,7 @@ :proponents: Dave Snowden :related: wardley-mapping :tags: complexity, decision-making, sensemaking, strategy, domains +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/devils-advocate.adoc b/docs/anchors/devils-advocate.adoc index 5eb53ae..79a974b 100644 --- a/docs/anchors/devils-advocate.adoc +++ b/docs/anchors/devils-advocate.adoc @@ -1,6 +1,7 @@ = Devil's Advocate :categories: problem-solving :roles: software-architect, team-lead, consultant, qa-engineer +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/diataxis-framework.adoc b/docs/anchors/diataxis-framework.adoc index 07ef527..de342e7 100644 --- a/docs/anchors/diataxis-framework.adoc +++ b/docs/anchors/diataxis-framework.adoc @@ -1,6 +1,7 @@ = Diátaxis Framework :categories: documentation :roles: technical-writer, educator +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/docs-as-code.adoc b/docs/anchors/docs-as-code.adoc index fc88642..5c5a8f9 100644 --- a/docs/anchors/docs-as-code.adoc +++ b/docs/anchors/docs-as-code.adoc @@ -1,6 +1,7 @@ = Docs-as-Code according to Ralf D. Müller :categories: documentation :roles: technical-writer, software-developer, devops-engineer +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/domain-driven-design.adoc b/docs/anchors/domain-driven-design.adoc index f449c17..a9a10c7 100644 --- a/docs/anchors/domain-driven-design.adoc +++ b/docs/anchors/domain-driven-design.adoc @@ -1,6 +1,7 @@ = Domain-Driven Design according to Evans :categories: software-architecture :roles: software-architect, software-developer, business-analyst, team-lead +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/dry-principle.adoc b/docs/anchors/dry-principle.adoc deleted file mode 100644 index 2608bae..0000000 --- a/docs/anchors/dry-principle.adoc +++ /dev/null @@ -1,38 +0,0 @@ -= DRY (Don't Repeat Yourself) -:categories: design-principles -:roles: software-developer, software-architect - -[%collapsible] -==== -Full Name:: Don't Repeat Yourself Principle - -[discrete] -== *Core Concepts*: - -Single representation:: Every piece of knowledge should have a single, unambiguous representation - -Avoid duplication:: Eliminate duplicate code, logic, and knowledge across the system - -Abstraction:: Extract common patterns into reusable components - -Maintenance efficiency:: Changes require modification in only one place - -Knowledge duplication vs. code duplication:: Focus on avoiding duplicate knowledge, not just duplicate code - -Normalized data:: Apply DRY to data structures and schemas - -Configuration management:: Centralize configuration and avoid scattered settings - - -Key Proponent:: Andy Hunt and Dave Thomas ("The Pragmatic Programmer", 1999) - -[discrete] -== *When to Use*: - -* Refactoring codebases with repeated logic or patterns -* Designing APIs and libraries to minimize client code duplication -* Creating maintainable systems where changes are frequent -* Establishing coding standards and best practices - -Related Concepts:: SPOT, SSOT, WET (Write Everything Twice - deliberate exception to DRY) -==== diff --git a/docs/anchors/dry-principle.de.adoc b/docs/anchors/dry-principle.de.adoc deleted file mode 100644 index db535f5..0000000 --- a/docs/anchors/dry-principle.de.adoc +++ /dev/null @@ -1,38 +0,0 @@ -= DRY (Don't Repeat Yourself) -:categories: design-principles -:roles: software-developer, software-architect - -[%collapsible] -==== -Vollständiger Name:: Don't Repeat Yourself-Prinzip (Wiederhole dich nicht) - -[discrete] -== *Kernkonzepte*: - -Einzelne Repräsentation:: Jedes Stück Wissen sollte eine einzelne, eindeutige Repräsentation haben - -Duplizierung vermeiden:: Duplizierten Code, Logik und Wissen über das System hinweg eliminieren - -Abstraktion:: Gemeinsame Muster in wiederverwendbare Komponenten extrahieren - -Wartungseffizienz:: Änderungen erfordern Modifikation an nur einer Stelle - -Wissensduplizierung vs. Code-Duplizierung:: Fokus auf Vermeidung duplizierter Wissen, nicht nur duplizierter Code - -Normalisierte Daten:: DRY auf Datenstrukturen und Schemata anwenden - -Konfigurationsmanagement:: Konfiguration zentralisieren und verstreute Einstellungen vermeiden - - -Schlüsselvertreter:: Andy Hunt und Dave Thomas ("The Pragmatic Programmer", 1999) - -[discrete] -== *Wann zu verwenden*: - -* Refactoring von Codebasen mit wiederholter Logik oder Mustern -* Entwerfen von APIs und Bibliotheken zur Minimierung von Client-Code-Duplizierung -* Erstellen wartbarer Systeme, bei denen Änderungen häufig sind -* Etablieren von Coding-Standards und Best Practices - -Verwandte Konzepte:: SPOT, SSOT, WET (Write Everything Twice - bewusste Ausnahme von DRY) -==== diff --git a/docs/anchors/ears-requirements.adoc b/docs/anchors/ears-requirements.adoc index 8334222..028e444 100644 --- a/docs/anchors/ears-requirements.adoc +++ b/docs/anchors/ears-requirements.adoc @@ -1,6 +1,7 @@ = EARS-Requirements :categories: requirements-engineering :roles: business-analyst, qa-engineer, technical-writer +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/event-driven-architecture.adoc b/docs/anchors/event-driven-architecture.adoc index 985637f..6b868f2 100644 --- a/docs/anchors/event-driven-architecture.adoc +++ b/docs/anchors/event-driven-architecture.adoc @@ -4,6 +4,7 @@ :proponents: Gregor Hohpe, Bobby Woolf, Martin Fowler :related: domain-driven-design, hexagonal-architecture, clean-architecture :tags: eda, events, async, messaging, publish-subscribe, decoupling, eventual-consistency +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/feynman-technique.adoc b/docs/anchors/feynman-technique.adoc index edb08c6..377a80e 100644 --- a/docs/anchors/feynman-technique.adoc +++ b/docs/anchors/feynman-technique.adoc @@ -1,6 +1,7 @@ = Feynman Technique :categories: problem-solving :roles: software-developer, educator, consultant, team-lead +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/five-whys.adoc b/docs/anchors/five-whys.adoc index 2aba3a9..39fbad0 100644 --- a/docs/anchors/five-whys.adoc +++ b/docs/anchors/five-whys.adoc @@ -1,6 +1,7 @@ = Five Whys (Ohno) :categories: problem-solving :roles: software-developer, qa-engineer, devops-engineer, team-lead +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/fowler-patterns.adoc b/docs/anchors/fowler-patterns.adoc index 59ef171..aa08b8a 100644 --- a/docs/anchors/fowler-patterns.adoc +++ b/docs/anchors/fowler-patterns.adoc @@ -4,6 +4,7 @@ :proponents: Martin Fowler :related: domain-driven-design, hexagonal-architecture, clean-architecture :tags: enterprise, architecture, patterns, design-patterns, orm +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/gherkin.adoc b/docs/anchors/gherkin.adoc index 057ba0a..dd0ffd6 100644 --- a/docs/anchors/gherkin.adoc +++ b/docs/anchors/gherkin.adoc @@ -4,6 +4,7 @@ :related: bdd-given-when-then, ears-requirements, tdd-london-school :proponents: Aslak Hellesøy :tags: gherkin, bdd, cucumber, given-when-then, specification-by-example, dsl, acceptance-testing, living-documentation +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/gof-abstract-factory-pattern.adoc b/docs/anchors/gof-abstract-factory-pattern.adoc index bafb8f1..233c21d 100644 --- a/docs/anchors/gof-abstract-factory-pattern.adoc +++ b/docs/anchors/gof-abstract-factory-pattern.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: gof-design-patterns -:tier: 2 +:tier: 3 :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :tags: GoF, design pattern, creational, abstract factory, family, platform independence diff --git a/docs/anchors/gof-adapter-pattern.adoc b/docs/anchors/gof-adapter-pattern.adoc index 8fa1349..4a8b59f 100644 --- a/docs/anchors/gof-adapter-pattern.adoc +++ b/docs/anchors/gof-adapter-pattern.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: gof-design-patterns -:tier: 1 +:tier: 3 :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :tags: GoF, design pattern, structural, adapter, wrapper, interface conversion, compatibility diff --git a/docs/anchors/gof-bridge-pattern.adoc b/docs/anchors/gof-bridge-pattern.adoc index 58bb6fd..cf767ec 100644 --- a/docs/anchors/gof-bridge-pattern.adoc +++ b/docs/anchors/gof-bridge-pattern.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: gof-design-patterns -:tier: 2 +:tier: 3 :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :tags: GoF, design pattern, structural, bridge, abstraction, implementation, decoupling diff --git a/docs/anchors/gof-builder-pattern.adoc b/docs/anchors/gof-builder-pattern.adoc index eb95e50..312d759 100644 --- a/docs/anchors/gof-builder-pattern.adoc +++ b/docs/anchors/gof-builder-pattern.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: gof-design-patterns -:tier: 1 +:tier: 3 :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :tags: GoF, design pattern, creational, builder, construction, fluent interface, complex objects diff --git a/docs/anchors/gof-chain-of-responsibility-pattern.adoc b/docs/anchors/gof-chain-of-responsibility-pattern.adoc index 1510357..4e4509e 100644 --- a/docs/anchors/gof-chain-of-responsibility-pattern.adoc +++ b/docs/anchors/gof-chain-of-responsibility-pattern.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: gof-design-patterns -:tier: 2 +:tier: 3 :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :tags: GoF, design pattern, behavioral, chain of responsibility, handler, pipeline, middleware diff --git a/docs/anchors/gof-command-pattern.adoc b/docs/anchors/gof-command-pattern.adoc index 8a106d7..8c5546a 100644 --- a/docs/anchors/gof-command-pattern.adoc +++ b/docs/anchors/gof-command-pattern.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: gof-design-patterns -:tier: 1 +:tier: 3 :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :tags: GoF, design pattern, behavioral, command, undo, queue, encapsulation, action diff --git a/docs/anchors/gof-composite-pattern.adoc b/docs/anchors/gof-composite-pattern.adoc index 2d2be21..3e02418 100644 --- a/docs/anchors/gof-composite-pattern.adoc +++ b/docs/anchors/gof-composite-pattern.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: gof-design-patterns -:tier: 2 +:tier: 3 :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :tags: GoF, design pattern, structural, composite, tree, hierarchy, part-whole diff --git a/docs/anchors/gof-decorator-pattern.adoc b/docs/anchors/gof-decorator-pattern.adoc index 2c83194..ed77ff5 100644 --- a/docs/anchors/gof-decorator-pattern.adoc +++ b/docs/anchors/gof-decorator-pattern.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: gof-design-patterns -:tier: 1 +:tier: 3 :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :tags: GoF, design pattern, structural, decorator, wrapper, dynamic behavior, composition diff --git a/docs/anchors/gof-design-patterns.adoc b/docs/anchors/gof-design-patterns.adoc index 0e897dc..ebdacac 100644 --- a/docs/anchors/gof-design-patterns.adoc +++ b/docs/anchors/gof-design-patterns.adoc @@ -4,6 +4,7 @@ :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :related: solid-principles, fowler-patterns, clean-architecture :tags: design-patterns, gang-of-four, oop, creational, structural, behavioral +:tier: 3 :sub-anchors: gof-strategy-pattern, gof-observer-pattern, gof-factory-method-pattern, gof-singleton-pattern, gof-adapter-pattern, gof-decorator-pattern, gof-command-pattern, gof-facade-pattern, gof-template-method-pattern, gof-builder-pattern, gof-state-pattern, gof-proxy-pattern, gof-abstract-factory-pattern, gof-composite-pattern, gof-iterator-pattern, gof-mediator-pattern, gof-chain-of-responsibility-pattern, gof-bridge-pattern, gof-prototype-pattern, gof-flyweight-pattern, gof-interpreter-pattern, gof-memento-pattern, gof-visitor-pattern [%collapsible] diff --git a/docs/anchors/gof-facade-pattern.adoc b/docs/anchors/gof-facade-pattern.adoc index 8cf098a..f8d07d5 100644 --- a/docs/anchors/gof-facade-pattern.adoc +++ b/docs/anchors/gof-facade-pattern.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: gof-design-patterns -:tier: 1 +:tier: 3 :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :tags: GoF, design pattern, structural, facade, simplification, subsystem, unified interface diff --git a/docs/anchors/gof-factory-method-pattern.adoc b/docs/anchors/gof-factory-method-pattern.adoc index ea52fcf..8c0c437 100644 --- a/docs/anchors/gof-factory-method-pattern.adoc +++ b/docs/anchors/gof-factory-method-pattern.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: gof-design-patterns -:tier: 1 +:tier: 3 :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :tags: GoF, design pattern, creational, factory, polymorphism, instantiation diff --git a/docs/anchors/gof-iterator-pattern.adoc b/docs/anchors/gof-iterator-pattern.adoc index cd31c53..98ee66d 100644 --- a/docs/anchors/gof-iterator-pattern.adoc +++ b/docs/anchors/gof-iterator-pattern.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: gof-design-patterns -:tier: 2 +:tier: 3 :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :tags: GoF, design pattern, behavioral, iterator, traversal, collection, aggregate diff --git a/docs/anchors/gof-mediator-pattern.adoc b/docs/anchors/gof-mediator-pattern.adoc index d95062f..7cd592a 100644 --- a/docs/anchors/gof-mediator-pattern.adoc +++ b/docs/anchors/gof-mediator-pattern.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: gof-design-patterns -:tier: 2 +:tier: 3 :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :tags: GoF, design pattern, behavioral, mediator, loose coupling, coordination, hub diff --git a/docs/anchors/gof-observer-pattern.adoc b/docs/anchors/gof-observer-pattern.adoc index 5ab1d5d..7d30e1b 100644 --- a/docs/anchors/gof-observer-pattern.adoc +++ b/docs/anchors/gof-observer-pattern.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: gof-design-patterns -:tier: 1 +:tier: 3 :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :tags: GoF, design pattern, behavioral, observer, publish-subscribe, event, notification, reactive diff --git a/docs/anchors/gof-prototype-pattern.adoc b/docs/anchors/gof-prototype-pattern.adoc index f6b4d3f..977d09e 100644 --- a/docs/anchors/gof-prototype-pattern.adoc +++ b/docs/anchors/gof-prototype-pattern.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: gof-design-patterns -:tier: 2 +:tier: 3 :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :tags: GoF, design pattern, creational, prototype, cloning, copy, object creation diff --git a/docs/anchors/gof-proxy-pattern.adoc b/docs/anchors/gof-proxy-pattern.adoc index 5caa80c..392f4e5 100644 --- a/docs/anchors/gof-proxy-pattern.adoc +++ b/docs/anchors/gof-proxy-pattern.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: gof-design-patterns -:tier: 1 +:tier: 3 :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :tags: GoF, design pattern, structural, proxy, access control, lazy loading, caching, virtual proxy diff --git a/docs/anchors/gof-singleton-pattern.adoc b/docs/anchors/gof-singleton-pattern.adoc index 2f21626..81eac9f 100644 --- a/docs/anchors/gof-singleton-pattern.adoc +++ b/docs/anchors/gof-singleton-pattern.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: gof-design-patterns -:tier: 1 +:tier: 3 :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :tags: GoF, design pattern, creational, singleton, global state, instance control diff --git a/docs/anchors/gof-state-pattern.adoc b/docs/anchors/gof-state-pattern.adoc index 763d99a..48da1c6 100644 --- a/docs/anchors/gof-state-pattern.adoc +++ b/docs/anchors/gof-state-pattern.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: gof-design-patterns -:tier: 1 +:tier: 3 :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :tags: GoF, design pattern, behavioral, state, state machine, finite automaton, context diff --git a/docs/anchors/gof-strategy-pattern.adoc b/docs/anchors/gof-strategy-pattern.adoc index 2c1e65b..b95383a 100644 --- a/docs/anchors/gof-strategy-pattern.adoc +++ b/docs/anchors/gof-strategy-pattern.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: gof-design-patterns -:tier: 1 +:tier: 3 :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :tags: GoF, design pattern, behavioral, strategy diff --git a/docs/anchors/gof-template-method-pattern.adoc b/docs/anchors/gof-template-method-pattern.adoc index ae96843..d5c7184 100644 --- a/docs/anchors/gof-template-method-pattern.adoc +++ b/docs/anchors/gof-template-method-pattern.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: gof-design-patterns -:tier: 1 +:tier: 3 :proponents: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides :tags: GoF, design pattern, behavioral, template method, algorithm skeleton, hook, inheritance diff --git a/docs/anchors/gom.adoc b/docs/anchors/gom.adoc index 77c0b04..567b4b2 100644 --- a/docs/anchors/gom.adoc +++ b/docs/anchors/gom.adoc @@ -4,6 +4,7 @@ :related: arc42, c4-diagrams, morphological-box :proponents: Jörg Becker, Michael Rosemann, Rolf Schütte :tags: modeling, enterprise-architecture, business-process, bpm, principles, quality +:tier: 2 [%collapsible] ==== diff --git a/docs/anchors/gutes-deutsch-wolf-schneider.adoc b/docs/anchors/gutes-deutsch-wolf-schneider.adoc index a8e52bf..99d69ca 100644 --- a/docs/anchors/gutes-deutsch-wolf-schneider.adoc +++ b/docs/anchors/gutes-deutsch-wolf-schneider.adoc @@ -4,6 +4,7 @@ :related: bluf, pyramid-principle :proponents: Wolf Schneider :tags: writing, german, clarity, style, prose, language +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/hexagonal-architecture.adoc b/docs/anchors/hexagonal-architecture.adoc index bece943..e599268 100644 --- a/docs/anchors/hexagonal-architecture.adoc +++ b/docs/anchors/hexagonal-architecture.adoc @@ -1,6 +1,7 @@ = Hexagonal Architecture (Ports & Adapters) :categories: software-architecture :roles: software-architect, software-developer +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/iec-61508-sil-levels.adoc b/docs/anchors/iec-61508-sil-levels.adoc index 740d889..a104eb3 100644 --- a/docs/anchors/iec-61508-sil-levels.adoc +++ b/docs/anchors/iec-61508-sil-levels.adoc @@ -4,6 +4,7 @@ :proponents: International Electrotechnical Commission (IEC) :related: testing-pyramid, mutation-testing :tags: safety, functional-safety, SIL, standards, certification, risk-assessment +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/impact-mapping.adoc b/docs/anchors/impact-mapping.adoc index 8202f23..7cfdf3a 100644 --- a/docs/anchors/impact-mapping.adoc +++ b/docs/anchors/impact-mapping.adoc @@ -1,6 +1,7 @@ = Impact Mapping :categories: strategic-planning :roles: product-owner, business-analyst, team-lead, consultant +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/jobs-to-be-done.adoc b/docs/anchors/jobs-to-be-done.adoc index cc1cd06..b667f4b 100644 --- a/docs/anchors/jobs-to-be-done.adoc +++ b/docs/anchors/jobs-to-be-done.adoc @@ -2,6 +2,7 @@ :categories: strategic-planning :roles: product-owner, ux-designer, business-analyst :proponents: Clayton Christensen, Alan Klement, Bob Moesta +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/lasr.adoc b/docs/anchors/lasr.adoc index c49d4f4..f22343f 100644 --- a/docs/anchors/lasr.adoc +++ b/docs/anchors/lasr.adoc @@ -4,6 +4,7 @@ :related: arc42, adr-according-to-nygard, c4-diagrams :proponents: Stefan Toth, Stefan Zörner :tags: architecture-documentation, solution-strategy, interfaces, risks, lightweight, communication +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/madr.adoc b/docs/anchors/madr.adoc index d1babb4..93b6a55 100644 --- a/docs/anchors/madr.adoc +++ b/docs/anchors/madr.adoc @@ -2,6 +2,7 @@ :categories: software-architecture :roles: software-architect, software-developer, team-lead :proponents: Oliver Kopp, Olaf Zimmermann (and MADR community) +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/mece.adoc b/docs/anchors/mece.adoc index 802983f..0e20bc3 100644 --- a/docs/anchors/mece.adoc +++ b/docs/anchors/mece.adoc @@ -1,6 +1,7 @@ = MECE Principle :categories: communication-presentation :roles: business-analyst, consultant, software-architect, data-scientist +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/mental-model-according-to-naur.adoc b/docs/anchors/mental-model-according-to-naur.adoc index 57d5ded..166b32a 100644 --- a/docs/anchors/mental-model-according-to-naur.adoc +++ b/docs/anchors/mental-model-according-to-naur.adoc @@ -1,51 +1,43 @@ -= Mental Model according to Naur += Programming as Theory Building (Naur) :categories: development-workflow :roles: software-developer, team-lead, educator, consultant +:related: adr-according-to-nygard, docs-as-code +:proponents: Peter Naur +:tier: 2 [%collapsible] ==== -Full Name:: Programming as Theory Building (Mental Model) according to Peter Naur +Also known as:: Mental Model according to Naur [discrete] == *Core Concepts*: -Theory building:: Programming is creating a mental model, not just writing code +Theory building:: Programming is creating a mental model, not just writing code. The real program exists in developers' minds, not in the code. -Theory of the program:: Deep understanding of why the program works and how it relates to the problem domain +Document the Why:: Code shows _what_ the system does. The theory captures _why_ it is built this way — the reasoning, trade-offs, and domain understanding behind the design. -Knowledge in people:: The real program exists in developers' minds, not in the code +Theory decay:: When original developers leave, the theory is lost. Written code alone cannot reconstruct it. This explains why maintenance by new teams is so difficult. -Theory decay:: When original developers leave, the theory is lost - -Documentation limitations:: Written documentation cannot fully capture the theory - -Maintenance as theory:: Effective maintenance requires possessing the theory - -Communication is key:: Theory must be shared through collaboration and conversation - -Ramp-up time:: New team members need time to build the theory - -Code as artifact:: Code is merely a representation of the underlying theory +Complement to ADRs:: ADRs document individual architectural decisions. Theory Building goes deeper: document the overarching understanding of why the system is shaped the way it is. +Communication is key:: Theory must be shared through collaboration, conversation, and documentation that captures intent, not just structure. Key Proponent:: Peter Naur (Turing Award winner, 1978) Original Work:: "Programming as Theory Building" (1985) [discrete] -== *Application in Software Development*: +== *When to Use*: -* Understanding why knowledge transfer is challenging -* Emphasizing pair programming and mob programming -* Justifying time for onboarding and code walkthroughs +* Tell an LLM: "Document the theory behind this code according to Naur — not what it does, but why it is built this way" +* Capturing design rationale beyond individual ADRs +* Onboarding documentation that explains the mental model behind a system +* Justifying time for knowledge transfer, pair programming, and code walkthroughs * Explaining technical debt accumulation when teams change -* Supporting documentation practices that capture "why" not just "what" -* Advocating for team stability and continuity [discrete] -== *Contrast with Other Views*: +== *Related Anchors*: -* Programming as text production → Focus on code output -* Programming as problem solving → Focus on algorithms -* Programming as theory building → Focus on understanding +* <> — complementary: ADRs for individual decisions, Theory Building for overarching understanding +* <> — the practice of maintaining this documentation alongside code ==== diff --git a/docs/anchors/morphological-box.adoc b/docs/anchors/morphological-box.adoc index d35ed2f..315ca48 100644 --- a/docs/anchors/morphological-box.adoc +++ b/docs/anchors/morphological-box.adoc @@ -4,6 +4,7 @@ :related: mece, pugh-matrix :proponents: Fritz Zwicky :tags: innovation, creativity, problem-solving, systematic-design, combinatorial-analysis +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/moscow.adoc b/docs/anchors/moscow.adoc index e8ee09a..7d695a1 100644 --- a/docs/anchors/moscow.adoc +++ b/docs/anchors/moscow.adoc @@ -4,6 +4,7 @@ :related: user-story-mapping, impact-mapping :proponents: Dai Clegg :tags: prioritization, requirements, agile, dsdm +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/mutation-testing.adoc b/docs/anchors/mutation-testing.adoc index a0c88c4..1fe4f92 100644 --- a/docs/anchors/mutation-testing.adoc +++ b/docs/anchors/mutation-testing.adoc @@ -2,6 +2,7 @@ :categories: testing-quality :roles: software-developer, qa-engineer :proponents: Richard Lipton (theoretical foundation, 1971), Richard DeMillo, Timothy Budd +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/myers-briggs-type-indicator.adoc b/docs/anchors/myers-briggs-type-indicator.adoc index 6b44f1d..f0286b7 100644 --- a/docs/anchors/myers-briggs-type-indicator.adoc +++ b/docs/anchors/myers-briggs-type-indicator.adoc @@ -3,6 +3,7 @@ :roles: team-lead, consultant, educator, ux-designer, product-owner :proponents: Isabel Briggs Myers, Katharine Cook Briggs, Carl Gustav Jung :tags: personality types, MBTI, psychological types, communication styles, team dynamics, Jungian psychology +:tier: 1 [%collapsible] ==== diff --git a/docs/anchors/nelson-rules.adoc b/docs/anchors/nelson-rules.adoc index ad85dd8..2d4fa5e 100644 --- a/docs/anchors/nelson-rules.adoc +++ b/docs/anchors/nelson-rules.adoc @@ -1,6 +1,8 @@ = Nelson Rules :categories: statistical-methods :roles: data-scientist, devops-engineer +:tier: 3 +:parent-anchor: spc [%collapsible] ==== diff --git a/docs/anchors/owasp-top-10.adoc b/docs/anchors/owasp-top-10.adoc index 993e3f3..e2a5850 100644 --- a/docs/anchors/owasp-top-10.adoc +++ b/docs/anchors/owasp-top-10.adoc @@ -4,6 +4,7 @@ :related: regulated-environment, iec-61508-sil-levels :proponents: OWASP Foundation :tags: security, web-security, vulnerabilities, risk, appsec, owasp +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/plain-english-strunk-white.adoc b/docs/anchors/plain-english-strunk-white.adoc index ecf909d..d711f43 100644 --- a/docs/anchors/plain-english-strunk-white.adoc +++ b/docs/anchors/plain-english-strunk-white.adoc @@ -4,6 +4,7 @@ :related: gutes-deutsch-wolf-schneider, bluf, pyramid-principle :proponents: William Strunk Jr., E.B. White :tags: writing, english, clarity, style, prose, language, plain-english +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/problem-space-nvc.adoc b/docs/anchors/problem-space-nvc.adoc index 10fe912..c856f3a 100644 --- a/docs/anchors/problem-space-nvc.adoc +++ b/docs/anchors/problem-space-nvc.adoc @@ -1,36 +1,41 @@ -= Problem Space NVC -:categories: requirements-engineering -:roles: business-analyst, product-owner, consultant, ux-designer += Nonviolent Communication (Rosenberg) +:categories: requirements-engineering, communication-presentation +:roles: business-analyst, product-owner, consultant, ux-designer, team-lead +:proponents: Marshall Rosenberg +:tags: nvc, communication, empathy, conflict-resolution, requirements +:tier: 3 [%collapsible] ==== -Full Name:: Problem Space in Nonviolent Communication +Also known as:: NVC, Problem Space NVC, Gewaltfreie Kommunikation (GFK) [discrete] == *Core Concepts*: -Observations:: Concrete, objective facts without evaluation +Observations:: Concrete, objective facts without evaluation or judgment. "The deploy failed three times this week" instead of "The deploy always fails." -Feelings:: Emotions arising from observations +Feelings:: Emotions arising from observations. "I feel frustrated" instead of "This is frustrating." -Needs:: Universal human needs underlying feelings +Needs:: Universal human needs underlying feelings. Reliability, autonomy, clarity, safety. The real driver behind every request. -Requests:: Specific, actionable requests (not demands) +Requests:: Specific, actionable asks (not demands). "Could we add a pre-deploy check?" instead of "Fix the deploy process." -Empathic connection:: Understanding before problem-solving +Four-step process:: Observe → Feel → Need → Request. Each step builds on the previous one. -Separating observation from interpretation:: Avoiding judgment - -Needs-based conflict resolution:: Finding solutions that meet everyone's needs +Key Proponent:: Marshall Rosenberg ("Nonviolent Communication: A Language of Life", 1999) +[discrete] +== *When to Use*: -Key Proponent:: Marshall Rosenberg +* Tell an LLM: "Reformulate this complaint using NVC according to Rosenberg" +* Tell an LLM: "Write this stakeholder email in NVC style — observation, feeling, need, request" +* Requirements elicitation that uncovers real user needs behind feature requests +* Conflict resolution in teams and retrospectives +* Transforming vague complaints into actionable requirements [discrete] -== *Application in Software Development*: +== *Related Anchors*: -* Requirements elicitation that uncovers real user needs -* Stakeholder communication and conflict resolution -* User story formulation focused on needs -* Retrospectives and team communication +* <> — complementary: NVC for expressing, Socratic for exploring +* <> — contrasting style: BLUF is conclusion-first, NVC is empathy-first ==== diff --git a/docs/anchors/property-based-testing.adoc b/docs/anchors/property-based-testing.adoc index 3cd68c9..0db0774 100644 --- a/docs/anchors/property-based-testing.adoc +++ b/docs/anchors/property-based-testing.adoc @@ -1,6 +1,7 @@ = Property-Based Testing :categories: testing-quality :roles: software-developer, qa-engineer +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/pugh-matrix.adoc b/docs/anchors/pugh-matrix.adoc index d88f304..07c1c4b 100644 --- a/docs/anchors/pugh-matrix.adoc +++ b/docs/anchors/pugh-matrix.adoc @@ -1,6 +1,7 @@ = Pugh-Matrix :categories: strategic-planning :roles: software-architect, team-lead, product-owner +:tier: 2 [%collapsible] ==== diff --git a/docs/anchors/pyramid-principle.adoc b/docs/anchors/pyramid-principle.adoc index 0e7b807..6d59b0a 100644 --- a/docs/anchors/pyramid-principle.adoc +++ b/docs/anchors/pyramid-principle.adoc @@ -1,6 +1,7 @@ = Pyramid Principle according to Barbara Minto :categories: communication-presentation :roles: business-analyst, consultant, team-lead, technical-writer +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/regulated-environment.adoc b/docs/anchors/regulated-environment.adoc index c7fe53d..9a13fff 100644 --- a/docs/anchors/regulated-environment.adoc +++ b/docs/anchors/regulated-environment.adoc @@ -4,6 +4,7 @@ :related: iec-61508-sil-levels, docs-as-code, conventional-commits, semantic-versioning :proponents: FDA (21 CFR Part 11), EMA (GMP Annex 11), ISO 9001, IEC 62304, GAMP 5 :tags: compliance, validation, traceability, audit-trail, change-control, documentation, GxP, FDA, IEC, ISO +:tier: 2 [%collapsible] ==== diff --git a/docs/anchors/rubber-duck-debugging.adoc b/docs/anchors/rubber-duck-debugging.adoc deleted file mode 100644 index e7c54bf..0000000 --- a/docs/anchors/rubber-duck-debugging.adoc +++ /dev/null @@ -1,48 +0,0 @@ -= Rubber Duck Debugging -:categories: problem-solving -:roles: software-developer, qa-engineer - -[%collapsible] -==== -Full Name:: Rubber Duck Debugging - -[discrete] -== *Core Concepts*: - -Explain to Understand:: Articulating a problem aloud surfaces gaps in understanding - -Step-by-Step Verbalization:: Force yourself to go through code/logic line by line - -Assumption Surfacing:: Speaking aloud exposes implicit assumptions that may be wrong - -No Expertise Required:: The "listener" (rubber duck, colleague, LLM) need not be an expert - -Slowing Down:: The act of explaining forces a slower, more deliberate thought process - -External Cognition:: Verbalizing creates an external representation that aids debugging - -Self-Directed Learning:: Often the explainer solves the problem before finishing the explanation - -Teaching to Learn:: Related to the Feynman Technique and learning-by-teaching principle - - -Key Origin:: "The Pragmatic Programmer" by Andrew Hunt and David Thomas (1999), referencing earlier programmer folklore - -Historical Context:: Decades-old practice in programming culture, formalized and named in influential software engineering literature - -[discrete] -== *When to Use*: - -* Debugging stubborn problems where you're stuck -* Code review where explaining to a colleague reveals issues -* Learning new concepts by teaching them to someone (or something) else -* Validating understanding of complex systems or algorithms -* When rubber-ducking to an LLM, explicitly adopting this frame to trigger step-by-step explanation - -[discrete] -== *Related Concepts*: - -* Pair programming (where explaining is continuous) -* <> (learning by simple explanation) -* <> (when the duck asks questions back) -==== diff --git a/docs/anchors/rubber-duck-debugging.de.adoc b/docs/anchors/rubber-duck-debugging.de.adoc deleted file mode 100644 index c300295..0000000 --- a/docs/anchors/rubber-duck-debugging.de.adoc +++ /dev/null @@ -1,48 +0,0 @@ -= Rubber Duck Debugging -:categories: problem-solving -:roles: software-developer, qa-engineer - -[%collapsible] -==== -Vollständiger Name:: Rubber Duck Debugging - -[discrete] -== *Kernkonzepte*: - -Erklären zum Verstehen:: Lautes Artikulieren eines Problems macht Verständnislücken sichtbar - -Schrittweise Verbalisierung:: Zwingt dazu, Code/Logik Zeile für Zeile durchzugehen - -Annahmen sichtbar machen:: Lautes Sprechen legt implizite Annahmen offen, die falsch sein könnten - -Keine Expertise erforderlich:: Der "Zuhörer" (Gummiente, Kollege, LLM) muss kein Experte sein - -Verlangsamung:: Der Akt des Erklärens erzwingt einen langsameren, überlegteren Denkprozess - -Externe Kognition:: Verbalisierung schafft eine externe Darstellung, die beim Debuggen hilft - -Selbstgesteuertes Lernen:: Oft löst der Erklärende das Problem, bevor er die Erklärung beendet - -Durch Lehren lernen:: Verwandt mit der Feynman-Technik und dem Lern-durch-Lehren-Prinzip - - -Schlüsselursprung:: "The Pragmatic Programmer" von Andrew Hunt und David Thomas (1999), unter Bezugnahme auf ältere Programmiererfolklore - -Historischer Kontext:: Jahrzehntealte Praxis in der Programmierkultur, formalisiert und benannt in einflussreicher Software-Engineering-Literatur - -[discrete] -== *Wann zu verwenden*: - -* Debugging hartnäckiger Probleme, bei denen man feststeckt -* Code-Review, bei dem das Erklären gegenüber einem Kollegen Probleme aufdeckt -* Lernen neuer Konzepte durch Lehren an jemanden (oder etwas) anderes -* Validierung des Verständnisses komplexer Systeme oder Algorithmen -* Beim Rubber-Ducking mit einem LLM, explizite Adoption dieses Rahmens, um schrittweise Erklärung auszulösen - -[discrete] -== *Verwandte Konzepte*: - -* Pair Programming (wo Erklären kontinuierlich ist) -* <> (Lernen durch einfache Erklärung) -* <> (wenn die Ente zurückfragt) -==== diff --git a/docs/anchors/semantic-versioning.adoc b/docs/anchors/semantic-versioning.adoc index 1a89c3e..744a258 100644 --- a/docs/anchors/semantic-versioning.adoc +++ b/docs/anchors/semantic-versioning.adoc @@ -1,6 +1,7 @@ = Semantic Versioning (SemVer) :categories: development-workflow :roles: software-developer, devops-engineer, product-owner +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/socratic-method.adoc b/docs/anchors/socratic-method.adoc index 1a34e9b..a8bf446 100644 --- a/docs/anchors/socratic-method.adoc +++ b/docs/anchors/socratic-method.adoc @@ -1,6 +1,7 @@ = Socratic Method :categories: dialogue-interaction :roles: educator, consultant, team-lead +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/solid-dip.adoc b/docs/anchors/solid-dip.adoc index 1cace79..a483445 100644 --- a/docs/anchors/solid-dip.adoc +++ b/docs/anchors/solid-dip.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: solid-principles -:tier: 1 +:tier: 3 :proponents: Robert C. Martin :tags: SOLID, design principle, DIP, dependency inversion diff --git a/docs/anchors/solid-isp.adoc b/docs/anchors/solid-isp.adoc index 62fac8f..595be74 100644 --- a/docs/anchors/solid-isp.adoc +++ b/docs/anchors/solid-isp.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: solid-principles -:tier: 1 +:tier: 3 :proponents: Robert C. Martin :tags: SOLID, design principle, ISP, interface segregation diff --git a/docs/anchors/solid-lsp.adoc b/docs/anchors/solid-lsp.adoc index 4b16df0..d73b03e 100644 --- a/docs/anchors/solid-lsp.adoc +++ b/docs/anchors/solid-lsp.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: solid-principles -:tier: 1 +:tier: 3 :proponents: Robert C. Martin, Barbara Liskov :tags: SOLID, design principle, LSP, liskov, substitution diff --git a/docs/anchors/solid-ocp.adoc b/docs/anchors/solid-ocp.adoc index 026e78a..148458e 100644 --- a/docs/anchors/solid-ocp.adoc +++ b/docs/anchors/solid-ocp.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: solid-principles -:tier: 1 +:tier: 3 :proponents: Robert C. Martin, Bertrand Meyer :tags: SOLID, design principle, OCP, open closed diff --git a/docs/anchors/solid-principles.adoc b/docs/anchors/solid-principles.adoc index 56eb5da..2fdbeb0 100644 --- a/docs/anchors/solid-principles.adoc +++ b/docs/anchors/solid-principles.adoc @@ -4,6 +4,7 @@ :proponents: Robert C. Martin :related: gof-design-patterns, clean-architecture :tags: design-principles, oop, solid, uncle-bob +:tier: 3 :sub-anchors: solid-srp, solid-ocp, solid-lsp, solid-isp, solid-dip [%collapsible] diff --git a/docs/anchors/solid-srp.adoc b/docs/anchors/solid-srp.adoc index 11b786e..6c07eee 100644 --- a/docs/anchors/solid-srp.adoc +++ b/docs/anchors/solid-srp.adoc @@ -2,7 +2,7 @@ :categories: design-principles :roles: software-developer, software-architect :umbrella: solid-principles -:tier: 1 +:tier: 3 :proponents: Robert C. Martin :tags: SOLID, design principle, SRP, single responsibility diff --git a/docs/anchors/sota.adoc b/docs/anchors/sota.adoc index 34c2262..b6d5a01 100644 --- a/docs/anchors/sota.adoc +++ b/docs/anchors/sota.adoc @@ -1,6 +1,7 @@ = SOTA (State-of-the-Art) :categories: development-workflow :roles: software-developer, data-scientist, consultant +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/spc.adoc b/docs/anchors/spc.adoc index 64966b1..d3f4f84 100644 --- a/docs/anchors/spc.adoc +++ b/docs/anchors/spc.adoc @@ -2,6 +2,8 @@ :categories: statistical-methods :roles: data-scientist, devops-engineer, team-lead, qa-engineer :proponents: Walter A. Shewhart (founder), W. Edwards Deming (dissemination), Western Electric Company +:tier: 3 +:sub-anchors: control-chart-shewhart, nelson-rules [%collapsible] ==== diff --git a/docs/anchors/spot-principle.adoc b/docs/anchors/spot-principle.adoc deleted file mode 100644 index 03d61ff..0000000 --- a/docs/anchors/spot-principle.adoc +++ /dev/null @@ -1,39 +0,0 @@ -= SPOT (Single Point of Truth) -:categories: design-principles -:roles: software-developer, software-architect - -[%collapsible] -==== -Full Name:: Single Point of Truth - -[discrete] -== *Core Concepts*: - -Implementation pattern:: Focuses on where and how data/logic is stored and accessed - -Centralized location:: Each piece of information resides in exactly one place - -Reference relationships:: Other locations reference the single point rather than duplicate it - -Data consistency:: Eliminates synchronization issues and conflicting data - -Update propagation:: Changes at the single point automatically affect all references - -Clear ownership:: Explicit responsibility for maintaining each piece of truth - -Code-level practice:: Applied at the code and system design level - - -[discrete] -== *When to Use*: - -* Implementing functions and utilities to avoid code duplication -* Database schema design to eliminate redundant data -* Configuration management across distributed systems -* State management in applications -* API design where data flows from a single endpoint - -Difference from SSOT:: SPOT emphasizes the implementation detail of where data lives, while SSOT emphasizes the authoritative, trusted nature of that data source - -Related Concepts:: DRY, SSOT, Normalized databases, Master data management -==== diff --git a/docs/anchors/spot-principle.de.adoc b/docs/anchors/spot-principle.de.adoc deleted file mode 100644 index 61e9e8c..0000000 --- a/docs/anchors/spot-principle.de.adoc +++ /dev/null @@ -1,39 +0,0 @@ -= SPOT (Single Point of Truth) -:categories: design-principles -:roles: software-developer, software-architect - -[%collapsible] -==== -Vollständiger Name:: Single Point of Truth - -[discrete] -== *Kernkonzepte*: - -Implementierungsmuster:: Fokussiert darauf, wo und wie Daten/Logik gespeichert und abgerufen werden - -Zentraler Ort:: Jede Information befindet sich an genau einer Stelle - -Referenzbeziehungen:: Andere Orte referenzieren den einzelnen Punkt, anstatt ihn zu duplizieren - -Datenkonsistenz:: Eliminiert Synchronisationsprobleme und widersprüchliche Daten - -Update-Propagierung:: Änderungen am einzelnen Punkt wirken sich automatisch auf alle Referenzen aus - -Klare Verantwortlichkeit:: Explizite Zuständigkeit für die Pflege jedes Wahrheitsstücks - -Code-Ebene-Praxis:: Angewendet auf Code- und Systemdesign-Ebene - - -[discrete] -== *Wann zu verwenden*: - -* Implementierung von Funktionen und Utilities zur Vermeidung von Code-Duplikation -* Datenbank-Schema-Design zur Eliminierung redundanter Daten -* Konfigurationsmanagement in verteilten Systemen -* State-Management in Anwendungen -* API-Design, wo Daten von einem einzelnen Endpoint fließen - -Unterschied zu SSOT:: SPOT betont das Implementierungsdetail, wo Daten leben, während SSOT die autoritative, vertrauenswürdige Natur dieser Datenquelle betont - -Verwandte Konzepte:: DRY, SSOT, Normalisierte Datenbanken, Master Data Management -==== diff --git a/docs/anchors/ssot-principle.adoc b/docs/anchors/ssot-principle.adoc index 67ff9d3..9d30626 100644 --- a/docs/anchors/ssot-principle.adoc +++ b/docs/anchors/ssot-principle.adoc @@ -1,6 +1,7 @@ = SSOT (Single Source of Truth) :categories: design-principles :roles: software-architect, data-scientist, business-analyst +:tier: 1 [%collapsible] ==== diff --git a/docs/anchors/swot.adoc b/docs/anchors/swot.adoc index e95232e..75bac2f 100644 --- a/docs/anchors/swot.adoc +++ b/docs/anchors/swot.adoc @@ -4,6 +4,7 @@ :related: pugh-matrix, wardley-mapping, moscow :proponents: Albert Humphrey :tags: swot, strategic-planning, analysis, strengths, weaknesses, opportunities, threats, business-analysis +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/tdd-chicago-school.adoc b/docs/anchors/tdd-chicago-school.adoc index 8c19051..ae0fc17 100644 --- a/docs/anchors/tdd-chicago-school.adoc +++ b/docs/anchors/tdd-chicago-school.adoc @@ -2,6 +2,7 @@ :categories: testing-quality :roles: software-developer, qa-engineer :proponents: Kent Beck, Martin Fowler +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/tdd-london-school.adoc b/docs/anchors/tdd-london-school.adoc index 2ea086a..fee29c2 100644 --- a/docs/anchors/tdd-london-school.adoc +++ b/docs/anchors/tdd-london-school.adoc @@ -2,6 +2,7 @@ :categories: testing-quality :roles: software-developer, qa-engineer, software-architect :proponents: Steve Freeman, Nat Pryce ("Growing Object-Oriented Software, Guided by Tests") +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/test-double-dummy.adoc b/docs/anchors/test-double-dummy.adoc new file mode 100644 index 0000000..01e62b6 --- /dev/null +++ b/docs/anchors/test-double-dummy.adoc @@ -0,0 +1,35 @@ += Test Double: Dummy (Meszaros) +:categories: testing-quality +:roles: software-developer, qa-engineer +:proponents: Gerard Meszaros +:related: test-double-meszaros, test-double-stub +:tags: test-double, dummy, testing, isolation +:tier: 3 +:parent-anchor: test-double-meszaros + +[%collapsible] +==== +[discrete] +== *Core Concepts*: + +Purpose:: An object passed to fill a required parameter but never actually used in the test. The simplest form of test double. + +Behavior:: Has no behavior. Calls to a Dummy should not occur — if they do, something is wrong with the test setup. + +Typical use:: Satisfying constructor or method signatures where the parameter is irrelevant to the test scenario. + +Key Proponent:: Gerard Meszaros ("xUnit Test Patterns", 2007) + +[discrete] +== *When to Use*: + +* Tell an LLM: "Create a Dummy test double for this parameter — it should never be called" +* When a method requires parameters that are irrelevant to the behavior being tested +* Filling dependency injection containers with unused dependencies + +[discrete] +== *Related Anchors*: + +* <> — umbrella taxonomy +* <> — when you need canned responses (Dummy provides none) +==== diff --git a/docs/anchors/test-double-fake.adoc b/docs/anchors/test-double-fake.adoc new file mode 100644 index 0000000..2e1575a --- /dev/null +++ b/docs/anchors/test-double-fake.adoc @@ -0,0 +1,38 @@ += Test Double: Fake (Meszaros) +:categories: testing-quality +:roles: software-developer, qa-engineer +:proponents: Gerard Meszaros +:related: test-double-meszaros, test-double-stub +:tags: test-double, fake, testing, isolation, in-memory +:tier: 3 +:parent-anchor: test-double-meszaros + +[%collapsible] +==== +[discrete] +== *Core Concepts*: + +Purpose:: A working but simplified implementation unsuitable for production. Has real behavior, but takes shortcuts. + +Behavior:: Actually processes inputs and produces outputs — unlike Stubs which return fixed data. The simplification makes it fast and predictable for tests. + +Typical examples:: In-memory database instead of real database, in-memory file system, local email sender that writes to a list instead of sending, simplified authentication that always succeeds. + +Distinction from Stub:: A Stub returns canned data. A Fake has *real logic*, just simplified. + +Key Proponent:: Gerard Meszaros ("xUnit Test Patterns", 2007) + +[discrete] +== *When to Use*: + +* Tell an LLM: "Create a Fake implementation of this repository using an in-memory store" +* Integration-style tests without external infrastructure +* When Stubs are too simplistic and the real implementation is too slow/complex +* Local development environments needing realistic but fast dependencies + +[discrete] +== *Related Anchors*: + +* <> — umbrella taxonomy +* <> — simpler alternative with fixed responses +==== diff --git a/docs/anchors/test-double-meszaros.adoc b/docs/anchors/test-double-meszaros.adoc index 7cce946..92a97a5 100644 --- a/docs/anchors/test-double-meszaros.adoc +++ b/docs/anchors/test-double-meszaros.adoc @@ -4,6 +4,8 @@ :proponents: Gerard Meszaros :related: tdd-london-school, tdd-chicago-school, property-based-testing :tags: test-double, mock, stub, spy, fake, dummy, xunit, testing, isolation +:tier: 3 +:sub-anchors: test-double-dummy, test-double-stub, test-double-spy, test-double-mock, test-double-fake [%collapsible] ==== diff --git a/docs/anchors/test-double-mock.adoc b/docs/anchors/test-double-mock.adoc new file mode 100644 index 0000000..58e8c6f --- /dev/null +++ b/docs/anchors/test-double-mock.adoc @@ -0,0 +1,39 @@ += Test Double: Mock (Meszaros) +:categories: testing-quality +:roles: software-developer, qa-engineer +:proponents: Gerard Meszaros +:related: test-double-meszaros, test-double-spy, test-double-stub, tdd-london-school +:tags: test-double, mock, testing, isolation, interaction-verification +:tier: 3 +:parent-anchor: test-double-meszaros + +[%collapsible] +==== +[discrete] +== *Core Concepts*: + +Purpose:: Pre-programmed with expectations about which calls should be made. Verifies that specific interactions occurred — the test fails if the expected interactions don't happen. + +Behavior:: Has built-in assertions. If the system under test calls the wrong method, with wrong arguments, or in the wrong order, the Mock fails the test immediately. + +Distinction from Stub:: A Stub provides data passively. A Mock actively *verifies behavior*. + +Distinction from Spy:: A Spy records calls for *post-hoc* assertion. A Mock enforces expectations *during* execution. + +Key Proponent:: Gerard Meszaros ("xUnit Test Patterns", 2007) + +[discrete] +== *When to Use*: + +* Tell an LLM: "Create a Mock test double that verifies these interactions occur" +* Interaction-based testing (London School TDD) +* When the *behavior* matters more than the *result* +* Verifying that a notification was sent, a log was written, or a service was called correctly + +[discrete] +== *Related Anchors*: + +* <> — umbrella taxonomy +* <> — post-hoc assertion instead of expectations +* <> — favors Mocks for outside-in design +==== diff --git a/docs/anchors/test-double-spy.adoc b/docs/anchors/test-double-spy.adoc new file mode 100644 index 0000000..0153134 --- /dev/null +++ b/docs/anchors/test-double-spy.adoc @@ -0,0 +1,37 @@ += Test Double: Spy (Meszaros) +:categories: testing-quality +:roles: software-developer, qa-engineer +:proponents: Gerard Meszaros +:related: test-double-meszaros, test-double-stub, test-double-mock +:tags: test-double, spy, testing, isolation, call-recording +:tier: 3 +:parent-anchor: test-double-meszaros + +[%collapsible] +==== +[discrete] +== *Core Concepts*: + +Purpose:: A Stub that also records how it was called — which methods, with what arguments, how many times. Assertions happen *after* the action, not as expectations *before*. + +Behavior:: Returns canned responses (like a Stub) and silently records all interactions for later inspection. + +Distinction from Mock:: A Spy records and lets *you* assert afterward. A Mock has pre-programmed expectations that fail immediately if violated. + +Key Proponent:: Gerard Meszaros ("xUnit Test Patterns", 2007) + +[discrete] +== *When to Use*: + +* Tell an LLM: "Create a Spy test double that records calls for later assertion" +* When you need to verify interactions but want assertions in the test body, not in setup +* Auditing what happened during a test without constraining the order of operations +* When the exact interaction pattern matters but you want flexible assertion + +[discrete] +== *Related Anchors*: + +* <> — umbrella taxonomy +* <> — Spy without call recording +* <> — pre-programmed expectations instead of post-hoc assertion +==== diff --git a/docs/anchors/test-double-stub.adoc b/docs/anchors/test-double-stub.adoc new file mode 100644 index 0000000..937580c --- /dev/null +++ b/docs/anchors/test-double-stub.adoc @@ -0,0 +1,38 @@ += Test Double: Stub (Meszaros) +:categories: testing-quality +:roles: software-developer, qa-engineer +:proponents: Gerard Meszaros +:related: test-double-meszaros, test-double-spy, test-double-mock +:tags: test-double, stub, testing, isolation, canned-response +:tier: 3 +:parent-anchor: test-double-meszaros + +[%collapsible] +==== +[discrete] +== *Core Concepts*: + +Purpose:: Provides predefined (canned) responses to calls made during a test. Does not verify interactions — only supplies data. + +Behavior:: Returns fixed values regardless of input. No assertion on whether or how it was called. + +Distinction from Mock:: A Stub never fails a test. It only provides data. A Mock has expectations and can fail the test if interactions are wrong. + +Key Proponent:: Gerard Meszaros ("xUnit Test Patterns", 2007) + +[discrete] +== *When to Use*: + +* Tell an LLM: "Create a Stub test double that returns this fixed data" +* Isolating the system under test from external dependencies (database, API) +* State-based testing (Chicago School TDD) +* When you care about the *result*, not about *how* it was obtained + +[discrete] +== *Related Anchors*: + +* <> — umbrella taxonomy +* <> — a Stub that also records calls +* <> — when you need interaction verification +* <> — favors Stubs over Mocks +==== diff --git a/docs/anchors/testing-pyramid.adoc b/docs/anchors/testing-pyramid.adoc index f9c6e64..070d771 100644 --- a/docs/anchors/testing-pyramid.adoc +++ b/docs/anchors/testing-pyramid.adoc @@ -1,6 +1,7 @@ = Testing Pyramid :categories: testing-quality :roles: software-developer, qa-engineer, team-lead, devops-engineer +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/timtowtdi.adoc b/docs/anchors/timtowtdi.adoc index 74cf9fd..75a37bc 100644 --- a/docs/anchors/timtowtdi.adoc +++ b/docs/anchors/timtowtdi.adoc @@ -1,6 +1,7 @@ = TIMTOWTDI :categories: development-workflow :roles: software-developer, software-architect, consultant, educator +:tier: 1 [%collapsible] ==== diff --git a/docs/anchors/todotxt-flavoured-markdown.adoc b/docs/anchors/todotxt-flavoured-markdown.adoc index f3690d3..4bb65ba 100644 --- a/docs/anchors/todotxt-flavoured-markdown.adoc +++ b/docs/anchors/todotxt-flavoured-markdown.adoc @@ -2,6 +2,7 @@ :categories: development-workflow :roles: software-developer, team-lead, technical-writer :proponents: Combines GitHub-flavoured Markdown task lists with Gina Trapani's todo.txt format +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/user-story-mapping.adoc b/docs/anchors/user-story-mapping.adoc index 38190bd..756cac1 100644 --- a/docs/anchors/user-story-mapping.adoc +++ b/docs/anchors/user-story-mapping.adoc @@ -1,6 +1,7 @@ = User Story Mapping :categories: requirements-engineering :roles: product-owner, business-analyst, team-lead, ux-designer +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/wardley-mapping.adoc b/docs/anchors/wardley-mapping.adoc index 871f06e..1f41a04 100644 --- a/docs/anchors/wardley-mapping.adoc +++ b/docs/anchors/wardley-mapping.adoc @@ -1,6 +1,7 @@ = Wardley Mapping :categories: strategic-planning :roles: product-owner, software-architect, consultant, team-lead +:tier: 3 [%collapsible] ==== diff --git a/docs/anchors/what-qualifies-as-a-semantic-anchor.adoc b/docs/anchors/what-qualifies-as-a-semantic-anchor.adoc index f4178f7..cbaa6dc 100644 --- a/docs/anchors/what-qualifies-as-a-semantic-anchor.adoc +++ b/docs/anchors/what-qualifies-as-a-semantic-anchor.adoc @@ -1,6 +1,7 @@ = The Spectrum of Semantic Anchors :categories: meta :roles: educator, consultant +:tier: 3 === What Qualifies as a Semantic Anchor diff --git a/docs/anchors/yagni.adoc b/docs/anchors/yagni.adoc index 68d4a5b..90d2f27 100644 --- a/docs/anchors/yagni.adoc +++ b/docs/anchors/yagni.adoc @@ -4,6 +4,7 @@ :proponents: Ron Jeffries, Kent Beck :related: dry-principle, spot-principle, tdd-chicago-school :tags: yagni, extreme-programming, simplicity, incremental-design, over-engineering +:tier: 1 [%collapsible] ==== diff --git a/docs/changelog.adoc b/docs/changelog.adoc index ae942b1..4c456af 100644 --- a/docs/changelog.adoc +++ b/docs/changelog.adoc @@ -2,6 +2,30 @@ A chronological record of all semantic anchors added to the catalog. Community contributors are credited with thanks. +== 2026-03-14 — Catalog Curation + +Quality review of all anchors: introduced a three-tier rating system (★★★ self-standing, ★★☆ needs qualification, ★☆☆ descriptive only) to measure how reliably an anchor improves LLM communication. All anchors now carry an internal `:tier:` attribute. + +*Removed:* + +* *Rubber Duck Debugging* — concept is fully covered by <>; no actionable LLM instruction on its own +* *DRY (Don't Repeat Yourself)* — design principle, but "make it DRY" is too vague as an LLM instruction +* *SPOT (Single Point of Truth)* — too similar to SSOT; consolidated into <> +* *Chatham House Rule* — well-defined rule, but no practical LLM application + +*Renamed & upgraded:* + +* *Mental Model (Naur)* → *Programming as Theory Building (Naur)* — sharpened focus on documenting the "why" behind code (★☆☆ → ★★☆) +* *Problem Space NVC* → *Nonviolent Communication (Rosenberg)* — stronger trigger, clear 4-step process (★★☆ → ★★★) +* *Test Double (Meszaros)* → ★★★ umbrella anchor with 5 new sub-anchors: *Dummy*, *Stub*, *Spy*, *Mock*, *Fake* — each a precise, actionable LLM instruction (★☆☆ → ★★★) +* *Jobs To Be Done* — upgraded to ★★★, strong for landing pages and customer analysis +* *SOTA* — upgraded to ★★★, "Recherchiere SOTA zu [Thema]" reliably activates research mode + +*New quality criteria for proposals:* + +* Review agent now evaluates anchors against the tier system +* ★☆☆ proposals are rejected unless a concrete prompt pattern is demonstrated + == 2026-03-09 * *GoF Design Patterns Umbrella* — 23 GoF patterns as sub-anchors with tier system (12 Tier-1, 7 Tier-2, 4 Tier-3) in https://github.com/LLM-Coding/Semantic-Anchors/pull/159[#159]