Skip to content

Commit c99c69d

Browse files
committed
refactor: Ruthlessly trim redundancies from user testing docs
Remove ~40 lines of redundant content: AgentScript template: 6 lines → 2 lines (environment section) Constraints: 7 lines → 4 lines (removed overlapping statements) docs: Removed 4 redundant 'discover UI' explanations (kept 2 key mentions) docs: Removed 4 excessive '3-5 users' references (kept Nielsen research + final note) docs: Condensed 'Run AI Agent Tests' from 10 lines to 1 paragraph Token savings: ~700 tokens Principle: Perfection is attained when there is nothing more to remove.
1 parent 83d98cb commit c99c69d

File tree

2 files changed

+16
-35
lines changed

2 files changed

+16
-35
lines changed

ai/rules/user-testing.mdc

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -40,12 +40,8 @@ AgentScript:template {
4040
"""
4141
# Agent Test: ${journey.name}
4242

43-
**Environment**: Drive a real browser like a human would
44-
- Use built-in browser (IDE browser, Chrome, etc.)
45-
- Discover UI without source code access (look at page to figure out what to click)
46-
- Navigate and interact with actual UI as a user would
47-
- Click, type, scroll through real DOM elements
48-
- Capture screenshots from browser viewport
43+
**Environment**: Drive real browser (IDE, Chrome) like a human
44+
- Discover UI by looking (no source code access), click/type/scroll, capture screenshots
4945

5046
**Persona behavior**:
5147
- Patience: ${persona.patience}/10
@@ -72,11 +68,8 @@ generateScripts(journey) => human + agent templates with persona-mapped behavior
7268
/run-test <script> - Execute agent script with screenshots
7369

7470
Constraints {
75-
AI agents drive real browser like humans (no source code access, discover UI by looking)
76-
NOT automation frameworks (Playwright/Puppeteer require pre-knowledge of selectors)
77-
Agent behavior reflects persona traits (patience → retries, techLevel → strategy)
78-
Execution varies between runs (stochastic, not deterministic)
79-
Capture screenshots from real browser viewport
80-
Both scripts validate identical success criteria against real rendered UI
81-
Agents validate UI discoverability, not just technical functionality
71+
Agents discover UI by looking (no source code/automation frameworks)
72+
Persona traits → behavior (patience → retries, techLevel → strategy)
73+
Stochastic execution (varies between runs)
74+
Both scripts validate identical success criteria
8275
}

docs/user-testing.md

Lines changed: 10 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -41,13 +41,10 @@ For manual testing with real people:
4141

4242
### 2. AI Agent Test Script
4343
For automated testing with AI using **real browsers**:
44-
- AI drives browser like a human (built-in IDE browser, Chrome, etc.)
45-
- **Discovers UI without source code access** - figures out what to click by looking at the page
46-
- Interacts with real UI by clicking, typing, scrolling
47-
- Screenshot capture at checkpoints from browser viewport
48-
- Persona-based behavioral variation
44+
- Drives browser like a human, discovers UI by looking (no source code access)
45+
- Screenshots at checkpoints, persona-based behavior
4946

50-
**Why not Playwright/Puppeteer?** Those frameworks require pre-existing knowledge of selectors (`page.click('#submit')`). AI agents discover the UI the same way users do - by looking at what's visible - validating that your UI is actually discoverable and understandable.
47+
**Why not Playwright/Puppeteer?** Those frameworks require pre-existing knowledge of selectors (`page.click('#submit')`). AI agents discover the UI the same way users do - validating that your UI is actually discoverable.
5148

5249
Both scripts test the **same journey** with **identical success criteria**, allowing you to:
5350
- Compare human vs. AI agent behavior
@@ -101,7 +98,7 @@ This outputs:
10198

10299
### 3. Run Human Tests
103100

104-
Recruit 3-5 participants matching your persona:
101+
Recruit participants matching your persona:
105102

106103
1. **Setup**: Screen recording software, test environment
107104
2. **Brief**: Explain think-aloud protocol (say what you're thinking)
@@ -115,23 +112,14 @@ Recruit 3-5 participants matching your persona:
115112
/run-test checkout-journey-agent.md
116113
```
117114

118-
AI agents drive a real browser like a human would:
119-
- Navigate to your application in a browser
120-
- **Discover what's on the page without privileged access to source code**
121-
- Click, type, scroll through actual UI elements based on what they see
122-
- Execute the journey with persona-based behavior
123-
- Capture screenshots from browser viewport at checkpoints and failures
124-
- Generate feedback on difficulty and expectations
125-
- Report blockers and completed steps
126-
127-
**Important**: Agents have no pre-existing knowledge of your UI - they figure out what to click the same way a real user does. This validates that your interface is actually discoverable, not just technically functional.
115+
Agents discover what to click by looking (no source code access), execute the journey with persona-based behavior, and capture screenshots at checkpoints/failures. This validates UI discoverability, not just technical functionality.
128116

129117
### 5. Compare & Iterate
130118

131119
- **Review human videos** for genuine confusion and unexpected behavior
132120
- **Review agent reports** for systematic failures and patterns
133121
- **Fix the highest-impact issues** (severity × frequency)
134-
- **Test again** with a new batch of 3-5 users
122+
- **Test again**
135123

136124
## Best Practices
137125

@@ -233,10 +221,10 @@ This cadence beats testing with 20 users once.
233221

234222
### Combining Human + Agent Tests
235223

236-
1. **Initial discovery**: 3-5 human tests to find major issues
224+
1. **Initial discovery**: Human tests to find major issues
237225
2. **Verify fixes**: AI agent tests after each fix
238226
3. **Regression testing**: AI agents test all journeys before releases
239-
4. **Validation**: 3-5 human tests to confirm fixes landed
227+
4. **Validation**: Human tests to confirm fixes landed
240228

241229
## Resources
242230

@@ -248,9 +236,9 @@ This cadence beats testing with 20 users once.
248236

249237
1. Create your first user journey with `/discover`
250238
2. Generate test scripts with `/user-test`
251-
3. Run 3-5 human tests
239+
3. Run human tests
252240
4. Fix the highest-impact issues
253241
5. Validate fixes with AI agent tests
254242
6. Iterate
255243

256-
Remember: **Small, frequent testing beats large, infrequent testing.** Start today with just 3 users.
244+
Remember: **Small, frequent testing beats large, infrequent testing.**

0 commit comments

Comments
 (0)