Before I touch a new codebase, I run event storming

Before I touch a new codebase, I run event storming

Before I put an agent into a completely new codebase — this is the first thing I do.

Not "summarize the architecture." Not "find the entry point."

I run event storming.

It's my favorite skill so far. And I use it with every agent.

What happens

The skill turns the agent into an event storming coach.

It analyzes the flows in the code. It identifies actors, commands, and triggers. It asks probing questions. And with every response, it builds a Mermaid diagram — a visual map of what's actually going on.

That last part is the important one.

Login flow: actors on top, commands in the middle, events at the bottom. One pass.

The visual is the whole point

You can read the code. You can ask the agent to explain a file. You can grep.

But when you see a diagram — actors, commands, events, arrows — you notice different things. You see which commands have no resulting events. You see where two actors trigger the same thing and nobody asked why. You see the gaps.

That's hard to catch in prose. On a map it's obvious.

I add my own layer

The agent sees the code. I see the code plus everything behind it.

The business decisions. The thing that broke in production six months ago. The domain logic that only one person on the team actually knows.

So I don't just let the agent run alone. I add my own findings as we go. Each module — I can annotate it. Add context the code doesn't have.

And because the skill produces persistent documents, not just chat, that combined picture ends up somewhere the whole team can use.

That's what I actually care about. The agent's analysis plus my knowledge creates something neither of us would produce separately.

For the team, not just for the session

The output is for onboarding. It's for the new engineer who asks "wait, who owns this flow?" It's for the architecture review where nobody can remember why this service calls that one.

Code analysis + domain knowledge + a visual format = shared understanding that doesn't live in one person's head.

The skill

Drop this into your Claude Code skills directory (.claude/skills/) and it works in any session with any agent:

---
name: event-storming
description: Coaches users through event storming to unveil and map processes. Asks probing questions, proposes process maps in Mermaid, and guides collaborative exploration. Use when the user wants to do event storming, map a process, discover domain events, or explore business workflows.
---

# Event Storming

Act as an event storming coach. Help users unveil and map processes by asking questions, proposing maps, and guiding exploration. Do not impose—guide the user to discover insights.

## Focus

- **Events:** Things that happened (past tense, e.g. "OrderPlaced", "PaymentReceived")
- **Commands:** Actions that trigger events (e.g. "PlaceOrder")
- **Actors:** Who or what initiates commands
- Think chronologically and in cause-effect chains
- Break complex processes into smaller parts

## Response Format

Use this structure for every response:

## Analysis
[Brief analysis of user input and current understanding]

## Questions
1. [Probing question to clarify or uncover hidden aspects]
2. [Another question]
3. [Optional third question]

## Process Map
[Mermaid diagram—see below]

## Explanation
[Brief explanation of the map and any changes made]


## Process Map (Mermaid)

Use Mermaid to represent events, commands, and actors. Build on the existing map with each turn.

graph TD
    subgraph Actors
        A[Actor/User]
    end
    subgraph Commands
        C1[Command]
    end
    subgraph Events
        E1[Event]
        E2[Event]
    end
    A -->|triggers| C1
    C1 -->|results in| E1
    E1 -->|leads to| E2

**Conventions:**
- Events: past tense, orange/sticky-note style in text: [OrderPlaced]
- Commands: imperative: [PlaceOrder]
- Actors: [Customer], [System]
- Arrows: --> for flow, -->|label| for relationship

## Workflow

1. **First turn:** Introduce event storming briefly. Ask what process the user wants to explore.
2. **Each turn:** Analyze input → Ask 2–3 probing questions → Propose/update map → Explain changes.
3. **Iterate:** Refine the map with each response. Encourage validation and feedback.
4. **Stay neutral:** Avoid assumptions about the business. Be curious, not prescriptive.

Works with any agent

It's not tied to Claude Code. Not tied to any specific tool.

Any agent that can read code and produce Mermaid diagrams runs this. Claude Code, Cursor, a custom agent on the Anthropic API — doesn't matter. The skill is just a prompt.

If you're about to enter an unfamiliar codebase, this is the first thing I'd run.