Measuring a FHIR Implementation Guide

Preconditions

1. The tool.

   python3

   must be runnable. The analyser is standard-library only — nothing to install. If

   python3

   is absent, say so and stop; do not fetch an interpreter.
2. The subject. One or more IGs, each given as a local path, a git URL, or a package

   .tgz

   .

   run

   resolves each itself (shallow clone for a URL, download for a package). Nothing needs to be discovered inside the repository beyond what the tool reads.
   • A local path with neither

     sushi-config.yaml

     nor

     input/

     is not an IG project. Report that and stop.
   • A git URL requires network access; if cloning fails, report the failure rather than reporting an empty measurement.
3. Static by default, and know what that costs. Without a build, the analysis is static: sushi-config/package metadata, FSH counts, narrative, directives, dependencies, linguistics, duplication, hygiene. Build-derived metrics (

   qa.json

   : errors, warnings, broken links, validation) stay

   null

   and are marked Build in the catalog. A package

   .tgz

   yields a further reduced analysis — generated resources only.
   State which mode produced the numbers whenever you report them. A

   null

   is not a zero.

Procedure

Resolve the script path first. The commands below name the tool relative to this skill's own directory, not to your working directory — which is the project you are operating on. Set

SKILL_DIR

to the directory containing this

SKILL.md

(you just read it, so you know where it is) and use it in every invocation:

bash

SKILL_DIR=<the directory containing this SKILL.md>   # e.g. .claude/skills/fhir-ig-analysis

Running a bare

scripts/...

from the project root does not merely fail — if the project happens to have its own

scripts/

directory with a same-named file, it silently runs that instead.

1. Measure. One IG or several, from the IG's root or anywhere:
   bash

   python3 "$SKILL_DIR/scripts/ig-stats.py" run <input…> [-o OUTDIR] [--label a,b]

   With two or more inputs this writes one report per IG plus

   compare-report.md

   automatically.

   --label

   sets the display label (report heading, compare columns), one per input; output filenames always derive from the IG id.
   Two consequences of how inputs resolve, so the numbers are read correctly: a git URL is shallow-cloned, so the git-history metrics (bus factor, maintenance cadence) are reported as not derivable (

   git.history_complete: false

   , values

   null

   ) — measure a full local clone when you need them. And the tool reports counted maturity components without an aggregated score: a 0–100 "readiness" number would be a forecast, which this skill deliberately does not produce.
2. Power-user entry points, when you want the stages separately:
   bash

   python3 "$SKILL_DIR/scripts/ig-stats.py" analyze <ig-dir> [-o stats.json]
   python3 "$SKILL_DIR/scripts/ig-stats.py" report  <stats.json>  [-o report.md]
   python3 "$SKILL_DIR/scripts/ig-stats.py" compare <stats.json…> [-o compare.md]

3. Read the mandatory-page finding carefully. The page set the tool checks against lives in

   references/report-content.json

   under

   mandatory_pages

   and is hand-editable on purpose. It is seeded with the MII KDS module template's actual page names.
   If a measured IG legitimately uses a different page set, correct the list rather than reporting its pages as missing — and say in your report which list you used. A page-completeness metric is only as good as the set it compares against.
4. Report both artefacts. The JSON is the durable one: it has a fixed schema, so a series of runs diffs cleanly and shows how a module grows between releases. The Markdown is for people.
5. Compare only on normalised metrics. Absolute counts across IGs of different size say almost nothing; the comparison report aggregates a Σ total for scope but the fair columns are the normalised ones.
6. Same-module verification is automatic. When every compared input carries the same

   packageId

   , the inputs are states of ONE module (typically: the platform source vs its migrated copy) and the report switches to Same-Module-Verifikation: identity-field equality, published-artifact-set equality (internal FSH constructs reported separately — template adoption adds scaffold rulesets legitimately), canonical-URL equality (read from

   fsh-generated

   when both inputs have it), and narrative per language level (default / translations / retained platform pages) with word-coverage indicators. The Σ column is dropped (meaningless for one module). Every verdict is counted, none forecast. Order matters: the FIRST input is the reference.

Verification

