Extracting Domain Events

Extracting Domain Events

Overview

This skill forces text-based EventStorming from PRDs or requirements. It translates unstructured business requirements into structured domain events, commands, and actors before any code is written, preventing premature implementation and monolithic thinking.

Foundational Principle: EventStorming is mandatory before ANY code or architecture, regardless of perceived simplicity, existing design docs, or time pressure. All rules in this skill are mandatory constraints. There is no complexity threshold below which you may skip event extraction.

When to Use

• When given a PRD, feature request, or any business requirements — especially when they seem "obvious".
• When a design document already exists — ER diagrams and API specs miss failure paths and compensating events.
• Before writing any code or proposing an architecture.

Do NOT use when: requirements are already structured as domain events, modifying logic within an established Bounded Context (use [coding-isolated-domains](../coding-isolated-domains/SKILL.md)), or the task is purely technical with no domain change.

Quick Reference

| Step | Action | Output | |:---|:---|:---| | 1 | Acknowledge & Analyze | Business goal summary | | 2 | First Draft | Initial domain events list | | 3 | Iterative Refinement | Actor / Command / Event (past-tense) / Rules | | 4 | Failure Paths | Compensating events | | 5 | Final Table | Approved Markdown table | | 6 | Persist to Filesystem | docs/ddd/phase-1-domain-events.md |

Ambiguity Handling

Follow the [Ambiguity Handling Protocol](../ddd-protocol/ambiguity-handling-reference.md) throughout this phase.

Phase 1 STOP triggers — confirm immediately (wrong assumption requires multi-step redo):

| Ambiguity | Why STOP | |:----------|:---------| | Business rule existence unclear | Determines whether a Domain Event exists at all | | Failure path compensation needed? | Missing compensating events cascade through Phase 2-7 | | Actor identity ambiguous | Wrong actor attribution corrupts command ownership | | Domain term meaning unclear | Ubiquitous Language violations propagate to all phases |

Phase 1 ASSUME & RECORD — proceed with explicit assumption:

| Ambiguity | Default assumption | |:----------|:------------------| | Event naming wording (e.g. OrderPlaced vs OrderCreated) | Choose most natural past-tense business term | | Event table ordering | Chronological order of business flow | | Business Rule description granularity | One sentence per rule, expand only if ambiguous |

Orchestrator Mode Exception

When invoked by an orchestrator (full-ddd, iterating-ddd, piloting-ddd, restructuring-ddd, importing-technical-solution) in Autonomous Mode, the interactive Q&A steps (1-4) are replaced by autonomous execution:

• Skip iterative human Q&A. Instead, derive the complete events table (including failure/compensating events) in a single pass from the input requirements.
• Apply STOP/ASSUME protocol: STOP for Phase 1 STOP triggers (above), ASSUME & RECORD for Phase 1 ASSUME items (above).
• Persist the events table immediately (Step 6). Do NOT wait for human approval — the orchestrator manages the approval gate.
• Return the events table to the orchestrator. If STOP was triggered, return the STOP reason instead.

This exception applies ONLY when dispatched as a subagent by an orchestrator. When invoked standalone (user directly asks for event extraction), the full interactive Q&A session is mandatory.

Implementation (Interactive Q&A Session)

CRITICAL RULE: Do NOT just generate the final table and stop. You must guide the user through an interactive, step-by-step extraction process.

1. Acknowledge & Analyze: Summarize business goal, ask clarifying questions if ambiguous.
2. First Draft: Propose initial Domain Events. Ask: "Does this cover the main happy path? What happens if [edge case] fails?"
3. Iterative Refinement: Extract Actor → Command → Event (past-tense) → Business Rules with the user. Enforce past-tense naming (PaymentReceived not ProcessPayment).

Minimum Completeness Criteria: The extraction round is sufficient when: (a) every identified happy-path event has at least one corresponding failure/compensating event, (b) every Actor appears in at least one Command, and (c) the Business Rules column is non-empty for every event row. In Autonomous Mode, apply these criteria as a self-check; in Interactive Mode, present the checklist to the user for confirmation.

1. Failure Paths: Explicitly ask about failure scenarios and compensating events. Do not only map the happy path.
2. Final Table: Output approved results as a Markdown table (see example below).
3. Persist to Filesystem: After user approval, write the complete Domain Events Table (including failure/compensating events and key Q&A decisions from this session) to docs/ddd/phase-1-domain-events.md. Use the template from ../full-ddd/templates/phase-1-domain-events.md (read the template file; populate fields from session output). Update docs/ddd/ddd-progress.md Phase 1 status to complete. Append key decisions to docs/ddd/decisions-log.md. This step is mandatory — do not skip even if the table is already visible in the conversation.

Example Output Table

| Actor | Command | Domain Event | Business Rules / Invariants | | :-------------- | :---------------- | :------------------ | :--------------------------------- | | Customer | Submit Checkout | CartCheckedOut | Cart must not be empty. | | System | Reserve Inventory | InventoryReserved | Sufficient stock must exist. | | System | Reserve Inventory | InventoryShortage | Triggers if stock is insufficient. | | Payment Gateway | Authorize Payment | PaymentAuthorized | Payment details must be valid. |

NEXT STEP: → [mapping-bounded-contexts](../mapping-bounded-contexts/SKILL.md)

Loading Guidance

Do not preload — load on demand:

• Step 2 (identify business actions): read [event-extraction-reference.md](./event-extraction-reference.md) § Extraction Methodology for verb identification and past-tense conversion.
• Step 3-4 (actors + business rules): read [event-extraction-reference.md](./event-extraction-reference.md) § Common Pitfalls and § Worked Example when encountering ambiguous event granularity.
• On first STOP/ASSUME decision: read ../ddd-protocol/ambiguity-handling-reference.md.
• Step 6 persist: read template from ../full-ddd/templates/phase-1-domain-events.md.

Self-Check Protocol

Follow the [Persistence Defense Reference](../ddd-protocol/persistence-defense-reference.md) after Step 6, with this context-specific item 4:

1. Phase 1 Artifact Exists: Verify docs/ddd/phase-1-domain-events.md exists and contains the approved events table.

If the check fails → STOP. Write the missing file. Do NOT proceed to Phase 2.

Note: This skill has no platform hooks. When invoked by an orchestrator ([full-ddd](../full-ddd/SKILL.md), [iterating-ddd](../iterating-ddd/SKILL.md), [piloting-ddd](../piloting-ddd/SKILL.md), [restructuring-ddd](../restructuring-ddd/SKILL.md), [importing-technical-solution](../importing-technical-solution/SKILL.md)), the orchestrator's hooks provide Layer 1 defense. When invoked standalone, this Self-Check Protocol (Layer 2) is the primary defense.

Session Recovery

If a Phase 1 session is interrupted:

1. Check docs/ddd/ddd-progress.md — read Phase 1 status.
2. If docs/ddd/phase-1-domain-events.md exists and is complete (contains a Domain Events table with Commands, Events, Actors, and Business Rules columns all populated, including failure/compensating events): Phase 1 is done. Proceed to Phase 2.
3. If phase-1-domain-events.md exists but is partial (missing columns, missing failure paths, or only some requirement sections processed): Read the file to determine which PRD requirement sections have been processed vs remaining. Resume extraction from the first unprocessed requirement section.
4. If phase-1-domain-events.md does not exist: Start Phase 1 from the beginning (Step 1).
5. Always re-read the PRD input (the source document provided by the user) before resuming — it is the input artifact and may have been updated.

Run sh skills/full-ddd/scripts/session-recovery.sh for a quick status report.

Rationalization Table

If you catch yourself thinking any excuse in the left column — STOP and re-read the Reality column.

| Excuse | Reality | |:---|:---| | "Requirements are obvious, skip EventStorming" | "Simple" requirements hide edge cases. Registration alone has: email conflicts, rate limiting, verification expiry, re-registration. | | "Design doc makes EventStorming redundant" | Design docs describe HOW to build. EventStorming describes WHAT happened in the business. Design docs miss failure paths. | | "EventStorming is for complex domains only" | No complexity threshold. Every feature has happy paths AND failure paths. | | "Pragmatism — just start coding" | Gambling your mental model is complete. EventStorming takes 30 min; debugging missed failures takes days. | | "Defer to the architect" | Authority does not override extraction. The design doc is input TO EventStorming, not a replacement. | | "Add failure events later / TODO" | Failure events are foundational domain facts. Gaps cascade through all downstream phases. | | "Avoid social friction with PO" | An incomplete events table is a professional failure. Insisting on failure paths is your responsibility. | | "We can always come back" | "Coming back" never happens. The next phase consumes the events table as-is. | | "The whole team agrees to skip it" | Team consensus does not override mandatory process. Democratic votes cannot make an incomplete events table complete. | | "This ambiguity doesn't matter, no need to record it" | Every unrecorded assumption is invisible technical debt. If wrong, it cascades downstream. Record it. | | "STOP is too disruptive, I'll finish the table first" | A STOP-level wrong assumption means redoing Phase 1 and all downstream phases. Pausing 30 seconds costs nothing. | | "The events table is visible in the conversation — persistence is done" | Conversation-visible ≠ persisted. The Self-Check Protocol verifies docs/ddd/phase-1-domain-events.md exists on the filesystem. If the file is not written, downstream phases cannot read it — they have zero access to this conversation's context. | | "Event names are clear — Business Rules column can be sparse" | Without rules, Phase 2 has no invariants to cluster on, Phase 6 has no constraints to enforce. Every event needs explicit business rules. | | "These events are related — combine into one aggregate event" | One transition = one event; merged events hide independent failure boundaries and produce incorrect downstream phase granularity. | | "Actor is 'System' for all automated events" | "System" is not an actor — it hides who AUTHORIZES the automated action. An auto-approval policy is owned by someone (underwriting, risk management, product); a routing rule is configured by someone. STOP and ask: "Who sets this threshold / owns this policy?" The answer determines Phase 2 bounded context boundaries. Name the business authority, not the execution mechanism. |

Red Flags — STOP and Restart Extraction

If you catch yourself thinking "requirements are obvious enough to skip", "the design doc covers it", "EventStorming is for complex domains only", "pragmatism — just start coding", "defer to the architect", "add failure events later", "avoid social friction with PO", "we can always come back", "the events table is visible in conversation — skip writing the file", "the whole team agrees to skip it", "this ambiguity doesn't matter", "STOP is too disruptive", "PRD already has an event list — use directly", "API spec events are sufficient", "state transitions don't need events", "technical events count as domain events", "one event per command is sufficient", "events can be added incrementally during coding", "the event naming convention doesn't matter", "commands and events are interchangeable terms", or "compensation events are edge cases — skip them" — STOP. No code. No schemas. Run the full EventStorming extraction first. Persist the artifact immediately.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lockp111
• Source: lockp111/agent-ddd-engineering
• License: MIT

Install and usage instructions live in the source repository linked above.