# Directive: project_auto_resume

**Type**: Project
**Level**: 3 (Operational Execution)
**Parent Directive**: aimfp_run
**Priority**: HIGH - Session continuity and workflow restoration

---

## Purpose

The `project_auto_resume` directive detects unfinished tasks or subtasks from `project.db` and resumes execution at the appropriate directive entry point. This directive serves as the **workflow continuity manager**, restoring work context between user sessions or after interruptions, ensuring seamless continuation of project work.

Key responsibilities:
- **Detect incomplete work** - Identify paused or in-progress tasks
- **Restore context** - Load task/subtask details and history
- **Resume execution** - Continue from last checkpoint
- **Handle interruptions** - Gracefully recover from session breaks
- **Prioritize resumption** - Follow priority order (sidequests → subtasks → tasks)
- **Prompt for confirmation** - User verifies resumption before proceeding

This is the **session continuity handler** - ensures work never gets lost or forgotten.

---

## When to Apply

This directive applies when:
- **Session start** - User returns after break ("continue", "resume work")
- **After interruption** - System crash, user logged out, session ended
- **Explicit resumption** - User says "resume" or "continue where we left off"
- **Task paused** - Work interrupted by subtask, now subtask complete
- **Called by other directives**:
  - `aimfp_run` - May auto-trigger on session start
  - `aimfp_status` - Identifies work to resume, may call auto_resume
  - `project_task_update` - After subtask completion, may resume parent
  - User directly - Manual resumption request

---

## Workflow

### Trunk: detect_incomplete_tasks

Identifies work that should be resumed based on status and priority.

**Steps**:
1. **Query incomplete work** - Find tasks/subtasks with status 'in_progress' or 'paused'
2. **Prioritize by hierarchy** - Sidequests > subtasks > tasks
3. **Load context** - Get task details, items, history
4. **Check resumability** - Verify task can continue (no blockers)
5. **Prompt user** - Confirm resumption or choose different work
6. **Resume execution** - Call appropriate directive to continue work

### Branches

**Branch 1: If task_paused**
- **Then**: `resume_from_checkpoint`
- **Details**: Task is paused, likely waiting for subtask completion
  - Check if blocking subtasks are complete
  - If all subtasks complete: Resume parent task
  - If subtasks remain: Continue with next subtask
  - Update task status from 'paused' to 'in_progress'
  - Load task context (items, completed work)
- **SQL**:
  **Use helper functions** for all project.db operations. Query available helpers.

**IMPORTANT**: Never use direct SQL for project.db - always use helpers or call project directives (like project_file_write).
- **Result**: Paused task resumed, user notified of context

**Branch 2: If sidequest_paused**
- **Then**: `prompt_resume`
- **Details**: Sidequest is paused or in-progress
  - Sidequests are exploratory, may be abandoned
  - Prompt user: "Resume sidequest or mark complete/cancelled?"
  - If resume: Load sidequest context
  - If complete: Mark complete, return to main work
  - If cancel: Mark cancelled, return to main work
- **SQL**:
  **Use helper functions** for database operations. Query available helpers for the appropriate database.
- **Prompt**:
  ```
  Sidequest in progress: "{sidequest_name}"
  Started: {created_at}
  Last updated: {updated_at}

  This sidequest is exploratory work related to task "{parent_task_name}".

  Options:
  1. Resume sidequest
  2. Mark complete (findings added to notes)
  3. Cancel (abandon exploration)

  Choose action:
  ```
- **Result**: User decides sidequest fate, work continues

**Branch 3: If subtask_incomplete**
- **Then**: `resume_subtask_work`
- **Details**: Subtask is in-progress, blocking parent task
  - Subtasks are high-priority, must complete before parent
  - Load subtask context (description, items, parent task)
  - Resume work on subtask
  - Parent task remains paused until subtask complete
- **SQL**:
  **Use helper functions** for all project.db operations. Query available helpers.

**IMPORTANT**: Never use direct SQL for project.db - always use helpers or call project directives (like project_file_write).
- **Context Loading**:
  **Use helper functions** for all project.db operations. Query available helpers.

**IMPORTANT**: Never use direct SQL for project.db - always use helpers or call project directives (like project_file_write).
- **Result**: Subtask work resumed, parent remains paused