python3 "$SKILL_DIR/scripts/ig-stats.py" run <ig-dir> -o /tmp/igstats
python3 -c "import json;d=json.load(open('/tmp/igstats/<name>-stats.json'));print(d['mode'],d['schemaVersion'])"

• The run exits 0 and writes one

  *-stats.json

  and one

  *-report.md

  per input.
• With ≥2 inputs,

  compare-report.md

  exists.

• mode

  in the JSON matches what you claim (

  static

  /

  reduced

  ), and

  schemaVersion

  is present.
• Every metric you quote is either a counted number or

  null

  — never an estimate. If a field is

  null

  , report it as not derivable statically rather than as zero.
• The mandatory-page result is plausible against the IG you measured. All-missing usually means the wrong page set, not a broken IG.
• On a same-module comparison, the Befund block states IDENTISCH/DIVERGIERT per aspect — a migration is only faithful when identity, published artifact set and canonical URLs are all IDENTISCH; the migration skill's Definition of Done requires exactly that.

Scope and delimitation

• Effort forecasting. The tool reports what it counted. It does not estimate person-days, cost or a readiness score, and an earlier version of this skill that framed the numbers as migration scoping was narrowed on purpose. Do not reintroduce it: a measurement dressed as a forecast is the least trustworthy thing this skill could produce.
• Migration onto the MII KDS module template — see

  mii-ig-migration

  . Verifying a migrated guide against its source belongs there too, in its

  scripts/verify-migration.py

  : artefact reachability, menu structure, content placement, rendered header metadata and toolchain provenance are pass/fail gates that read the migration's page map and run log — inputs that are not properties of an IG and would break this skill's "a path, a URL or a

  .tgz

  " contract. The same-module verification below is the measurement that gate consumes, not a substitute for it: it proves an artefact is PRESENT, never that anything links to it.
• Translation — see

  fhir-ig-translation

  .
• Convention and naming checks against the MII meta wiki or the metadata contract. Those are a different check, and the module template ships its own skill for them.
• Building or publishing anything. Read-only is a guardrail, not a default.

Guardrails

• Read-only. Never modify the analysed IG; never force a build.
• Measurement, not forecasting. See above.
• Fair comparison only via normalised metrics.
• No invention. A missing input yields

  null

  , never a guess. Heuristic metrics are marked as heuristics in the catalog and must be reported as such.

References

• references/metrics-catalog.md

  — the parameter catalog (groups A–N), each metric with its source and its use. Hand-extensible; this is the SSOT for what is measured.

• references/ig-stats-schema.json

  — the schema of

  ig-stats.json

  .

• references/report-content.json

  — plain-language texts, glossary, directive patterns, metric explanations, and the

  mandatory_pages

  list. Hand-editable.

• references/triggers.md

  — the Gate 3 prompt set.

• scripts/ig-stats.py

  — the analyser (

  run

  /

  analyze

  /

  report

  /

  compare

  ).

Provenance

skills/ig-analyze

forschungsgruppe-digital-health/mii-kds-module-template

b5beedb17a66a4397d597429668c7b6d54202c62

ig-analyze

forschungsgruppe-digital-health/mii-kds-sample-ig-inoffiziell

• The analyser now ships with the skill. It previously lived in the source repository's

  scripts/

  and was referenced by parent traversal, so the skill pointed at a file it could not reach once installed elsewhere.

• scripts/ig-stats.py

  locates

  references/report-content.json

  relative to its own path. It previously built that path from a computed repository root plus a hard-coded

  skills/ig-analyze/references/…

  , which broke twice here: there is no repository root to compute, and the skill was renamed.
• The mandatory-page list moved out of the code into

  references/report-content.json

  and was corrected. The inherited list named eleven pages of which six do not exist in the template modules are built from (

  use-cases

  ,

  data-sets

  ,

  uml

  ,

  context

  ,

  references

  ,

  security-privacy

  ), so every measurement reported six false missing pages.

kerndatensatz-dokument

kerndatensatz-basis

Reifegrad

history_complete: false

null

references/ig-stats-schema.json

mandatory_missing

mii-kds-dokument-ig-inoffiziell

docs/reports/dry-run-2026-07-31/

scripts/

stable