claude-os/docs/guides/MANDATORY_SESSIONS.md

# Mandatory Sessions - The New Claude OS Model

**Every conversation is a session. Period.**

---

## 🎯 The Philosophy

**Old Model:** Sessions are optional, you choose when to track work
**New Model:** You're ALWAYS in a session. The only choice is WHAT session.

**Why?**
- Zero context loss
- Complete work history
- Automatic tracking
- Better insights over time

---

## 🚀 How It Works

### Every Conversation Start

```
═══════════════════════════════════════════════════════════════
🚀 CLAUDE OS - SESSION MANAGER
═══════════════════════════════════════════════════════════════

Project: Pistn
Last Session: Dashboard Redesign (2 days ago, 2h 15m)
Progress: 45% complete (PHASE2-TASK3 in progress)

Options:
  1. Resume "Dashboard Redesign" [loads full context]
  2. Start new session [what are you working on?]
  3. Quick question [auto-session, no setup needed]

Choice: _
═══════════════════════════════════════════════════════════════
```

**You MUST pick one. No "just chatting" option.**

---

## 📋 Session Types

### 1. Feature Implementation
```
Type: feature
Duration: Tracked
Kanban: Linked to spec + tasks
Auto-saves: High-value patterns and decisions

Example: "Dashboard Redesign"
Context: Spec tasks, memories, coding standards
Tracking: Task completion, time per task, blockers
```

### 2. Bug Fix
```
Type: bug
Duration: Tracked
Priority: Detected from description (high/medium/low)
Auto-saves: Root cause, solution, prevention

Example: "API 500 Errors"
Context: Error logs, similar past issues, integration patterns
Tracking: Time to fix, solution approach, related issues
```

### 3. Exploration / Learning
```
Type: exploration
Duration: Tracked
Auto-saves: Key learnings, architecture insights

Example: "Understand authentication flow"
Context: Relevant code, architecture docs
Tracking: Files explored, patterns discovered
```

### 4. Refactoring / Maintenance
```
Type: maintenance
Duration: Tracked
Auto-saves: Refactoring patterns, improvements made

Example: "Clean up controller concerns"
Context: Coding standards, similar refactors
Tracking: Files changed, complexity reduced
```

### 5. Code Review
```
Type: review
Duration: Tracked
Auto-saves: Review comments, patterns identified

Example: "Review PR #234"
Context: Project standards, common issues
Tracking: Issues found, suggestions made
```

### 6. Quick Question (Auto-Managed)
```
Type: question
Duration: Auto-tracked (ends after 5 min inactivity)
Auto-saves: Only if valuable insight

Example: "How does Draper work?"
Context: Minimal (just project standards)
Tracking: Questions asked, answers given
```

---

## 🔄 Session Lifecycle

### Phase 1: Session Selection (Every Conversation Start)

**Option 1: Resume Existing Session**
```
You: "1" (resume)

Claude:
═══════════════════════════════════════════════════════════════
✓ RESUMING: Dashboard Redesign
═══════════════════════════════════════════════════════════════

[Loads all context automatically:]
✓ Spec: Group Account Rendering (45% complete)
✓ Current Task: PHASE2-TASK3 (Implement concern methods)
✓ 5 relevant memories loaded
✓ Coding standards loaded
✓ Git: 3 files modified on feature/appointment-redesign

Duration this session: 0h 0m
Total duration: 2h 15m

Ready! Let's continue implementing PHASE2-TASK3.
═══════════════════════════════════════════════════════════════
```

**Option 2: Start New Session**
```
You: "2" (new session)

Claude: "What are you working on?

         (I'll detect the type and load relevant context)"

You: "Fix the Tekmetric API 500 errors"

Claude:
═══════════════════════════════════════════════════════════════
✓ NEW BUG SESSION STARTED
═══════════════════════════════════════════════════════════════

Session: "Fix Tekmetric API 500 errors"
Type: Bug Fix (detected)
Priority: High (500 errors are critical)

[Auto-loaded context:]
✓ Searched memories: "Tekmetric API integration errors"
✓ Found 3 similar issues from past sessions
✓ Loaded integration patterns
✓ Git status checked

Previous session "Dashboard Redesign" paused.

Let's debug this! What's the error message?
═══════════════════════════════════════════════════════════════
```

**Option 3: Quick Question**
```
You: "3" (quick question)

Claude: "What's your question?"

You: "How do I use Draper decorators?"

Claude:
═══════════════════════════════════════════════════════════════
💬 QUICK QUESTION SESSION
═══════════════════════════════════════════════════════════════

[Gives answer]

This auto-session will end after 5 minutes of inactivity.
Need more help, or ready to resume Dashboard Redesign?
═══════════════════════════════════════════════════════════════
```

