Merge pull request #444 from raifdmueller/add-slap-occam-code-smells-anchors

feat: add SLAP, Occam's Razor, Code Smells anchors (#440, #439, #435)

Author: rdmueller

docs/anchors/code-smells.adoc

@@ -0,0 +1,56 @@
+= Code Smells
+:categories: design-principles
+:roles: software-developer, software-architect, educator, team-lead
+:related: fowler-patterns, cohesion-criteria, solid-principles, solid-srp, kiss-principle
+:proponents: Kent Beck, Martin Fowler, Robert C. Martin
+:tags: refactoring, code-quality, clean-code, maintainability, smells
+:tier: 2
+
+[%collapsible]
+====
+Full Name:: Code Smells
+
+Also known as:: Bad Smells in Code, Refactoring Smells
+
+[discrete]
+== *Core Concepts*:
+
+What a smell is::
+A *surface indication* in the code that usually points to a deeper design problem. Smells are heuristic: they are quick to spot, do not prove a defect exists, and are evaluated in context. A smell tells you *where to look*, not *what to do*.
+
+Fowler's catalogue::
+Martin Fowler's _Refactoring_ (1999, 2nd ed. 2018, with the original smell chapter co-authored by Kent Beck) is the canonical catalogue. Each smell is paired with a refactoring that typically resolves it. Common groupings of Fowler's 20+ smells:
++
+* *Bloaters* — structures that grow too large: Long Method, Large Class, Long Parameter List, Primitive Obsession, Data Clumps.
+* *Object-Orientation Abusers* — incomplete or inverted use of OO: Switch Statements, Refused Bequest, Alternative Classes with Different Interfaces, Temporary Field.
+* *Change Preventers* — structures that multiply the cost of change: Divergent Change (one class changes for many reasons), Shotgun Surgery (one change touches many classes), Parallel Inheritance Hierarchies.
+* *Dispensables* — code that earns its keep poorly: Comments (as compensation), Duplicate Code, Lazy Class, Data Class, Dead Code, Speculative Generality.
+* *Couplers* — excessive or inappropriate coupling: Feature Envy, Inappropriate Intimacy, Message Chains, Middle Man.
+
+Martin's extensions::
+Robert C. Martin's _Clean Code_ (2008), Appendix A "Smells and Heuristics", extends Fowler's catalogue with additional smells organised by concern — Comments, Environment, Functions, General, Java, Names, Tests — about 65 heuristics in total. These are complementary refinements, not a replacement for Fowler's set.
+
+Terminology origin::
+Kent Beck coined the term "code smell" in the 1990s; Fowler wrote the book that made it the standard vocabulary. "It just feels wrong" became expressible and teachable.
+
+Key Proponents:: Kent Beck (coined the term), Martin Fowler (_Refactoring_, 1999, 2nd ed. 2018 — canonical catalogue), Robert C. Martin (_Clean Code_, 2008, Appendix A — extended enumeration).
+
+[discrete]
+== *When to Use*:
+
+* Code review: a shared vocabulary for "this feels wrong" that turns taste into checkable signals
+* Refactoring planning: each smell maps to known refactorings, so a smell is an actionable handle
+* Teaching: junior developers learn faster from a named smell + named fix than from abstract design lectures
+* Technical-debt inventory: enumerate smells to quantify and prioritise cleanup work
+* LLM prompting: asking the model to "identify code smells" activates a richer inspection than "find problems"
+* Self-review before PR: a mental pass over the smell list catches issues a reader would otherwise flag
+
+[discrete]
+== *Related Anchors*:
+
+* <<fowler-patterns,Patterns of Enterprise Application Architecture>> - Same author; Fowler's broader design-pattern vocabulary
+* <<cohesion-criteria,Cohesion Criteria>> - Many smells (Feature Envy, Divergent Change, Large Class) are low-cohesion symptoms
+* <<solid-principles,SOLID Principles>> - SOLID violations manifest as identifiable smells; smell→principle is a useful diagnostic direction
+* <<solid-srp,SOLID SRP>> - Divergent Change is almost always an SRP violation
+* <<kiss-principle,KISS Principle>> - Speculative Generality and Comments-as-compensation are KISS failures
+====

