openEHR Specification Document Review

Review an openEHR specification document against the conventions used across all specifications-XX repositories.

Review Process

1. Identify the target — determine the spec directory (e.g., docs/ehr/) and read the key files
2. Run each check category — work through the full catalog in references/check-catalog.md,

collecting findings as ERROR, WARNING, or INFO

1. Present findings grouped by category with file:line references
2. Propose fixes for ERRORs and WARNINGs (only modify files if asked)

Inline Review or Subagent

Choose by scope:

• Review inline for one chapter, one file, or a few files. Apply only the checks those files

allow and state which checks were skipped.

• Dispatch the `spec-reviewer` subagent for a whole spec directory, a whole component, or a

pre-release review. It runs this same catalog in an isolated context and returns only the findings table.

• Dispatch the `xref-auditor` subagent when the concern is links. XREF-01 to XREF-04 only check

that attributes are defined and links are styled; the subagent also resolves <<anchor>> targets and, with web access, cross-spec #fragment anchors.

• Dispatch the `identifier-grounding` subagent to verify that class, attribute, and function

names exist in the published specifications. No check in this catalog does this.

Pre-Review: File Discovery

Read these files for the target spec:

• master.adoc — main entry point
• manifest_vars.adoc — per-document variables
• master00-amendment_record.adoc — amendment record
• master01-preface.adoc — preface
• Every chapter file in scope (master02-*.adoc, etc.); search all chapters for the pattern checks (FIG, ADOC, XREF, CONTENT) rather than sampling
• The component's manifest.json (in the repo root)

Also reference the shared infrastructure in the sibling specifications-AA_GLOBAL checkout (if it is absent, skip XREF-01 and say so):

• specifications-AA_GLOBAL/docs/boilerplate/global_vars.adoc
• specifications-AA_GLOBAL/docs/references/reference_definitions.adoc

Check Categories

Run all eight categories. The full check list — each with an ID, severity, and condition — is in `references/check-catalog.md`; load it when performing a review.

XREF checks use the attribute naming patterns in ../authoring/references/cross-references.md.

Output Format

Present findings as a table:

| ID | Severity | Location | Finding |
|----|----------|----------|---------|
| STRUCT-02 | ERROR | manifest_vars.adoc | Missing `:keywords:` attribute |
| AMEND-01 | ERROR | master00-amendment_record.adoc:5 | Missing `[[latest_issue]]` anchor |
| FIG-01 | WARNING | master03-overview.adoc:42 | Image directive missing `id=` |

List failing checks only, unless the author asks for passing checks too.

Follow with a summary:

• Total: N findings (E errors, W warnings, I info)
• Recommended actions (grouped, prioritised)

Route fixes: AMEND- to the `amendment-record` skill, ADOC-03 to `class-generation`, XREF- to ../authoring/references/cross-references.md.

Scope Boundaries

• Review only the AsciiDoc sources of openEHR specifications in specifications-XX repositories (RM, AM, BASE, LANG, PROC, SM, QUERY, CNF, TERM, ITS-*). Derive every finding from the catalog.
• Do not review archetypes, templates, AQL queries, the governance process, or non-openEHR documents.
• Do not modify files; report findings for the author to act on, unless asked to fix them.
• Run static checks only. Missing includes or images show up in a build, so tell the author to run /openehr-specs:publish (user-invoked) to surface Asciidoctor warnings.