Semantic Anchors — Complete Reference

Structuring training sessions, workshops, or technical presentations

Writing tutorials, explainers, or onboarding documentation

Designing conference talks that engage both practitioners and theorists

Planning educational content across the motivation-to-mastery arc

LLM prompting for instructional material: "Explain X using the 4MAT cycle"

Pyramid Principle - Top-down structure for written communication; complements 4MAT which is experience-first

Feynman Technique - Self-directed learning; 4MAT is teacher-directed instructional design

Diátaxis Framework - Documentation types (tutorial/how-to/reference/explanation) map loosely to 4MAT quadrants

4MAT rests on learning-styles theory, and the matching claim lacks empirical support: Pashler, McDaniel, Rohrer & Bjork, "Learning Styles: Concepts and Evidence" (Psychological Science in the Public Interest, 2008) found virtually no valid evidence that teaching matched to a diagnosed learning style improves outcomes

Paul Kirschner, "Stop propagating the learning styles myth" (Computers & Education, 2017) — nearly all studies claiming supporting evidence fail basic criteria of scientific validity

The common defense: 4MAT’s Why/What/How/What-If cycle works as a lesson-sequencing device that every learner moves through — a reading that survives even when the underlying learning-styles claim is dropped

Structuring marketing copy, landing pages, ads, cold emails, or pitch openings

Reviewing a draft for a missing stage — most often a weak hook (Attention) or an absent call to action (Action)

LLM prompting for persuasive text: "Write this product announcement using the AIDA model"

Sequencing a sales conversation from hook to close

Informational or reference writing where persuasion is not the goal — use BLUF or the Inverted Pyramid instead

As a measured model of buyer psychology — it is a copywriting heuristic, not validated cognitive science

Long, relationship-based B2B sales, where multi-touch journeys outgrow a single linear funnel

Inverted Pyramid Style - News structure front-loads the full story; AIDA deliberately withholds the ask until Desire is built

Pyramid Principle - Logical top-down argument for clarity; AIDA is an emotional persuasion sequence for conversion

BLUF (Bottom Line Up Front) - Leads with the conclusion; the opposite move to AIDA, which earns the conclusion across four stages

Robert Heath & Paul Feldwick, "Fifty years using the wrong model of advertising" (International Journal of Market Research, 2008) — the rational, sequential persuasion model behind AIDA misrepresents how advertising actually works: largely through emotional, low-attention processing rather than attentive information processing

Demetrios Vakratsas & Tim Ambler, "How Advertising Works: What Do We Really Know?" (Journal of Marketing, 1999) — reviewing over 250 studies, they found little empirical support for any fixed hierarchy of effects and recommended abandoning the hierarchy concept as a planning assumption

The model’s age is part of the critique: AIDA originates around 1898, pre-dating formal marketing science, yet still dominates campaign planning — precisely the persistence Heath and Feldwick criticize

Building richer, evidence-based user personas in UX research (score along OCEAN instead of inventing ad-hoc traits)

Tailoring communication or messaging to a described audience’s trait profile

Reasoning about team composition and likely friction (e.g., high- vs. low-Conscientiousness pairings)

Coaching and self-reflection grounded in a validated trait vocabulary

Structuring qualitative analysis of interview or survey text into comparable trait dimensions

❌ "Big Five sorts people into types" — it describes continuous traits, not categories

❌ "Scores are fixed" — traits are relatively stable in adulthood but shift across the lifespan

❌ "It explains why someone behaves as they do" — the model is descriptive and predictive, not causal

✓ "Big Five is the empirically dominant trait model" — it is, which is why it is the usual scientific benchmark against MBTI and DISC

Writing learning objectives so they name a verifiable cognitive level, not a vague "know about"

Designing assessments and quizzes that target higher-order thinking (Apply, Analyze) instead of recall

Defining what "demonstrated understanding" means — set the gate at Apply/Analyze, not Remember

Reviewing training material or documentation for whether it only informs or also builds skill

LLM prompting: "Write quiz questions at the Apply and Analyze levels of Bloom’s Taxonomy"

As a rigid linear sequence every lesson must climb in order — it is a design lens, not a script

For affective or motor learning — the cognitive taxonomy does not cover attitudes (affective domain) or physical skills (psychomotor domain)

4MAT — 4MAT sequences a lesson (Why/What/How/What-If); Bloom grades the cognitive level each step targets

Feynman Technique — explaining-it-back is a concrete check at the Understand level; Bloom names the levels above it

Socratic Method — questioning drives learners up the levels; Bloom labels where they are

Diátaxis Framework — documentation types map loosely to cognitive levels (tutorial → Apply, explanation → Understand)

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, "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)"

Executive summaries and briefings

Status reports to leadership

Email to busy stakeholders

Incident reports requiring immediate action

Any high-stakes communication where the reader needs the conclusion first

Technical documentation for time-constrained readers

Related to Pyramid Principle but more narrowly focused on conclusion-first structure

Complements MECE by providing the organizational principle for grouped information

Contrasts with narrative or exploratory writing styles

Be First. An information vacuum does not stay empty. Communicating early, with a timestamp and an explicit account of what is not yet known, beats waiting for a complete picture.

Be Right. Accuracy over completeness: separate what is confirmed from what is unknown from what is being investigated, and commit in advance to correcting what turns out wrong.

Be Credible. Honesty and consistency over reassurance. Admitting uncertainty preserves the standing you will need for the next message.

Express Empathy. Name the disruption and the distress before explaining the cause. People who feel unacknowledged stop reading.

Promote Action. Give something concrete and feasible to do. Action restores a sense of control and displaces speculation.

Show Respect. Address the audience as capable adults. Dismissing concerns as irrational forfeits the trust the other five principles are spending.

Communication under uncertainty is the design premise. The framework assumes you must speak before the facts are in — which is exactly the situation a status update during an unresolved incident is written in.

The crisis has a lifecycle. Preparation, initial reaction, maintenance, resolution, evaluation. What the audience needs, and therefore what the message should carry, differs by phase.

Writing the first public statement about an incident whose cause is not yet known

Status pages, customer notifications and internal updates while an outage is still unresolved

Security disclosures, where the temptation to wait for certainty is strongest and most costly

Preparing the communication plan before the incident, which is the phase the framework treats as primary

Using the bare acronym. "CERC" alone is not reliable vocabulary. Asked without context, a frontier model returns India’s Central Electricity Regulatory Commission, Canada Excellence Research Chairs and a coastal engineering centre before it reaches this framework — and in our measurement it did not reach it at all. Spell the name out. The prior-test register carries the evidence.

Reading "Be First" as speed over accuracy. It is first with what is known, including the fact that little is. The two principles constrain each other rather than compete.

Treating empathy as a tone. It is a content requirement — naming the concrete effect on the reader — not a softer register applied to the same sentences.

Reviewing documentation, tutorials, or onboarding material for an audience less expert than the author

Diagnosing why an explanation, talk, or error message confuses its readers

Teaching: deciding which steps and terms must be made explicit rather than assumed

Prompting an LLM to write for a non-expert audience, or to surface and state its own assumptions and defined terms

Code review of comments, API docs, and commit messages that assume too much context

Feynman Technique

Bloom’s Taxonomy

BLUF

Inverted Pyramid Style

Steven Pinker reframed the bias as a writing problem in "The Sense of Style" (2014), calling it "the single best explanation I know of why good people write bad prose" and prescribing testing prose against a representative reader — the framing most likely to dominate present-day discussion of the term outside economics

Don’t criticise, condemn or complain. Carnegie’s opening move and the one the rest depends on: criticism puts people on the defensive and they justify rather than reconsider.

Give honest, sincere appreciation. Stated as a precondition, not a technique — Carnegie distinguishes appreciation from flattery repeatedly and insists the difference is sincerity.

Arouse in the other person an eager want. Argue from their interest rather than yours. "Talk in terms of the other person’s interests" is the same move applied to conversation.

Begin with praise, then raise the problem. The characteristic structure: honest appreciation first, the difficulty second, and the correction framed so the other person keeps their standing.

Point out mistakes indirectly, and let the other person save face. Blame the circumstance, the ambiguous spec, your own earlier explanation — anything that leaves the person room to change their mind without conceding incompetence.

Ask questions instead of giving direct orders. "Could you look at this?" rather than "redo it". The instruction lands the same and the standing does not.

Try honestly to see things from the other person’s point of view. Invite their reasoning before delivering your own — they may have seen what you did not.

Review comments that have to be read by the person who wrote the code

Disagreements where being right is not the same as being effective

As a compact shorthand in a long-running instruction set, where spelling the posture out each time is expensive and drifts

Reading it as a licence to soften the substance. The principles govern how a correction is delivered, not whether it is made. A review comment that no longer names the defect has failed on Carnegie’s terms too.

Treating it as manipulation. This is the standard charge and it is worth taking seriously — see Criticism. Carnegie’s own answer is that every technique is void without sincerity, which is a defence that can be stated but not enforced.

Expecting it to add tact a current model lacks. In our measurement the unanchored baseline was already careful with the person. What the term reliably adds is the opening appreciation and the face-saving frame — a narrower and more specific effect than the reputation suggests.

Framing communication and collaboration preferences within a team (D/I/S/C tendencies as a shared shorthand)

Facilitation, coaching, or workshop settings where a lightweight behavioural vocabulary helps dialogue

Tailoring how a message is delivered to a described counterpart’s style

Onboarding conversations about working styles

