content-patterns · diff
git:20260605.b66fd15 to git:20261007.d097047
13 added, 15 removed. Audit A to A.
---
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.
+ Patterns for writing openEHR specification prose (package overviews, class/concept semantics,
+ design rationale, clinical examples, requirements sections, deprecated/TBD markers, and figure
+ introductions) in `specifications-XX` repos. This skill should be used when the user asks how to
+ phrase, draft, or improve spec prose, or about openEHR spec writing style. Not for document
+ structure (use authoring), convention checks (use review), amendment records (use
+ amendment-record), ITS-REST descriptions (use its-rest), 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.
+ Apply these recurring prose patterns when writing new chapters or sections, to match the quality
+ and consistency of the existing specification library. They are derived from the openEHR
+ specification documents in the `specifications-XX` repositories (RM, AM, BASE, LANG, PROC, SM,
+ QUERY, CNF, TERM, ITS-*) and the shared infrastructure in `specifications-AA_GLOBAL`.
## 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.
+ - **Ground every claim**: reference RM classes, archetype paths, or external standards. Never invent identifiers; after drafting, dispatch the `identifier-grounding` subagent to verify each class, attribute, and function name against the published specifications.
- **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 |
+ | Inventing class or attribute names | Reference only names found in the published RM/AM/BASE (see "Ground every claim" above) |
+ | Explaining every attribute of a class in prose | Class definition tables are generated (see `class-generation`); 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 |