gremiumhub/.claude/skills/seed-yaml-sync/SKILL.md

name, description

name	description
seed-yaml-sync	Use when modifying seed files in template/ or demo/ directories - ensures structural consistency, visibility condition correctness, and test data synchronization between template and demo form

Seed YAML Synchronization

Overview

The Legal Consent Hub has two interdependent seed file directories that must stay synchronized:

1. Template (seed/template/) - isTemplate: true - defines the form structure, element types, options, visibility conditions, section spawn triggers, and template sections.
2. Demo form (seed/demo/) - isTemplate: false - a realistic SAP S/4HANA application form with pre-filled values derived from the template. Used for development testing and UI validation.

Changes to either directory can break the other. This skill ensures consistency.

File Structure

legalconsenthub-backend/src/main/resources/seed/
├── template/                              # Template (source of truth for structure)
│   ├── _main.yaml                         # Main file: isTemplate, name, !include directives
│   ├── section_01_angaben_zum_itsystem.yaml
│   ├── section_02_modulbeschreibung.yaml
│   ├── ... (16 sections total)
│   └── section_16_informationen_zur_kuenstlichen_intelligenz.yaml
│
└── demo/                                  # Demo form (SAP S/4HANA test data)
    ├── _main.yaml                         # Main file: isTemplate, name, !include directives
    ├── section_01_angaben_zum_itsystem.yaml
    ├── section_02_rollen_und_berechtigungen.yaml
    ├── ... (11 sections total)
    └── section_11_informationen_zur_kuenstlichen_intelligenz.yaml

File Format

_main.yaml contains form metadata and includes section files:

isTemplate: true  # or false for demo
name: Name des IT-Systems

formElementSections:
  - !include section_01_angaben_zum_itsystem.yaml
  - !include section_02_modulbeschreibung.yaml
  # ... more sections

Section files contain a single section definition (title, subSections, elements).

The SplitYamlLoader class merges these files before deserialization.

When to Use

• Adding, removing, or modifying form elements in template sections
• Changing visibility conditions, section spawn triggers, or options
• Adding or modifying template sections
• Changing element types, references, or clonable settings
• Any edit to files in either template/ or demo/ directory

The Synchronization Rules

Rule 1: Template is the structural source of truth

The template defines ALL structural properties. The demo form must mirror them exactly:

Property	Template defines	Demo form mirrors
reference	Yes	Must match exactly
title	Yes	Must match exactly
type	Yes	Must match exactly
options[].label	Yes	Must match exactly
options[].processingPurpose	Yes	Must match exactly
options[].employeeDataCategory	Yes	Must match exactly
options[].columnConfig	Yes	Must match exactly
visibilityConditions	Yes	Must match exactly
sectionSpawnTriggers	Yes	Must match exactly
isClonable	Yes	Must match exactly
tableRowPreset	Yes	Must match exactly
options[].value	Defaults (empty/false)	Realistic SAP S/4HANA values
description	Yes	Must match exactly

Rule 2: Demo form values must be contextually appropriate

The demo form simulates a realistic "SAP S/4HANA Einfuehrung" (introduction) scenario. When adding test data:

• RADIOBUTTON: Set value: 'true' for the selected option, empty string for others
• CHECKBOX: Set value: 'true' for checked options, value: 'false' for unchecked
• TEXTAREA/TEXTFIELD: Set value to realistic SAP S/4HANA content
• TABLE: Set value to JSON arrays with realistic SAP data (e.g., role IDs, processing IDs)
• DATE: Set value to a realistic date string
• RICH_TEXT: Set value to formatted content

Demo form context: The form represents an "Einfuehrung" (introduction) of SAP S/4HANA with:

• art_der_massnahme = "Einfuehrung" selected
• luv_beabsichtigt = "Ja" (performance/behavior monitoring intended)
• personenbezogene_daten_verarbeitet = "Ja"
• Modules: FI/CO, HCM, SCM (3 spawned module sections)
• 5 processing operations (V001-V005)
• 5 roles (R001-R005), 6 permissions (P001-P006), 4 scopes (S001-S004)
• 5 interfaces (IF001-IF005)

Rule 3: Visibility conditions must be logically consistent

When changing visibility conditions:

1. Check the condition chain: If element B depends on element A, and element C depends on element B, changing A's options or reference affects B AND C.
2. sourceFormElementReference must exist: Every sourceFormElementReference value must match an existing element's reference in the same form context (same section or a parent-spawning section).
3. formElementExpectedValue must match an option: The expected value must correspond to an actual label (for RADIOBUTTON) or label (for CHECKBOX) of the referenced element.
4. Operator consistency:
   • EQUALS / NOT_EQUALS: Compare against option labels (RADIOBUTTON) or option labels with value 'true' (CHECKBOX)
   • IS_EMPTY / IS_NOT_EMPTY: No expected value needed
5. AND vs OR logic:
   • AND: All conditions must be true (used for nested dependencies)
   • OR: Any condition can be true (used for showing across multiple art_der_massnahme values)

Rule 4: Section spawn triggers must reference existing templates

Every sectionSpawnTriggers[].templateReference must match a section's templateReference in the template directory where isTemplate: true in _main.yaml.

Rule 5: Table cross-references must be valid

When a table column has columnConfig.sourceTableReference:

• The referenced table must exist in the same form context
• sourceColumnIndex must be a valid column index in the referenced table
• If rowConstraint is used, all constraint references must be valid

Rule 6: Only extend demo data when contextually appropriate

When new elements or sections are added to the template:

DO add demo data when:

• The element is visible in the "Einfuehrung" path (check visibility conditions)
• The element belongs to a spawned section that would be active (e.g., rollen_berechtigungen_template, verarbeitung_mitarbeiterdaten_template, etc.)
• The element is a new table column in an existing table that has data

DO NOT add demo data when:

• The element is only visible for "Aenderung IT-System" or "Einstellung IT-System" paths
• The element belongs to a template section that wouldn't spawn in the demo scenario
• Adding data would be contradictory to the existing demo context (e.g., adding "Nein" data where parent says "Ja")

Rule 7: Section naming conventions

Template sections are named by functional purpose:

• section_01_angaben_zum_itsystem.yaml
• section_07_rollen_und_berechtigungen.yaml
• section_02_modulbeschreibung.yaml (template section for spawned modules)

Demo sections include spawned section instances:

• section_07_modul_sap_finance_and_controlling_fico.yaml (spawned from template)
• section_08_modul_sap_human_capital_management_hcm.yaml (spawned from template)
• section_09_modul_sap_supply_chain_management_scm.yaml (spawned from template)

Rule 8: _main.yaml must include all sections

When adding a new section file:

1. Create the section file with appropriate naming
2. Add the !include directive to the corresponding _main.yaml
3. Maintain logical section ordering

Rule 9: Change process must start with template, then sync demo

Any change request that affects form structure, visibility conditions, or section spawn triggers must follow this process:

1. Modify the template: Make all necessary changes to the template files first, ensuring structural integrity and logical consistency
2. Sync the demo form: After the template is updated, modify the demo form to mirror the structural changes and add contextually appropriate test data
3. Verify both: Ensure that the template remains the source of truth and that the demo form accurately reflects the template's structure and visibility logic

Checklist for Template Changes

When you modify files in the template/ directory, verify each item:

• Structural sync: Every changed element's structure (type, options labels, visibility conditions, spawn triggers) is mirrored in the corresponding demo section for elements that exist there
• New elements: If a new element is visible in the "Einfuehrung" path, add it to the demo form with appropriate SAP S/4HANA test data
• Removed elements: If an element is removed from the template, remove it from the demo form
• Visibility chain integrity: If you changed a visibility condition's source reference or expected value, trace all downstream dependencies
• Spawn trigger integrity: If you changed spawn triggers, verify the template section references still exist
• Table column consistency: If you added/removed/reordered table columns, update all tables that cross-reference this table (check sourceTableReference, sourceColumnIndex, filterCondition.sourceColumnIndex)
• Option label changes: If you renamed an option label, update all visibility conditions that reference that label as formElementExpectedValue
• _main.yaml update: If you added/removed a section file, update template/_main.yaml

Checklist for Demo Form Changes

When you modify files in the demo/ directory, verify:

• No structural drift: You haven't changed any structural property that should come from the template (types, labels, visibility conditions, spawn triggers)
• Value consistency: New values are consistent with the SAP S/4HANA "Einfuehrung" context
• Table data alignment: Table JSON arrays all have the same length within a single table element
• Cross-reference integrity: Table values that reference other tables use valid IDs from those tables
• _main.yaml update: If you added/removed a section file, update demo/_main.yaml