review · diff
git:20260605.b66fd15 to git:20261007.d097047
32 added, 14 removed. Audit A to A.
---
name: review
description: >
Review an openEHR specification document for quality, completeness, and convention compliance in
`specifications-XX` repos. This skill should be used when the user asks to review, lint, or
- quality-check an openEHR spec, validate its conventions, or run a pre-release review. Not for
- archetype/template review (openehr-assistant plugin), the governance process (use governance), or
- non-openEHR documents.
+ quality-check an openEHR spec or chapter, validate its conventions, or run a pre-release review.
+ Not for prose-style advice (use content-patterns), archetype/template review (openehr-assistant
+ plugin), the governance process (use governance), or non-openEHR documents.
---
# openEHR Specification Document Review
- This skill performs a structured review of an openEHR specification document against the
- conventions used across all `specifications-XX` repositories.
+ 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
3. **Present findings** grouped by category with `file:line` references
4. **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
- - At least 2-3 chapter files (`master02-*.adoc`, etc.)
+ - 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:
+ 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.
| # | Category (ID prefix) | Covers |
|---|----------------------|--------|
| 1 | Document Structure (STRUCT) | `master.adoc` include order, required files, section scaffolding |
| 2 | Preface Completeness (PREF) | Purpose, Related Documents, Status, Feedback, Conformance |
| 3 | Amendment Record (AMEND) | `latest_issue` anchors, entry order, release boundaries, Jira refs |
| 4 | Cross-References (XREF) | `{openehr_*}` attributes resolve; display text + `^` markers; no hardcoded URLs |
| 5 | Figures and Diagrams (FIG) | `image::` `id=`/`align`, titles, `[.text-center]`, path attributes |
| 6 | AsciiDoc Conventions (ADOC) | Monospace class/attribute names, generated class tables, `[.tbd]`/`[.deprecated]` |
- | 7 | Manifest Consistency (MANIFEST) | `manifest.json` entry present and consistent with `manifest_vars.adoc` |
- | 8 | Content Quality (CONTENT) | Chapter headings, Overview sections, no hardcoded site URLs |
+ | 7 | Manifest Consistency (MAN) | `manifest.json` entry present and consistent with `manifest_vars.adoc` |
+ | 8 | Content Quality (CONTENT) | Chapter headings, Overview sections, TBD and deprecated inventories |
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
- - This skill reviews **openEHR specification documents** — the AsciiDoc sources in `specifications-XX` repositories (RM, AM, BASE, LANG, PROC, SM, QUERY, CNF, TERM, ITS-*)
- - All checks are derived from conventions observed in the openEHR specification library and its shared infrastructure in `specifications-AA_GLOBAL`
- - It does NOT apply to non-openEHR specifications, general AsciiDoc documents, or other standards
- - It does NOT review archetypes, templates, AQL queries, or governance process
- - It does NOT modify files — it reports findings for the author to act on (unless asked to fix)
+ - 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.