Validation

Epilogue Tracker includes a validation command that checks your work model for completeness and consistency.

Running Validation

et validate

Successful output:

Validation Report
=================

Loaded: 3 actor(s), 8 goal(s), 15 interaction(s), 4 journey(s)

✓ No issues found. All relationships are valid.

What Gets Validated

Actors

Check	Type	Description
Has goals	Warning	Actor should have at least one goal assigned
Goals exist	Error	Referenced goals must exist

Goals

Check	Type	Description
Has actor	Warning	Goal should be linked to an actor (orphan check)
Actor exists	Error	Referenced actor must exist
Has interactions	Warning	Goal should have interactions supporting it

Interactions

Check	Type	Description
Has goal	Warning	Interaction should link to a goal
Goal exists	Error	Referenced goal must exist
Actor exists	Error	performed_by actor must exist

Journeys

Check	Type	Description
Actor exists	Error	Referenced actor must exist
Goal exists	Error	Referenced goal must exist
Steps exist	Error	All interaction steps must exist
Goal alignment	Warning	Goal's actor should match journey's actor
Step alignment	Warning	Step's performed_by should match journey's actor

Understanding Output

Errors vs Warnings

Errors indicate broken references: something points to an entity that doesn't exist:

Errors:
  ✗ [goal/checkout] References non-existent actor 'customer'
  ✗ [journey/flow] References non-existent interaction step 'missing'

Errors cause et validate to exit with code 1.

Warnings indicate potential issues: things that work but might not be intentional:

Warnings:
  ! [actor/admin] Actor has no goals assigned
  ! [interaction/api_call] Interaction is not linked to any goal
  ! [goal/orphan] Goal is not linked to any actor (orphan goal)

Warnings don't affect the exit code.

JSON Output

For programmatic use:

et validate --json

{
  "valid": false,
  "issues": [
    {
      "type": "error",
      "entity": "goal",
      "id": "checkout",
      "message": "References non-existent actor 'missing_actor'"
    },
    {
      "type": "warning",
      "entity": "interaction",
      "id": "orphan_task",
      "message": "Interaction is not linked to any goal"
    }
  ],
  "summary": {
    "actors": 2,
    "goals": 5,
    "interactions": 10,
    "journeys": 2,
    "errors": 1,
    "warnings": 1
  }
}

Fixing Common Issues

Orphan Goals

Warning: goal 'feedback' is not linked to any actor

Fix by assigning an actor:

et update goal feedback --actor customer

Unlinked Interactions

Warning: interaction 'api_call' is not linked to any goal

Fix by linking to a goal:

et update interaction api_call --goal relevant_goal

Or if there's no relevant goal, create one:

et create goal --id "new_goal" --description "..." --actor "..."
et update interaction api_call --goal new_goal

Missing References

Error: goal 'checkout' references non-existent actor 'old_customer'

Fix by updating the reference:

et update goal checkout --actor customer

Or create the missing entity:

et create actor --id "old_customer" --name "..." --description "..."

Journey Misalignment

Warning: journey 'checkout_flow' - Step 'admin_action' is performed by 'admin', not journey actor 'customer'

This might be intentional (some journeys involve multiple actors) or might indicate an error. Review and either:

• Update the interaction's performed_by if it's wrong
• Accept the warning if the cross-actor step is intentional

CI/CD Integration

Use validation in your CI pipeline:

#!/bin/bash
et validate
if [ $? -ne 0 ]; then
  echo "Validation failed! Fix errors before merging."
  exit 1
fi

Best Practices

1. Run validation often: After any changes to the model
2. Fix errors immediately: Broken references cause problems
3. Review warnings: They often indicate work without clear user value
4. Validate before commits: Keep the model healthy in version control

Next Steps

• CLI Reference: Full command documentation
• Breaking Down Work: Prevent validation issues