❌ "My DISC type says what I can do" — it describes a behavioural preference, not ability

❌ "DISC is scientifically validated" — it is not; it predicts job performance no better than chance

✓ "DISC is a conversational starting point" — correct use is exploratory dialogue, never selection or diagnosis

Diagnosing recurring misunderstandings in teams or coaching conversations

Teaching active listening and feedback skills

Giving or receiving feedback by separating the factual side from the relationship side

Defusing conflict by surfacing the self-revelation and appeal layers of a charged statement

Prompting an LLM to analyze a message on all four communication levels

Writing clear, effective German prose for professional or public audiences

Reviewing or editing technical documentation, reports, and emails

Coaching writers to reduce bureaucratic or academic language

Improving internal corporate communication

Teaching German writing style and rhetoric

BLUF (Bottom Line Up Front) — complements Schneider’s clarity-first approach with a structure that leads with the conclusion

Pyramid Principle according to Barbara Minto — a complementary framework for structuring arguments hierarchically

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 "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 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 Strunk & White

When integrity, fairness, or exploitation risk is the relevant axis (ethics discussions, counterparty modelling) — the Honesty-Humility factor the Big Five omits

Reasoning about dark-personality patterns (Dark Triad) with a validated trait vocabulary

Richer persona or team modelling where honesty-humility carries signal

Any Big Five use case where the extra sixth dimension adds discriminating information

❌ "HEXACO is just the Big Five renamed" — it adds a genuinely distinct sixth factor (H) and rotates two others

❌ "Honesty-Humility is a truthfulness test" — it is a personality disposition, not a lie detector

✓ "HEXACO’s reason to exist is the H factor" — its distinct utility over Big Five is Honesty-Humility

News-style announcements, release notes, incident updates, changelog entries

Any text where readers skim and many will stop after the first lines

LLM-generated summaries that should front-load the takeaway

Arguments that must be followed in full → use the Pyramid Principle

Ultra-short, single-message contexts → use BLUF

Narrative or suspense-driven writing where withholding is intentional

BLUF (Bottom Line Up Front) — front-loaded but deliberately short

Pyramid Principle — complete, MECE argument structure

Diátaxis Framework — choosing the right documentation shape

Problem decomposition and analysis

Software architecture and component design

Module boundary definition to avoid overlapping responsibilities

Requirements organization and breakdown

API endpoint structure and design

Decision tree construction

Issue tree development

Organizing complex information

System design and modular architecture

Foundational to the Pyramid Principle

Supports Single Responsibility Principle

Enables Separation of Concerns

Used in logic trees and issue trees

Understanding communication preferences and potential friction sources within a team

Facilitating team retrospectives or kickoffs where interpersonal dynamics matter

Coaching individuals on leadership and communication style

Career development discussions to align role expectations with personal working style

UX research to consider how different user types might interact with a product

Onboarding programs to accelerate mutual understanding among new team members

❌ "My type means I can’t do X" — MBTI describes preferences, not capabilities or limits

❌ "Types are fixed for life" — Preferences can shift with experience, stress, or context

❌ "One type is better than another" — All 16 types bring value; the framework is descriptive, not evaluative

✓ "MBTI is a starting point for self-reflection and dialogue" — Correct use is exploratory, not diagnostic

David J. Pittenger, via the MBTI overview — poor test-retest reliability: between 39% and 76% of respondents obtain a different type when retaking the indicator after only five weeks (about 50% change on at least one scale). Predictive validity for job performance is poor, and the instrument’s own manual discourages using it to predict job success.

Widely regarded as pseudoscience by the scientific community (organizational psychologist Adam Grant: "there’s no evidence behind it") — the four binary dichotomies impose discrete types on traits that are in fact continuous.

Scientifically discredited yet commercially dominant — roughly 50 million people have taken it and thousands of businesses and colleges use it. Treat it as a starting point for self-reflection and dialogue, never as a diagnostic or selection tool; this is why the anchor carries an :advisory: flag. The empirically validated alternatives are the Big Five / OCEAN and HEXACO.

Writing technical documentation, reports, emails, and API documentation

Reviewing or editing any English prose for clarity and conciseness

Coaching writers to reduce verbose or bureaucratic language

Preparing communications for broad, non-specialist audiences

Any writing where clarity and brevity are paramount

Gutes Deutsch nach Wolf Schneider — the German-language equivalent of clarity-first writing principles

BLUF (Bottom Line Up Front) — complements plain style with a structure that leads with the conclusion

Pyramid Principle according to Barbara Minto — a complementary framework for structuring arguments hierarchically

Geoffrey K. Pullum, "50 Years of Stupid Grammar Advice" (The Chronicle of Higher Education, 2009) — several of the book’s grammar claims are factually wrong (some "passive" examples are not passive), and the authors routinely violate their own rules; linguists fault the book for presenting personal style preferences as rules of English

The blanket rules ("avoid passive voice", "omit needless words") are criticised as dogma when applied mechanically — the passive is the correct choice whenever the receiver of the action is the topic

Alternatives named in the discourse: Joseph M. Williams, "Style: Toward Clarity and Grace" (1990) and Steven Pinker, "The Sense of Style" (2014) — clarity guidance grounded in linguistics and reader psychology rather than prescription

Plain language is defined by what the reader can do, not by how the text looks. The standard builds on the definition the International Plain Language Federation adopted in 2014: a communication is in plain language if its wording, structure and design are so clear that the intended readers can easily find what they need, understand what they find, and use that information.

Four governing principles, each with guidelines. Readers get what they need (relevant); readers can easily find what they need (findable); readers can easily understand what they find (understandable); readers can easily use the information (usable).

Relevant starts before the first sentence. Identify the readers, their purpose and the context in which they read, then choose the document type and only the content they need.

Findable is about structure. Headings, a logical order, information design, and supplementary material kept apart from what most readers need.

Understandable covers more than word choice. Familiar words, clear sentences and paragraphs, cohesion, tone and supporting images.

Usable means evaluating with readers. The document is checked during development, with real readers, and after release — not just with a readability score.

For most languages. The principles are language- and culture-neutral; national bodies add language-specific rules, such as DIN 8581-1 (2024) for German.

Letters, notices, forms and web pages for the public, especially from government, insurers, banks and health services

Terms and conditions, privacy notices and other legal texts that readers must act on

Reviewing a document against an outcome ("can the reader find, understand and use this?") rather than a style rule

Product and API documentation for readers outside the team that wrote it

Reading it as "simple words". Word choice is one guideline among many. A rewrite that only shortens sentences and swaps words fails the findable and usable principles. In our prior test the bare words "plain language" produced exactly that: shorter prose without structure. Naming the standard produced headings and steps for the reader on every tier we tested.

Confusing it with Plain English according to Strunk & White. Strunk & White is a style manual for English prose. ISO 24495 is an outcome standard for most written languages, and it asks for evaluation with readers throughout, not only at the end.

Confusing it with Simplified Technical English. ASD-STE100 is a controlled language with a closed word list. ISO 24495 is principle-based and prescribes no vocabulary.

Confusing it with Easy Language. In German, ISO 24495 corresponds to Einfache Sprache. Leichte Sprache, for readers with cognitive impairments, is a different concept; DIN 8581-1 explicitly excludes it.

Expecting a readability score. The standard does not set one; usability is checked with readers.

The plain language movement’s premise is contested by data. Yonathan Arbel, "The Readability of Contracts: Big Data Analysis" (Journal of Empirical Legal Studies 21, 2024), analysed about two million contracts. He writes that the study "challenges fundamental tenets of the plain language movement": consumer agreements "have median reading scores almost indistinguishable from those of daily news articles", and readability tools give large grade-level differences for identical texts. The critique targets readability-score arguments, which ISO 24495 itself does not rely on.

A young standard, still growing. Part 1 was approved on 20 June 2023; the International Plain Language Federation’s timeline traces it from a 2007 motion through the 2014 definition to ISO TC 37 in 2019. Part 2, Legal communication, was approved on 25 August 2025, and Part 3, Science writing, was published on 12 May 2026; both build on Part 1’s four principles. IIID reports that a further part on document design is in preparation. The training-data prior for the bare term "plain language" points to the older movement and its style guides; the ISO name is what reaches the four principles.

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

Socratic Method — complementary: NVC for expressing, Socratic for exploring

BLUF — contrasting style: BLUF is conclusion-first, NVC is empathy-first

Designing UIs for applications with many features or configuration options

Structuring documentation so that one entry point serves both beginners and experts

Building onboarding flows that let new users succeed before exposing advanced settings

Prompting an LLM to produce layered output — executive summary first, full detail on request

Authoring tutorials where novice and expert readers share the same page

Curse of Knowledge

Inverted Pyramid Style

Diátaxis Framework

Bloom’s Taxonomy

Carroll and Rosson (1997) noted that empirical support for progressive disclosure is narrow: the foundational training-wheels studies used a single application (a word processor) and a single interface style (menu-based control), leaving the technique’s generalizability unconfirmed (cited in IxDF Glossary of Human-Computer Interaction)

Nielsen warns that exceeding two disclosure levels consistently produces low usability — the technique can mask an underlying information-architecture problem rather than solve it (NN/g, 2006)

Executive presentations and briefings

Written reports and proposals

Complex arguments requiring clear structure

Stakeholder communication where time is limited

Business cases and recommendations

Consulting deliverables

Any situation requiring persuasive, structured communication