docs/anchors/code-smells.de.adoc

@@ -0,0 +1,56 @@
+= Code Smells
+:categories: design-principles
+:roles: software-developer, software-architect, educator, team-lead
+:related: fowler-patterns, cohesion-criteria, solid-principles, solid-srp, kiss-principle
+:proponents: Kent Beck, Martin Fowler, Robert C. Martin
+:tags: refactoring, code-qualität, clean-code, wartbarkeit, smells
+:tier: 2
+
+[%collapsible]
+====
+Vollständiger Name:: Code Smells
+
+Auch bekannt als:: Bad Smells in Code, Refactoring-Smells, "schlechter Geruch im Code"
+
+[discrete]
+== *Kernkonzepte*:
+
+Was ein Smell ist::
+Ein *oberflächliches Indiz* im Code, das üblicherweise auf ein tieferliegendes Designproblem hinweist. Smells sind heuristisch: sie sind schnell zu erkennen, beweisen keinen Defekt und müssen im Kontext bewertet werden. Ein Smell sagt dir *wo du hinschauen sollst*, nicht *was zu tun ist*.
+
+Fowlers Katalog::
+Martin Fowlers _Refactoring_ (1999, 2. Aufl. 2018, das ursprüngliche Smell-Kapitel zusammen mit Kent Beck) ist der kanonische Katalog. Jeder Smell ist mit einem Refactoring gepaart, das ihn typischerweise auflöst. Übliche Gruppierung der über 20 Fowler-Smells:
++
+* *Bloaters* — zu groß gewachsene Strukturen: Long Method, Large Class, Long Parameter List, Primitive Obsession, Data Clumps.
+* *Object-Orientation Abusers* — unvollständige oder verdrehte OO-Nutzung: Switch Statements, Refused Bequest, Alternative Classes with Different Interfaces, Temporary Field.
+* *Change Preventers* — Strukturen, die Änderungskosten vervielfachen: Divergent Change (eine Klasse ändert sich aus vielen Gründen), Shotgun Surgery (eine Änderung berührt viele Klassen), Parallel Inheritance Hierarchies.
+* *Dispensables* — Code, der seinen Platz schlecht rechtfertigt: Comments (als Kompensation), Duplicate Code, Lazy Class, Data Class, Dead Code, Speculative Generality.
+* *Couplers* — übermäßige oder unangemessene Kopplung: Feature Envy, Inappropriate Intimacy, Message Chains, Middle Man.
+
+Martins Erweiterungen::
+Robert C. Martins _Clean Code_ (2008), Anhang A "Smells and Heuristics", erweitert Fowlers Katalog um weitere Smells, organisiert nach Thema — Comments, Environment, Functions, General, Java, Names, Tests — insgesamt ca. 65 Heuristiken. Das sind komplementäre Verfeinerungen, kein Ersatz für Fowlers Set.
+
+Herkunft des Begriffs::
+Kent Beck prägte den Begriff "Code Smell" in den 1990ern; Fowler schrieb das Buch, das ihn zum Standardvokabular machte. "Fühlt sich irgendwie falsch an" wurde damit ausdrückbar und lehrbar.
+
+Schlüsselvertreter:: Kent Beck (Begriffsprägung), Martin Fowler (_Refactoring_, 1999, 2. Aufl. 2018 — kanonischer Katalog), Robert C. Martin (_Clean Code_, 2008, Anhang A — erweiterte Enumeration).
+
+[discrete]
+== *Wann zu verwenden*:
+
+* Code Review: gemeinsames Vokabular für "das fühlt sich falsch an", das Geschmack in prüfbare Signale verwandelt
+* Refactoring-Planung: jeder Smell ist mit bekannten Refactorings verknüpft, also ein handlungsleitender Griff
+* Lehre: Junior-Entwickler lernen schneller an benanntem Smell + benanntem Fix als an abstrakten Designvorträgen
+* Technical-Debt-Inventur: Smells zählen, um Aufräumarbeit zu quantifizieren und zu priorisieren
+* LLM-Prompting: "identifiziere Code Smells" aktiviert eine reichere Inspektion als "finde Probleme"
+* Selbst-Review vor PR: ein mentaler Durchgang über die Smell-Liste fängt Issues, die ein Reviewer sonst flagt
+
+[discrete]
+== *Verwandte Anker*:
+
+* <<fowler-patterns,Patterns of Enterprise Application Architecture>> - Gleicher Autor; Fowlers breiteres Design-Pattern-Vokabular
+* <<cohesion-criteria,Kohäsionskriterien>> - Viele Smells (Feature Envy, Divergent Change, Large Class) sind Symptome niedriger Kohäsion
+* <<solid-principles,SOLID-Prinzipien>> - SOLID-Verletzungen zeigen sich als erkennbare Smells; Smell→Prinzip ist eine nützliche Diagnoserichtung
+* <<solid-srp,SOLID SRP>> - Divergent Change ist fast immer eine SRP-Verletzung
+* <<kiss-principle,KISS-Prinzip>> - Speculative Generality und Comments-als-Kompensation sind KISS-Verstöße
+====

