Pattern Authoring

How a pattern in this handbook is written, and how the pattern library coheres as a whole — the single source of truth for pattern anatomy, classification, cross-linking, and evolution.

Status: Approved Type: Organizational (Required*)

*Required whenever you author or edit a pattern in this handbook.

Problem

Patterns need one authoritative definition of how they are written and how they fit together. Without it, the library drifts:

• Duplicate definitions — one concept defined in two patterns that silently contradict each other when one changes.
• Stale examples — a pattern keeps an example of a structure a later revision removed.
• History leaks in — "why we changed X" prose accumulates where only the current state belongs.
• Dangling cross-references and divergent front-matter — the docs portal renders inconsistently.

This pattern defines that structure and the rules that keep the set coherent.

Context

When to Use This Pattern

• Authoring a new pattern under patterns/organizational/ or patterns/technical/.
• Editing an existing pattern, including the reconciliation sweep an edit triggers.
• Reviewing a pattern pull request.
• Classifying a pattern (organizational vs technical; required vs recommended; maturity).
• Resolving a contradiction or overlap between two patterns.
• Writing or maintaining a repo-local pattern in .context/patterns/ — these principles apply; only the lightweight format is defined by Repository Context Directory.

When NOT to Use This Pattern

• Principles — durable values in principles/, not solutions; they have their own voice.
• Templates — the seed files in templates/.

Audience & Scope

This pattern is for contributors — human and AI — who work on this handbook. Its boundary with Repository Context Directory is deliberate and worth stating, because both are "how we capture knowledge":

Every pattern MUST state its own audience and scope the same way, so neighbouring patterns have a clear, non-overlapping boundary.

Solution

A pattern is one file with a fixed anatomy. The library is two layers, single-sourced and cross-linked.

The Two Layers

Principles (durable values)        principles/   — why we work this way; change in years
   ↓ applied by
Patterns (concrete solutions)      patterns/     — what & how; evolve in months, edited in place

A pattern names the principles it applies (its Applies Principles section) and otherwise stands on its own. It always describes the current approved practice — nothing more. Earlier states are not kept in the file; git history is the archive. Patterns evolve by being edited in place (see Evolution & Coherence).

Single Source of Truth

Every concept has exactly one authoritative pattern. Other patterns that touch it cross-reference the canonical one; they never redefine or restate it. When you find a concept defined in two places, that is a bug to reconcile (see Evolution & Coherence), not a style choice.

Reference, Don't Duplicate

Link to the canonical pattern or principle instead of copying its content. A copy is a second source of truth that will drift. This mirrors the same rule AGENTS.md applies across the org.

Anatomy of a Pattern

A pattern file has four parts, in this order: front-matter, header block, the body in canonical section order, and cross-links.

Front-matter

YAML front-matter drives docs-portal rendering. Keep it consistent with neighbouring patterns.

Header Block

Immediately under the H1 and the one-line description, a blockquote states the pattern's standing:

> **Status**: Approved
> **Type**: Organizational (Required-if-applicable)

Status MUST match the front-matter badges value. Type is Organizational | Technical plus the requirement level. When the level is conditional, mark it Required\* and add a > \*… footnote line stating the condition.

Canonical Section Order

# <Title>
<one-line description>

> **Status** / **Type** header block

## Problem            (required)  — the recurring pain, concretely
## Context            (required)  — When to Use / When NOT to Use / Audience & Scope
## Solution           (required)  — the approach in prose
## Structure          (optional)  — directory/layout/schema, when the pattern prescribes one
## <Domain sections>  (optional)  — pattern-specific detail, between Solution and Consequences
## Implementation     (recommended) — concrete steps or a checklist
## Consequences       (required)  — a ✅ / ⚠️ trade-off table
## Applies Principles (required)  — which principles/engineering.md values this embodies
## Examples           (optional)  — real usage from Ontopix repositories
## Variations         (optional)  — alternative contexts or approaches, when they exist
## Related Patterns   (required)  — complementary patterns, relative links
## References         (required)  — the README §Principles vs Patterns, related material, external sources

Insert domain-specific sections (numbered or named) between Solution and Consequences — that is where larger patterns like Service Structure carry their detail. The anchor sections above stay in this order so any reader, human or agent, navigates every pattern the same way.

Examples Are Part of the Contract

Every example MUST reflect the current canonical structure. An example that shows a layer a later revision removed is a defect, not stale documentation — fix it in the same change that revises the structure. Examples are real (drawn from Ontopix repositories where possible), never aspirational.

