Schema version 1.0. This version number changes only when a dimension is
added, removed, or its required shape changes, and tools/check-structure.py
is updated to match in the same commit.
Every pattern entry in this repository carries all 18 dimensions below. An entry
missing a dimension is not finished. This is the single difference between a
master reference and a getting started overview, and it is enforced by
tools/check-structure.py in CI.
- Original prose only. Never copy or closely paraphrase a source. Read the source, understand the pattern, write the explanation yourself. If a sentence could be diffed against a source and match, rewrite it.
- Every factual claim carries a citation. Book claims cite author, title, edition, and page or chapter. Web claims cite the full URL plus the date the page was verified. No citation means the claim does not ship.
- ASCII diagrams live inside fenced code blocks only. Never in prose.
- No em dashes, no en dashes, no decorative colons. Periods and commas.
- Real production usage must name a real system, with a source. "Used in many web frameworks" is not acceptable. "Used by the Java Servlet filter chain, see the Jakarta Servlet 6.0 specification section 6.2" is.
- Trade-off tables compare against named alternatives, never against a generic "the naive approach".
---
name: Chain of Responsibility
slug: chain-of-responsibility
id: pat.01.chain-of-responsibility
kind: pattern
family: 01-design-patterns-gof
category: Behavioral
aliases: [Chain of Command, Responsibility Chain]
first_described: "Gamma, Helm, Johnson, Vlissides 1994"
maturity: canonical
related: [command, composite, decorator, mediator]
related_concepts: []
incompatible_with: []
incompatible_concepts: []
verified: 2026-08-02
last_reviewed: 2026-08-02
next_review_due: 2027-01-29
---maturity is one of canonical, established, emerging, contested,
deprecated. Emerging and contested entries must say plainly in the body what
is not yet settled.
id is pat.<family number>.<slug>. The family number is the two digits that
start the directory name. kind is pattern, smell, technique,
principle, law, or anti-pattern. Family 02 is smell, family 03 is
technique, family 04 is principle except the named laws (ACID, BASE, CAP,
PACELC, Conway, Postel, Demeter), family 18 is anti-pattern, and every other
family is pattern.
related and incompatible_with name published entries. Use the bare slug
when it is unique, and family/slug when the same slug exists in two
families. A name that is not a published entry goes in related_concepts or
incompatible_concepts. Those two lists are notes, not links.
tools/check-links.py rejects a ref that does not resolve, and it rejects a
concept that does resolve.
verified, last_reviewed, and next_review_due are YYYY-MM-DD.
last_reviewed starts equal to verified. next_review_due is 180 days
later until a reviewer sets a new date. A boolean true in verified is not a
date and does not pass.
Canonical name. Every alias in real use. Who first described it, in which publication, in which year, with the citation. If the name is contested or the pattern is known by a different name in another community, say so here.
The concrete situation that creates the need. Written so a reader who has never heard the pattern name can recognise the problem in their own codebase. State the context in which the problem arises, because a pattern outside its context is an anti-pattern.
The competing pressures the pattern balances. At minimum consider latency, coupling, consistency, operability, cost, team topology, and cognitive load. Say which forces the pattern favours and which it sacrifices. A pattern that sacrifices nothing is described wrongly.
Two lists. When to reach for it. When NOT to, with the reason. The second list is the more valuable one and is the one most catalogs omit.
Participants with their responsibilities, and the relationships between them. Name each participant with the role it plays, not with a generic class name.
Inside a fenced code block. Boxes and arrows showing the participants and their relationships. Must be readable in a plain terminal at 80 columns.
How the participants interact at runtime. A sequence flow, a state transition, or an event flow, whichever fits. Also inside a fenced code block when drawn.
The real ways this pattern is built in practice, with the trade-off of each. Include the language-idiomatic variants where a language changes the shape, for example a closure replacing a Strategy class.
Named systems, libraries, frameworks, or standards, each with a source. At least two. This is the dimension that proves the pattern is real and not academic.
Positive and negative, as two explicit lists. Every pattern has a cost. Name it.
How this pattern breaks in production, and how people misuse it. Include the symptom a reader would actually observe, not the abstract mistake alone.
A table comparing this pattern against its named alternatives across the forces from dimension 3. The alternatives must be named patterns, not strawmen.
Which patterns compose with this one, which ones replace it, and which ones actively conflict with it. Explain the relationship, never a bare list of names.
How to introduce this pattern into code that does not have it, step by step. And how to remove it when it stops earning its place. Cross reference the refactoring family where a named refactoring applies.
How to test code that uses this pattern. What is easy to test because of it, and what became harder. Name the test doubles or techniques that apply.
What to log, trace, or measure so this pattern is visible in production. What a healthy instance looks like on a dashboard, and what a failing one looks like.
The attack surface the pattern opens or closes. Data handling implications. Where it is silent, say so plainly rather than inventing a concern.
Every source used, with author, title, edition or version, page or section, URL where one exists, and the date the URL was verified. Sources must be independently checkable by a reader.
An author may close dimension 18 with a short, honest confidence tag on the
entry's own sourcing, distinct from maturity in the frontmatter. maturity
grades how settled the PATTERN is in industry. This addendum grades how solid
the SOURCING behind this particular entry is, which can diverge, a contested
pattern can still be sourced with high confidence, and a canonical one can
still lean on a thin citation somewhere.
**Evidence grade.** high | medium | low | mixed | unknown
**Most solid findings.** One to three bullets naming the claims this entry is
most confident in and why.
**Unverified or unclear.** What still needs a closer source before it should
be treated as settled fact, named plainly rather than smoothed over.Optional, new-only. Existing entries are not retroactively required to carry
it, and tools/check-structure.py does not enforce it, the same new-only
posture as the advisory duplicate check. Adopted from the evidence_grade and
evidence_snapshot convention in nibzard/awesome-agentic-patterns'
TEMPLATE.md, adapted here as a documented addendum inside dimension 18
rather than a frontmatter-only tag, since our dimension 18 already carries the
per-source detail this confidence judgement sits beside.
Every entry carries working code in at least three languages from this set. TypeScript, Python, Java, Go, Rust, C#, Swift, Kotlin. Choose the languages where the pattern is genuinely idiomatic, and say why a language is omitted when the pattern does not translate.
Code is original, minimal, and runnable. No framework scaffolding. No comment longer than two lines, per the repository comment policy.
An entry is sent back when any of these is true.
- A dimension is missing or is a single filler sentence.
- A claim has no citation, or a citation does not resolve.
- Production usage is unnamed or unsourced.
- The trade-off table compares against a strawman.
- The prose reads as a paraphrase of a single source.
- The ASCII diagram sits outside a fenced code block.
- The entry omits the non-applicability list.
Every entry in this repository is authored at full depth. All eighteen dimensions, every entry, no exceptions and no lighter class of entry.
A tiered model was considered and rejected by the repository owner. The trade was roughly 200 deep entries plus 700 lighter ones against 900 deep entries. The owner chose 900 deep entries with the cost visible. This note exists so the decision is not silently re-litigated later by a contributor who finds the authoring effort large.
Not every sentence in an entry can carry a citation, and pretending otherwise produces fake citations. The rule is honest labelling, not universal sourcing.
Must be sourced. Anything a reader could check and find wrong.
- Who named the pattern, when, and in which publication.
- Any statement about what a named library, language, or specification does.
- Any named production use.
- Any claim about a language feature, a memory model, or an API contract.
- Any historical or attribution claim, including "X called this an anti-pattern".
May be engineering judgement. State it as reasoning, never dress it as fact.
- Dimension 3, forces, where you weigh which pressure dominates.
- Dimension 10, consequences, where the cost is a matter of degree.
- Dimension 11, failure modes, where the symptom is drawn from experience.
- Dimension 15, testing, and dimension 16, observability, which are practice.
- Dimension 17, security, where the implication is analytical.
An entry that presents judgement as a sourced fact is worse than an entry with fewer citations. When a dimension is largely judgement, say so in one line at the top of that dimension so the reader can weigh it accordingly.
Compile or run every sample you can, and state plainly which you could not.
| Language | Availability |
|---|---|
| Python | python3, present |
| Go | go, present |
| TypeScript | via npx tsc, present |
| JavaScript | node, present |
| Swift | swiftc, present |
| Java | javac, being installed, check before assuming |
| Rust | rustc, being installed, check before assuming |
| C#, Kotlin | not installed, hand-check and say so |
A sample you could not compile is still acceptable. Silently implying you did compile it is not.