**Branch 4: If task_in_progress**
- **Then**: `resume_task_work`
- **Details**: Task is in-progress, no blocking subtasks
  - Load task context (items, completed work, milestone)
  - Show progress: X/Y items complete
  - Continue with next incomplete item
  - Update task as in-progress
- **SQL**:
  **Use helper functions** for all project.db operations. Query available helpers.

**IMPORTANT**: Never use direct SQL for project.db - always use helpers or call project directives (like project_file_write).
- **Context Report**:
  ```
  Resuming task: "{task_name}"
  Milestone: {milestone_name}
  Progress: {completed_items}/{total_items} items complete

  Completed:
  - {item_1_name} ✓
  - {item_2_name} ✓

  Remaining:
  - {item_3_name}
  - {item_4_name}

  Next: {item_3_name}
  ```
- **Result**: Task work resumed with clear next action

**Branch 5: If no_incomplete_work**
- **Then**: `mark_as_resolved`
- **Details**: No paused or in-progress work found
  - All tasks either pending or completed
  - Report: "No work to resume"
  - Suggest: Check status or start new task
- **Result**: User informed no resumption needed

**Branch 6: If resume_conflict**
- **Then**: `prompt_user_choice`
- **Details**: Multiple incomplete tasks, ambiguous which to resume
  - List all in-progress/paused work
  - Show priority and last updated
  - Prompt user to choose
  - Resume selected work
- **Prompt**:
  ```
  Multiple incomplete work items found:

  1. Subtask: "Fix memory leak" (priority: high, updated 2 days ago)
     Parent: Task "Optimize database"

  2. Task: "Implement caching" (in_progress, updated 5 days ago)
     Milestone: Performance

  3. Sidequest: "Research Redis" (in_progress, updated 1 week ago)
     Parent: Task "Implement caching"

  Which should I resume? (1-3, or 'none' to start fresh)
  ```
- **Result**: User selects work to resume

**Branch 7: If checkpoint_invalid**
- **Then**: `discard_and_start_fresh`
- **Details**: Resume state is corrupted or outdated
  - Task/subtask exists but context missing
  - Items deleted or task structure changed
  - Prompt: "Cannot resume, state changed. Start fresh?"
  - Options: Mark current as cancelled, start new task
- **Result**: Corrupt state handled gracefully

**Branch 8: If auto_resume_enabled**
- **Then**: `auto_resume_highest_priority`
- **Details**: User preferences set to auto-resume without prompt
  - Select highest priority incomplete work
  - Load context automatically
  - Begin execution without user confirmation
  - Log auto-resume action
- **User Preference Check**:
  **Use helper functions** for all user_preferences.db operations. Query available helpers for settings operations.
- **Result**: Work resumed automatically

**Fallback**: `mark_as_resolved`
- No work to resume or cannot determine correct action
- Report "No resumable work" and suggest next steps

### Error Handling

**on_failure**: `prompt_user`
- If resumption fails: Log error, prompt user for manual action
- Common issues: Context missing, state corrupted, database inconsistency

---

## Examples

### Example 1: Resume Paused Task After Subtask Completion

**Context**: User completed subtask, parent task auto-resumes

**AI Execution**:
1. Subtask "Fix memory leak" marked complete (via `project_task_update`)
2. `project_task_update` checks parent task:
   **Use helper functions** for all project.db operations. Query available helpers.

**IMPORTANT**: Never use direct SQL for project.db - always use helpers or call project directives (like project_file_write).
3. Checks for remaining subtasks:
   **Use helper functions** for all project.db operations. Query available helpers.

**IMPORTANT**: Never use direct SQL for project.db - always use helpers or call project directives (like project_file_write).
4. Triggers `project_auto_resume` for task #15
5. Updates task status:
   **Use helper functions** for all project.db operations. Query available helpers.

**IMPORTANT**: Never use direct SQL for project.db - always use helpers or call project directives (like project_file_write).
6. Loads task context:
   **Use helper functions** for all project.db operations. Query available helpers.

**IMPORTANT**: Never use direct SQL for project.db - always use helpers or call project directives (like project_file_write).
7. Reports to user:
   ```
   ✓ Subtask "Fix memory leak" complete!

   Resuming parent task: "Optimize database"
   Progress: 3/5 items complete

   Completed:
   - Profile slow queries ✓
   - Add indexes ✓
   - Fix memory leak ✓ (just completed)

   Remaining:
   - Optimize connection pooling
   - Load test improvements

   Next: Optimize connection pooling
   ```
8. User continues work on next item