Naming the root phenomenon before choosing a diagnostic framework — use this term to describe the problem, then choose Shannon-Weaver, Schulz von Thun, Hall, or Clark to diagnose its cause

Reviewing a document, email, or specification to ask whether the receiver’s likely decoding matches the sender’s intent

Debriefing after a miscommunication in a team: "We had a sender-receiver discrepancy — which layer broke down?"

Prompting an LLM to evaluate a draft from the reader’s perspective, not the writer’s

Framing a communication training or workshop before introducing specific models

Curse of Knowledge

Four-Sides Model (Schulz von Thun)

Feynman Technique

Problem Space NVC

Plain English (Strunk & White)

BLUF

Data-ink ratio. Of all the ink on the page, the share that encodes data should be as large as it usefully can be. Gridlines, frames, fills, shadows and 3-D effects encode no data; at best they help the eye find its way. They are therefore the first candidates for removal, not automatic deletions: a gridline that lets the eye read a value off the chart is doing work, and muting it usually beats deleting it.

Chartjunk. The name for decoration that competes with the evidence — moiré patterns, ornamental icons, gratuitous colour. Naming it as a defect is what makes it removable.

Graphical integrity, measured by the lie factor. The size of the effect shown should equal the size of the effect in the data. A distorted axis or a scaled-area icon is a quantitative error, not a matter of taste.

Small multiples. Repeat one compact panel across subsets on identical axes. The comparison then happens in the eye rather than in the reader’s memory.

Sparklines. A word-sized graphic set inside the sentence it belongs to, so the number and its history occupy the same line.

Direct labelling instead of legends. Put the name on the line. A legend forces the reader to hold a colour in memory and look it up again for every mark.

Density is the point, not emptiness. This is the distinction that decides whether the term was understood: remove what carries no information, then spend the reclaimed space on more information. A Tufte-style page usually contains more than the one it replaces.

Words, numbers and images belong together. Caption, annotation and graphic sit in one place rather than in three. The sidenote layout that carries Tufte’s name is this principle applied to running text.

Designing a dashboard or a status report, especially where the default is large KPI tiles, gauges and traffic lights

Reviewing a chart before it goes into documentation, a slide deck or a paper

Anywhere a graphic has to survive being printed in black and white, or read at a glance

When a report has grown to several pages because each number was given its own panel

Reading it as minimalism. A minimalist chart contains little; a Tufte-style chart often contains a great deal and merely wastes no ink. Stripping detail to look clean inverts the principle.

Treating it as a visual skin. It is a set of decisions about evidence — what is compared, at what scale, against what baseline — not a palette and a font.

Taking the data-ink ratio for a law. It is a heuristic, and experiment has put some of its premises in question. See Criticism.

Confusing the two things the name covers. "Tufte style" names both the chart principles and the sidenote page layout of Tufte CSS and tufte-latex. They share an author and a motive, but a request for one does not deliver the other; say which you mean.

Designing instruction or onboarding content: pitch difficulty just above the learner’s current independent ability, not at or below it

LLM prompting: "Explain X at the level of someone who knows Y but not yet Z" — targeting the ZPD rather than explaining from scratch or over-explaining

Coaching and mentoring: identify what the mentee can almost do alone; scaffold from there and withdraw support as skill grows

Documentation review: check whether explanations assume too much (beyond the reader’s ZPD) or repeat what is already known (below it)

Calibrating AI-assisted tutoring: use demonstrated learner performance as the baseline and target the next challenge level

Bloom’s Taxonomy — classifies the cognitive level of a task; ZPD locates the challenge band where a specific learner can grow

4MAT — structures a teaching arc from motivation to transfer; ZPD identifies where in that arc the learner currently stands

Feynman Technique — surfaces the learner’s actual understanding floor, which maps to the lower bound of their ZPD

"Scaffolding" is widely attributed to Vygotsky in secondary literature, but the term is absent from his writing. The distinction matters when prompting an LLM: invoking "ZPD" activates Vygotsky’s sociocultural framing; invoking "scaffolding" activates Wood/Bruner/Ross’s instructional mechanics. Both are valid anchors for related but distinct ideas.

Moll (1990) argued that interpretations focused on skill-transfer from expert to novice are "too narrow, theoretically misleading, and of limited instructional utility," calling instead for collective, activity-based zones rather than individual expert–novice dyads. See: Luis C. Moll, "Vygotsky’s zone of proximal development: Rethinking its instructional implications", Infancia y Aprendizaje, 1990

Short stories and novellas where pace is paramount

Any narrative that must grip immediately and sustain tension throughout

Genre fiction (thriller, horror, action) requiring constant momentum

Instructing LLMs to write with "constant crisis" and "rapid pacing" constraints

Diagnosing why a story feels slow — the Fichtean Curve demands crises, not lulls

Three-Act Structure

Freytag’s Pyramid

Save the Cat! (15-Beat Sheet)

Analysing classical plays, tragedies, and literary fiction

Teaching the universal arc of dramatic tension to students or LLMs

Diagnosing whether a story’s climax is properly positioned at the midpoint

Writing tragedy or dramatic fiction where the protagonist’s flaw drives the collapse

Understanding why Act 2 / Rising Action sags — it must contain escalating complications, not filler

Three-Act Structure

Hero’s Journey (Monomyth)

Fichtean Curve

Save the Cat! (15-Beat Sheet)

Novelist and writing professor Jane Alison (Meander, Spiral, Explode, 2019; excerpt at CRAFT) objects that the pyramid was never a general theory of stories — "Novels didn’t exist for Aristotle and weren’t Freytag’s subject" — calls the swell-climax-collapse arc "masculo-sexual", and proposes waves, meanders, and spirals as equally valid narrative designs

Freytag derived the model from five-act stage tragedy, not narrative in general; Chris Winkle (Mythcreants, 2024) argues it "isn’t really applicable to modern stories"

Defenders such as TD Storm (Storm Writing School) counter that, read as Freytag intended — an analysis of classical drama — it is a descriptive lens; the criticism properly targets its later misuse as a universal template

Structuring transformation stories — character arcs where the protagonist changes fundamentally

Identifying whether a narrative has mythic resonance and universal appeal

Guiding LLMs to write archetypal stories or analyse existing myths and films

Deepening character development by mapping each stage to internal transformation

Marketing narratives positioning the customer as the hero

Three-Act Structure

Story Circle (Dan Harmon)

Freytag’s Pyramid

Folklorists broadly reject the monomyth’s claim to universality: Alan Dundes ("Folkloristics in the Twenty-First Century", Journal of American Folklore 118/470, 2005) called Campbell a "non-expert" whose pattern survives only by source-selection bias, and Barre Toelken noted Campbell "could construct a monomyth of the hero only by citing those stories that fit his preconceived mold" (overview with citations: Jeana Jorgensen, "Why Folklorists Hate Joseph Campbell’s Work")

David Brin (Salon, 1999) attacks the template’s value system: the Campbellian demigod formula carries elitist, anti-democratic ideals

Since Christopher Vogler’s Disney memo turned Campbell into a screenwriting guide, forcing stories into the template has been blamed for predictable, interchangeable plots — defenders reply that Campbell described recurring mythic patterns, not a recipe

Writing short fiction, manga, or poetry where surprise recontextualisation replaces conflict

Crafting non-confrontational narratives (slice-of-life, meditative, philosophical)

Instructing LLMs to write with "no villain" — structures built on insight rather than opposition

Game level design, puzzle design, or UX flows where each step recontextualises the previous

Breaking Western narrative assumptions when conflict-based structure feels forced

Three-Act Structure

Story Circle (Dan Harmon)

Hero’s Journey (Monomyth)

Writing commercially viable screenplays or genre fiction with audience-tested pacing

Auditing a story beat-by-beat for structural gaps or pacing problems

Instructing LLMs to generate story outlines aligned with Hollywood conventions

Teaching story structure with precise page/percentage targets

Developing the "logline" (one-sentence pitch) that encapsulates the premise

Three-Act Structure

Freytag’s Pyramid

Fichtean Curve

Peter Suderman, "Save the Movie!" (Slate, 2013) — the beat sheet "has taken over Hollywood screenwriting" and "made every movie feel the same": where Syd Field and Robert McKee treated structure as "an organizing principle", Snyder pinned named beats to page numbers, turning description into prescription

The piece sparked an industry debate; responses like Christopher Boone’s at No Film School (2013) accept that screenplays need structure but ask whether writers lean on the beat sheet instead of the story — the recurring defense being that Snyder catalogued beats that already recur in successful films

Writing or analysing episodic TV where each episode needs a mini-arc

Identifying the "want vs. need" gap — the engine of character-driven stories

Instructing LLMs to write stories with clear transformation arcs at any scale

Teaching Campbell’s Monomyth in a compressed, actionable eight-step format

Diagnosing stories where the protagonist doesn’t change — the circle requires transformation

Hero’s Journey (Monomyth)

Three-Act Structure

Kishōtenketsu

Structuring any narrative-driven content (fiction, screenplays, marketing copy, presentations)

Checking whether a story has a balanced beginning, middle, and end

Diagnosing pacing problems — too much setup, sagging middle, rushed ending

Guiding LLMs to write or critique stories with classical dramatic structure

Hero’s Journey (Monomyth)

Freytag’s Pyramid

Save the Cat! (15-Beat Sheet)

Fichtean Curve

Story Circle (Dan Harmon)

Arduino and other microcontroller code that has to react to input while something else is timed

