# Personal Assistant Spec for Rivet
**Created:** 2026-02-06  
**Status:** Ready to Build  
**Design Principle:** Reduce cognitive load, don't add to it

---

## Michael's Reality

| Time | Activity | Assistant Mode |
|------|----------|----------------|
| 4:15-5:30 AM | Gym | **SILENT** (no notifications) |
| 5:30 AM-6:00 PM | Construction site | Brief, actionable only |
| 6:00-6:30 PM | Commute | Longer updates OK |
| 6:30-11:00 PM | Coding/RateRight | Technical context welcome |
| After 11:00 PM | Sleep | Queue for morning |

**Key constraints:**
- 12-hour physical labor days = minimal patience for fluff
- Phone checks happen on breaks, not constantly
- Hip issues from 30 years of steelfixing = recovery matters
- Running a startup solo = every minute counts

---

## Feature Priority (by Real Value)

### Tier 1: Daily Impact (Build First)

#### 1. Morning Brief (5:00 AM)
One message, everything he needs before leaving the house.

**Contains:**
- Weather: temp, rain %, UV index, wind
- Today's calendar: meetings/appointments
- Critical reminders due today
- Any overnight alerts (emails, system issues)

**Why it matters:** Construction work requires weather prep. Know if you need rain gear, extra water, sunscreen before you leave.

**Implementation:** Single cron job at 5:00 AM → Telegram message

---

#### 2. Weather Alerts (Construction-Critical)
Proactive warnings for site-relevant conditions.

**Trigger conditions:**
- Rain >40% within 2 hours → "Rain likely by [time]. Secure materials?"
- UV index >6 → "High UV today. Sunscreen + shade breaks."
- Temp >35°C → "Heat warning. Extra hydration."
- Wind >40km/h → "High winds. Check scaffolding/crane ops."
- Storm/lightning → "Storm approaching. Consider early knockoff."

**When to send:** Only during work hours (5:30 AM - 6 PM). Check every 2 hours.

**Implementation:** Weather API check via cron, Sydney location, threshold-based alerts

---

#### 3. Calendar Sync + Reminders
Never miss an appointment.

**Features:**
- Sync Google Calendar daily at 6:00 AM
- Reminder 1 hour before any event (except recurring work hours)
- Conflict detection: "You have [meeting] at 7pm but also [gym] - which takes priority?"
- Evening preview: "Tomorrow: [events]" at 6:30 PM

