Authoring guide

The pattern card

Every pattern in the library uses these nine sections in this order. Keeping the shape fixed lets readers compare patterns quickly and lets new cards be added without design work. Two finished examples: Fast/Slow Escalation and Evaluator–Optimizer.

Header

Number, name, also-known-as, one-line intent, family, maturity and DoF axes.

Intent ≤ 20 words. Say what the pattern does, not why it’s good. Pick 1–3 axes it changes most.

Problem

The recurring situation and the forces pulling in different directions.

One short paragraph plus 3–4 forces. A force is a tension, like cost vs. accuracy. If there’s no tension, it’s not a pattern.

Solution

How the pattern resolves the forces.

One paragraph. Name the roles and the decision points. Leave framework code for the worked example.

Diagram

The mechanism as boxes and arrows.

4–7 nodes. Highlight the pattern’s signature element (the gate, the loop, the handoff). Caption it with one fact about real behavior.

When to use

Conditions where it fits, and where it doesn't.

3–4 bullets each. Write conditions a reader can check against their own system.

Trade-offs

Four 1–5 meters, plus gains and costs.

Same four meters on every card: latency, cost, complexity, reliability. This makes cards comparable side by side.

Worked example

A concrete scenario traced step by step.

4–6 steps with named actors. Use real-looking values (amounts, scores, timings). End with what the logs teach you.

Failure modes

What goes wrong in production and how to guard against it.

3–4 rows: failure, symptom, mitigation.

Related patterns

How this pattern connects to others.

3–5 links, each typed: alternative, combines with, specializes, next step.

File

Adding a pattern

Each pattern is one Markdown file in the _patterns/ folder of the site repo. The file name becomes the URL, so _patterns/draft-verify.md is published at /agentic/patterns/draft-verify/. Change status: stub to status: full once every section is filled in.

---
title: Pattern Name
n: 49                     # catalog number, unique
family: core              # Agentic systems: core | multi | context | safety | runtime | eval | fastslow
                          # Coding agents:   setup | buildloop | review
maturity: emg             # est | emg | hor
axes: [decision]          # decision | tool | context | verification | coordination
intent: One line, 20 words max.
aka: Other names, comma separated
status: full              # stub until every section is written

problem: >-
  The recurring situation, in one short paragraph.
forces:
  - Tension one, like latency vs. accuracy.
  - Tension two.
  - Tension three.

solution: >-
  How the pattern resolves the forces. Name the roles and decision points.

diagram: pattern-name     # _includes/patterns/diagrams/pattern-name.svg
diagram_caption: One fact about how it behaves in practice.

use_when:
  - A condition the reader can check.
avoid_when:
  - A condition where it does not fit.

tradeoffs:                # 1-5; same four on every card
  latency:     { score: 3, note: "…" }
  cost:        { score: 3, note: "…" }
  complexity:  { score: 3, note: "…" }
  reliability: { score: 3, note: "…" }
gains:
  - …
costs:
  - …

example:
  scenario: The concrete situation.
  steps:
    - who: User
      what: "What happens, with real values. `inline code` works."

failures:
  - failure: Name
    symptom: What you see
    fix: How to guard against it

related:                  # pattern = another file name, without .md
  - { type: Combines with, pattern: reflection }
---