content-patterns git:20260605.b66fd15A

Immutable. This exact content never changes and is served at /api/v1/blob/fe3ff33085b6a58d.

---
name: content-patterns
description: >
  Patterns for writing production-quality openEHR specification prose — overviews, class/concept
  semantics, design rationale, and clinical examples — in `specifications-XX` repos. This skill
  should be used when the user asks how to phrase or improve spec prose, draft a package/class
  description, write a design-rationale or semantics section, or asks about openEHR spec writing
  style. Not for creating or scaffolding the document or its structure (use authoring), amendment
  records (use amendment-record), or non-openEHR writing.
---

# openEHR Specification Content Patterns

This skill captures the recurring prose patterns found across all openEHR specification
documents in the `specifications-XX` repositories (RM, AM, BASE, LANG, PROC, SM, QUERY,
CNF, TERM, ITS-*), derived from the existing library and its shared infrastructure in
`specifications-AA_GLOBAL`. Apply them when writing new chapters or sections to match the
quality and consistency of the existing specification library. They do not apply to
non-openEHR specifications or general technical documentation.

## References

- **Prose pattern catalog**: see `references/prose-patterns.md` for the full structure,
  AsciiDoc template, real example, and conventions for each pattern indexed below.
- **Cross-reference attribute guide**: see `../authoring/references/cross-references.md` for
  how to find and use `{openehr_*}` attributes when writing cross-references in spec prose.

## General Principles

- **Formal register**: third person, present tense, no contractions, no hedging.
- **Declarative facts first**: lead with what the model defines, not how the reader should interpret it.
- **Design rationale where non-obvious**: explain why, not just what.
- **Ground every claim**: reference RM classes, archetype paths, or external standards. Never invent identifiers.
- **Clinical examples**: use concrete clinical scenarios to illustrate abstract model concepts.

## Pattern Catalog

Pick the pattern that matches the section being written and read its detailed entry in
**`references/prose-patterns.md`**.

| # | Pattern | Use when writing… |
|---|---------|-------------------|
| 1 | Package/Chapter Overview | the opening of a chapter that describes a model package (opening paragraph → UML diagram → package/class enumeration) |
| 2 | Class/Concept Semantics | the prose for a class or major concept (purpose, typing, identification, structure, lifecycle, relationships) |
| 3 | Design Rationale | an explanation of *why* a non-obvious design choice was made (problem/requirement → chosen design → rejected alternatives) |
| 4 | Clinical/Practical Examples | a concrete clinical scenario that grounds an abstract model concept |
| 5 | Requirements Sections | an explicit numbered-requirements section preceding a design (common in Data Types, EHR IM) |
| 6 | Deprecated and TBD Markers | `[.deprecated]` or `[.tbd]` annotations for legacy or pending content |
| 7 | Figures and Diagrams in Context | any diagram — always introduced by text and followed by explanation |

## Anti-Patterns to Avoid

| Anti-Pattern | Correct Approach |
|-------------|-----------------|
| "This section describes..." | State what the package/class defines directly |
| "We decided to..." | "The design uses..." / "The approach taken is..." |
| Passive hedging ("it might be...") | Declarative statements ("it is..." / "this enables...") |
| Inventing class or attribute names | Only reference names from the published RM/AM/BASE |
| Explaining every attribute of a class in prose | Class definition tables are auto-generated; prose covers semantics and rationale |
| Orphan figures (no intro or follow-up text) | Always introduce and explain diagrams |
| Hardcoded URLs | Use `{openehr_*}` attributes from reference_definitions.adoc |