Skip to content

Commit c6bdb08

Browse files
nikmaniatisnikmaniatis
committed
v1.0.0
0 parents  commit c6bdb08

34 files changed

+2499
-0
lines changed

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
venv
2+
.DS_Store

‎docs/ai/narrative-generation.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# From Journey to Narrative
2+
3+
## Overview
4+
5+
Experience Notation provides a rich, structured representation of user journeys. With large language models (LLMs), you can convert these formal models into engaging narratives, first-person stories, or UX case studies.
6+
7+
This guide explains how to prompt LLMs to generate natural language outputs based on `.expn` journeys, maintaining fidelity to personas, context, and emotional tone.
8+
9+
---
10+
11+
## Why Generate Narratives from `.expn`?
12+
13+
* Translates structured design into human-readable form
14+
* Useful for stakeholders, usability reporting, or storytelling
15+
* Captures the lived experience from the perspective of defined personas
16+
* Helps explore emotional and behavioural impact
17+
18+
---
19+
20+
## Prompt Strategy: Convert Journey to First-Person Story
21+
22+
Provide the LLM with a valid Experience Notation file and ask it to retell the journey from the perspective of one of the defined personas.
23+
24+
### Example Prompt: Journey to Narrative
25+
26+
```plaintext
27+
Below is an Experience Notation journey. Write a short first-person story from the point of view of the persona involved in the steps.
28+
29+
Experience Notation:
30+
31+
Persona: Returning Customer
32+
Traits: { loyalty=medium, patience=low }
33+
Experience: Wants a quick resolution after recent issues
34+
35+
Event: Reopen Account
36+
Step: Visit site
37+
User: Returning Customer
38+
Action: Opens the homepage
39+
UI-Element: Home
40+
41+
Step: Enter credentials
42+
User: Returning Customer
43+
Action: Types username and password
44+
UI-Element: Login Form
45+
46+
Step: Locked out
47+
User: Returning Customer
48+
Action: Encounters account lock message
49+
UI-Element: Modal Dialog
50+
51+
Step: Contact support
52+
User: Returning Customer
53+
Action: Sends support request
54+
UI-Element: Contact Form
55+
56+
Step: Receives email
57+
User: Returning Customer
58+
Action: Gets response with unlock link
59+
UI-Element: Email
60+
```
61+
62+
### Expected Output
63+
64+
```plaintext
65+
"I just wanted to check my order status, but when I logged in, I was locked out. The warning popped up without explanation. I felt frustrated — I’ve had issues before. I used the support form, hoping someone would respond quickly. Thankfully, an email arrived not long after with a link. At least this time it worked."
66+
```
67+
68+
---
69+
70+
## Tips
71+
72+
* Include only the relevant persona’s actions and traits
73+
* Maintain first-person voice and align tone with `Experience:` and `Metrics:` fields
74+
* Remove technical syntax from the prompt (e.g., block headers) if needed for more natural phrasing
75+
* Encourage storytelling that maps step-by-step onto the journey
76+
77+
---
78+
79+
## Extended Use: Generate Summaries for Stakeholders
80+
81+
In addition to stories, you can prompt the model to generate:
82+
83+
* Executive summaries of the journey
84+
* Persona-specific walkthroughs
85+
* Narrative UX case studies
86+
87+
---
88+
89+
## Prompt Example: Generate an Empathy-Focused Summary
90+
91+
```plaintext
92+
Here is an `.expn` journey. Summarise the user's experience with empathy, highlighting their emotional reactions at each step.
93+
94+
[Insert Experience Notation content here]
95+
```
96+
97+
---
98+
99+
This concludes the AI & LLM Integration section. Return to the [Tutorials](../tutorials/syntax-primer.md) to explore more foundational modelling examples.

