Proactive Tasks

---
name: proactive-tasks
description: Proactive goal and task management system. Use when managing goals, breaking down projects into tasks, tracking progress, or working autonomously on objectives. Enables agents to work proactively during heartbeats, message humans with updates, and make progress without waiting for prompts.
---

# Proactive Tasks

A task management system that transforms reactive assistants into proactive partners who work autonomously on shared goals.

## Core Concept

Instead of waiting for your human to tell you what to do, this skill lets you:
- Track goals and break them into actionable tasks
- Work on tasks during heartbeats
- Message your human with updates and ask for input when blocked
- Make steady progress on long-term objectives

## Quick Start

### Creating Goals

When your human mentions a goal or project:

```bash
python3 scripts/task_manager.py add-goal "Build voice assistant hardware" \
  --priority high \
  --context "Replace Alexa with custom solution using local models"
```

### Breaking Down into Tasks

```bash
python3 scripts/task_manager.py add-task "Build voice assistant hardware" \
  "Research voice-to-text models" \
  --priority high

python3 scripts/task_manager.py add-task "Build voice assistant hardware" \
  "Compare Raspberry Pi vs other hardware options" \
  --depends-on "Research voice-to-text models"
```

### During Heartbeats

Check what to work on next:

```bash
python3 scripts/task_manager.py next-task
```

This returns the highest-priority task you can work on (no unmet dependencies, not blocked).

### Completing Tasks

```bash
python3 scripts/task_manager.py complete-task <task-id> \
  --notes "Researched Whisper, Coqui, vosk. Whisper.cpp looks best for Pi."
```

### Messaging Your Human

When you complete something important or get blocked:

```bash
python3 scripts/task_manager.py mark-needs-input <task-id> \
  --reason "Need budget approval for hardware purchase"
```

Then message your human with the update/question.

## Phase 2: Production-Ready Architecture

Proactive Tasks v1.2.0 includes battle-tested patterns from real agent usage to prevent data loss, survive context truncation, and maintain reliability under autonomous operation.

### 1. WAL Protocol (Write-Ahead Logging)

**The Problem:** Agents write to memory files, then context gets truncated. Changes vanish.

**The Solution:** Log critical changes to `memory/WAL-YYYY-MM-DD.log` BEFORE modifying task data.

**How it works:**
- Every `mark-progress`, `log-time`, or status change creates a WAL entry first
- If context gets cut mid-operation, the WAL has the details
- After compaction, read the WAL to recover what was happening

**Events logged:**
- `PROGRESS_CHANGE`: Task progress updates (0-100%)
- `TIME_LOG`: Actual time spent on tasks
- `STATUS_CHANGE`: Task state transitions (blocked, completed, etc.)
- `HEALTH_CHECK`: Self-healing operations

**Automatically enabled** - no configuration needed. WAL files are created in `memory/` directory.

### 2. SESSION-STATE.md (Active Working Memory)

**The Concept:** Chat history is a BUFFER, not storage. SESSION-STATE.md is your "RAM" - the ONLY place task details are reliably preserved.

**Auto-updated on every task operation:**
```markdown
## Current Task
- **ID:** task_abc123
- **Title:** Research voice models
- **Status:** in_progress
- **Progress:** 75%
- **Time:** 45 min actual / 60 min estimate (25% faster)

## Next Action
Complete research, document findings in notes, mark complete.
```

**Why this matters:** After context compaction, you can read SESSION-STATE.md and immediately know:
- What you were working on
- How far you got
- What to do next

### 3. Working Buffer (Danger Zone Safety)

**The Problem:** Between 60% and 100% context usage, you're in the "danger zone" - compaction could happen any time.

**The Solution:** Automatically append all task updates to `working-buffer.md`.

