# Event State Machine — UX Review

**Date:** 2026-04-29
**Status:** Draft — needs Matt review

---

## Current States (from test data)

| State | Count | Meaning | User Action |
|-------|-------|---------|-------------|
| **confirmed** | 9 | ✅ On the calendar, no action needed | View only |
| **pending** | 3 | ⏳ Not fully committed, needs decision | Confirm / Decline / Modify |
| **needs_confirmation** | 1 | ❓ Someone asked, waiting for response | Yes / No / Counter-propose |

---

## Proposed State Machine

### Primary States

```
[needs_confirmation] ──Yes──► [confirmed]
       │
       ├──No──► [declined]
       │
       └──Counter──► [pending]

[pending] ──Confirm──► [confirmed]
    │
    ├──Decline──► [cancelled]
    │
    └──Modify──► [pending] (updated)

[confirmed] ──Cancel──► [cancelled]
    │
    └──Reschedule──► [pending]
```

### Visual States

| State | Badge | Color | Actions |
|-------|-------|-------|---------|
| **confirmed** | ✅ | Green | Cancel, Reschedule |
| **pending** | ⏳ | Yellow | Confirm, Decline, Modify |
| **needs_confirmation** | ❓ | Orange | Yes, No, Counter |
| **declined** | ❌ | Gray | (none — hidden by default) |
| **cancelled** | 🚫 | Red strikethrough | (none — hidden by default) |

---

## Interaction Patterns by Event Type

### Calendar Events (auto-extracted from emails)
- **confirmed**: On Radicale calendar → show "Reschedule" or "Cancel"
- **pending**: Email found but not on calendar → show "Add to Calendar" or "Ignore"
- **cancelled**: User removed from calendar → fade out

### Coordination Events (from chat, HBM)
- **needs_confirmation**: "Can you cover Thursday?" → show "Yes / No / Propose Alt"
- **confirmed**: Both parties agreed → show "Reschedule" or "Cancel"
- **pending**: Tentatively held, not confirmed → show "Confirm / Release"

---

## Dashboard Interactions

### Card-Level Actions

```
┌─────────────────────────────────────────┐
│ 📅 Sullivan Baseball Practice           │
│ Today 4:30 PM • St. Philip's Field    │
│ ✅ Confirmed                             │
│                                        │
│ [Reschedule] [Cancel]                  │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│ 🗣️ Costco Run                          │
│ Sat May 02 • Aundrea asked             │
│ ❓ Needs Confirmation                   │
│                                        │
│ [✅ Yes] [❌ No] [💬 Counter]         │
└─────────────────────────────────────────┘
```

### Bulk Actions
- Select multiple → "Confirm All" / "Decline All"
- Swipe on mobile → Quick confirm/decline

---

## Questions for Matt

1. **Do we want "declined" and "cancelled" visible, or hidden (archive)?**
   - Hidden keeps dashboard clean
   - Visible provides audit trail

2. **Should "coordination" events auto-create calendar entries when confirmed?**
   - Yes: Seamless flow
   - No: Keep calendar clean, coordination stays in Event Graph only

3. **Should pending events expire?**
   - After 48 hours: auto-decline?
   - After 7 days: auto-archive?

4. **Can Aundrea interact, or Matt-only?**
   - Aundrea sees but can't modify (read-only)?
   - Aundrea can confirm/decline via Telegram bot?
   - Full shared access?

---

## Recommended Next Steps

| Priority | Task | Owner |
|----------|------|-------|
| **P0** | Matt reviews this state machine | Matt |
| **P1** | Daedalus designs interaction mockups | Daedalus |
| **P2** | Socrates wires state transitions (POST endpoints) | Socrates |
| **P3** | Test on iPad with real interactions | Matt |

---

*Prepared by Wadsworth 📋 | Awaiting Matt's feedback*