Fix IG Export Links (Canonical Version)

Architecture: This skill generates module-specific fix scripts based on configuration.

How It Works

1. Read module config from .claude/config.json or CLAUDE.md
2. Generate customized script at .claude/skills/fix-ig-export-links/scripts/fix-links.sh
3. Run script on downloaded IG export
4. Verify remaining links are intentional

Required Module Configuration

Your module's .claude/config.json must define:

{
  "ig_export": {
    "module_id": "onkologie",
    "package_name": "de.medizininformatikinitiative.kerndatensatz.onkologie",
    "canonical_base": "https://www.medizininformatik-initiative.de/fhir/ext/modul-onko",
    "guide_name": "mii-ig-modul-onkologie-v2026-de",
    "resource_prefix": "mii-pr-onko",
    "dependencies": {
      "hl7.fhir.r4.core": "4.0.1",
      "hl7.terminology.r4": "7.0.0",
      "de.basisprofil.r4": "1.5.4",
      "de.medizininformatikinitiative.kerndatensatz.base": "2026.0.0",
      "de.medizininformatikinitiative.kerndatensatz.medikation": "2026.0.0",
      "de.medizininformatikinitiative.kerndatensatz.molgen": "2026.0.4"
    },
    "special_dependencies": {
      "genomics_reporting": {
        "package": "hl7.fhir.uv.genomics-reporting",
        "version": "3.0.0",
        "url_base": "https://hl7.org/fhir/uv/genomics-reporting/STU3/"
      }
    }
  }
}

Configuration Fields

Link Categories Fixed

The generated script fixes these link patterns:

Always Fixed (All Modules)

• FHIR R4 Core → https://hl7.org/fhir/R4/...
• HL7 Terminology (THO) → https://terminology.hl7.org/...
• German base profiles → Simplifier packages
• MII Base Module → Simplifier packages

Module-Specific (Based on Dependencies)

• MII module dependencies (medikation, molgen, onkologie, etc.) → Simplifier packages
• Special dependencies (genomics-reporting, etc.) → Configured URL bases
• Internal artifacts (profiles, ValueSets, CodeSystems, Extensions) → Module-specific canonical URLs

HTML Encoding Variants

• Single-quoted href='...' with &
• Double-quoted href="..." with &

Procedure

Step 1: Generate the Fix Script

Run the generator from your module root:

# From module root (e.g., kerndatensatzmodul-onkologie/)
cd /path/to/kerndatensatzmodul-<module>

# Run generator
python3 /path/to/mii-kerndatensatz-dev/.claude/skills/fix-ig-export-links/scripts/generate-fix-script.py

Or if the skill is already synced to your module:

python3 .claude/skills/fix-ig-export-links/scripts/generate-fix-script.py

What the generator does:

1. Reads ig_export config from .claude/config.json
2. Validates required fields are present
3. Loads template from templates/script-template.sh
4. Generates dependency-specific sed commands
5. Fills in all placeholders (module ID, canonical URLs, prefixes, etc.)
6. Writes fix-links.sh to .claude/skills/fix-ig-export-links/scripts/
7. Makes script executable (chmod +x)

Expected output:

MII IG Export Links Fix Script Generator
==================================================

Module: onkologie
Package: de.medizininformatikinitiative.kerndatensatz.onkologie
Canonical: https://www.medizininformatik-initiative.de/fhir/ext/modul-onko
Dependencies: 6

Generating fix-links.sh...
✓ Generated: .claude/skills/fix-ig-export-links/scripts/fix-links.sh

Next steps:
1. Download IG export from Simplifier
2. Extract ZIP file
3. Run: cd <extracted-dir> && bash /path/to/fix-links.sh
4. Verify: grep -c 'resolve?' *.html | grep -v ':0$'

Step 2: Download and Extract IG

# Download from Simplifier
# Example: [email protected]

# Extract
unzip "[email protected]" -d ig-export
cd ig-export

Step 3: Run the Generated Script

# Run from extracted IG directory
bash /path/to/module/.claude/skills/fix-ig-export-links/scripts/fix-links.sh

Step 4: Verify

# Check remaining resolve links (should only be intentional Simplifier links)
grep -c "resolve?" *.html | grep -v ":0$"

# Expected: Only module canonical URLs remain as Simplifier resolve links
grep -o "simplifier.net/resolve" *.html | wc -l

Expected Remaining Links

After running the script, these Simplifier resolve links are intentional:

• Module profile/ValueSet/CodeSystem canonical URLs → https://simplifier.net/resolve?canonical=...&fhirVersion=R4
• CapabilityStatement canonical → Simplifier resolve

These link to Simplifier for up-to-date profile documentation.

Technical Notes

Link Pattern Types

• ?canonical=: Links to profile canonical URLs (resolved via Simplifier for module resources)
• ?filepath=: Links to package files (converted to official spec URLs or Simplifier packages)

Script Generation Logic