‎docs/ai/roleplay.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Roleplaying Personas with LLMs
2+
3+
## Overview
4+
5+
Experience Notation enables LLMs to participate in structured roleplaying by anchoring behaviour, traits, and emotional context within a formal model. This guide focuses on prompting LLMs to **act out roles inside journeys**, using complete `.expn` files that include both `Persona:` blocks and related `Event:` steps.
6+
7+
Unlike basic persona prompts, this approach places characters inside a sequence of experiences — making their reactions, decisions, and expressions more grounded and meaningful.
8+
9+
---
10+
11+
## Why Roleplay Inside `.expn`?
12+
13+
* Adds believability and depth to user modelling
14+
* Supports simulations, usability walkthroughs, and agent testing
15+
* Anchors behaviour to concrete steps and UI interactions
16+
* Promotes consistency across multi-step flows
17+
18+
---
19+
20+
## Prompt Strategy: React Within a Step
21+
22+
Ask the model to respond from the perspective of a persona *at a specific step* of a journey.
23+
24+
### Example Prompt: Simulate Step Experience
25+
26+
```plaintext
27+
Here is an Experience Notation journey:
28+
29+
Persona: Apprehensive Student
30+
Traits: { tech_savvy=false, age=17 }
31+
Experience: Nervous about using online platforms
32+
33+
Event: Course Onboarding
34+
Step: Start registration
35+
User: Apprehensive Student
36+
Action: Visits course portal
37+
UI-Element: Landing Page
38+
39+
Prompt:
40+
As the persona above, describe how they feel in the 'Start registration' step.
41+
```
42+
43+
### Sample Output
44+
45+
```plaintext
46+
"I’m unsure where to begin. There’s a lot going on visually, and I worry I might click the wrong thing."
47+
```
48+
49+
---
50+
51+
## Prompt Strategy: Roleplay Conversation from Journey
52+
53+
Provide a `.expn` with at least two personas and a relevant `Event:` block. Then ask the model to simulate a realistic interaction based on the journey.
54+
55+
### Example Prompt: Dialogue Simulation from Journey
56+
57+
```plaintext
58+
Experience Notation:
59+
60+
Persona: Support Agent
61+
Traits: { empathy=high }
62+
Experience: Calm and professional
63+
64+
Persona: Confused User
65+
Traits: { tech_savvy=false }
66+
Experience: Lost in the navigation process
67+
68+
Event: Request Assistance
69+
Step: User opens help window
70+
User: Confused User
71+
Action: Clicks on the help button
72+
UI-Element: Header Navigation
73+
74+
Step: Agent engages
75+
User: Support Agent
76+
Action: Starts a live chat greeting
77+
UI-Element: Chat Window
78+
79+
Prompt:
80+
Write a realistic conversation between these two personas during the 'Request Assistance' event.
81+
```
82+
83+
84+
### Sample Output
85+
86+
```plaintext
87+
Chat Window – Live Support Conversation
88+
89+
Support Agent:
90+
Hello there! You’re through to course support. I’m here to help — what seems to be the trouble today?
91+
92+
Confused User:
93+
Hi, sorry… I’m trying to register for a course, but I can’t figure out where to go. The page has so many buttons and I’m not sure what I’m doing.
94+
95+
Support Agent:
96+
That’s absolutely fine — you’re not the only one who feels that way. I’ll guide you through it step by step. Could you tell me what you see on your screen right now?
97+
98+
Confused User:
99+
There’s a big banner at the top, and some menu links. I clicked something earlier and it took me to a different page, but now I can’t find where I was.
100+
101+
Support Agent:
102+
No worries — let’s get you back on track. Look at the top of the page; do you see a menu item that says “Courses” or “Register”? Confused User: Yes! There’s a “Courses” tab.
103+
104+
Support Agent:
105+
Perfect. Please hover your mouse over that and a drop-down menu should appear. You’ll want to click “New Student Registration”.
106+
107+
Confused User:
108+
Okay… I clicked it. Yes, now it says “Step 1: Create an Account”.
109+
110+
Support Agent:
111+
Brilliant — you’re in the right place. From here, just fill in your name and email, and let me know if anything is unclear along the way. I’m right here with you.
112+
113+
Confused User:
114+
Thank you… I really wasn’t sure what to do. This helps a lot.
115+
116+
Support Agent:
117+
You’re very welcome — take your time, and don’t hesitate to message me again if you get stuck. You’ve got this.
118+
119+
```
120+
121+
---
122+
123+
## Tips for Effective Roleplay
124+
125+
* Always pair `Persona:` with related `Event:` and `Step:` context
126+
* Use `Experience:` and `Metrics:` to influence tone and sentiment
127+
* Ask the model to focus on a single step or simulate transitions
128+
* Use `Adaptation:` to reflect behavioural evolution over time
129+
130+
---
131+
132+
Continue to [Generating Narrative From Journeys](narrative-generation.md) to explore how `.expn` models can be created directly through structured prompt engineering.