### Example 2: User Returns After Break

**Context**: User says "continue" after logging back in

**AI Execution**:
1. Triggered by `aimfp_run` detecting "continue" keyword
2. Queries for incomplete work:
   **Use helper functions** for all project.db operations. Query available helpers.

**IMPORTANT**: Never use direct SQL for project.db - always use helpers or call project directives (like project_file_write).
3. Loads task context:
   **Use helper functions** for all project.db operations. Query available helpers.

**IMPORTANT**: Never use direct SQL for project.db - always use helpers or call project directives (like project_file_write).
4. Prompts user:
   ```
   Welcome back!

   You were working on: "Implement authentication"
   Milestone: Core Features
   Progress: 2/6 items (33%)
   Last updated: 2 hours ago

   Resume this task? (y/n)
   ```
5. User: "y"
6. Loads full context:
   **Use helper functions** for all project.db operations. Query available helpers.

**IMPORTANT**: Never use direct SQL for project.db - always use helpers or call project directives (like project_file_write).
7. Reports:
   ```
   Resuming: "Implement authentication"

   Completed:
   - Set up auth schema ✓
   - Create user model ✓

   Next:
   - Implement password hashing
   - Create login endpoint
   - Add JWT tokens
   - Write auth tests

   Starting with: Implement password hashing
   ```
8. Work continues

### Example 3: Multiple Incomplete Work Items

**Context**: User has paused sidequest, in-progress task, and paused task

**AI Execution**:
1. Queries all incomplete work:
   **Use helper functions** for all project.db operations. Query available helpers.

**IMPORTANT**: Never use direct SQL for project.db - always use helpers or call project directives (like project_file_write).
2. Results:
   - Sidequest #5: "Research Redis alternatives" (in_progress, 1 week ago)
   - Task #18: "Implement caching" (in_progress, 3 days ago)
   - Task #12: "Refactor database" (paused, 5 days ago)
3. Prompts user with priority order:
   ```
   Multiple incomplete work items:

   1. [SIDEQUEST] "Research Redis alternatives" (highest priority)
      Status: in_progress
      Last updated: 1 week ago
      Note: Exploratory work, may be abandoned

   2. [TASK] "Implement caching"
      Status: in_progress
      Progress: 2/8 items (25%)
      Last updated: 3 days ago

   3. [TASK] "Refactor database"
      Status: paused (blocked by subtask previously)
      Last updated: 5 days ago

   Which should I resume? (1-3, 'status' for more info, 'none' to start fresh)
   ```