**Smart timing:**
- Appointment during work hours → remind at 6:00 AM (morning brief)
- Appointment after work → remind 1 hour before
- Gym-related → never remind (it's automatic)

**Implementation:** Google Calendar API already connected. Add sync cron + reminder check.

---

#### 4. Quick Capture Reminders
"Remind me to X" should just work.

**Input methods:**
- Natural language: "remind me to call the plumber after work"
- Quick syntax: `/remind 18:30 call plumber`
- Time-relative: "remind me in 2 hours to check concrete"

**Smart delivery:**
- "after work" → 6:15 PM
- "tomorrow morning" → 5:00 AM (with morning brief)
- "when I get home" → 6:00 PM
- "this weekend" → Saturday 9:00 AM

**Implementation:** Parse Telegram messages, store in `memory/personal/reminders.json`, check via cron.

---

### Tier 2: Weekly Value (Build Second)

#### 5. Gym Tracking
Log workouts, track progression, manage hip recovery.

**Input:** 
- "gym: squat 100x5x3, bench 80x5x3" 
- "hip pain 3/5 today"
- "deload week"

**Output:**
- Weekly summary (Sunday 7 PM): lifts trending up/down, volume, hip pain patterns
- Progression suggestions based on current program (5/3/1, SVR II, etc.)
- Deload recommendations when volume/pain indicate need

**Why it matters:** 30 years of physical labor + heavy lifting = injury prevention is critical. Track hip pain correlation with work intensity.

**Implementation:** Telegram message parser, `memory/personal/gym-log.json`, weekly analysis cron.

---

#### 6. Hydration Reminders (Hot Days Only)
Don't spam. Only when it matters.

**Trigger:** Forecast temp >28°C for the day  
**Action:** One reminder at 10:00 AM and one at 2:00 PM: "Hot one today. Water break?"

**Why conditional:** Sydney winter doesn't need hydration spam. Summer construction absolutely does.

**Implementation:** Check morning weather, conditionally schedule hydration crons.

---

#### 7. Life Admin Tracking
Bills, appointments, renewals - things that slip through cracks.

**Track:**
- Recurring bills (rent, utilities, subscriptions)
- Annual appointments (dentist, doctor, rego renewal)
- Important deadlines

**Alerts:**
- 3 days before bill due
- 1 week before annual appointment
- Day-of reminder for critical items

**Input:** `/bill 150 electricity 2026-02-15` or natural language

**Implementation:** `memory/personal/bills.json`, daily check cron at 7:00 AM.

---

### Tier 3: Nice to Have (Build Later)

#### 8. Weekend Weather Forecast
Friday 6:00 PM: "Weekend weather: Saturday [conditions], Sunday [conditions]"

Helps plan outdoor activities, site prep for Monday.

---

#### 9. Sleep/Recovery Tracking (Opt-in)
If Michael wants to track: "slept 6h, woke 2x, quality 3/5"

Correlate with:
- Gym performance
- Hip pain levels
- Work intensity

Only useful if he'll actually log it. Don't push.

---

#### 10. Travel Assistant
When trips are added to calendar:
- Weather at destination
- Reminder to pack
- Flight check-in reminder (24h before)
- Time zone awareness for meetings

---

## Integration Requirements

### Already Available
| Integration | Status | Notes |
|-------------|--------|-------|
| Google Calendar | ✅ Connected | OAuth in `/root/.clawdbot/google-oauth.json` |
| Telegram | ✅ Primary channel | All notifications go here |
| Cron system | ✅ Running | Add new jobs to HEARTBEAT.md or cron |
| Weather API | ✅ Available | Via Clawdbot/web tools |

### Needs Setup
| Integration | Effort | Priority |
|-------------|--------|----------|
| Sydney weather location | 5 min | High - just configure |
| Reminder parser | 1 hour | High - basic NLP |
| Gym log storage | 30 min | Medium |
| Bill tracking | 30 min | Medium |

### Optional Future
| Integration | Value | Complexity |
|-------------|-------|------------|
| Bank API (read-only) | Auto-detect bills | Medium |
| Fitness tracker API | Auto-log workouts | Low if using app |
| Outlook/work calendar | Unified view | Medium |

---

## Proactive Notification Strategy

### The Golden Rule
**Every notification should pass the "worth interrupting for?" test.**

Michael's on a construction site. He checks his phone on breaks. Don't waste those moments.

### Notification Tiers

#### 🔴 Immediate (Any Time Except Gym/Sleep)
- Weather emergency (storm, extreme heat)
- Calendar event in <1 hour
- System down / revenue at risk
- Security incident

#### 🟡 Batched (Morning Brief or Evening)
- Tomorrow's schedule
- Bills due this week
- Non-urgent reminders
- Weekly summaries

#### 🟢 Silent (Log Only, Don't Notify)
- Routine syncs completing
- Successful backups
- Gym log confirmations

### Time-Based Filtering

```
if time.hour < 4 or time.hour >= 23:
    queue_for_morning()
elif 4 <= time.hour < 5.5:  # Gym
    queue_for_after_gym()
elif urgency == "immediate":
    send_now()
else:
    batch_for_next_window()
```

### Message Format
**Bad:** "Hi Michael! I wanted to let you know that tomorrow's weather forecast indicates there may be some precipitation in the afternoon, specifically around 2pm, with approximately 65% chance of rain. You might want to consider..."

**Good:** "Rain likely 2pm tomorrow (65%). Secure exposed materials."

---

## Implementation Plan

### Week 1: Foundation
- [ ] Create `memory/personal/` directory structure
- [ ] Set up morning brief cron (5:00 AM)
- [ ] Implement weather alerts (construction-specific thresholds)
- [ ] Build basic reminder system (Telegram → JSON → cron)
- [ ] Calendar sync + same-day reminders

**Deliverable:** Michael gets useful morning brief + weather alerts + can set reminders

### Week 2: Tracking
- [ ] Gym logging via Telegram
- [ ] Bill/appointment tracking
- [ ] Evening preview message (6:30 PM)
- [ ] Weekly gym summary (Sunday 7 PM)

**Deliverable:** Full personal tracking without manual apps

### Week 3: Polish
- [ ] Conditional hydration reminders
- [ ] Weekend weather forecast
- [ ] Calendar conflict detection
- [ ] Smarter reminder parsing ("remind me when I get home")

**Deliverable:** Proactive assistant that anticipates needs

### Week 4: Optimization
- [ ] Review notification frequency (too much? too little?)
- [ ] Add any missing integrations
- [ ] Document patterns learned
- [ ] Tune thresholds based on feedback

---

## File Structure

```
memory/personal/
├── preferences.json      # Notification settings, locations, thresholds
├── reminders.json        # Active and completed reminders
├── calendar-cache.json   # Today's events (synced daily)
├── gym-log.json          # Workout history
├── bills.json            # Recurring bills and due dates
├── weather-cache.json    # Current conditions (updated hourly)
└── health/
    ├── hip-pain.json     # Pain tracking over time
    └── sleep.json        # Optional sleep logs
```

---

## Example Interactions

### Morning Brief (5:00 AM)
```
☀️ Morning Brief - Thursday Feb 6

Weather: 28°C, sunny, UV 7 (high). No rain.
💧 Hot day - hydration reminders on.

Calendar:
- 7:00 PM: Dentist @ Sydney CBD Dental

Reminders:
- Call electrician about site power
- Pick up microplates from gym

Nothing urgent overnight. Have a good one.
```

### Weather Alert (During Work)
```
⚡ Storm Warning

Lightning detected 15km west, moving east.
ETA your area: ~45 min.

Consider: securing loose materials, early knockoff if exposed work.
```

### Quick Reminder
**Michael:** "remind me to order more sunscreen this weekend"

**Rivet:** "Got it. I'll remind you Saturday 9am."

**Saturday 9:00 AM:**
```
⏰ Reminder: Order more sunscreen

(from Thursday: "remind me to order more sunscreen this weekend")
```

### Gym Log
**Michael:** "gym: squat 102.5x5x3, ohp 52.5x5x3, rows 70x8x3. Hip felt good."

**Rivet:** "Logged. Squat up 2.5kg from last week. Hip pain: 1/5. Nice work."

### Bill Reminder
```
💰 Bill Due in 3 Days

Electricity - $147
Due: Feb 9

Reply "paid" when done, or I'll remind you day-of.
```

---

## Success Metrics

### User Experience
- Zero missed appointments
- Weather-appropriate site prep every day
- Never interrupted during gym (4:15-5:30 AM)
- Never woken up (after 11 PM)

### System Performance
- <1 min/day of Michael's input required
- <5 notifications per day (excluding responses to his queries)
- Zero false-positive urgent alerts

### Michael's Feedback Loop
After 2 weeks, ask:
1. "Too many notifications?"
2. "Missing anything you wish I'd remind you about?"
3. "What's been most useful?"

Adjust thresholds based on answers.

---

## What NOT to Build

- ❌ Complex dashboards (he won't look at them)
- ❌ Detailed analytics (save for monthly reviews)
- ❌ Social media scheduling (not personal assistant scope)
- ❌ Expense categorization (overkill for solo founder)
- ❌ Meditation/mindfulness reminders (not his style)

**Philosophy:** Build what a great construction foreman would do - anticipate needs, communicate clearly and briefly, handle the admin so he can focus on the work.

---

## Dependencies on Michael

Before building, confirm:
1. ✅ Google Calendar access (already connected)
2. ⏳ Work site location for accurate weather (assume Sydney CBD for now)
3. ⏳ Current gym program details (for progression calculations)
4. ⏳ Recurring bills list (or start empty, add as they come)
5. ⏳ Any "do not disturb" times beyond gym/sleep

Most can be inferred or asked once, then remembered.

---

*"The assistant that makes 12-hour days + startup building feel slightly less impossible."*