Archetype authoring

Archetype Authoring

Conflict Resolution

When guides conflict, apply this priority (highest first):

1. Rules and structural constraints
2. Syntax specifications
3. Anti-patterns
4. Principles and examples
5. Convenience

Step 1: Load Guides (MANDATORY)

Before any archetype work, load the authoritative guides:

guide_get("archetypes/principles")
guide_get("archetypes/rules")
guide_get("archetypes/adl-syntax")

Load additional guides as needed:

• guide_get("archetypes/structural-constraints") — for cardinality, occurrences, existence rules
• guide_get("archetypes/terminology") — for terminology binding patterns
• guide_get("archetypes/anti-patterns") — to avoid common mistakes
• guide_get("archetypes/formatting") — for ADL formatting conventions

Step 2: Research Before Creating

Before creating a new archetype, ALWAYS search CKM first:

ckm_archetype_search("<concept>")

Reuse-first principle: If a suitable archetype exists, use it. Only create new archetypes when no existing archetype covers the concept. If a close match exists, consider specialization instead.

For deep reuse surveys (unfamiliar domain, or the first few hits look marginal), dispatch the ckm-scout agent instead of running searches inline. It runs 3 parallel phrasings, ranks candidates, and returns a reuse/specialize/new recommendation — keeping CKM search noise out of this skill's context.

Consult gold-standard reference archetypes (when applicable)

For a small set of well-curated CKM archetypes — blood pressure, medication order, problem/diagnosis, encounter, procedure, anatomical location (CLUSTER), translation requirements (ADMIN_ENTRY) — try examples_search(kind="archetypes") when authoring or reviewing an archetype of the same type. These are native .adl files exposed as openehr://examples/archetypes/{name} and serve as concrete prior-art references for RM-type intent, terminology binding patterns, and structural idioms. Skip this step when the concept is outside the curated set.

Import a CKM archetype for reuse

When reuse means pulling a published archetype into the workspace (not just citing it), make it land as a wired-in file rather than a copy-paste note:

1. Fetch the native ADL with ckm_archetype_get("<id>").
2. Write it into the project (e.g. a local/ directory) under its canonical openEHR-EHR-<TYPE>.<concept>.v<N>.adl filename.
3. If it fills a slot in a target archetype/template, add the constrained slot reference (allow_archetype … include) so the reuse is actually wired in.

A reused file keeps its published uid/checksums; do not alter them.

Step 3: Concept Design

One Concept Per Archetype

Each archetype represents exactly one clinical concept. When multiple independent ideas appear, split into separate archetypes connected via slots.

RM Entry Type Selection

Choose the correct Reference Model entry type:

RM Type	Purpose	Examples
OBSERVATION	Measured/observed data	Blood pressure, body weight, lab result
EVALUATION	Assessed/interpreted data	Diagnosis, risk assessment, problem
INSTRUCTION	Orders/requests	Medication order, procedure request
ACTION	Activities performed	Medication administration, procedure
ADMIN_ENTRY	Administrative data	Admission, discharge, transfer
CLUSTER	Reusable data groups	Address, anatomical location, device

Use type_specification_get to verify RM type structure when uncertain.

Identifier Scheme

Follow the pattern: openEHR-EHR-<RM_TYPE>.<concept>.v<VERSION>

Examples:

• openEHR-EHR-OBSERVATION.blood_pressure.v2
• openEHR-EHR-CLUSTER.anatomical_location.v1

Step 4: ADL Authoring

Constraint Patterns

Use guide_adl_idiom_lookup for specific ADL constraint patterns:

• Coded text constraints
• Quantity ranges with units
• Ordinal / rating scales — DV_ORDINAL for integer-only steps; DV_SCALE (RM ≥ 1.1.0) for non-integer steps (e.g. Borg CR10 0.5). See the DV_SCALE vs DV_ORDINAL idiom.
• Date/time constraints
• Slot definitions

Terminology Section

• Define all at-codes with clear, descriptive text
• Bind to standard terminologies (SNOMED CT, LOINC, ICD-10) where appropriate
• Use terminology_resolve to verify terminology codes
• Ensure semantic equivalence, not approximation, in bindings

Design for Reuse

• Keep archetypes terminology-neutral (avoid hardcoding specific value sets)
• Use explicit slot constraints (avoid open wildcards like include all)
• Design for international use — avoid locale-specific assumptions

Identifiers and checksums

• A new archetype needs a fresh uid — mint a random UUID (v4). If a shell is available, uuidgen (or python3 -c 'import uuid; print(uuid.uuid4())') works; otherwise generate the UUID directly (this skill has no Bash tool, so don't assume shell access).
• Do not hand-write build checksums (MD5-CAM-*, build_uid) — they are tool-computed by CKM/ADL tooling. If you edit a published archetype, its checksum simply becomes stale: note that for upstream recomputation rather than inventing a value. This is advisory, not a blocker — a missing/stale checksum never stops local authoring.

Step 5: Editing Existing Archetypes

When modifying existing archetypes:

• Path stability: Never rename or remove existing paths in minor versions
• Backwards compatibility: Additions are safe; removals require major version bump
• Deprecation over removal: Mark elements as deprecated before removing in next major version

Step 6: Specialization

When extending via specialization:

• Only specialize for genuine semantic subtypes (e.g., blood_pressure -> invasive_blood_pressure)
• Single inheritance only — one parent archetype
• Preserve parent meaning — specialization narrows, never contradicts
• Maintain transparent lineage in the archetype identifier

Step 7: Review, remediate & write rationale

When reviewing an archetype for quality, publication, or CKM submission, run the full pipeline. Stages at a glance: intent & provenance → lint → remediate → review packet, then optional rationale prose. Quick provenance note (advisory): if the file mirrors a published CKM archetype, editing it locally diverges from canonical and stales its MD5-CAM checksum — prefer contributing upstream; never a blocker. For a quick lint with no remediation, use the archetype-lint skill (/archetype-lint).

• Full pipeline (lint → fix-plan → patch → re-lint → review packet + checklist): load references/review-remediate.md.
• Drafting description / purpose / misuse / use prose: load references/rationale-prose.md.

Step 8: Translate / add a locale

To add or translate per-language text (ontology.term_definitions) for a target language, load references/translation.md — it covers the three tab-sensitive insertion points and the at-code-parity verification gate. (Translations live in the ontology block in ADL 1.4, not a top-level terminology section.)

Output

Generate valid ADL 1.4 files. Use the Write tool to create .adl files in the appropriate project location.