event-model-validation

name	event-model-validation
description	Event model validation and rendering; use when checking information completeness, validating workflow JSON, or rendering event-model HTML.

Event Model Validation

Use this skill after creating or editing an event model, and whenever the user asks about information completeness or generated HTML.

Commands

Validate one workflow model:

python3 scripts/validate_event_model.py docs/event-model/workflows/<workflow>.eventmodel.json

Render one workflow model:

python3 scripts/render_event_model.py docs/event-model/workflows/<workflow>.eventmodel.json > docs/event-model/generated/<workflow>.html

Validate every workflow model:

for file in docs/event-model/workflows/*.eventmodel.json; do python3 scripts/validate_event_model.py "$file" || exit 1; done

Only run the all-workflows command when at least one workflow file exists.

What The Validator Checks

The validator checks structural references and information completeness:

• required top-level keys exist
• top-level lists have valid object names
• stream, event, command, and read model names are unique within a file
• every event is produced by a command
• commands only read known read models
• commands only produce known events
• event streams reference known streams
• event attributes have valid sources
• read model fields reference known event attributes
• slices reference known commands, events, and read models
• state-change slices include given, when, and then
• state-view slices include given and then

Source Rules

Event attribute sources must be one of:

• generated.<kind>
• command.<input> where <input> exists on a producing command
• external.<external_input>.<field> where <external_input> exists on a producing command
• read_model.<read_model>.<field> where <read_model> exists in a producing command's reads

Read model field sources must reference known event attributes:

• EventName.attribute_name
• event.EventName.attribute_name is accepted but not preferred

Manual Completeness Review

After the script passes, do a short human review:

• Does each event name describe a completed business fact?
• Does each command describe an action/request rather than a fact?
• Does each read model have a real user or process that needs it?
• Does each attribute have a believable source in the story?
• Are generated values truly generated by the system?
• Are external values clearly outside the modeled boundary?
• Are business rules represented with concrete examples?
• Are alternate/error flows captured or intentionally deferred?
• Is the workflow scope clear enough that future agents will not overgeneralize it?

Handling Failures

When validation fails, fix the model rather than weakening the validator.

For each error:

• Explain the issue in plain language.
• Identify the missing or inconsistent model element.
• Ask the user only when the missing information is a real business decision.
• Re-run validation after edits.

Do not silently invent events, command inputs, read models, or sources to satisfy validation.