4. User: "2" (Choose task #18)
5. Loads context for task #18 and resumes

### Example 4: Sidequest Resumption or Abandonment

**Context**: User has paused sidequest, needs to decide fate

**AI Execution**:
1. Detects sidequest #7: "Explore graph databases" (paused, 2 weeks ago)
2. Loads sidequest context:
   **Use helper functions** for all project.db operations. Query available helpers.

**IMPORTANT**: Never use direct SQL for project.db - always use helpers or call project directives (like project_file_write).
3. Prompts user:
   ```
   Sidequest found: "Explore graph databases"
   Related to: Task "Choose database solution"
   Started: 2 weeks ago
   Status: Paused

   This sidequest has been inactive for 2 weeks.

   Options:
   1. Resume exploration
   2. Mark complete (add findings to notes)
   3. Cancel (abandon, no longer relevant)

   Choose action:
   ```
4. User: "2" (Mark complete)
5. Prompts for findings:
   ```
   Sidequest complete! Any findings to note?
   (Optional, press Enter to skip)
   ```
6. User: "Neo4j looks promising but too complex for our use case"
7. Marks complete and logs:
   **Use helper functions** for all project.db operations. Query available helpers.

**IMPORTANT**: Never use direct SQL for project.db - always use helpers or call project directives (like project_file_write).
8. Returns to main work

### Example 5: Auto-Resume Enabled

**Context**: User has preference set to auto-resume highest priority

**AI Execution**:
1. User says "continue" or starts session
2. Checks user preference:
   **Use helper functions** for all user_preferences.db operations. Query available helpers for settings operations.
3. Queries incomplete work (same as Example 3)
4. Selects highest priority automatically:
   - Sidequest #5 (highest priority by hierarchy)
5. Loads context and begins without prompt:
   ```
   Auto-resuming: Sidequest "Research Redis alternatives"
   (User preference: auto-resume enabled)

   Context: Exploring cache solutions for Task "Implement caching"
   Started: 1 week ago

   Continuing exploration...
   ```
6. Work resumes automatically

### Example 6: No Work to Resume

**Context**: All tasks either pending or completed

**AI Execution**:
1. Queries incomplete work:
   **Use helper functions** for all project.db operations. Query available helpers.

**IMPORTANT**: Never use direct SQL for project.db - always use helpers or call project directives (like project_file_write).
2. Reports:
   ```
   No work to resume.

   All tasks are either:
   - Pending (not started)
   - Completed

   Suggested next steps:
   1. Check status: 'aimfp_status'
   2. Start new task from current milestone
   3. Review completed work

   What would you like to do?
   ```
3. User decides next action

---

## Integration with Other Directives

### Called By:
- `aimfp_run` - May auto-trigger on session start
- `aimfp_status` - Identifies work to resume
- `project_task_update` - After subtask completion
- User directly - Manual "resume" or "continue"

### Calls:
- Task execution directives - Resumes appropriate work
- `aimfp_status` - Provides context for resumption

---

## Database Updates

### Tables Modified:

**project.db**:
**Use helper functions** for all project.db operations. Query available helpers.

**IMPORTANT**: Never use direct SQL for project.db - always use helpers or call project directives (like project_file_write).

---

## Roadblocks and Resolutions

### Roadblock 1: resume_conflict
**Issue**: Multiple incomplete tasks, unclear which to resume
**Resolution**: Prompt user to choose branch or discard task, list all incomplete work with priority

### Roadblock 2: context_corrupted
**Issue**: Task exists but items/context missing
**Resolution**: Mark task as corrupted, suggest starting fresh or investigating

### Roadblock 3: ambiguous_priority
**Issue**: Cannot determine highest priority work
**Resolution**: Prompt user with all options, let user decide

### Roadblock 4: auto_resume_failure
**Issue**: Auto-resume enabled but cannot determine work to resume
**Resolution**: Fall back to manual prompt, log failure

---

## Intent Keywords

- "resume"
- "continue"
- "checkpoint"
- "where was I"
- "continue work"
- "pick up where I left off"

**Confidence Threshold**: 0.7

---

## Related Directives

- `aimfp_run` - Gateway directive, may trigger auto-resume
- `aimfp_status` - Provides context for resumption decisions
- `project_task_update` - May trigger resume after subtask completion
- `project_task_decomposition` - Creates tasks that may need resumption

---

## Resumption Priority Order

**Hierarchy**:
1. **Sidequests** (highest priority)
   - Exploratory work, often forgotten
   - Prompt for completion/cancellation if old

2. **Subtasks** (high priority)
   - Block parent tasks
   - Must complete before parent continues

3. **Tasks** (standard priority)
   - Main work items
   - Resume in order of priority and recency

**Selection Logic**:
```
if sidequests.in_progress:
    prompt_sidequest_action()
elif subtasks.in_progress:
    resume_subtask()
elif tasks.paused:
    check_subtasks_complete()
    if all_subtasks_complete:
        resume_task()
elif tasks.in_progress:
    resume_task()
else:
    no_work_to_resume()
```

---

## User Preferences

### auto_resume_enabled
- **Type**: Boolean
- **Default**: false
- **Effect**: Auto-resume highest priority work without prompt
- **Use Case**: Power users who want seamless continuation

### resume_confirmation_required
- **Type**: Boolean
- **Default**: true
- **Effect**: Always prompt before resuming, even with single item
- **Use Case**: Users who want explicit control

### auto_abandon_stale_sidequests
- **Type**: Boolean + duration
- **Default**: false
- **Effect**: Auto-cancel sidequests older than N days
- **Use Case**: Clean up forgotten exploratory work

---

## Notes

- **Priority order** - Sidequests → subtasks → tasks
- **Context restoration** - Load full task/item context before resuming
- **Prompt for confirmation** - User verifies resumption (unless auto-resume enabled)
- **Handle abandonment** - Gracefully handle stale sidequests
- **Auto-resume parent** - When subtask completes, resume parent task
- **Detect conflicts** - Multiple incomplete items, prompt user to choose
- **Preserve state** - Never lose work progress
- **Log resumptions** - Audit trail in notes table
- **Support preferences** - Respect user settings for auto-resume
- **Graceful degradation** - Handle corrupted state by starting fresh