Normative Language

State requirements with MUST / SHOULD / MAY (and their negatives), in the RFC 2119 sense, so obligations are unambiguous. Reserve them for genuine requirements; non-normative prose stays plain.

Classification

Three orthogonal axes classify a pattern.

Category — which directory it lives in:

• organizational/ — how we organize work; applies across repositories (structure, conventions, governance).
• technical/ — how we solve a specific technical problem (a deploy strategy, a test layout).

Requirement level — the Type header and the index Status:

• Required — every repository must comply.
• Required-if-applicable — required only when a condition holds (e.g. backend services, repos invoking Bedrock). Marked Required\* with a footnote naming the condition.
• Recommended — apply with judgement.

Maturity — the badges value and Status, on a ladder:

Emerging  →  Approved  →  Production
(proposed, validating) (accepted standard) (battle-tested, broadly adopted)

When to Create a Pattern

Create a pattern when the same problem has been solved 3+ times across different projects, or when an organizational standard must be set deliberately. Not for one-off solutions, project-specific implementations, unproven experiments, or problems with an obvious answer.

Cross-Linking & Registration

• Relative links, always with the .md extension (./service-structure.md, ../../principles/engineering.md). This is unambiguous for both the docs portal and direct file navigation.
• Related Patterns lists the complementary patterns a reader will want next, with a short note on the relationship.
• Register every pattern in patterns/README.md — the index is the catalog. An on-disk pattern missing from the index is invisible; an index row pointing at a moved file is a dangling reference. Keep both ends in sync, including the Status column and any Required\* footnote.

Evolution & Coherence

Patterns are living documents. They evolve by being edited in place. A pattern carries no version of its own — git versions it. Only the current definition is authoritative; every earlier state lives in git history, not in the file.

• No version suffixes, no archive copies. Never create pattern-name-v2.md, a deprecated/ copy, or an archive/ folder. Edit the file. Delete superseded content — git history is the archive.
• An edit triggers a reconciliation sweep. When you change a pattern, find and reconcile every contradiction the change creates across the whole library: overlapping definitions (the same concept now described in two places), stale examples, dangling cross-references, and divergent front-matter or classification. A change is not done until the set is coherent again.
• Keep it current-state-only. A pattern describes what is now, not why it used to be different. Prior states live in git history, not in the file.
• Surface discrepancies; don't diverge silently. If your work contradicts a pattern, follow the Pattern Discrepancy Rule: propose Path A (evolve the pattern, with justification) or Path B (a documented, approved exception).
• Escalate org-wide changes. Editing this handbook changes the standard for every Ontopix repository. Per the AGENTS.md escalation rules, changing or removing a pattern requires human review before merge.

Implementation

Authoring a new pattern

1. Confirm it qualifies — the 3+-times threshold, or a deliberate organizational mandate.
2. Choose the category (organizational/ or technical/) and a kebab-case slug matching the title.
3. Write the file using the canonical anatomy; make every example reflect current practice.
4. Add a Related Patterns section and register the pattern in patterns/README.md.
5. Branch docs/* (Git Conventions), use Conventional Commits, open a PR, and escalate for review.

Editing an existing pattern

1. Edit the file in place — never fork a -v2.
2. Update every affected example so it matches the revised structure.
3. Run the reconciliation sweep: resolve every contradiction, stale example, and dangling link the change introduces.
4. Keep the pattern current-state-only — prior states live in git history.
5. If an org standard changed, escalate for human review.

Consequences

Applies Principles

• Code Quality & Maintainability — single source of truth and reference-don't-duplicate are DRY for documentation.
• Simplicity First — one home per concept; concise prose, no preamble or filler.
• Long-Term Thinking — a coherent, evolvable library compounds in value; git history is its durable archive.
• Human-AI Collaboration — a uniform, machine-parseable structure serves human readers and AI agents equally.
• Evidence Over Assumptions — the 3+-times bar and real examples keep patterns grounded, not aspirational.
• Continuous Learning & Improvement — patterns evolve in place and are reconciled as understanding improves.

Related Patterns

• Repository Context Directory — the repo-local tier of the pattern system; defines the .context/patterns/ format these principles apply to.
• AI Agent Entrypoint — the Pattern Discrepancy Rule and escalation rules that govern proposing, reviewing, and evolving patterns.

References

• Principles vs Patterns — the layer model in the main README.
• Core Engineering Principles — the values patterns apply.