‎docs/ai/structured-prompting.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Generating Experience Notation Journeys with LLMs
2+
3+
## Overview
4+
5+
Structured prompting refers to crafting LLM prompts that guide the model to return predictable, well-formed outputs. Experience Notation is particularly suited for this purpose thanks to its consistent block syntax, defined EBNF grammar, and human-readability.
6+
7+
This guide demonstrates how to prompt large language models to produce `.expn` journeys directly.
8+
9+
---
10+
11+
## Why Use Experience Notation in Prompts?
12+
13+
* Encourages models to produce structured, multi-step outputs
14+
* Helps LLMs represent flows, personas, and decision logic
15+
* Reduces the ambiguity of natural language-only tasks
16+
* Can be validated against the [EBNF grammar](../spec/ebnf.md)
17+
18+
---
19+
20+
## Prompt Strategy: Providing Structure
21+
22+
LLMs respond more accurately when the output format is suggested explicitly.
23+
24+
Including the [full EBNF grammar](../spec/ebnf.md) or a simplified form of the Experience Notation structure can:
25+
26+
* Reduce hallucinated fields
27+
* Improve field ordering and indentation
28+
* Help the model understand block hierarchy
29+
30+
### Option A: Full EBNF Embedding
31+
32+
💡 **Recommended when tokens are not an issue.**
33+
Include the complete EBNF specification in the prompt for maximum structural fidelity.
34+
35+
```plaintext
36+
You are a UX modeller. Generate an Experience Notation journey from the scenario below.
37+
Use the EBNF grammar that follows to guide the structure.
38+
39+
Scenario:
40+
A new user signs up, verifies their email, and logs into the platform.
41+
42+
---
43+
EBNF Specification:
44+
[Insert full EBNF grammar here]
45+
```
46+
47+
### Option B: Minimal Format Hint
48+
49+
Use a format hint like this at the end of your prompt:
50+
51+
```plaintext
52+
Each step follows this structure:
53+
Step:
54+
User: [persona name]
55+
Action: [what the user does]
56+
UI-Element: [interface they interact with]
57+
Conditional:
58+
IF: [condition]
59+
THEN: [result]
60+
ELSE: [alternative result]
61+
```
62+
63+
---
64+
65+
## Prompt Example: Zero-Shot
66+
67+
```plaintext
68+
You are a UX modeller. Describe the following onboarding flow using Experience Notation:
69+
70+
Scenario:
71+
A user visits a website, signs up with email, confirms via email link, and logs in.
72+
73+
Return the output in `.expn` format. Use clear indentation and syntax blocks.
74+
```
75+
76+
### Sample Output
77+
78+
```plaintext
79+
Journey-Title: Basic Onboarding
80+
Journey-Description: A user signs up and logs into the platform
81+
82+
Event: Sign Up
83+
Step: Enter details
84+
User: New Visitor
85+
Action: Fills out name and email
86+
UI-Element: Signup Form
87+
88+
Step: Submit form
89+
User: New Visitor
90+
Action: Clicks "Register"
91+
UI-Element: Signup Form
92+
```
93+
94+
---
95+
96+
## Prompt Example: Few-Shot Completion
97+
98+
```plaintext
99+
Here’s a partial Experience Notation journey. Complete the next event using the same format.
100+
101+
EBNF-Version: 1.1
102+
Syntax-Version: 1.0
103+
Journey-Title: Support Ticket
104+
105+
Event: Submit Issue
106+
Step: Describe problem
107+
User: Frustrated Customer
108+
Action: Types issue into support form
109+
UI-Element: Contact Page
110+
111+
[Continue with next event...]
112+
```
113+
114+
---
115+
116+
## Tips
117+
118+
* Always anchor to `EBNF-Version: 1.1` and `Syntax-Version: 1.0` if possible
119+
* Use delimiters or triple backticks to frame outputs
120+
* Be specific about persona names and UI interactions
121+
* When tokens allow, embed the full EBNF grammar
122+
* Start with a minimal version for lightweight prompting, then scale
123+
124+
---
125+
126+
Continue to [Roleplaying Personas](roleplay.md) to explore how Experience Notation enables agent simulation.

‎docs/assets/images/hero.jpg‎

2.38 MB
Loading

‎docs/assets/images/hero.png‎

2.38 MB
Loading

‎docs/assets/images/logo.png‎

674 KB
Loading

0 commit comments

Comments
 (0)