| name | event-definition |
| description | Review or create event definitions for event-driven architecture. Covers event names, payload field names, event_type identity, stream naming boundaries, and record metadata/context/payload placement for both domain events (event-sourcing) and integration events (cross-service). Use when designing a new event definition, reviewing an existing event definition, or auditing event definition consistency across a catalog. Do not use for full event modeling workflows (use trogonstack-eventmodeling skills), event schema evolution or migration strategy, or event store implementation design. |
| allowed-tools | ["AskUserQuestion","Write","Read","Bash"] |
Review or Create Event Definitions
Review or create event definitions for event-driven systems. Keep the default pass focused on event identity, naming, field placement, record boundaries, and the quality gate; load references only when a decision needs examples, detailed criteria, or deeper modeling guidance.
Progressive Disclosure
Read these references only when the task needs that depth:
references/event-naming-rules.md - examples for event tense, domain language, CRUD naming, suffixes, infrastructure terms, negatives, and integration-event prefixes.references/field-naming-rules.md - examples for field names, identifiers, temporal fields, enums vs booleans, derived values, money, collections, polymorphic payloads, PII, and casing.references/event-record-boundaries.md - event type identity, stream names, stream version vs event schema revision, actor context, ownership checks, and deterministic handlers.references/quality-checklist.md - full checklist for pass/fail reviews and future criteria additions.
Core Principle
An event definition declares what happened, how it is identified, and which business facts were captured.
Keep three layers distinct:
- Record metadata: event-store facts such as
event_id, stream_id, stream_version, and recorded_at
- Event context/envelope: generic event-sourcing facts such as
event_type, actor_id, on_behalf_of, occurred_at, correlation_id, and causation_id
- Payload: domain facts such as
order_id, owner_id, approved_by, effective_at, and expires_at
Do not push generic causality, tracing, persistence, or transport facts into the domain payload. Keep actor and time fields in the payload only when they are part of the domain rule.
Interview
Before reviewing or creating event definitions, establish:
- Domain or integration? Domain events live inside a bounded context and are the source of truth for state. Integration events cross service boundaries and form a public contract.
- What business process or workflow does this event belong to?
- What conventions already exist in the codebase? If there is an event catalog, read it first and follow it unless it violates these rules.
If the user provides event definitions to review, skip to the review. If the user asks to design new event definitions, gather the business context first.
Event Naming Rules
- Use past tense because events are facts:
OrderPlaced, not PlaceOrder.
- Use domain language instead of CRUD or implementation language:
ClaimApproved, not ClaimStatusChanged, unless status changes are the domain concept.
- Be specific enough to understand the fact without reading the payload:
OrderItemAdded, not OrderChanged.
- Reserve
Created, Updated, and Deleted for domains where those operations are the business concept.
- Keep one event to one thing that happened. Split combined facts even when they share a cause.
- Choose one naming format and apply it consistently: PascalCase, dot.delimited, or kebab-case.
- Avoid redundant suffixes such as
Event, Message, or Notification.
- Keep infrastructure and broker names out of event names.
- Prefer positive domain facts with reason fields over negative event names, unless the negative term is natural domain language.
For examples and edge cases, read references/event-naming-rules.md.
Integration Event Naming Rules
Integration events cross service boundaries and form public contracts.
- Prefix or namespace integration events with the originating bounded context or service when they can collide across domains.
- Use shared vocabulary that consumers understand, not private implementation jargon.
For examples and collision guidance, read references/event-naming-rules.md.
Event Type And Stream Identity
Persisted event_type should identify the domain/event schema contract without requiring stream-name parsing. Stream names are storage/routing addresses and may be compact, e.g. tenant/tenant_123/orders/order_456; keep tenant, environment, region, and shard values out of event_type.
Do not carry both a versioned event_type and a separate schema_version when both encode the same schema version. Keep event_type stable for compatible additive changes; use revisions such as OrderPlacedV2 only for incompatible schema or semantic changes.
For self-identifying event types, stream names, stream version vs event schema revision, and tenant-scoped streams, read references/event-record-boundaries.md.
Field Naming Rules
- Capture What, Who, and When through the event type plus typed event context.
- Keep generic actor and occurrence time in context:
actor_id, occurred_at.
- Use payload
_by, _at, or _on fields only when that actor or time is part of the domain fact.
- Use domain language for fields and avoid vague names or abbreviations.
- Make identifiers explicit:
order_id, not id.
- Use
_at for datetimes and _on for dates; keep generic occurred_at in context.
- Prefer enums over booleans unless the field is permanently binary.
- Keep computed or derived values out of domain events; put them in read models.
- Include currency with monetary amounts.
- Use plural names for collections and singular names for scalar values.
- Split polymorphic payloads into separate event types.
- Avoid direct PII in immutable events; reference mutable records by identifier.
- Use consistent casing across the event catalog.
For examples and edge cases, read references/field-naming-rules.md.
Record Metadata, Context, And Payload
Keep record metadata, event context, and business payload separate. Generic actor, time, correlation, causation, persistence, transport, and routing facts belong outside payload unless they are themselves domain facts.
Use actor_id only for the initiating/requesting actor in event context; do not infer ownership or authorization from it. Validate ownership against domain state or policy before emitting events.
Event handlers and projections should consume immutable recorded-event data and avoid clocks, random IDs, actor lookups, or authorization services during replay.
For record-layer, actor-context, ownership, and deterministic-handler rules, read references/event-record-boundaries.md.
Quality Checklist
Use this as the required quality gate when creating or reviewing event definitions:
- Names are factual, past-tense, domain-specific, and scoped enough to avoid collisions.
- Field names describe domain facts with explicit identifiers, temporal naming, casing, and safe value shapes.
event_type is a self-identifying schema discriminator and is not coupled to stream routing details.- Record metadata, event context, and payload stay separate.
- Actor context, ownership checks, and handler inputs support deterministic replay.
For formal pass/fail review output or when adding criteria, read references/quality-checklist.md.
Output
Provide:
- List of events reviewed with pass/fail per quality checklist item
- Suggested corrections for any violations
- Domain vs integration classification if not already clear
- Field naming corrections with rationale
- Payload vs context classification for disputed actor, time, causality, and schema identity fields