Rewriting a sketch that uses delay() before adding a second task to it

Teaching the step from a single blocking loop to cooperative multitasking and state machines

Driving a model: "add the button, BlinkWithoutDelay style" removes every delay() and keeps the input responsive, where "add the button" tends to keep the delay() calls

❌ "BlinkWithoutDelay is about blinking LEDs" — the LED is the demonstration; the subject is not blocking the loop

❌ "`millis() >= previousMillis + interval` is equivalent" — it fails when millis() wraps; subtract, then compare

❌ "This is an interrupt-based timer" — it is polling in the main loop; interrupts and hardware timers are a different technique

❌ "It replaces an RTOS" — it covers cooperative tasks that finish quickly; long-running or preemptive work needs more

✓ "Every task checks its own elapsed time on every pass, and nothing ever waits"

Check the module in cleaner than you checked it out. The unit of improvement is the visit, not the project. Every time a file is opened for some other reason, it leaves in slightly better shape than it arrived.

Scoped to what you already touched. The cleanup rides along with work that was going to happen anyway. Code you did not need to open is out of scope — that is the line between the rule and drive-by refactoring.

Small enough to need no permission. Rename an unclear variable, extract a method, delete dead code, fix a stale comment. If it needs a ticket, it is no longer this rule.

Aimed at entropy, not at perfection. The target is the slow decay of a codebase nobody is responsible for, not a standard of cleanliness. Slightly better, repeatedly, beats a rewrite that never comes.

Safe only under test. The rule assumes a green test suite. Without one, "improvement" is an unverified change to code you opened for a different reason.

Fixing a bug in a file nobody has read in years

Codebases with no dedicated refactoring budget, where improvement has to be smuggled into ordinary work

As a shared team norm, so the cleanup is expected rather than defended in review

Where code is generated or changed faster than humans critically review it, and decay would otherwise accumulate unobserved

Reading it as a licence to refactor anything nearby. The rule is bounded by what the task already touched. Unbounded, it produces pull requests whose reviewers cannot find the actual change.

Mixing structural and behavioural change in one commit. The cleanup and the fix should be separable, so that a reviewer can read one without the other and a revert does not take both. Kent Beck’s Tidy First? makes that separation its central rule.

Confusing "cleaner" with "in my style". Reformatting to personal preference adds diff noise and removes no decay.

Applying it without tests. Then it is not tidying, it is an unreviewed change under a virtuous name.

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

Patterns of Enterprise Application Architecture - Same author; Fowler’s broader design-pattern vocabulary

Cohesion Criteria - Many smells (Feature Envy, Divergent Change, Large Class) are low-cohesion symptoms

SOLID Principles - SOLID violations manifest as identifiable smells; smell→principle is a useful diagnostic direction

SOLID SRP - Divergent Change is almost always an SRP violation

KISS Principle - Speculative Generality and Comments-as-compensation are KISS failures

Evaluating module quality during code reviews or refactoring

Deciding whether to split a class or module that feels too large

Arguing for refactoring with concrete criteria instead of gut feeling

Teaching software design: the scale makes abstract quality tangible

Assessing architecture decisions around module boundaries

GRASP - "High Cohesion" is one of the nine GRASP patterns

SOLID SRP - Single Responsibility Principle targets functional cohesion

Clean Architecture - Organizes code by cohesive business rules

Vertical Slice Architecture - Groups by feature cohesion rather than technical layer

Designing or reviewing a class or module API, when a reader must see from the signature whether a call is safe to repeat

Sorting an existing interface: any method that both mutates and returns is a question to answer, not automatically a defect

Wherever assertions, contracts or invariants will call into the code (design-by-contract)

Writing code a model will extend: a command/query split survives being read out of context better than a convention in the docstring

Naming the deliberate exceptions, so pop() is a decision in the record and not an oversight

Per slice in vertical-slice-architecture, where the command/query split is the natural seam before any CQRS-scale separation

❌ "CQS and CQRS are the same thing, one is just the abbreviation" — CQS is Meyer’s per-method rule from 1988; CQRS is the architectural pattern with two models

❌ "CQS means you need separate read and write databases" — that is CQRS; CQS costs nothing architecturally and needs no second store

❌ "A query must have no side effects at all" — it must have no observable ones; caching and counters are fine

❌ "The rule is absolute" — Fowler breaks it for pop() on purpose, and atomic compare-and-set cannot obey it without reintroducing a race

❌ "A command may return a status code" — returning an error or a status is the usual, defensible bend; returning the created entity’s ID is the contested one

✓ "Every method is a command or a query, and the exceptions are named" — the rule plus its named exceptions is the whole practice

Early OO design phases — discovering classes, responsibilities, and relationships before writing code

Collaborative design sessions where multiple stakeholders or developers shape the domain model

Teaching object-oriented thinking by making abstract concepts tangible and interactive

Validating design with LLMs by describing cards and role-playing request flows

Lightweight architecture exploration before committing to a UML tool or full model

GRASP - Patterns for assigning responsibilities to classes in OO design

GoF Design Patterns - Design patterns that can emerge from CRC-Card sessions

Domain-Driven Design - CRC Cards support ubiquitous language and entity discovery

The definition is intact — index cards with Class, Responsibilities, Collaborators, exactly as Beck & Cunningham published at OOPSLA 1989; the original paper is still hosted on Ward Cunningham’s site

The technique survives mainly as a teaching and workshop tool for object-oriented thinking — its original stated purpose ("A Laboratory for Teaching Object-Oriented Thinking") — and remains a defined entry in the Agile Alliance glossary; day-to-day design discussion has largely moved to whiteboard sketches and lightweight diagrams

Properties, not principles. A principle is a rule you either follow or break. A property is a quality code has more or less of, and that you move toward. This is the distinction the term is built on, and the one most often lost when it is summarised.

Composable. Small surface area, few dependencies, clear intent — so the code is easy to pick up, reuse and combine with things its author never saw.

Unix philosophy. Does one thing well. Close to single responsibility, but stated from the outside: about what the code does, not about why it would have to change.

Predictable. Does what you expect. Behaves consistently, is deterministic where it can be, and is observable enough that you can tell its internal state from its outputs.

Idiomatic. Feels natural. Follows the conventions of its language, framework and team, so the next reader spends attention on the problem rather than on the style.

Domain-based. Names, structure and boundaries follow the problem domain rather than technical layers or framework concepts.

Positioned against SOLID, not on top of it. North’s argument is that SOLID’s criteria are met or missed at the level of a class, while what makes code pleasant to work in is a set of overlapping qualities that reinforce each other.

Reviewing a module whose problems are qualities rather than rule violations — a class that breaks no principle and is still unpleasant to work in

As a vocabulary for code review, where "this is hard to compose" is a more useful sentence than a principle acronym

When SOLID has become a checklist and the discussion has stopped being about the code

Reading the D as "Domain-driven". It is Domain-based. The pull toward DDD is strong enough that weaker language models make this substitution reliably — see the prior-test register. CUPID’s D is a statement about naming and structure, not an endorsement of a method.

Reading the I as "Intelligible". It is Idiomatic. Intelligibility is a consequence North argues for, not the property he named.

Treating them as five boxes to tick. They are deliberately not binary, and a scorecard turns them back into the thing they were proposed against.

Designing a module’s public API — evaluate whether the interface is simpler than the implementation it hides

Reviewing a proposed class decomposition for whether it reduces complexity or merely redistributes it

Identifying pass-through methods and wrapper chains that add interface cost without hiding detail

Instructing an LLM to design APIs or class boundaries with minimal caller-visible surface area

Choosing between a general-purpose and a special-purpose API — prefer the deeper, more general option

SOLID Principles

KISS Principle

Separation of Concerns

GRASP

Andrey Lebedev, "Not My Philosophy of Software Design" (Medium) — argues that forcing depth into a single class violates the Single Responsibility Principle; the Java I/O example conflates file reading with buffering, two genuinely separate concerns; deep general-purpose classes also resist composition and create coupling that contradicts domain-driven design practice

"Modules Should Be Deep!" (Software Engineering: A Modern Approach) — adds nuance: String.isEmpty() provides semantic clarity and safe encapsulation despite its trivial implementation, challenging a purely quantitative interpretation of depth; Bertrand Meyer’s iceberg metaphor — small visible tip over large submerged base — is cited as a complementary framing

Code that reads input it does not control: parsers, file importers, API handlers, device drivers

Deciding where validation lives in a module, so it happens once at the public interface and not in every private helper

Choosing between robustness and correctness for a system, and writing the choice down

Reviewing error handling that swallows exceptions or returns plausible defaults for impossible states

Driving a model: "apply defensive programming according to McConnell, with a barricade at the public API and assertions inside" asks for a placement, not just for more checks

❌ "Defensive means wrapping everything in try/catch" — swallowing errors is the opposite of the practice; a hidden fault is harder to find than a crash

❌ "Check every argument in every function" — the barricade exists so that internal code does not repeat boundary checks

❌ "Assertions are input validation" — assertions catch programmer errors and may be compiled out; user input needs real error handling

❌ "Defensive programming and fail-fast are opposites" — assertions that stop the program at the first broken assumption are part of the practice

❌ "Defensive programming is a security architecture" — that is defense-in-depth; this is a coding practice inside one program

✓ "Validate at the boundary, assert inside, and decide whether this system prefers robustness or correctness"

Specifying the obligations and guarantees of a module’s public API precisely

Designing class hierarchies that must remain substitutable (behavioural subtyping)