docs/anchors/occams-razor.adoc

@@ -0,0 +1,55 @@
+= Occam's Razor
+:categories: problem-solving
+:roles: software-architect, software-developer, consultant, educator
+:related: kiss-principle, yagni, five-whys, mece, devils-advocate
+:proponents: William of Ockham
+:tags: heuristic, parsimony, epistemology, simplicity, hypothesis-selection
+:tier: 2
+
+[%collapsible]
+====
+Full Name:: Occam's Razor (also spelled Ockham's Razor)
+
+Also known as:: Law of Parsimony, Principle of Parsimony, _Lex Parsimoniae_, "Entities should not be multiplied beyond necessity"
+
+[discrete]
+== *Core Concepts*:
+
+Core rule::
+Among competing hypotheses that explain the same observations equally well, prefer the one that requires the fewest assumptions. The razor *shaves off* unnecessary entities, causes, or mechanisms.
+
+What it is *not*::
+* Not a rule to be brief or terse — that is a stylistic choice, not an epistemic one.
+* Not a proof that the simpler answer is *true* — only a guide to which hypothesis to prefer, investigate first, or commit to under uncertainty.
+* Not a licence for KISS-style solution simplification — Occam operates at the level of *explanations*, KISS at the level of *solutions*. They overlap but are not the same razor.
+
+How it is used::
+* As a *selection filter* under uncertainty — when two stories fit the data, start with the one that assumes less.
+* As a *debugging heuristic* — before assuming a bug requires a race condition plus caching layer plus stale DNS, check whether a single off-by-one explains everything.
+* In *architecture decisions* — a design that needs three new components to justify itself is evidentially weaker than one that reuses existing pieces.
+* In *diagnostic reasoning* — prefer explanations grounded in the system's known mechanics over ones that require novel failure modes.
+
+Limits and counters::
+The razor is a *prior*, not a verdict. Reality is frequently non-parsimonious, and "simpler" is relative to a chosen ontology. Einstein's corollary — "_as simple as possible, but no simpler_" — warns against under-fitting. Pair Occam with evidence, not as a substitute for it.
+
+Key Proponents:: William of Ockham (c. 1287–1347, _Summa Logicae_, _Quodlibetal Questions_); the principle predates Ockham in Aristotle and Scotus but carries his name due to his repeated methodological use of it. Modernised by Bertrand Russell and formalised as minimum-description-length / Bayesian simplicity priors in 20th-century philosophy of science.
+
+[discrete]
+== *When to Use*:
+
+* Debugging: triage competing theories of a bug before instrumenting for all of them
+* Architecture review: challenge proposals that introduce new components to explain observed requirements
+* Root-cause analysis: pair with Five Whys to avoid stopping at an elaborate but unjustified explanation
+* Incident response: the outage likely has *one* cause matching the data, not a conspiracy
+* Requirements clarification: pick the interpretation that requires fewest hidden assumptions about the user
+* LLM prompting: ask the model to prefer the explanation with the fewest moving parts when diagnosing
+
+[discrete]
+== *Related Anchors*:
+
+* <<kiss-principle,KISS Principle>> - Sibling razor applied to *solutions* rather than *explanations*
+* <<yagni,YAGNI>> - Applies parsimony to future requirements: don't build what you can't justify
+* <<five-whys,Five Whys>> - Occam helps pick which "why" to pursue when the chain forks
+* <<mece,MECE Principle>> - Both disciplines of hypothesis hygiene; MECE ensures coverage, Occam ranks by parsimony
+* <<devils-advocate,Devil's Advocate>> - Devil's Advocate stress-tests the hypothesis Occam has selected
+====

