| name | slice-scenarios |
| description | Slice Scenarios Skill - Guide for writing Given-When-Then scenarios in slice details. Covers scenario structure, element references, YAML data patterns, and best practices for documenting behavior. Use this skill when tasked to add user stories or Given-When-Then (GWTs) scenarios to a chapter on prooph board. |
Slice Scenarios Skill - Writing Given-When-Then Scenarios for Slices
This document describes how to write effective slice scenario documentation in prooph board, based on analysis of real-world modeling examples.
Overview
Slice scenarios document the behavior and business rules for a specific step in the process. They use a Given-When-Then format to describe:
- What state exists before (Given)
- What action happens (When)
- What state/results after (Then)
Scenarios are written in the slice details and are visible to all users including non-technical business stakeholders.
Structure Template
Basic Scenario Structure
```markdown
### Scenario: [Scenario Title]
As a [role], I want to [action]
to [benefit].
#### Given
[Pre-condition state]
#### When
:::element [type]
[Element Name]
```yaml
[data payload]
```
:::
#### Then
:::element [type]
[Element Name]
```yaml
[result state]
```
:::
Element References in Scenarios
Use the :::element directive to reference elements in the slice:
Syntax
```markdown
:::element [elementType]
[Element Name]
```yaml
[data]
```
:::
Supported Element Types
| Type | Example |
|---|
command | User/system action |
event | Business fact |
information | Data/state |
ui | User interface |
hotspot | Warning/error state |
automation | Automated process |
Complete Examples from a Time Tracking Model
Example 1: Happy Path Scenario (Clock In)
```markdown
### Scenario: Start Work Day Time Tracking
As an employee, I want to clock in at the beginning of the work day
to start a new time tracking session.
#### Given
A new work day: `2026-03-05`
#### When
:::element command
Clock In
```yaml
employee: Anna
location: loc-abc
```
:::
#### Then
:::element event
Employee Clocked In
```yaml
trackingId: track1
employee: Anna
location: loc-abc
day: 2026-03-05
startTime: 9am
```
:::
Why it works:
- Clear user story format
- Simple given condition
- Shows command input and event output
- Uses concrete example data
Example 2: Error/Edge Case Scenario
```markdown
### Scenario: Time Tracking already started
As an employee, I cannot have more than one active time tracking sessions.
#### Given
:::element event
Employee Clocked In
```yaml
trackingId: track1
employee: Anna
location: loc-abc
day: 2026-03-05
startTime: 9am
```
:::
#### When
:::element command
Clock In
```yaml
employee: Anna
location: loc-abc
```
:::
#### Then
:::element hotspot
Time Tracking is already running
```yaml
employee: Anna
location: loc-abc
```
:::
Why it works:
- Documents business rule (no duplicate sessions)
- Shows error state with hotspot
- Same given/when as happy path, different then
Example 3: Access Control Scenario
```markdown
### Scenario: Cannot view other time tracking
As an employee, I'm not allowed to view other's time tracking
#### Given
`Employee: Anna`
:::element event
Employee Clocked In
```yaml
trackingId: track1
employee: Bob
location: loc-abc
day: 2026-03-05
startTime: 9am
```
:::
#### Then
:::element hotspot
Access Denied
```yaml
reason: You don't have permission to view this time tracking.
```
:::
Why it works:
- Documents security/authorization rule
- Uses inline variable declaration (
Employee: Anna)
- Shows denied access with reason
Example 4: Multiple Given Events
```markdown
### Scenario: Clock In After Break
As an employee, I want to clock in again after my break
to continue tracking my work time.
#### Given
:::element event
Employee Clocked In
```yaml
trackingId: track1
employee: Anna
location: loc-abc
day: 2026-03-05
startTime: 9am
```
:::
:::element event
Employee Clocked Out For Break
```yaml
trackingId: track1
# ...
breaks:
-
startTime: 1pm
endTime: ?
```
:::
#### When
:::element command
Clock In After Break
```
trackingId: track1
```
:::
#### Then
:::element event
Employee Clocked In After Break
```yaml
trackingId: track1
# ...
breaks:
-
startTime: 1pm
endTime: 1:30pm
```
:::
Why it works:
- Shows accumulated state from multiple prior events
- Uses
# ... to indicate unchanged data
- Uses
? to indicate future values
- Demonstrates how GIVEN section can contain multiple events that build up the current state
Example 5: Idempotent Operation Scenario
```markdown
### Scenario: Already clocked out for break
#### Given
:::element event
Employee Clocked In
```yaml
trackingId: track1
employee: Anna
location: loc-abc
day: 2026-03-05
startTime: 9am
```
:::
:::element event
Employee Clocked Out For Break
```yaml
trackingId: track1
# ...
breaks:
-
startTime: 1pm
endTime: ?
```
:::
#### When
:::element command
Clock Out For Break
```
trackingId: track1
```
:::
#### Then
silently ignore clock out for break
Why it works:
- Documents idempotent behavior
- Multiple given events show accumulated state
- Plain text then (no element) for simple behavior
Example 6: Failed Operation Scenario
```markdown
### Scenario: No active time tracking session
#### Given
:::element event
Employee Clocked In
```yaml
trackingId: track1
employee: Anna
location: loc-abc
day: 2026-03-05
startTime: 9am
```
:::
:::element event
Employee Clocked Out at Workday End
```yaml
trackingId: track1
endTime: 6pm
```
:::
#### When
:::element command
Clock Out For Break
```
trackingId: track1
```
:::
#### Then
:::element hotspot
Failed to clock out for break
```yaml
reason: no active time tracking session found
```
:::
Why it works:
- Shows invalid state transition
- Documents error message
- Explains why operation failed
Example 7: Complex State Scenario
```markdown
### Scenario: View active Time Tracking
As an employee, I want to view my active time tracking session.
#### Given
:::element event
Employee Clocked In
```yaml
trackingId: track1
employee: Anna
location: loc-abc
day: 2026-03-05
startTime: 9am
```
:::
:::element event
Employee Clocked Out For Break
```yaml
trackingId: track1
# ...
breaks:
-
startTime: 1pm
endTime: ?
```
:::
#### Then
:::element information
Time Tracking
```yaml
trackingId: track1
employee: Anna
location: loc-abc
day: 2026-03-05
startTime: 9am
breaks:
-
startTime: 1pm
endTime: ?
```
:::
Why it works:
- Shows accumulated state from multiple events
- Documents what information is available
- Shows projected/read model state
YAML Data Patterns
Pattern 1: Complete State Snapshot
trackingId: track1
employee: Anna
location: loc-abc
day: 2026-03-05
startTime: 9am
Use when: Documenting full entity state
Pattern 2: Partial State with Ellipsis
trackingId: track1
breaks:
-
startTime: 1pm
endTime: ?
Use when: Only showing changed fields, # ... indicates unchanged data
Pattern 3: Dynamic Values
day: now()|date()
startTime: now()|time()
endTime: now()|time()
Use when: Values are computed at runtime
Pattern 4: Optional Fields
endTime: ?
Use when: Field may or may not exist
Pattern 5: Error/Reason Payload
reason: no active time tracking session found
reason: You don't have permission to view this time tracking.
Use when: Documenting error details
Pattern 6: Inline Variable Declaration
```markdown
`Employee: Anna`
`Date: 2026-03-05`
Use when: Setting context variables for scenario
Pattern 7: ASCII Mock: Add visual context in Given-When-Then scenarios if illustrating the user journey adds value.
```markdown
#### Then
:::element ui
Time Tracking Dashboard
## ASCII Mockup
```bash
┌─────────────────────────────────────┐
│ Time Tracking Dashboard │
├─────────────────────────────────────┤
│ Anna M. | loc-abc | 2026-03-05 │
│ Status: In Progress │
│ Started: 9:00 AM │
├─────────────────────────────────────┤
│ [ Pause ] [ Clock Out ] │
└─────────────────────────────────────┘
```
:::
Use when: Illustrating how the UI state changes as part of the scenario
Pattern 8: Markdown Tables for List/Database State Changes
Use markdown tables to illustrate how list views or database tables change through a scenario:
```markdown
#### Given
| taskId | assignee | status | dueDate |
|--------|----------|------------|------------|
| T-001 | Anna | in_progress| 2026-03-10 |
| T-002 | Bob | open | 2026-03-12 |
#### When
:::element command
Complete Task
```yaml
taskId: T-001
```
:::
#### Then
| taskId | assignee | status | dueDate |
|--------|----------|------------|------------|
| T-001 | Anna | completed | 2026-03-10 |
| T-002 | Bob | open | 2026-03-12 |
Use when: Documenting how a collection or table changes through a scenario
Scenario Types
1. Happy Path
The normal, expected flow:
```markdown
### Scenario: Start Work Day Time Tracking
As an employee, I want to clock in at the beginning of the work day
to start a new time tracking session.
#### Given
A new work day: `2026-03-05`
#### When
[Command]
#### Then
[Success Event]
2. Business Rule Validation
Enforcing domain constraints:
```markdown
### Scenario: Time Tracking already started
As an employee, I cannot have more than one active time tracking sessions.
#### Given
[Active session exists]
#### When
[Duplicate clock in attempt]
#### Then
[Hotspot - already running]
3. Authorization/Access Control
Permission checks:
```markdown
### Scenario: Cannot view other time tracking
As an employee, I'm not allowed to view other's time tracking
#### Given
`Employee: Anna`
[Bob's time tracking event]
#### Then
[Hotspot - Access Denied]
4. Error Handling
Invalid operations:
```markdown
### Scenario: No active time tracking session
#### Given
[Session already ended]
#### When
[Clock out for break attempt]
#### Then
[Hotspot - Failed with reason]
5. Idempotent Operations
Safe retry behavior:
```markdown
### Scenario: Already clocked out for break
#### Given
[Already on break]
#### When
[Clock out for break again]
#### Then
silently ignore clock out for break
6. State Projection
Read model behavior:
```markdown
### Scenario: View active Time Tracking
As an employee, I want to view my active time tracking session.
#### Given
[Multiple events showing state]
#### Then
[Information element with projected state]
Best Practices
1. Use User Story Format
```markdown
✅ Good:
As an employee, I want to clock in at the beginning of the work day
to start a new time tracking session.
❌ Avoid:
User clicks clock in button to start tracking.
2. Keep Scenarios Atomic
Each scenario should test ONE behavior:
```markdown
✅ Good:
### Scenario: Clock Out For Break
### Scenario: Already clocked out for break
### Scenario: No active time tracking session
❌ Avoid:
### Scenario: Clock Out For Break with all edge cases and errors
3. Use Concrete Example Data
```markdown
✅ Good:
```yaml
employee: Anna
location: loc-abc
trackingId: track1
```
❌ Avoid:
```yaml
employeeId: string|format:uuid
locationId: string|format:uuid
```
4. Show State Transitions Clearly
```markdown
✅ Good:
#### Given
[Initial state]
#### When
[Action]
#### Then
[Resulting state]
❌ Avoid:
Mixing given/when/then or skipping sections
5. Use Hotspots for Errors
```markdown
✅ Good:
#### Then
:::element hotspot
Access Denied
```yaml
reason: You don't have permission
```
:::
❌ Avoid:
#### Then
Event: Access Denied (but it's not really an event)
6. Document Both Success and Failure
For each command, consider:
```markdown
✅ Complete:
- Scenario: Successful operation
- Scenario: Invalid state (can't do this now)
- Scenario: Already done (idempotent)
- Scenario: Permission denied
- Scenario: Missing data
7. Use Comments for Unchanged Data
```markdown
✅ Good:
```yaml
trackingId: track1
# ...
breaks:
- startTime: 1pm
```
❌ Avoid:
Repeating all fields when only some changed
8. Use Visual Aids for UI and Data Changes (ask first!)
When illustrating how UI state changes or how lists/tables are affected by a scenario, consider adding visual aids — but always ask the user first:
```markdown
✅ Good (ASCII mockup for UI state change, if user wants it):
#### Then
:::element ui
Time Tracking Dashboard
```bash
┌──────────────────────────┐
│ Status: In Progress │
│ Started: 9:00 AM │
└──────────────────────────┘
```
:::
✅ Good (markdown table for list/database changes):
#### Given
| taskId | status |
|--------|--------|
| T-001 | open |
#### Then
| taskId | status |
|--------|-----------|
| T-001 | completed |
❌ Avoid:
Adding ASCII mockups without asking — user may prefer screenshots or wireframes
Checklist for Writing Slice Scenarios
Common Mistakes
❌ Mistake 1: Missing User Story
```markdown
❌ Bad:
### Scenario: Clock In
#### Given
...
✅ Better:
### Scenario: Start Work Day Time Tracking
As an employee, I want to clock in at the beginning of the work day
to start a new time tracking session.
#### Given
...
❌ Mistake 2: Using Technical Schema
```markdown
❌ Bad:
```yaml
employeeId: string|format:uuid
locationId: string|format:uuid
day: string|format:date
```
✅ Better:
```yaml
employee: Anna
location: loc-abc
day: 2026-03-05
```
❌ Mistake 3: Incomplete Element Reference
```markdown
❌ Bad:
Clock In command with employee data
✅ Better:
:::element command
Clock In
```yaml
employee: Anna
location: loc-abc
```
:::
❌ Mistake 4: Mixing Multiple Behaviors
```markdown
❌ Bad:
### Scenario: Clock In and Clock Out and Handle Errors
✅ Better:
### Scenario: Start Work Day Time Tracking
### Scenario: Clock Out For Break
### Scenario: Time Tracking already started
❌ Mistake 5: No Error Scenarios
```markdown
❌ Bad:
Only happy path documented
✅ Better:
- Happy path
- Already done (idempotent)
- Invalid state
- Permission denied
- Missing data
Scenario Organization in Slice Details
Multiple scenarios in one slice:
```markdown
### Scenario: Clock Out For Break
As an employee, I want to clock out for break during the day
to pause my time tracking.
#### Given
...
#### When
...
#### Then
...
### Scenario: Already clocked out for break
#### Given
...
#### When
...
#### Then
...
### Scenario: No active time tracking session
#### Given
...
#### When
...
#### Then
...
Relationship to Other Documentation
| Documentation | Scope | Purpose |
|---|
| Slice Scenarios | Local to slice | Document behavior for this process step |
| Element Description | Local to element instance | Document what this element does in this context |
| Element Details | Global (all similar elements) | Technical specification (schema, rules, etc.) |
Best Practice: Use slice scenarios to document how elements interact in this specific process step. Keep technical details in element details.
Summary
Slice scenarios are a powerful tool for documenting business behavior in a format that:
- ✅ Is understandable by business stakeholders
- ✅ Uses Given-When-Then format for clarity
- ✅ References elements with
:::element syntax
- ✅ Shows concrete example data in YAML
- ✅ Documents both success and failure paths
- ✅ Captures business rules and constraints
- ✅ Complements element descriptions and details
Remember: Scenarios live in slice details and describe what happens in THIS specific process step with THESE specific elements.
