# Tutorial UX Review — nWave CLI

**Date**: 2026-02-17
**Reviewer**: Luna (nw-product-owner)
**Input**: Tutorial best practices research + grojas123 incident analysis
**Status**: Approved with recommendations

---

## Context: What Happened to grojas123

User followed `tutorial-first-feature.md`, typed `/nw:discuss "user login with email and password"`.
nWave correctly interpreted this as a full feature: 20 TDD steps, 4 phases, 5 ADRs.
User got through 6 of 20 steps in 33 minutes, thought it was stuck, gave up.

Key quotes:
- "Claude not stopped to do things"
- "Instructions must be more specific to get first results faster"

---

## Validation of 10 Research Principles

All 10 principles are UX-sound. Four are violated by the current tutorial:

| Principle | Current Status | Issue |
|-----------|---------------|-------|
| 1. <5 min visible result | VIOLATED | 33 min for one feature |
| 2. Lead with examples | OK | Commands are clear |
| 3. Copy-pasteable commands | OK | Works as-is |
| 4. Progressive levels | VIOLATED | Jumps straight to complex feature |
| 5. Show expected output | VIOLATED | No interim output shown during /nw:deliver |
| 6. Minimize prerequisites | OK | One pipx install |
| 7. --help as guide | UNKNOWN | Not audited |
| 8. Errors as teaching | VIOLATED | No explanation for async silence |
| 9. Test tutorials in CI | UNKNOWN | Not implemented |
| 10. Measure TTFHW | MISSING | No telemetry |

---

## The Unique Challenge: Async AI Agents

nWave has a fundamentally different execution model than traditional CLI tools:

```
Traditional:  User runs command → Output in 2 sec → Done
nWave:        User runs command → Agent starts → [SILENCE 20-30 sec] → Output → Approve → Next
```

This breaks the standard feedback loop. Users interpret silence as failure.

### Solution: Sub-5-second feedback loops

Each long-running wave should emit streaming progress events so the user never waits more than 5 seconds without feedback.

---

## Three Missing UX Elements

### Gap A: "Is It Stuck?" Problem
The `/nw:deliver` command runs for 20+ minutes with no interim feedback. User has no way to distinguish "still working" from "hung" from "error occurred".

**Fix**: Emit progress events after each TDD phase (PREPARE, RED, GREEN, COMMIT).

### Gap B: No Progressive Complexity
Tutorial jumps from zero to full-stack login (20 steps, 33 min). No intermediate stepping stone.

**Fix**: Add a 2-minute "Hello, nWave" tutorial before the login tutorial.

### Gap C: No Expected Output at Checkpoints
Step 4 (`/nw:deliver`) doesn't tell the user what they should see or how long to wait.

**Fix**: Add expected output blocks and timing estimates at every checkpoint.

---

## Recommendations (Priority Order)

### Immediate (1-2 Days)

1. **Create "Hello, nWave" tutorial (2 min)**
   - Micro-feature: "greet user by name"
   - Same workflow as login tutorial but trivial scope
   - User succeeds quickly, gains confidence

2. **Add "Why Is It Quiet?" guide**
   - Explains async agent behavior
   - Shows how to monitor progress
   - Links from tutorial Step 4

3. **Add expected outputs to every checkpoint**
   - What files get created
   - What the output looks like
   - How long each step takes

### Short-term (This Week)

4. **Emit progress events from /nw:deliver**
   - Event after each TDD phase
   - To stdout and to `.nwave/delivery-progress.log`

5. **Create starter edition of login tutorial**
   - Option A: Minimal login (3 min, hardcoded, teaches TDD pattern)
   - Option B: Full login (33 min, teaches complete workflow)

### Medium-term (Next Sprint)

6. **Test tutorials in CI** — run exact steps, verify output
7. **Measure TTFHW** — telemetry on command start/completion times

---

## Key Insight

The fix is not to redesign the framework. It's to add better UX scaffolding:
1. A 2-minute win before the 33-minute deep dive
2. Progress feedback during long-running operations
3. Clear expectations at every checkpoint

These require no changes to the core framework — just better documentation and progress reporting.
