path: root/makima/docs/USER-STORIES-resume-history-system.md

# Resume and History System - User Stories

## Epic: History Viewing

### US-HV-01: View Contract History Timeline
**As a** developer using Makima
**I want to** view a complete timeline of all activities in my contract
**So that** I can understand what happened across all phases and tasks

**Acceptance Criteria:**
- Timeline shows all activities chronologically
- Activities include task creation, completions, checkpoints, phase changes, and chat messages
- Timeline can be filtered by phase
- Timeline can be filtered by time range
- Timeline supports pagination for large datasets

### US-HV-02: View Task Conversation History
**As a** developer
**I want to** view the complete conversation history for any task
**So that** I can understand what the AI did and how it arrived at its solution

**Acceptance Criteria:**
- All messages are displayed in chronological order
- Tool calls are shown with their inputs
- Tool results are shown with outputs
- Error messages are clearly highlighted
- Token usage and cost are displayed if available

### US-HV-03: View Checkpoint with Diff
**As a** developer
**I want to** see what code changes were made in each checkpoint
**So that** I can review the work done at each step

**Acceptance Criteria:**
- Checkpoint details show commit message and timestamp
- Diff shows files changed with additions/deletions
- Diff uses syntax highlighting for code
- Can navigate between checkpoints
- Shows summary statistics (files changed, lines added/removed)

### US-HV-04: View Supervisor Conversation
**As a** developer managing a contract
**I want to** view the supervisor's conversation history
**So that** I can understand how tasks were orchestrated and decisions were made

**Acceptance Criteria:**
- Full conversation history is displayed
- Spawned tasks are linked and visible
- Pending tasks are indicated
- Phase information is shown
- Tool calls and decisions are visible

## Epic: Resume System

### US-RS-01: Resume Interrupted Supervisor
**As a** developer
**I want to** resume my supervisor conversation after a daemon disconnect
**So that** I don't lose my progress and context

**Acceptance Criteria:**
- Supervisor can be resumed with full conversation context
- Can choose resume mode (continue, restart phase, from checkpoint)
- Resume works on any available daemon
- Original context is preserved
- New activity continues from where it left off

### US-RS-02: Resume Interrupted Task
**As a** developer
**I want to** resume a task that was interrupted
**So that** the AI can continue without redoing completed work

**Acceptance Criteria:**
- Task resumes with conversation context
- Worktree state is preserved
- Can specify context size limit
- Resume works on different daemon if needed
- Progress is not lost

### US-RS-03: Resume from Specific Checkpoint
**As a** developer
**I want to** resume work from a specific checkpoint
**So that** I can try a different approach from a known good state

**Acceptance Criteria:**
- Can select any checkpoint to resume from
- Code state matches checkpoint
- Can optionally include conversation up to that point
- New task is created with appropriate context
- Original task remains unchanged

### US-RS-04: Continue from Previous Task
**As a** developer
**I want to** start a new task that inherits another task's worktree
**So that** I can build on previous work without copying files manually

**Acceptance Criteria:**
- New task inherits worktree state from source task
- Can specify which files to copy
- Git history is preserved
- Source task is not modified
- New task gets its own isolated worktree

## Epic: Rewind/Restore Features

### US-RW-01: Rewind Code to Checkpoint
**As a** developer
**I want to** rewind my code to a previous checkpoint
**So that** I can undo changes and try a different approach

**Acceptance Criteria:**
- Can select any checkpoint to rewind to
- Can choose to discard current changes
- Can choose to preserve current state as branch
- Can choose to stash current changes
- Rewind is atomic (all or nothing)

### US-RW-02: Rewind Conversation
**As a** developer
**I want to** rewind the conversation to an earlier point
**So that** I can remove problematic AI responses and try again

**Acceptance Criteria:**
- Can specify rewind point by message ID, timestamp, or message count
- Messages after rewind point are removed
- Optionally rewind code to matching checkpoint
- Supervisor state is updated
- Can continue conversation from new point

### US-RW-03: Fork Task from History
**As a** developer
**I want to** create a new task from a point in history
**So that** I can explore an alternative approach without losing original work

**Acceptance Criteria:**
- Can fork from any checkpoint
- Can fork from any conversation point
- New task gets code state from fork point
- Can optionally include conversation history
- Original task is not modified
- New branch is created in git

### US-RW-04: Create Branch from Checkpoint
**As a** developer
**I want to** create a git branch from any checkpoint
**So that** I can preserve or share a specific point in development

**Acceptance Criteria:**
- Can specify branch name
- Branch is created at checkpoint's commit
- Can optionally checkout the new branch
- Works even if task is completed
- Branch is visible in git

## Epic: CLI Integration

### US-CLI-01: View History via CLI
**As a** developer using the terminal
**I want to** view contract and task history via CLI
**So that** I can understand project history without opening the web UI

**Acceptance Criteria:**
- `makima contract history` shows timeline
- `makima task history` shows conversation
- `makima task checkpoints` lists checkpoints
- `makima task checkpoint-diff` shows code changes
- Output is formatted for terminal readability

### US-CLI-02: Resume via CLI
**As a** developer using the terminal
**I want to** resume supervisors and tasks via CLI
**So that** I can recover from interruptions without the web UI

**Acceptance Criteria:**
- `makima supervisor resume` resumes supervisor
- `makima task resume` resumes interrupted task
- `makima task resume-from` resumes from checkpoint
- Can specify resume options via flags
- Clear feedback on resume success/failure

### US-CLI-03: Rewind via CLI
**As a** developer using the terminal
**I want to** perform rewind operations via CLI
**So that** I can quickly undo changes or fork without the web UI

**Acceptance Criteria:**
- `makima task rewind` rewinds code
- `makima supervisor rewind-conversation` rewinds conversation
- `makima task fork` creates fork from history
- Can specify options via flags
- Confirmation required for destructive operations

## Epic: Frontend Integration

### US-FE-01: History Timeline UI
**As a** developer using the web interface
**I want to** see a visual timeline of contract activities
**So that** I can quickly understand project progression

**Acceptance Criteria:**
- Timeline is visually clear and scrollable
- Events are color-coded by type
- Can click events for details
- Can filter and search
- Responsive on different screen sizes

### US-FE-02: Conversation Viewer UI
**As a** developer using the web interface
**I want to** view conversations in a chat-like interface
**So that** I can easily read and understand AI interactions

**Acceptance Criteria:**
- Messages are displayed in chat format
- Different message types are visually distinct
- Code blocks have syntax highlighting
- Tool calls are collapsible
- Can copy message content

### US-FE-03: Checkpoint Browser UI
**As a** developer using the web interface
**I want to** browse and interact with checkpoints
**So that** I can review, restore, or branch from any point

**Acceptance Criteria:**
- Checkpoints listed with details
- Can view diff for each checkpoint
- Can trigger rewind from UI
- Can create branch from UI
- Can resume from checkpoint via UI

### US-FE-04: Rewind Controls UI
**As a** developer using the web interface
**I want to** easily rewind code or conversation
**So that** I can undo changes with clear visual feedback

**Acceptance Criteria:**
- Clear controls for rewind operations
- Preview of what will be affected
- Confirmation dialog for destructive actions
- Progress indication during operation
- Clear success/failure feedback