create-domain-story

Files (1)

• SKILL.md

SKILL.md (first lines)

# Domain Story Creation

## Desired Outcome

Visualize the business process of a specific domain as a narrative using the Domain Storytelling technique. The story is expressed in three elements:

- **Actors** — People, roles, and systems that appear in the story
- **Work Items** — Objects and information handled by actors
- **Activities** — Actions performed by actors (numbered sequence arrows)

Generate one domain story per domain, with a Mermaid sequence diagram and narrative prose.

## Invocation

```
/architect:create-domain-story [--domain=<DomainName>] [--mode=story|event-storming] [--auto]
```

- `--domain` — Target domain name (e.g., `Order`, `Inventory`, `Payment`). Prompted interactively if omitted.
- `--mode` — `story` (default): the seven-stage Domain Storytelling facilitation below. `event-storming`: Stage 4 runs as a Process Modeling EventStorming session — per step the event, the command and its actor, what was read, and the policy that reacts (@rules/product/event-storming.md §3) — and the document gains a Process Model section. Refused under `--auto`: the skill falls back to `story` and says so.
- `--auto` — Skip facilitation and generate automatically from existing analysis files.

## Execution Modes

### Interactive Mode (Default)

Facilitate a 7-stage process through dialogue with the user to elicit the domain story:

**Stage 1 — Setting the Scene**
Ask the user:
- Which domain to focus on (if `--domain` was not specified)?
- What is the scope of this story (a single use case, the main business flow, an exception scenario)?
- Which granularity level: coarse-grained (service level) or fine-grained (user task level)?

**Stage 2 — Actors**
Identify actors from `actors-roles-permissions.md` and present them for confirmation:
- Primary actors (people, user roles)
- Supporting actors (external systems, automated processes)
- Ask: "Are there any actors missing or incorrect?"

**Stage 3 — Work Items**
Identify work items (data, documents, domain objects) relevant to the domain:
- Reference `ubiquitous-language.md` for domain term alignment
- Ask: "What information or objects does each actor handle?"

**Stage 4 — Main Flow**
With `--mode=event-storming`, run the Process Modeling walk of @rules/product/event-storming.md §3
instead — the activities are its commands in event order, the table is the Process Model section
(§4). Otherwise walk through the main (happy path) flow step by step:
- Ask: "What does [Actor] do first?"
- For each step: who does what with which work item, and to whom?
- Assign sequential numbers to activities

**Stage 5 — Exception Scenarios**
Identify alternative and error flows:
- Ask: "What happens when [activity] fails or is not possible?"
- Note up to 3 significant exception paths

**Stage 6 — Technical Context**
Capture system constraints and technical elements:
- Which systems are involved behind the scenes?
- Are there asynchronous operations, batch jobs, or external integrations?
- Are there transaction boundaries relevant to this story?

**Stage 7 — Review and Document**
Summarize the elicited story and confirm with the user:
- Present the draft story for review
- Ask: "Does this accurately reflect how the business works?"
- Incorporate any corrections, then write the output file

### Auto-Generation Mode (`--auto`)

Generate the story automatically from existing analysis files without facilitation. Lower fidelity than interactive mode but suitable for bulk processing of multiple domains.

Steps:
1. Read `reports/03_design/bounded-contexts-redesign.md` — identify BC boundary and contained aggregates
2. Read `reports/01_analysis/actors-roles-permissions.md` — extract actors
3. Read `reports/01_analysis/ubiquitous-language.md` — build a term lookup table from the "Domain Term" column (this header is localized when output_language is not "en"; match the localized equivalent for the configured language)
4. Infer the most plausible main flow from the aggregate lifecycle
5. When naming actors and work items, look up each concept in the term table from step 3 and use the exact term verbatim. Do not invent synonyms or paraphrases.
6. Generate the story document directly

## Prerequisites

| File | Required/Recommended | Source |
|------|---------------------|--------|
| reports/03_design/bounded-contexts-redesign.md | Recommended | /architect:redesign |
| reports/01_analysis/ubiquitous-language.md | Recommended | /architect:analyze |
| reports/01_analysis/actors-roles-permissions.md | Recommended | /architect:analyze |

If none of these files exist, ask the user to provide domain context directly.

## Output

| File | Content |
|------|---------|
| `reports/04_stories/domain-story-{domain}.md` | Domain story — actors, work items, activity flow, Mermaid diagram, exception notes |

`{domain}` is the kebab-case domain name (e.g., `order`, `inventory`, `payment`).

Write all story content in the language configured in `work/pipeline-progress.json` (`options.output_language`). The YAML frontmatter keys remain in English regardless of the output language.

## Output Document Structure

```markdown
---
title: "Domain Story: {Domain}"
schema_version: 1
phase: "Phase 4: Domain Stories"
skill: create-domain-story
generated_at: "ISO8601"
domain: "{domain}"
mode: "interactive|auto"
input_files:
  - reports/03_design/bounded-contexts-redesign.md
  - reports/01_analysis/actors-roles-permissions.md
  - reports/01_analysis/ubiquitous-language.md
---

From Ryuking1228/ai-dev-codex-version, MIT.

More from Ryuking1228/ai-dev-codex-version