### Phase 2: Active Session (During Work)

**Live Tracking:**
```
[Active Session: Dashboard Redesign]
Duration: 1h 23m
Files changed: 3
Quick saves: 2
Last activity: 2 minutes ago

/claude-os-session status  → Shows current session details
/claude-os-session save "insight"  → Quick save to memories
/claude-os-session switch "bug fix"  → Switch to different session
```

**Smart Prompts:**
```
[After 2 hours of work]
Claude: "You've been working for 2h. You usually take a break around now.
         Want to commit your work and pause the session?"

[When pattern detected]
Claude: "This looks like the service object pattern. Should I save
         this as a reusable pattern for future reference?"

[When blocker encountered]
Claude: "Want me to track this as a blocker and search for solutions
         from past sessions?"
```

### Phase 3: Session End (Explicit or Auto)

**Explicit End:**
```
You: "/claude-os-session end"

Claude:
═══════════════════════════════════════════════════════════════
📊 SESSION SUMMARY: Dashboard Redesign
═══════════════════════════════════════════════════════════════

Duration: 1h 23m
Files changed: 3 files
Quick saves: 2
Commits: 1

Work completed:
  ✓ Implemented concern methods for PHASE2-TASK3
  ✓ Fixed N+1 query issue
  ✓ Added helper methods for PHASE2-TASK4

Progress: 45% → 53% (8% increase!)
Tasks completed: 2 tasks (PHASE2-TASK3, PHASE2-TASK4)

═══════════════════════════════════════════════════════════════
💾 SMART SAVES DETECTED
═══════════════════════════════════════════════════════════════

I found 2 items worth saving:

1. 💎 HIGH VALUE - Concern Method Pattern
   "Extracted group account logic to concern with proper
    service object integration. Reusable pattern."

   Save to project_profile? [Y/n]

2. 📊 MEDIUM VALUE - N+1 Query Fix
   "Fixed N+1 in appointments loading by eager loading
    with includes(:group_account)"

   Save to project_memories? [Y/n]

═══════════════════════════════════════════════════════════════
```

**Auto-End (Inactivity):**
```
[After 15 minutes of inactivity]

Claude: "Session 'Dashboard Redesign' has been inactive for 15 minutes.

         Options:
         1. Keep session active
         2. Pause session (can resume later)
         3. End session (save and summarize)

         Choice: _"
```

---

## 🎛️ Session Switching

### Mid-Session Switch
```
[Active: Dashboard Redesign, 45m elapsed]

You: "Actually I need to fix a bug first"

Claude: "Want to switch sessions?

         1. Pause 'Dashboard Redesign' and start 'Bug Fix' session
         2. Continue 'Dashboard Redesign' (handle bug within this session)

         Choice: _"

You: "1"

Claude:
═══════════════════════════════════════════════════════════════
✓ SESSION SWITCHED
═══════════════════════════════════════════════════════════════

Paused: Dashboard Redesign (45m, 45% complete)
Started: Bug Fix Session

What's the bug?
═══════════════════════════════════════════════════════════════
```

### Multiple Sessions Same Day
```
═══════════════════════════════════════════════════════════════
📊 TODAY'S SESSIONS
═══════════════════════════════════════════════════════════════

09:00 - 11:15  Dashboard Redesign     2h 15m  ✓ Ended
11:15 - 11:45  API Bug Fix             30m   ✓ Ended
12:00 - 13:30  Dashboard Redesign     1h 30m  ⏸ Paused
14:00 - 15:30  Code Review            1h 30m  🔄 Active

Total: 5h 45m across 4 sessions
Most time: Dashboard Redesign (3h 45m, 2 sessions)
═══════════════════════════════════════════════════════════════
```

---

## 📊 Session Statistics

### Daily Summary
```
═══════════════════════════════════════════════════════════════
📊 END OF DAY SUMMARY - November 4, 2025
═══════════════════════════════════════════════════════════════

Total sessions: 4
Total time: 5h 45m
Average session: 1h 26m

Session breakdown:
  • Feature work: 3h 45m (65%)
  • Bug fixes: 30m (9%)
  • Code review: 1h 30m (26%)

Productivity:
  • Tasks completed: 4 tasks
  • Memories saved: 6 insights
  • Patterns discovered: 2 patterns
  • Blockers resolved: 1

Most productive session: Dashboard Redesign (2h 15m, 3 tasks)
Longest session: Dashboard Redesign (2h 15m)

Great day! 🚀
═══════════════════════════════════════════════════════════════
```