docs/anchors/occams-razor.de.adoc

@@ -0,0 +1,55 @@
+= Occams Rasiermesser
+:categories: problem-solving
+:roles: software-architect, software-developer, consultant, educator
+:related: kiss-principle, yagni, five-whys, mece, devils-advocate
+:proponents: William of Ockham
+:tags: heuristik, sparsamkeit, epistemologie, einfachheit, hypothesenauswahl
+:tier: 2
+
+[%collapsible]
+====
+Vollständiger Name:: Occams Rasiermesser (auch Ockhams Rasiermesser)
+
+Auch bekannt als:: Sparsamkeitsprinzip, Prinzip der Parsimonie, _Lex Parsimoniae_, "Entitäten sind nicht über das Notwendige hinaus zu vermehren"
+
+[discrete]
+== *Kernkonzepte*:
+
+Grundregel::
+Unter konkurrierenden Hypothesen, die dieselben Beobachtungen gleich gut erklären, bevorzuge diejenige mit den wenigsten Annahmen. Das Rasiermesser *schneidet* unnötige Entitäten, Ursachen oder Mechanismen weg.
+
+Was es *nicht* ist::
+* Keine Regel, sich kurzzufassen — das wäre stilistisch, nicht erkenntnistheoretisch.
+* Kein Beweis, dass die einfachere Antwort *wahr* ist — nur eine Präferenzregel, welche Hypothese zuerst zu untersuchen oder unter Unsicherheit anzunehmen ist.
+* Keine Lizenz für KISS-artige Lösungsvereinfachung — Occam arbeitet auf der Ebene der *Erklärungen*, KISS auf der Ebene der *Lösungen*. Sie überlappen, sind aber nicht dasselbe Rasiermesser.
+
+Wie es angewendet wird::
+* Als *Auswahlfilter* unter Unsicherheit — wenn zwei Geschichten zu den Daten passen, beginne mit der, die weniger annimmt.
+* Als *Debugging-Heuristik* — bevor du annimmst, dass ein Bug eine Race Condition plus Caching-Schicht plus veralteten DNS braucht, prüfe, ob ein einzelner Off-by-One alles erklärt.
+* Bei *Architekturentscheidungen* — ein Entwurf, der drei neue Komponenten zu seiner Rechtfertigung braucht, steht evidenziell schwächer da als einer, der Bestehendes wiederverwendet.
+* Im *diagnostischen Denken* — bevorzuge Erklärungen, die auf den bekannten Mechanismen des Systems basieren, gegenüber solchen, die neue Fehlermodi voraussetzen.
+
+Grenzen und Gegenargumente::
+Das Rasiermesser ist ein *Prior*, kein Urteil. Die Realität ist häufig nicht sparsam, und "einfacher" ist relativ zur gewählten Ontologie. Einsteins Korollar — "_so einfach wie möglich, aber nicht einfacher_" — warnt vor Underfitting. Paare Occam mit Evidenz, nicht als Ersatz für sie.
+
+Schlüsselvertreter:: Wilhelm von Ockham (ca. 1287–1347, _Summa Logicae_, _Quodlibeta_); das Prinzip ist älter (Aristoteles, Duns Scotus), trägt aber Ockhams Namen wegen seines konsequenten methodischen Einsatzes. Modernisiert durch Bertrand Russell und in der Wissenschaftsphilosophie des 20. Jh. als Minimum-Description-Length / Bayesianische Simplicity-Priors formalisiert.
+
+[discrete]
+== *Wann zu verwenden*:
+
+* Debugging: konkurrierende Theorien für einen Bug triagieren, bevor du für alle instrumentierst
+* Architektur-Review: Vorschläge hinterfragen, die neue Komponenten einführen, um beobachtete Anforderungen zu erklären
+* Root-Cause-Analyse: kombiniert mit Five Whys verhindert Stehenbleiben bei elaborierten, aber unbegründeten Erklärungen
+* Incident Response: der Ausfall hat wahrscheinlich *eine* Ursache, die zu den Daten passt, keine Verschwörung
+* Requirements-Klärung: wähle die Interpretation, die die wenigsten versteckten Annahmen über den Nutzer macht
+* LLM-Prompting: bitte das Modell, bei der Diagnose die Erklärung mit den wenigsten beweglichen Teilen zu bevorzugen
+
+[discrete]
+== *Verwandte Anker*:
+
+* <<kiss-principle,KISS-Prinzip>> - Verwandtes Rasiermesser, angewandt auf *Lösungen* statt *Erklärungen*
+* <<yagni,YAGNI>> - Überträgt Parsimonie auf zukünftige Anforderungen: baue nicht, was du nicht rechtfertigen kannst
+* <<five-whys,Five Whys>> - Occam hilft zu wählen, welchem "Warum" zu folgen ist, wenn die Kette sich verzweigt
+* <<mece,MECE-Prinzip>> - Beide sind Hygienewerkzeuge für Hypothesen; MECE sichert Abdeckung, Occam bewertet nach Sparsamkeit
+* <<devils-advocate,Devil's Advocate>> - Devil's Advocate stresst die von Occam gewählte Hypothese
+====