Pushing input validation to a single, well-defined seam instead of scattering defensive checks

Prompting an LLM to generate routines with explicit pre/postconditions and invariants

Reasoning about correctness before reaching for exhaustive tests (complements, not replaces, testing)

Liskov Substitution Principle — DbC’s inheritance rules formalize behavioural subtyping

SOLID Principles — DbC reinforces the substitutability guarantee SOLID depends on

Postel’s Law — opposing stance on input strictness; reconciled by boundary scope

EARS Requirements — pre/postconditions express requirements as checkable assertions

Defensive Programming according to McConnell — the opposite instinct, checking wherever bad data could arrive; McConnell’s barricade reconciles the two by validating once at the boundary

Bjarne Stroustrup, on the C26 contracts design (https://www.theregister.com/2026/03/31/cplusplus26_approved/[The Register], 2026) — "It's claimed to be a minimal viable product. It's not minimal, it's not viable" — and recommended not using contracts in C. Native, end-to-end DbC stays largely confined to Eiffel; mainstream languages get only partial or contested support.

Expressiveness limit (Supporting Design by Contract in Java) — contracts written in a subset of the host language often lack the power to state full functional correctness, forcing cumbersome workarounds; runtime-checked contracts catch violations late rather than proving absence of them.

C contracts were *removed* from the C20 working draft in 2019, restarted by study group SG21, and only landed in the standard as part of C26 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2025/p2899r1.pdf[P2899 Rationale]; https://www.theregister.com/2026/03/31/cplusplus26_approved/[The Register], 2026) — so language-level DbC remains young and contested outside Eiffel. Training-data priors from before 2026 likely treat C contracts as absent or experimental.

Native support exists in Ada 2012, Eiffel, D, Kotlin, and others; Python relies on third-party libraries (e.g. deal, icontract) rather than a language feature.

Consolidating a business rule, constant, or schema that appears in several places

Designing a single source of truth (config, types, API contracts) that other artifacts derive from

Reviewing code for knowledge duplication that causes change to require edits in many spots

Before the Rule of Three — resist abstracting on the first or second occurrence

When two similar fragments change for different reasons — coupling them via a shared abstraction is worse than the duplication

As dogma over readability: a little duplication can beat a leaky, over-general abstraction

Single Source of Truth — the data-layer cousin of DRY’s knowledge rule

Single Level of Abstraction Principle — keeps extracted abstractions coherent

KISS Principle — the simplicity counterweight to over-abstraction

YAGNI — don’t build the abstraction until you actually need it

Sandi Metz, "The Wrong Abstraction" (2016) — overzealous DRY produces abstractions that later requirements don’t fit: "duplication is far cheaper than the wrong abstraction"; her advice is to re-introduce the duplication until the right abstraction reveals itself

The authors themselves concede the principle is widely misread: in the 20th Anniversary Edition (2019), Thomas & Hunt write they "did a poor job of explaining" DRY — it targets duplication of knowledge and intent; code deduplication is "a tiny and fairly trivial part" (official chapter extract)

The corollary both critiques share: two pieces of code that look alike but encode different business knowledge are not a DRY violation — merging them creates coupling, not clarity

Logic that depends on a history of events: protocols, device controllers, UI flows, order and document lifecycles

Replacing a tangle of boolean flags whose combinations include impossible ones

Writing requirements and tests: every row of the table is a test case, and every empty cell is a question for the product owner

Embedded control loops where a task must advance step by step without blocking, as in blink-without-delay

Driving a model: "model this as a finite state machine with an explicit transition table, and say what happens for each invalid event" asks for the table, not just for an enum

❌ "A status field makes it a state machine" — without a finite list of states and defined transitions, it is just a variable

❌ "FSM means the GoF State pattern" — the pattern is one object-oriented way to code the model

❌ "Unhandled events can be ignored silently" — ignoring is a valid choice only if the table says so

❌ "Booleans are simpler" — three booleans give eight combinations, and the code has to rule out the impossible ones by hand

❌ "An FSM can count" — a finite machine has no unbounded memory; counters and stacks are extended state

✓ "Name the states, list the events, fill every cell of the table"

Designing complex enterprise applications with data persistence

Building layered architectures with clear separation of concerns

Working with object-relational mapping and database interactions

Designing web applications with proper presentation layer patterns

Managing distributed system communication

Handling concurrency in multi-user enterprise systems

Creating maintainable and testable enterprise code

Domain-Driven Design - Complements PEAA with domain modeling approach

Hexagonal Architecture - Architectural style emphasizing ports and adapters

Clean Architecture - Layered architecture pattern with dependency rules

The prior reproduces the 2002 catalog (Active Record, Data Mapper, Unit of Work, Repository …) as hand-rolled patterns; Fowler himself notes "many patterns are now implemented by common frameworks" while maintaining they are "still relevant today" (P of EAA book page)

The online catalog is content-unchanged since its "original 2003 publication", and the planned follow-up volumes (eaaDev) have been "pretty much frozen" since 2006 — the catalog reflects the J2EE/.NET era, not current distributed and frontend-heavy practice

When a system should be independent of how its products are created

When a system should be configured with one of multiple families of products

When related product objects are designed to be used together and you need to enforce this constraint

GoF Design Patterns (Umbrella)

When you want to use an existing class whose interface doesn’t match what you need

When you want to create a reusable class that cooperates with unrelated classes

GoF Design Patterns (Umbrella)

When you want to avoid a permanent binding between an abstraction and its implementation

When both the abstractions and their implementations should be extensible by subclassing

When changes in the implementation should have no impact on clients

GoF Design Patterns (Umbrella)

When the algorithm for creating a complex object should be independent of the parts and how they are assembled

When the construction process must allow different representations

GoF Design Patterns (Umbrella)

When more than one object may handle a request, and the handler isn’t known a priori

When you want to issue a request to one of several objects without specifying the receiver explicitly

When the set of objects that can handle a request should be specified dynamically

GoF Design Patterns (Umbrella)

When you want to parameterize objects with an action to perform

When you need undo/redo functionality

When you need to queue, log, or schedule requests

GoF Design Patterns (Umbrella)

When you want to represent part-whole hierarchies of objects

When you want clients to be able to ignore the difference between compositions of objects and individual objects

GoF Design Patterns (Umbrella)

To add responsibilities to objects dynamically and transparently

When extension by subclassing is impractical

GoF Design Patterns (Umbrella)

Object-oriented design requiring proven solutions to recurring problems

Communicating design decisions using a shared vocabulary

Teaching object-oriented design principles through concrete examples

Refactoring code to increase flexibility and reusability

SOLID Principles - Design principles that GoF patterns help implement

Fowler Patterns - Enterprise application architecture patterns (complementary scope)

Clean Architecture - Architectural style leveraging GoF principles

Peter Norvig, "Design Patterns in Dynamic Languages" (1996/1998) — 16 of the 23 patterns have a "qualitatively simpler implementation" in Lisp or Dylan than in C++, or vanish into the language entirely: many patterns compensate for missing language features rather than capture universal design wisdom

Paul Graham, "Revenge of the Nerds" (2002) — recurring patterns may be evidence of "the human compiler at work": "When I see patterns in my programs, I consider it a sign of trouble", a sign the language’s abstractions are not powerful enough

The authors themselves treat the catalog as a 1994 snapshot, not a closed canon: in the 2009 InformIT interview they discuss how they would reorganize and trim it today (see also the Criticism on Singleton)

When you want to provide a simple interface to a complex subsystem

When there are many dependencies between clients and implementation classes

GoF Design Patterns (Umbrella)

When a class can’t anticipate the class of objects it must create

When a class wants its subclasses to specify the objects it creates

GoF Design Patterns (Umbrella)

When you need to access an aggregate object’s contents without exposing its internal representation

When you want to support multiple traversals of aggregate objects

When you want to provide a uniform interface for traversing different aggregate structures

GoF Design Patterns (Umbrella)

When a set of objects communicate in well-defined but complex ways

When reusing an object is difficult because it refers to and communicates with many other objects

When behavior distributed between several classes should be customizable without excessive subclassing

GoF Design Patterns (Umbrella)

When changes to one object require changing others, and you don’t know how many objects need to change

When an object should notify others without knowing who they are

GoF Design Patterns (Umbrella)

When a system should be independent of how its products are created and represented

When classes to instantiate are specified at runtime

When you want to avoid building a class hierarchy of factories that parallels the class hierarchy of products

GoF Design Patterns (Umbrella)

When you need a more versatile or sophisticated reference to an object than a simple pointer (remote, virtual, protection, or smart reference proxy)

GoF Design Patterns (Umbrella)

When there must be exactly one instance of a class

When the sole instance should be extensible by subclassing

GoF Design Patterns (Umbrella)

Erich Gamma, co-author of the original GoF book, said in the 2009 interview "Design Patterns 15 Years Later" (InformIT, Larry O’Brien) that he favours dropping Singleton from the pattern catalog: "Its use is almost always a design smell"

Miško Hevery, "Singletons are Pathological Liars" (Google Testing Blog, 2008) — Singletons hide dependencies from the API surface and make code hard to test in isolation

Widely categorised as an anti-pattern in modern practice: it introduces global mutable state, couples consumers to a concrete class, and complicates concurrency and test isolation — dependency injection of a single instance is the commonly recommended alternative

When an object’s behavior depends on its state and must change at runtime

When operations have large conditional statements that depend on the object’s state

GoF Design Patterns (Umbrella)

Finite State Machine — the model this pattern implements; the pattern is one way to code it

Multiple related classes differ only in behavior

You need different variants of an algorithm

An algorithm uses data that clients shouldn’t know about

GoF Design Patterns (Umbrella)

When you want to implement the invariant parts of an algorithm once and leave it to subclasses to implement varying behavior

When common behavior among subclasses should be factored and localized in a common class

GoF Design Patterns (Umbrella)

Designing object-oriented systems and deciding where to assign responsibilities

Improving cohesion and reducing coupling in existing codebases

Guiding refactoring decisions by evaluating current responsibility assignments

Teaching foundational object-oriented design principles

SOLID Principles - Complementary OO design principles for maintainable systems

GoF Design Patterns - Patterns that often embody GRASP principles

Clean Architecture - Architectural style that leverages GRASP-based thinking

Domain-Driven Design - Uses responsibility assignment in the domain model

Refactoring hybrid functions that mix high-level orchestration with low-level details — IOSP tells you how to split, not just that you should

TDD: structuring code so that operations emerge naturally as testable leaves, with integrations as trivial wiring

Code review: a concrete, checkable rule — a function either calls other functions or contains logic, never both. If a reviewer spots a hybrid, it’s a clear finding

Teaching clean code: unlike SRP (which is often debated), IOSP is crystal clear at a glance — there is no interpretation question

Reducing DIP/IoC complexity: if the only reason for DIP is testability, IOSP eliminates that need

Architecture design with IODA (Integration-Operation-Data-API): IOSP scales to module level, producing dependency-free operational modules composed by integration modules

Designing data flows: integrations become explicit "ditch-diggers" for data to flow between operations

.NET development with IospAnalyzer: automated Roslyn Analyzer catches IOSP violations at compile time

Single Level of Abstraction Principle (SLAP) - IOSP naturally enforces SLAP: integrations are high-level, operations are low-level

SOLID Principles - IOSP applies SRP at the function level and can reduce the need for DIP

SOLID SRP - IOSP is a special case of SRP applied at the function level, separating the responsibility of "what to compute" from "how to compose"

Cohesion Criteria - IOSP produces functional cohesion by dedicating each function to a single kind of work (either logic or composition)

GRASP - GRASP’s "High Cohesion" and "Low Coupling" are structurally supported by IOSP’s tree-like composition

SOLID DIP - IOSP can replace DIP for the purpose of testability; DIP is retained only for genuine alternative implementations

Clean Architecture - Layered abstraction at architecture scale mirrors IOSP’s function-level separation

The canonical source is Ralf Westphal’s own writing — "Integration Operation Segregation Principle (IOSP)" (Substack); note that clean-code-developer.de, often assumed to host it, has no IOSP page

The prior is thin: the principle originates from a small German Clean Code Developer / Flow Design school, with the inventor’s blog posts as primary sources and mostly German-language secondary coverage — state the rule explicitly in the prompt (functions either contain logic or call other functions, never both)

Designing a pipeline or system that must halt on a bad signal rather than push a defect downstream — failing builds that block merge, a canary that aborts the rollout

Arguing against "keep it green, we’ll fix it later" — jidoka is the named counter-position

Fail-fast design: assertions, preconditions, circuit-breaker tripping, refusing to serve on a failed health check

Giving the person closest to the work the authority to stop it, and making that stop visible

Whenever the discussion is about detection and the response to detection, since jidoka insists both belong together

❌ "Jidoka means automation" — the whole point is the extra character; plain automation is 自動化

❌ "Jidoka is the andon cord" — the cord is one instance; the principle is detect-stop-fix-investigate

❌ "Stopping is the goal" — stopping is the trigger for the investigation that follows

❌ "Jidoka and Just-in-Time are alternatives" — they are the two pillars and depend on each other

✓ "Build quality in rather than inspect it in" — the standard English gloss, and accurate

When facing the choice between a simple and a complex solution

Reviewing code for maintainability and readability

Designing APIs, interfaces, or data models

Onboarding new team members to an unfamiliar codebase

Refactoring code that has grown unnecessarily complicated

YAGNI - Don’t implement what you don’t need yet (complementary simplicity principle)

DRY - Eliminate redundancy to keep codebases simple and consistent

SOLID Principles - Structured guidelines that reinforce clean, simple designs

Reviewing code for hidden coupling and fragile call chains

Designing object APIs that hide their internal structure

Teaching encapsulation and "tell, don’t ask"

Guiding refactorings away from train-wreck expressions

For fluent interfaces / builders where chaining is the intended design

For immutable value objects and data-query DSLs where traversal is the point

SOLID Principles — complementary coupling/cohesion guidance

GRASP — Low Coupling and Information Expert overlap with LoD

Cohesion Criteria — the cohesion side of the same design concern

Writing CI/CD pipelines — the measurement below shows this is where the anchor actually changes output

IAM policies, service accounts, workload identity and database grants

Agent and tool permissions, where the grant is an LLM’s reach into a system (meaningful-human-control)

Container and process design: which capability does this process genuinely need

Reviewing an Elevation of Privilege threat from stride, or Broken Access Control from owasp-top-10

❌ "Least privilege means read-only" — it means the least set for the job, which sometimes includes write

❌ "It is purely a security principle" — damage from "an accident or error" is the first reason the authors give

❌ "Zero Trust is least privilege" — per-request verification and minimal grants are separate properties

❌ "Grant it once and you are done" — the minimum is defined relative to the job, so it has to shrink when the job ends

❌ "The minimum set can be computed" — the central academic objection says it cannot (see Criticism)

✓ "Default deny, grant the least set for this job, and make the grant expire" — the operational form

The principle in one sentence, from the essay that named it: "The behaviour of a unit of code should be as obvious as possible by looking only at that unit of code."

Read-time cost over write-time cost. The measure is how far a reader must travel to answer "what happens when this runs", not how few characters the author typed.

Behaviour at a distance is the failure mode. A handler registered in a remote file, a convention that binds by name, a framework hook that fires invisibly — each is correct code that cannot be understood locally.

Co-location as the remedy: markup, handler, styling and validation for one element live where that element is.

An explicit trade, not a law. The essay argues against DRY and Separation of Concerns where they scatter one feature across many files, and concedes the trade openly rather than claiming the other principles are wrong.

Reviewing a design where understanding one element requires opening several unrelated files

Deciding whether an abstraction earns its indirection, or only moves code elsewhere

Weighing convention-over-configuration, dependency injection, event buses, decorators and lifecycle hooks — all of which trade locality for other goods

Arguing about whether a repeated fragment should be extracted at all

Reading it as anti-abstraction. A good abstraction leaves its invocation and effects obvious at the call site; that is entirely compatible with the principle.

Confusing it with Locality of Reference. That is a hardware-performance concept about memory access patterns (temporal and spatial locality). The name is a coincidence, not a lineage.

Treating co-location as sufficient. Visible is not the same as understandable — see the Criticism section.

Using the abbreviation on its own. "LoB" reads as "Line of Business" far more often than as this principle.

When a recurring defect traces back to a slip anyone could make, not to missing knowledge

Designing APIs, CLIs, and configuration formats so a wrong call cannot be expressed — types over validation, enums over strings, required arguments over defaults

Build and deployment guardrails: a pre-commit hook that refuses a secret, a pipeline that cannot deploy an untagged image

User interfaces where a destructive action needs a forcing function rather than a warning dialogue

As the counterweight to five-whys: once the cause is known, poka-yoke is what makes the cause unrepeatable

❌ "Poka-yoke means idiot-proofing" — Shingo renamed it precisely to drop that reading

❌ "A warning light is a poka-yoke" — it is the weaker class; a real poka-yoke removes the option

❌ "It eliminates human error" — it eliminates the consequence; the error still occurs

❌ "It is a manufacturing technique" — the mechanism is a constraint in a design, and applies wherever a design can carry one

✓ "Make the wrong thing impossible, not merely discouraged" — the working test for whether you have built one

Designing protocol, API, or event-schema contracts that must evolve

Deciding how strictly a parser/validator should reject input

Reasoning about forward/backward compatibility and graceful degradation

Security-sensitive parsing where ambiguity is dangerous — prefer strict validation

Internal interfaces under one team’s control, where strictness catches bugs earlier

Semantic Versioning — the explicit-versioning complement to tolerant inputs

SOLID Principles — interface design and contract stability

Event-Driven Architecture — tolerant readers for evolving event schemas

Eric Allman, "The Robustness Principle Reconsidered" (ACM Queue, 2011) — decades of liberal acceptance bred de-facto protocol forks and security holes; tolerance that was meant to be transitional became permanent

RFC 9413, "Maintaining Robust Protocols" (Thomson & Schinazi, IETF, 2023) — formal IETF guidance that blanket liberality harms protocol ecosystems over time; ambiguous tolerance enables interoperability failures and attacks such as request smuggling

Alternative named in the discourse: active protocol maintenance with strict parsing and explicit versioning ("fail fast") instead of silently accepting malformed input — see Semantic Versioning

Use-case orchestration where several fallible steps compose in sequence: validate, check uniqueness, persist, notify

Parsing and validation at a boundary, where the caller must be told what was wrong

Replacing a chain of try/catch blocks whose only purpose is to translate one exception into another

Making expected failure visible in signatures, so a reviewer or a model can see which calls need handling

Naming the style across languages when the team’s type is Either, Try or a hand-rolled Result, and you want the two-track shape rather than that library’s idioms

Alongside design-by-contract: contracts push failure to pre-conditions, ROP carries it in the return type — the choice between them is worth making deliberately

❌ "Railway Oriented Programming is an F# library" — it is a composition style; Result is a type, and the style predates and outlives any one package

❌ "Use Result for every error" — Wlaschin wrote a whole post against exactly that; infrastructure failures and programmer bugs are not domain errors

❌ "ROP replaces exceptions" — it replaces exceptions for expected failures only; panics and unrecoverable faults stay outside the two tracks

❌ "The failure track is for error messages" — it carries a modelled type; a string failure track throws away the information the caller needs to branch on

❌ "Bind and applicative are interchangeable" — bind short-circuits, applicative accumulates; validation usually needs the second

✓ "Two tracks, a switch per step, and a modelled failure type at the boundaries" — that is the anchor, and it transfers across languages

Restructuring legacy code where you want named, reversible steps instead of one large rewrite

Immediately after code-smells has identified a symptom and you need the matching treatment

Reviewing a pull request: ask which named refactoring the diff claims to be, and whether behaviour really stayed put

Preparatory work before a feature, to separate the structural commit from the behavioural one

Driving a model: "refactor using Fowler’s catalog and name each refactoring you apply" yields a step sequence you can review, not a rewrite you have to re-read

Alongside mikado-method when the refactoring will not complete in one step, and test-seam when the safety net does not exist yet

❌ "Refactoring means cleaning up the code" — it means a behaviour-preserving transformation; cleanup that changes behaviour is a rewrite with a flattering label

❌ "A big restructuring is a big refactoring" — Fowler calls the long broken build the tell: that is restructuring, not refactoring

❌ "The catalog is the smell list" — the smells are the diagnosis chapter; the catalog is the remedy, and most of the book

❌ "Fowler’s catalog is Repository and Unit of Work" — those are fowler-patterns, a different book

❌ "The names are fixed" — the 2nd edition renamed entries (Extract Method became Extract Function), so a name alone can date a conversation

✓ "Name the refactoring, then run the tests at the step the mechanics say" — the mechanics are the reason the catalog is more than vocabulary

Setting an explicit API design target before implementation — "Level 2, and here is why not Level 3"

Describing an existing HTTP API in one word to another engineer or to a model, instead of listing its URI and verb conventions

Reviewing an API for the specific Level 2 defects: POST used for reads, 200 returned with an error body, verbs encoded in the path

Deciding whether hypermedia is worth its cost for a given client population, with the tradeoff named rather than implied

Reading REST literature, where Level 0 to Level 3 is assumed vocabulary

❌ "Level 3 is the goal for every API" — Richardson’s own talk explains why most teams stop at Level 2, and the cost falls on clients that do not need discoverability

❌ "Level 2 means RESTful" — Roy Fielding’s position is that hypertext is a precondition, not a finishing touch; on that reading Levels 0 to 2 are simply not REST

❌ "Higher level means better API" — the levels rank conformance to REST constraints, not fitness for purpose; an internal RPC-style service can be the right design at Level 0

❌ "RMM is an assessment framework" — Fowler explicitly rejects that use (see Criticism)

✓ "RMM is a vocabulary for naming where an API sits and where you want it" — accurate, and the form in which it is actionable

Decomposing a system into modules, layers, or services with clear boundaries

Reviewing code for tangled responsibilities (e.g. business logic mixed with I/O or presentation)

Justifying architectural seams — why persistence, domain, and UI are kept apart

Teaching why high cohesion and low coupling matter

Prompting an LLM to structure code into well-bounded, independently changeable units

Cohesion Criteria

Unix Philosophy

Single Responsibility Principle

Don’t Repeat Yourself

Clean Architecture

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

Cohesion Criteria - SLAP produces functional cohesion by keeping a function focused on one conceptual step

KISS Principle - SLAP is one concrete technique for keeping functions simple

SOLID SRP - SRP applies at the class level what SLAP applies at the function level

Clean Architecture - Layered abstraction at the architectural scale mirrors SLAP at the code scale

High-level business logic directly instantiates infrastructure classes

Changing a database or framework requires modifying business logic

Unit testing requires running actual external services

SOLID Principles (Umbrella)

Hexagonal Architecture - Architectural application of DIP

Classes implement interface methods they don’t need (empty or throwing)

Changes to an interface affect clients that don’t use the changed methods

Fat interfaces with many methods serving different client groups

SOLID Principles (Umbrella)

Subclass overrides break expected behavior of the base class

instanceof/type checks appear in client code

Inheritance hierarchies violate "is-a" relationships

SOLID Principles (Umbrella)

Adding new features requires modifying existing working code

Frequent changes to a module break other parts of the system

You need a plugin or strategy-based extension mechanism

SOLID Principles (Umbrella)

GoF-Strategy Pattern - Common OCP implementation

Designing maintainable and scalable object-oriented systems

Refactoring legacy code to improve structure

Building systems where flexibility and testability are important

Teaching or enforcing good software design practices

Dan North, "CUPID — for joyful coding" (2022; preceded by his 2017 talk "Why Every Single Element of SOLID is Wrong") — the principles are too vague to guide decisions ("responsibility" is undefined) and optimise for a style of OO design that mainstream practice has moved past; he proposes the CUPID properties as an alternative

John Ousterhout, "A Philosophy of Software Design" (2018) — SRP-driven decomposition produces many shallow classes whose interfaces add more complexity than their implementations hide; he argues for fewer, deeper modules

The principles rest on anecdote and authority rather than empirical evidence — a recurring point in the debate around both critiques

A class has multiple unrelated responsibilities

Changes to one feature require modifying unrelated code

Unit testing requires complex setup due to tangled concerns

SOLID Principles (Umbrella)

Version control systems (Git as SSOT for code)

Database design and data warehousing

Documentation and knowledge management

Configuration management

Master data management (MDM)

Designing data architecture for enterprise systems

Establishing documentation standards and knowledge bases

Building data pipelines and ETL processes

Implementing microservices with clear data ownership

Creating audit trails and ensuring compliance

Resolving conflicts between multiple data sources

Designing CLI tools, scripts, and pipelines meant to compose with others

Deciding whether to extend an existing program or build a separate, focused one

Arguing for plain-text, line-oriented data formats over opaque binary blobs

Reviewing a tool that is accumulating flags and feature creep

Prompting an LLM to produce small, single-purpose, composable Unix-style programs

Separation of Concerns

DRY (Don’t Repeat Yourself)

KISS Principle

Code Smells

Rob Pike and Brian Kernighan, "Program Design in the UNIX Environment" / "cat -v Considered Harmful" (1984) — argue that Unix itself drifted from the philosophy, with utilities like cat accreting flags (-n, -s, -b, -v) that violate "do one thing well"; summarized at Unix philosophy (Wikipedia)

Simson Garfinkel, Daniel Weise, Steven Strassmann (eds.), The UNIX-HATERS Handbook (1994) — a compilation of the UNIX-HATERS mailing list attacking the "worse is better" design culture as a source of obscure flags, cryptic errors, and lost work

Richard P. Gabriel, "The Rise of Worse is Better" (1989, published 1991) — frames the philosophy descriptively rather than as a virtue: simple-but-incomplete designs (C, Unix) outcompeted more correct, elegant ones (Lisp machines), implying the style spreads for market reasons, not because it is right

The philosophy remains the conceptual core of CLI tooling, shells, and pipelines, but sits in tension with modern monolithic GUI/IDE and all-in-one platform tooling, where integration and discoverability are valued over composition of small text-stream tools

Eric S. Raymond’s 17 rules (2003) are the most cited modern codification; training-data priors most plausibly serve the McIlroy summary and Raymond’s rules, while the Pike/Kernighan critique of Unix’s own drift is the documented counter-current

Fighting over-engineering and premature abstraction

Agile projects with iterative delivery and evolving requirements

Refactoring legacy systems burdened with unused features

When tempted to add "just in case" functionality or configurability

DRY - Eliminates duplication of existing knowledge (complementary but distinct)

SPOT - Single Point of Truth, related simplicity principle

TDD, Chicago School - YAGNI is a core principle of classicist TDD

KISS Principle - Keep systems as simple as possible (complementary simplicity principle)

Writing commit messages in any Git repository

Configuring commit.template or linting with commitlint or a .gitmessage hook

Code review: checking whether a commit message gives reviewers and future git bisect users enough context

Instructing an LLM to generate a commit message — naming "50/72 Rule" activates the full convention without repeating each constraint

Plain English (Strunk & White) — the same economy-of-words discipline applied to prose

BLUF — state the conclusion (subject line) first; supporting detail follows in the body

Inverted Pyramid Style — most important information first, supporting context below

Chris Beams' "How to Write a Git Commit Message" is the most widely linked elaboration of Tim Pope’s original post; it adds capitalization, no trailing period, and the "explain why vs. how" distinction as formal rules

Conventional Commits adds a type(scope): prefix that competes directly with the 50-character budget; Thirstybear (2025) argues that this metadata belongs in commit trailers rather than the subject line, and defends the 50-character limit on typographic grounds — citing Swiss designer Emil Ruder’s 50–60 characters per line as the readability optimum

Establishing who may halt work — the naming makes the authority explicit rather than implicit

Red-build discipline and stop-the-line rules around CI, the direct descendant of the idea (red-green-tdd)

Canary and progressive rollouts, where an automatic or manual abort is the andon

Diagnosing a quiet team: if nobody ever stops anything, ask whether the authority exists or only the button does

Designing escalation paths where the responder, not the reporter, owns the problem once the signal is raised

❌ "One worker pulling the cord stops the whole factory" — Graban calls this the myth; buffers between sections absorb a local stop, and the line halts only at the next fixed position

❌ "Andon is a line-stop device" — it is first a call for help; most pulls are resolved before any stop

❌ "Install the cord and you have andon" — without a responder within seconds and a no-blame reaction, the cord is decoration

❌ "Many pulls means the process is bad" — early on it means the process is finally visible

✓ "Andon is jidoka performed by a person" — accurate, and the reason it belongs next to kaizen rather than to tooling

Block: .search-form

Element: .search-forminput, .search-formbutton

Modifier: .search-form—​compact, .search-form__button—​disabled

Large-scale web applications with many components

Team projects requiring consistent (S)CSS naming conventions

When (S)CSS maintainability and scalability are priorities

Projects where developers need to quickly understand (S)CSS structure

Component-based architectures (React, Vue, Angular)

The definition at getbem.com and bem.info is stable and still accurate — BEM itself is a finished methodology

Mainstream practice has shifted: State of CSS 2024 shows Tailwind CSS "far ahead of other, more traditional competitors", and the survey no longer even tracks naming methodologies as it did in 2020; CSS Modules, CSS-in-JS, and native scoping/nesting/cascade layers solve by platform the global-namespace problem BEM solved by convention

Check the module in cleaner than you checked it out. The unit of improvement is the visit, not the project. Every time a file is opened for some other reason, it leaves in slightly better shape than it arrived.

Scoped to what you already touched. The cleanup rides along with work that was going to happen anyway. Code you did not need to open is out of scope — that is the line between the rule and drive-by refactoring.

Small enough to need no permission. Rename an unclear variable, extract a method, delete dead code, fix a stale comment. If it needs a ticket, it is no longer this rule.

Aimed at entropy, not at perfection. The target is the slow decay of a codebase nobody is responsible for, not a standard of cleanliness. Slightly better, repeatedly, beats a rewrite that never comes.

Safe only under test. The rule assumes a green test suite. Without one, "improvement" is an unverified change to code you opened for a different reason.

Fixing a bug in a file nobody has read in years

Codebases with no dedicated refactoring budget, where improvement has to be smuggled into ordinary work

As a shared team norm, so the cleanup is expected rather than defended in review

Where code is generated or changed faster than humans critically review it, and decay would otherwise accumulate unobserved

Reading it as a licence to refactor anything nearby. The rule is bounded by what the task already touched. Unbounded, it produces pull requests whose reviewers cannot find the actual change.

Mixing structural and behavioural change in one commit. The cleanup and the fix should be separable, so that a reviewer can read one without the other and a revert does not take both. Kent Beck’s Tidy First? makes that separation its central rule.

Confusing "cleaner" with "in my style". Reformatting to personal preference adds diff noise and removes no decay.

Applying it without tests. Then it is not tidying, it is an unreviewed change under a virtuous name.

The parable moves the burden of proof onto the remover. G.K. Chesterton, The Thing (1929), chapter "The Drift from Domesticity": "There exists in such a case a certain institution or law; let us say for the sake of simplicity, a fence or gate erected across a road. The more modern type of reformer goes gaily up to it and says, 'I don’t see the use of this; let us clear it away.' To which the more intelligent type of reformer will do well to answer: 'If you don’t see the use of it, I certainly won’t let you clear it away. Go away and think. Then, when you can come back and tell me that you do see the use of it, I may allow you to destroy it.'" Not seeing a reason is a fact about the observer, not about the fence.

The unexplained artifact is evidence, not noise. Chesterton’s supporting argument is the half that travels best into engineering: "The gate or fence did not grow there. It was not set up by somnambulists who built it in their sleep." A hard-coded seven-second retry delay, a feature flag that has been on for two years, a defensive check nobody can justify — each one is a cheap record of a failure that once happened to somebody.

It buys a delay, not a veto — and Chesterton wrote the exit clause himself. Two sentences later in the same essay: "If he knows how it arose, and what purposes it was supposed to serve, he may really be able to say that they were bad purposes, or that they have since become bad purposes, or that they are purposes which are no longer served." A good-faith, timeboxed investigation that turns up nothing earns the removal. Take it out reversibly — behind a flag, in a revertible commit — and watch the signal that would tell you the fence was load-bearing.

It looks backwards, where second-order thinking looks forwards. second-order-thinking asks "and then what?" about a change you are about to make. Chesterton’s Fence asks "and why is this here?" about something already standing. The two compose: recover the reason first, then trace what removing it sets in motion.

The dig is a method, not an attitude. git log and git blame on the line, git log -S on the unexplained string, the ticket or pull request that introduced it, the incident it followed, the on-call runbook and the alert definitions, and the author if they are still reachable. Operational documentation usually explains a strange line of code faster than the code does.

The effort scales with the blast radius. An unused CSS class and a retry delay in a payment flow do not deserve the same archaeology. Let what breaks if you are wrong set the timebox.

Inheriting or modernising a system whose oddities nobody on the current team can explain — the case the principle was made for

Any cleanup list that already contains the words "safe", "obviously unused" or "quick win"

Reviewing a pull request whose diff is mostly deletions

Deprecating an API, a config flag, a cron job or a database column that appears to have no callers

Joining a team and meeting a process that looks pointless from the outside

As a brake on a static analyser — or an LLM — that confidently reports dead code

❌ "Never change anything you don’t understand" — the principle demands an investigation, not permanent preservation. Chesterton explicitly allows destruction once the purpose is known and found wanting.

❌ "The fence stays until someone proves it useless" — that turns the burden into an unfalsifiable one, because nobody can prove the absence of a reason. The test is a serious attempt to find the reason, bounded in time.

❌ "It is an argument for tradition" — in Chesterton’s essay it was one. Applied to a codebase it is an argument about evidence: the artifact is the only surviving witness to a failure whose ticket is long closed.

❌ "Understanding it means reading the code" — the reason is rarely in the code. It is in the incident, the contract, the regulator’s letter, the vendor who used to time out.

✓ "It is a stopping rule for confident deletion" — fair, and that is what makes it usable rather than merely wise.

A specification for adding human and machine readable meaning to commit messages

Determining a semantic version bump (based on the types of commits landed)

Communicating the nature of changes to teammates, the public, and other stakeholders

feat: - introduce new feature to the codebase (→ Semver Minor)

fix: - patches a bug in your codebase (→ SemVer Patch)

docs: - documentation improvements to the codebase

chore: - codebase/repository housekeeping changes

style: - formatting changes that do not affect the meaning of the code

refactor: - implementation changes that do not affect the meaning of the code

! - BREAKING CHANGE (→ SemVer Major)

BREAKING CHANGE: introduces a breaking API change

everything-as-code paradigm targeted

team-/community-communication

repository quality improvements

Establishing a consistent quality standard across a Scrum or agile team

Onboarding new team members so they understand what "finished" means

Reducing rework and late-cycle defects by agreeing on criteria upfront

Aligning developers, QA, and product owners on release readiness

BDD (Behavior-Driven Development) - Given-When-Then scenarios that operationalize acceptance criteria

User Story Mapping - Planning technique that identifies the scope Definition of Done must cover

MoSCoW - Prioritization method used to decide which DoD items are must-haves

Onboarding new Go developers to idiomatic Go style

Code review discussions about Go conventions

Establishing team-wide Go coding standards

Explaining Go idioms that differ from other languages (e.g. error handling, interfaces)

Prompting an LLM to produce idiomatic, production-quality Go code

Dated by its own admission — 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 (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 Go Code Review Comments (self-described "supplement to Effective Go") and Google’s maintained Go Style series (Guide, Decisions, Best Practices)

Onboarding Java developers to idiomatic, robust API and class design

Code review discussions grounded in a shared, citable rule set ("Item 17: minimize mutability")

Establishing team-wide Java coding standards and design conventions

Explaining Java-specific contracts (equals/hashCode, generics, PECS) and their pitfalls

Prompting an LLM to produce idiomatic, robust Java code

Effective Go

Builder Pattern

SOLID Principles

The 3rd edition (Addison-Wesley, published December 2017, commonly cited as 2018) is the current edition. It added items for Java 7-9 features — lambdas, streams, the java.time package, and try-with-resources

Because it predates Java’s six-month release cadence, some Item advice now has newer language alternatives: records (Java 16) replace much hand-written immutable-class and Builder boilerplate; sealed classes (Java 17) and pattern matching for switch (Java 21) supersede some inheritance and instanceof guidance; virtual threads (Java 21) change the "prefer executors to threads" calculus

The book’s design principles (favour immutability, composition over inheritance, the object contracts, PECS) remain valid; only the mechanics for some Items have shifted. A training-data prior keyed on "Effective Java" most plausibly reflects the 3rd edition and is therefore silent on records, sealed classes, and virtual threads

Onboarding Python developers to idiomatic, robust ("Pythonic") code

Code review discussions grounded in a shared, citable rule set ("Item 30: consider generators instead of returning lists")

Establishing team-wide Python coding standards and conventions

Explaining Python-specific idioms and pitfalls (comprehensions, generators, the GIL, @property, keyword-only arguments)

Prompting an LLM to produce idiomatic, production-quality Python code

Effective Java

Effective Go