**How it works:**
```bash
# Every progress update, time log, or status change appends:
- PROGRESS_CHANGE (2026-02-12T10:30:00Z): task_abc123 → 75%
- TIME_LOG (2026-02-12T10:35:00Z): task_abc123 → +15 min
- STATUS_CHANGE (2026-02-12T10:40:00Z): task_abc123 → completed
```

**After compaction:** Read `working-buffer.md` to see exactly what happened during the danger zone.

**Manual flush:** `python3 scripts/task_manager.py flush-buffer` to copy buffer contents to daily memory file.

### 4. Self-Healing Health Check

**Agents make mistakes.** Task data can get corrupted over time. The health-check command detects and auto-fixes common issues:

```bash
python3 scripts/task_manager.py health-check
```

**Detects 5 categories of issues:**

1. **Orphaned recurring tasks** - No parent goal
2. **Impossible states** - Status=completed but progress < 100%
3. **Missing timestamps** - Completed tasks without `completed_at`
4. **Time anomalies** - Actual time >> estimate (flags for review, doesn't auto-fix)
5. **Future-dated completions** - Completed tasks with future timestamps

**Auto-fixes 4 safe categories** (time anomalies just flagged for human review).

**When to run:**
- During heartbeats (every few days)
- After recovering from context truncation
- When task data seems inconsistent

### Production Reliability

These four patterns work together to create a robust system:

```
User request → WAL log → Update data → Update SESSION-STATE → Append to buffer
     ↓              ↓            ↓                ↓                    ↓
Context cut? → Read WAL → Verify data → Check SESSION-STATE → Review buffer
```

**Result:** You never lose work, even during context truncation. The system self-heals and maintains consistency autonomously.

### 5. Compaction Recovery Protocol

**Trigger:** Session starts with `<summary>` tag, or you're asked "where were we?" or "continue".

**The Problem:** Context was truncated. You don't remember what task you were working on.

**Recovery Steps (in order):**

1. **FIRST:** Read `working-buffer.md` - Raw danger zone exchanges
   ```bash
   # Check if buffer exists and has recent content
   cat working-buffer.md
   ```

2. **SECOND:** Read `SESSION-STATE.md` - Active task state
   ```bash
   # Get current task context
   cat SESSION-STATE.md
   ```

3. **THIRD:** Read today's WAL log
   ```bash
   # See what operations happened
   cat memory/WAL-$(date +%Y-%m-%d).log | tail -20
   ```

4. **FOURTH:** Check task data for the task ID from SESSION-STATE
   ```bash
   python3 scripts/task_manager.py list-tasks "Goal Title"
   ```

5. **Extract & Update:** Pull important context from buffer into SESSION-STATE if needed

6. **Present Recovery:** "Recovered from compaction. Last task: [title]. Progress: [%]. Next action: [what to do]. Continue?"

**Do NOT ask "what were we discussing?"** - The buffer and SESSION-STATE literally have the answer.

### 6. Verify Before Reporting (VBR)

**The Law:** "Code exists" ≠ "feature works." Never report task completion without end-to-end verification.

**Trigger:** About to mark a task `completed` or say "done":

1. **STOP** - Don't mark complete yet
2. **Test** - Actually run/verify the outcome from user perspective
3. **Verify** - Check the result, not just the output
4. **Document** - Add verification details to task notes
5. **THEN** - Mark complete with confidence

**Examples:**

❌ **Wrong:** "Added health-check command. Task complete!"
✅ **Right:** "Added health-check. Testing... detected 4 issues, auto-fixed 3. Verified on broken test data. Task complete!"

❌ **Wrong:** "Implemented SESSION-STATE updates. Done!"
✅ **Right:** "Implemented SESSION-STATE. Tested with mark-progress, log-time, mark-blocked - all update correctly. Done!"

**Why this matters:** Agents often report completion based on "I wrote the code" rather than "I verified it works." VBR prevents false completions and builds trust.

## Proactive Mindset

**The Core Question:** Don't ask "what should I do?" Ask "what would genuinely help my human that they haven't thought to ask