docs/anchors/single-level-of-abstraction-principle.adoc

@@ -0,0 +1,50 @@
+= Single Level of Abstraction Principle (SLAP)
+:categories: design-principles
+:roles: software-developer, software-architect, educator
+:related: cohesion-criteria, kiss-principle, solid-srp, clean-architecture
+:proponents: Kent Beck, Robert C. Martin
+:tags: clean-code, abstraction, function-design, readability, composed-method
+:tier: 2
+
+[%collapsible]
+====
+Full Name:: Single Level of Abstraction Principle
+
+Also known as:: SLAP, SLA Principle, One Level of Abstraction Per Function
+
+[discrete]
+== *Core Concepts*:
+
+Core rule::
+All statements within a single function (or block) should operate at the same level of abstraction. High-level orchestration and low-level mechanics do not belong in the same body.
+
+Why it works::
+A reader scanning a function can trust it to answer *one* question at *one* resolution. Mixing levels forces the reader to context-switch between "what is this step doing" and "how exactly is it being done" on every line, which is the primary driver of the "I have to read this three times" feeling.
+
+Applying SLAP::
+* When you notice a function mixing levels, extract the low-level details into well-named helper functions whose names *express the next level of detail*.
+* The top-level function becomes a readable summary — almost a table of contents — of the work.
+* This is the *Composed Method* pattern (Kent Beck, _Smalltalk Best Practice Patterns_, 1996): build functions from calls to other methods at the same conceptual level.
+
+Relation to Clean Code::
+Robert C. Martin formalised SLAP as one of the function-design rules in _Clean Code_ (2008), alongside "Functions should be small", "Do one thing", and "Use descriptive names". SLAP is the organising principle that makes "small functions" readable rather than just fragmented.
+
+Key Proponents:: Kent Beck (_Smalltalk Best Practice Patterns_, 1996 — "Composed Method"), Robert C. Martin (_Clean Code_, 2008).
+
+[discrete]
+== *When to Use*:
+
+* Refactoring a long function that "does too much" — SLAP tells you *how* to split it, not just that you should
+* Code review: a natural smell-detector for functions that mix orchestration with mechanics
+* Teaching junior developers a concrete, checkable rule that produces readable code
+* Designing a new algorithm top-down: write the high-level steps as calls to not-yet-existing helpers, then fill them in
+* Reconstructing the intent of legacy code — lift the orchestration out and the design becomes visible
+
+[discrete]
+== *Related Anchors*:
+
+* <<cohesion-criteria,Cohesion Criteria>> - SLAP produces functional cohesion by keeping a function focused on one conceptual step
+* <<kiss-principle,KISS Principle>> - SLAP is one concrete technique for keeping functions simple
+* <<solid-srp,SOLID SRP>> - SRP applies at the class level what SLAP applies at the function level
+* <<clean-architecture,Clean Architecture>> - Layered abstraction at the architectural scale mirrors SLAP at the code scale
+====