# Event Modeling

> Use this skill to discover workflows, map events, commands, read models, automations, and Given/When/Then scenarios before implementation. It keeps discovery separate from architecture and implementation decisions.

- Skill: `jwilger/event-modeling-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jwilger/event-modeling-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jwilger/event-modeling-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: jwilger (https://skillmd.com/u/jwilger)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jwilger/event-modeling-2

---


# Event Modeling

Use this skill to understand a workflow before writing code.

## Core rule

Do not jump from vague product language straight to implementation. Map the workflow first.

The default standard for workflow documents is information completeness, not
just structural completeness.

## Two phases

1. **Domain discovery**
   - Identify actors, major workflows, external integrations, and the best starting workflow.
   - Capture the overview in `docs/event_model/domain/overview.md`.
2. **Workflow design**
   - Work through one workflow at a time.
   - Identify events, commands, views, automations, and translations.
   - Start from the shared workflow template at
     `plugins/codex-sdlc/templates/event_model_workflow.md` unless the user
     explicitly asks for a different artifact shape.
   - Produce pattern-specific Given/When/Then scenarios with concrete command
     and view examples.
   - For first-party UI workflows, model the user-visible screens and screen
     submissions rather than internal HTTP endpoints or transport details.

## Modeling rules

- Events are past-tense business facts.
- Read models must trace back to source events.
- Commands depend on user input and prior events, not on read models.
- Automations need a trigger, a view or condition, a process, and a resulting command.
- Keep architecture selection and implementation details out of the event-modeling session.
- Remove unresolved either/or choices from event contracts before calling the
  workflow done.
- Separate operator-facing queries/views from internal inspection queries/views.
- If a workflow has no standalone automation or translation slice, say so
  explicitly instead of leaving the section implied.
- When later design-system or designer-agent work depends on the workflow,
  include the screens because they define the user-visible surfaces that must
  be designed.

## Information completeness

Run an information-completeness pass for every workflow and rerun it after
every substantive model change.

At minimum, verify:

- every event attribute has an explicit source from command input, generation,
  or a stated derivation rule
- every projection attribute traces back to source events or an explicit
  query-time derivation rule
- absence states are modeled explicitly rather than implied
- workflows with replace, renew, reissue, supersede, expire, cancel,
  deactivate, suspend, reactivate, or reopen semantics get a dedicated
  lifecycle pass before being called complete
- at least one Given/When/Then scenario proves that historical records no
  longer block future commands once the latest active state has ended
- event contracts do not contain unresolved alternatives
- command preconditions trace back to prior events, not only to convenient
  read-model language

## Slice rules

- Each slice must include an application-boundary acceptance scenario.
- A slice that only changes internal code without an observable boundary is not a full vertical slice.
- Slices sharing the same event contract should stay independently testable.
- Classify every slice as one of the four patterns below. Do not mix pattern
  types inside one scenario.

## Pattern-specific scenarios

- `State Change`: `Given [EVENTS], When [COMMAND], Then [EVENTS | ERROR]`
- `State View`: `Given [EVENTS], Then [PROJECTION]`
- `Automation`: `Given [EVENTS | TIMER], When [AUTOMATION], Then [COMMAND -> EVENTS]`
- `Translation`: `Given [EXTERNAL EVENT], When [TRANSLATION], Then [INTERNAL COMMAND -> EVENTS]`

## Boundary examples

- Provide a concrete CLI or equivalent boundary example for every
  application-facing command.
- Provide a concrete CLI or equivalent boundary example for every
  operator-facing view/query.
- For first-party UI flows, the equivalent boundary example is the screen and
  user action, not an internal `GET` or `POST` endpoint.
- Internal inspection queries may exist, but they must be labeled as supporting
  surfaces rather than accidental public views.

## Implementation-only invariants

- Record non-business constraints that should not distort the event model but
  must still be covered in TDD and implementation.
- Typical examples include bootstrap behavior, open-vs-create behavior, path
  safety, idempotence expectations, and operator-safety guards.
- Add these invariants to the workflow artifact explicitly so they become
  concrete follow-up checks instead of hidden shell assumptions.

## Codex-specific guidance

- Ask clarifying questions when domain knowledge is missing.
- Prefer explicit documents under `docs/event_model/` over transient chat-only analysis.
- Use this skill before major TDD work when the workflow is not yet well-shaped.
- After any model edit, revisit the `Information Completeness Check` section
  before claiming the workflow is done.
- After the final material edit, rerun information completeness explicitly and
  confirm the rerun result before claiming the workflow is complete.

## Common failure modes

- stopping at structural completeness instead of information completeness
- mixing state-change and state-view scenarios in the same slice
- omitting CLI examples for commands or views
- modeling first-party UI flows as internal HTTP endpoints instead of screens
  and screen submissions
- leaving a modeled command or modeled projection without at least one GWT
  scenario
- inventing a fake automation slice for a synchronous flow narrative
- adding internal debug views without modeling the supporting queries

## Done when

- the workflow is mapped clearly enough to decompose into pattern-specific
  slices
- each slice has concrete GWT scenarios in the correct pattern form
- every modeled command has at least one concrete GWT scenario
- every modeled projection has at least one concrete GWT scenario
- every application-boundary command and operator-facing view has a concrete
  example
- lifecycle-changing workflows have a dedicated lifecycle pass and a historical
  state scenario proving re-entry or future eligibility when applicable
- every event attribute has an explicit source
- every projection attribute has a traceable source path
- implementation-only invariants are captured explicitly for TDD and shell work
- absent automation or translation patterns are explicitly stated when they do
  not exist
- no major workflow gap remains unaccounted for
- the final post-edit information-completeness rerun has been performed and any
  remaining gaps have been resolved