Design Pattern Documentation¶

Documented pattern — instantiates Emergent Formalization

Names a recurring solution form and records the context, forces, and consequences that tell you when to reach for it — and when not to.

Design Pattern Documentation captures a solution shape that keeps reappearing — not a procedure to run, but a reusable form with a name, the recurring problem it answers, the competing forces it balances, and the consequences of applying it. Its defining move is that it formalizes applicability judgment rather than steps: the deliverable is the reader's ability to recognize "this is one of those situations" and to know the trade-off they are buying. What makes it THIS mechanism is the insistence that a pattern must have genuinely recurred before it is written, and must carry its non-examples — where it does not apply — as first-class content.

Example¶

A platform team notices the same shape solving the same problem in four different services: every time a call to a flaky downstream dependency fails, engineers independently write "retry, but wait longer each time, and give up after N tries." Design Pattern Documentation turns that convergence into a named pattern — Exponential Backoff with Jitter — written not as code but in the classic pattern form: the context (calls over an unreliable network), the forces it balances (recover from transient failures vs. avoid hammering a struggling service vs. avoid synchronized retry storms), the structure of the solution, its consequences (added latency, the need for idempotent operations), and pointed non-examples (do not use it for a permanent error — retrying a malformed request is just noise). Because the shape had already appeared independently several times, the team knows it is a real pattern and not one clever person's preference; the write-up is dated and owned so it can be revised or flagged an anti-pattern later. Now the fifth team reaches for a named, understood tool instead of reinventing it — and knows the one case where it backfires.

How it works¶

Its distinguishing machinery is evidence-gated and forces-centered. The discipline is the rule of three: a solution is documented as a pattern only after it has recurred in several independent, real cases, which is what separates a pattern from a proposal.^[1] The write-up leads with forces — the tensions that make the pattern the right call — because those, not the code, are the transferable judgment. It scopes itself with explicit non-examples, and it lives in a catalog that can deprecate a pattern or reclassify it as an anti-pattern when the context that justified it passes.

Tuning parameters¶

Recurrence bar — how many independent uses before something is "a pattern." A high bar (rule of three or more) keeps the catalog trustworthy; a low bar fills it with speculative patterns nobody follows.
Forces depth — how fully the competing tensions are drawn out. Rich forces make the applicability judgment transferable; thin ones reduce the pattern to a recipe misapplied everywhere.
Non-example weight — how much attention goes to where the pattern fails. Heavier non-examples prevent over-application, the pattern catalog's chief failure.
Abstraction level — a narrow, concrete pattern vs. a broad, general one. General patterns cover more but drift toward truism; specific ones are actionable but proliferate.
Catalog freshness — how aggressively stale patterns are deprecated or flagged as anti-patterns as practice moves on.

When it helps, and when it misleads¶

Its strength is that it gives a community a shared vocabulary for solution shapes, transfers hard-won applicability judgment, and prevents constant reinvention. A well-drawn pattern is teachable and inspectable in a way scattered folklore is not.

Its failure mode is that a documented pattern invites over-application — people wield it as a hammer and see every problem as its nail, applying it where the forces do not actually hold. Patterns also fossilize: a form that was right for its era gets cargo-culted long after the constraint that motivated it is gone. The classic misuse is dressing up a personal preference as an established pattern by writing it up before it has really recurred. The discipline that guards against this is to gate on genuine recurrence, foreground the forces and non-examples over the structure, and keep a live path to deprecate patterns that have curdled into anti-patterns.

How it implements the components¶

Design Pattern Documentation realizes the recognize-and-scope side of the archetype — the components that establish a form is real and bound where it fits:

stabilization_evidence — the rule-of-three gate: a shape is documented only after it has independently recurred enough to count as a real pattern.
tacit_context_capture — the forces and consequences sections capture the applicability judgment that tells a reader when the pattern fits.
scope_boundary — explicit context and non-examples state where the pattern applies and, pointedly, where it does not.
revision_and_sunset_loop — the catalog can revise, deprecate, or reclassify a pattern as an anti-pattern when its context passes.

It does not roll the pattern into an executed procedure or enforce its use — that is Standard Operating Procedure and Style Guide Creation — nor does it establish that the shape is *good, only that it recurs; the usefulness judgment belongs to Governance Rule Creation.*

Instantiates: Emergent Formalization — codifies a recurring solution form as a named, catalogued pattern.
Sibling mechanisms: Playbook Creation · Protocol Standardization from Usage · Standard Operating Procedure · Apprenticeship-to-Protocol Capture · Checklist Conversion · Community Norm Codification · Governance Rule Creation · Legal Custom Formalization · Style Guide Creation

Notes¶

A design pattern is descriptive, not prescriptive: it says "here is a shape and when it fits," it does not tell you to do it. That distinguishes it from a Playbook Creation (a situational guide to action) and a Standard Operating Procedure (a fixed procedure to follow). Losing that stance — treating a pattern as a mandate — is how catalogs turn into cargo cults.

References¶

[1] The rule of three is a common heuristic in the software patterns community: a solution is written up as a "pattern" only after it has appeared in at least three independent real systems. The pattern form itself — context, forces, consequences — descends from Christopher Alexander's A Pattern Language in architecture. ↩