### Weekly Summary
```
Week of Oct 28 - Nov 3, 2025

Total sessions: 23
Total time: 32h 15m
Average daily: 4h 36m

Session types:
  • Feature: 18 sessions (24h, 74%)
  • Bug fix: 3 sessions (2h, 6%)
  • Exploration: 2 sessions (6h 15m, 20%)

Top projects:
  1. Pistn: 28h (Dashboard Redesign: 18h)
  2. Claude OS: 4h 15m (Kanban feature: 4h 15m)

Memories saved: 23 insights
Patterns discovered: 5 patterns

Most productive day: Oct 31 (6h 30m, 8 tasks)
```

### Project Summary
```
Dashboard Redesign - Complete History

Total sessions: 5
Total time: 12h 45m
Status: In Progress (53% complete)

Session history:
  • Oct 29: 2h 15m (PHASE1: Sidebar + Cards)
  • Oct 31: 3h 00m (PHASE1: Toggles + Forms)
  • Nov 1:  2h 30m (PHASE2: Concerns started)
  • Nov 3:  3h 00m (PHASE2: Helper methods)
  • Nov 4:  2h 00m (PHASE2: Testing)

Progress:
  • Tasks completed: 27 of 52 (53%)
  • Phases completed: 1 of 3
  • Estimated remaining: 10h 30m

Velocity:
  • Average: 2.4 tasks per session
  • Average: 0.47h per task
  • Projected completion: Nov 6
```

---

## 🎯 Commands Reference

### Session Management
```bash
# At conversation start (automatic prompt)
[Choose 1/2/3]

# During session
/claude-os-session status          # Current session details
/claude-os-session save "note"     # Quick save
/claude-os-session switch "task"   # Switch to different session
/claude-os-session pause           # Pause current session
/claude-os-session end             # End with summary

# View history
/claude-os-session today           # Today's sessions
/claude-os-session week            # This week
/claude-os-session history [task]  # History for specific task
```

---

## 🔧 Configuration

### Session Preferences (`.claude-os/config.json`)
```json
{
  "session_management": {
    "mandatory": true,
    "auto_prompt_on_start": true,
    "auto_save_frequency": "15_minutes",
    "inactivity_timeout": 15,
    "auto_switch_detection": true,
    "daily_summary": true,
    "break_reminders": {
      "enabled": true,
      "interval_minutes": 120
    }
  }
}
```

---

## 💡 Best Practices

### 1. Name Sessions Descriptively
```
✅ Good: "Fix Tekmetric sync 500 errors"
✅ Good: "Implement group account rendering"
❌ Bad: "Work on stuff"
❌ Bad: "Bug fix"
```

### 2. Use Session Types Correctly
- **Feature:** Building new functionality
- **Bug:** Fixing specific issues
- **Exploration:** Learning/understanding code
- **Maintenance:** Refactoring/cleanup
- **Review:** Code review
- **Question:** Quick questions (auto-managed)

### 3. End Sessions Cleanly
```
Don't just close terminal!
Use: /claude-os-session end

Benefits:
  • Captures work summary
  • Suggests valuable saves
  • Updates statistics
  • Prepares next session
```

### 4. Switch Sessions When Context Changes
```
Don't mix unrelated work in one session!

Working on Dashboard → API bug appears → Switch sessions!

Keeps tracking clean and relevant.
```

---

## 🚀 Benefits Recap

### For You:
- **Never lose work** - Everything tracked
- **Perfect continuity** - Resume exactly where you left off
- **Understand productivity** - Real metrics
- **Learn from history** - See what works

### For Me (Claude):
- **Complete context** - Know what we're working on
- **Smart suggestions** - Based on session type
- **Proactive saves** - Capture valuable insights
- **Better guidance** - Relevant to current task

### For The Team:
- **Shared knowledge** - All insights saved
- **Velocity tracking** - Understand capacity
- **Pattern recognition** - Learn what works
- **Onboarding** - New members see work history

---

## 🎯 The Goal

**Every moment of coding is tracked, categorized, and learned from.**

No more:
- ❌ "What was I doing?"
- ❌ "How long did that take?"
- ❌ "Where did we leave off?"
- ❌ "Did we solve this before?"

Only:
- ✅ Instant context on session start
- ✅ Complete work history
- ✅ Automatic learning
- ✅ Zero context loss

**This is the complete AI development system working at full power.** 🚀

---

**Next Steps:**
1. Update CLAUDE.md template with mandatory session flow
2. Update `/claude-os-session` command to reflect new model
3. Start using it TODAY in current projects
4. Track results and iterate

**Let's make sessions mandatory!** 💪