The skill generates sed commands based on:

1. Module canonical pattern: scope=...${moduleid}...canonical=${canonicalbase}/... → Simplifier resolve
2. Dependency patterns: For each dependency, create sed rules for its filepath patterns
3. Internal artifacts: Based on resource_prefix, fix paths to local HTML or Simplifier canonical

Validation

The skill validates config before generating:

• Required fields present
• canonical_base is a valid URL
• Dependencies is a non-empty object
• resource_prefix follows MII naming convention (mii-pr-, mii-vs-, etc.)

Example Configurations

Simple Module (molgen)

{
  "ig_export": {
    "module_id": "molgen",
    "package_name": "de.medizininformatikinitiative.kerndatensatz.molgen",
    "canonical_base": "https://www.medizininformatik-initiative.de/fhir/ext/modul-molgen",
    "guide_name": "mii-modul-molekulargenetischer-befundbericht-v2026-de",
    "resource_prefix": "mii-pr-molgen",
    "dependencies": {
      "hl7.fhir.r4.core": "4.0.1",
      "hl7.terminology.r4": "7.0.0",
      "de.basisprofil.r4": "1.5.4",
      "de.medizininformatikinitiative.kerndatensatz.base": "2026.0.0"
    },
    "special_dependencies": {
      "genomics_reporting": {
        "package": "hl7.fhir.uv.genomics-reporting",
        "version": "3.0.0",
        "url_base": "https://hl7.org/fhir/uv/genomics-reporting/STU3/"
      }
    }
  }
}

Complex Module (mtb - many dependencies)

{
  "ig_export": {
    "module_id": "mtb",
    "package_name": "de.medizininformatikinitiative.kerndatensatz.molekulares-tumorboard",
    "canonical_base": "https://www.medizininformatik-initiative.de/fhir/ext/modul-mtb",
    "guide_name": "mii-ig-mtb-v2026-de",
    "resource_prefix": "mii-pr-mtb",
    "dependencies": {
      "hl7.fhir.r4.core": "4.0.1",
      "hl7.terminology.r4": "7.0.0",
      "de.basisprofil.r4": "1.5.4",
      "de.medizininformatikinitiative.kerndatensatz.base": "2026.0.0",
      "de.medizininformatikinitiative.kerndatensatz.medikation": "2026.0.0",
      "de.medizininformatikinitiative.kerndatensatz.molgen": "2026.0.4",
      "de.medizininformatikinitiative.kerndatensatz.onkologie": "2026.0.0",
      "de.medizininformatikinitiative.kerndatensatz.patho": "2026.0.0",
      "de.medizininformatikinitiative.kerndatensatz.biobank": "2026.0.0",
      "de.medizininformatikinitiative.kerndatensatz.consent": "2025.0.4",
      "de.medizininformatikinitiative.kerndatensatz.studie": "2026.0-ballot"
    },
    "special_dependencies": {
      "genomics_reporting": {
        "package": "hl7.fhir.uv.genomics-reporting",
        "version": "3.0.0",
        "url_base": "https://hl7.org/fhir/uv/genomics-reporting/STU3/"
      }
    }
  }
}

Maintenance

Updating for New Dependencies

When a module adds a new dependency:

1. Add to dependencies in config
2. Regenerate script by running this skill
3. Test on sample IG export

Updating for New Link Patterns

If new broken link patterns are discovered:

1. Update script template in mii-kerndatensatz-dev
2. Sync skill to all modules
3. Regenerate scripts

IG Structure Changes

CRITICAL: When the IG Publisher changes its output structure or link generation logic, this skill must be updated.

Common trigger events:

• IG Publisher version upgrade (e.g., 1.5.x → 1.6.x)
• SUSHI version upgrade changing output format
• Simplifier export format changes
• New HTML encoding patterns
• New dependency package patterns

Update workflow:

1. Download sample IG export with new structure
2. Identify what link patterns changed
3. Update skill logic in mii-kerndatensatz-dev
4. Test on all 5 modules
5. Sync to all modules
6. Document changes in CATALOG.md

Testing after IG structure changes:

• Test with recent IG exports from all 5 modules
• Verify no regression (old patterns still work)
• Verify new patterns are fixed correctly
• Check remaining link count is reasonable

Syncing to Modules

Source of truth: mii-kerndatensatz-dev/.claude/skills/fix-ig-export-links/

Sync to a module:

rsync -av \
  /path/to/mii-kerndatensatz-dev/.claude/skills/fix-ig-export-links/ \
  /path/to/kerndatensatzmodul-<module>/.claude/skills/fix-ig-export-links/

After syncing, regenerate the fix script to pick up new logic.

Version Tracking

See mii-kerndatensatz-dev/CATALOG.md for version history and sync status across modules.

Canonical Version: v1.0.0 (2026-01-10) Maintained in: mii-kerndatensatz-dev Deployed to: molgen, seltene, onkologie, proms, mtb