Skip to content

04-task-tracking-system.md

Latest commit

 

History

History
327 lines (234 loc) · 8.88 KB

04-task-tracking-system.md

File metadata and controls

327 lines (234 loc) · 8.88 KB

Task Tracking & Roadmap System

Purpose: Lightweight task/roadmap tracking that keeps Claude's context focused on ONLY open items
Pattern: Completed items archived so they don't waste tokens
Created: December 2025
Source: Production implementation (Entry #163)

Overview

A simple but effective system for tracking tasks, features, and technical debt across Claude Code sessions:

  • Only open items loaded into context
  • Completed items archived (not deleted, just moved)
  • Priority-based organization (P1/P2/P3)
  • Quick wins highlighted for momentum
  • Recurring tasks tracked with due dates
  • Memory MCP backup for cross-session recall

File Structure

memory-bank/
├── always/
│   └── system-status.json           # Summary + reference path (always loaded)
└── ondemand/
    └── reference/
        └── FUTURE-FEATURES.md       # Full task details (ONLY open items)

Why Two Files?

File Loaded Purpose Size
system-status.json Always Quick summary, feature flags, references ~2KB
FUTURE-FEATURES.md On-demand Detailed task list with context ~5-15KB

Multi-Branch Projects 🆕

For projects with multiple branches, use per-branch ROADMAPs:

CURRENT/
├── dev-Data/
│   └── dev-Data-ROADMAP.md      # Data-specific tasks
├── dev-UI/
│   └── dev-UI-ROADMAP.md        # UI-specific tasks
└── dev-Knowledge/
    └── dev-Knowledge-ROADMAP.md  # Knowledge-specific tasks

→ See Chapter 31: Branch-Aware Development for:

  • ROADMAP template with standard format
  • Instructions template per branch
  • branch-variables.json for skill weighting

Quick Start (10 minutes)

Step 1: Create system-status.json

Add to memory-bank/always/system-status.json:

{
  "last_updated": "2025-12-18",
  "current_sprint": "Feature Development Sprint 1",
  "branch": "dev",
  "system_health": {
    "production": { "status": "operational", "url": "https://yourapp.com" },
    "staging": { "status": "operational" },
    "localhost": { "status": "operational", "port": 8080 }
  },
  "features": [
    { "name": "User_Auth", "passes": true, "entry": 1 },
    { "name": "Dashboard", "passes": true, "entry": 2 },
    { "name": "API_Cache", "passes": false, "entry": 3 }
  ],
  "recent_fixes": [
    { "issue": "Login timeout bug", "date": "2025-12-17", "entry": 10 }
  ],
  "active_blockers": [],
  "future_features_summary": "5 OPEN items (~4h) - P2: 3 items, P3: 2 items - See FUTURE-FEATURES.md",
  "reference_paths": {
    "future_features": "memory-bank/ondemand/reference/FUTURE-FEATURES.md"
  }
}

Step 2: Create FUTURE-FEATURES.md

Add to memory-bank/ondemand/reference/FUTURE-FEATURES.md:

# Future Features - Active Roadmap

**Updated**: 2025-12-18
**Purpose**: ONLY remaining tasks (completed archived below)
**Total Open**: 5 items (~4h)

---

## 📋 OPEN TASKS ONLY

### P1 - High Priority (0 items)

| Task   | Time | Details |
| ------ | ---- | ------- |
| (none) | -    | -       |

### P2 - Medium Priority (3 items, ~2.5h)

| Task               | Time   | Details                              |
| ------------------ | ------ | ------------------------------------ |
| **Add_API_Cache**  | 1h     | Redis caching for /api/data endpoint |
| **Fix_Mobile_Nav** | 30 min | Hamburger menu not closing on click  |
| **Update_Docs**    | 1h     | Add deployment section to README     |

### P3 - Low Priority (2 items, ~1.5h)

| Task               | Time   | Details                        |
| ------------------ | ------ | ------------------------------ |
| **Refactor_Utils** | 1h     | Split utils.js into modules    |
| **Add_Dark_Mode**  | 30 min | CSS variables already prepared |

---

## 🎯 QUICK WINS (Do First)

1. **Fix_Mobile_Nav** - 30 min
2. **Add_Dark_Mode** - 30 min

---

## 📅 RECURRING TASKS

| Task          | Frequency | Next Due     |
| ------------- | --------- | ------------ |
| Weekly_Backup | Weekly    | Dec 25, 2025 |
| Monthly_Audit | Monthly   | Jan 1, 2026  |

---

## ✅ COMPLETED (Archived)

| Task        | Completed | Notes                  |
| ----------- | --------- | ---------------------- |
| Setup_CI_CD | Dec 15    | GitHub Actions working |
| Add_Auth    | Dec 10    | JWT implementation     |

Workflow

Adding Tasks

1. Add to appropriate priority section in FUTURE-FEATURES.md
2. Update count in system-status.json summary
3. (Optional) Store summary in Memory MCP for cross-session recall

Completing Tasks

1. Move from OPEN to COMPLETED section (with date)
2. Update counts in system-status.json
3. If recurring, update next due date instead of completing

Cleanup (YAGNI)

1. Identify tasks no longer needed
2. Move to REMOVED section with reason
3. Update counts
4. Don't delete - document why removed for future reference

Key Principles

  1. Only Open Items in Context - Completed items don't waste tokens
  2. Priority-Based Organization - P1/P2/P3 with time estimates
  3. Quick Wins Highlighted - Easy tasks surfaced for momentum
  4. Recurring Tasks Tracked - Weekly/daily checks with due dates
  5. Memory MCP Backup - Store summary for cross-session recall
  6. YAGNI Cleanup - Remove unnecessary items, document why

Integration with Claude Code

Session Start

# Check current status
cat memory-bank/always/system-status.json | jq '.future_features_summary'

# See full details if needed
cat memory-bank/ondemand/reference/FUTURE-FEATURES.md

After Completing Work

# Update the files
# 1. Move task to COMPLETED in FUTURE-FEATURES.md
# 2. Update summary in system-status.json
# 3. Commit changes

git add memory-bank/
git commit -m "docs(roadmap): Complete [task name]"

Store in Memory MCP (Optional)

// Use mcp__basic-memory__write_note to store summary
{
  "title": "Project Roadmap - Active Tasks",
  "content": "5 OPEN items: P2 (3), P3 (2). Quick wins: Fix_Mobile_Nav, Add_Dark_Mode",
  "folder": "project/planning"
}

Best Practices

DO

  • ✅ Keep system-status.json under 100 lines
  • ✅ Archive completed items (don't delete)
  • ✅ Update counts when moving tasks
  • ✅ Use time estimates for planning
  • ✅ Mark quick wins for momentum

DON'T

  • ❌ Load full task history into always/ directory
  • ❌ Delete completed tasks (archive them)
  • ❌ Skip updating the summary field
  • ❌ Create separate files per task

Example: Real Usage

Before Session

Claude sees in system-status.json:
"future_features_summary": "5 OPEN items (~4h) - P2: 3, P3: 2"

Knows there's work to do, but doesn't load 50 completed items.

During Session

User: "What's left to do?"
Claude: "You have 5 open items. Quick wins: Fix_Mobile_Nav (30 min),
         Add_Dark_Mode (30 min). Want to tackle one?"

After Completing Task

Claude updates FUTURE-FEATURES.md:
- Moves Fix_Mobile_Nav to COMPLETED
- Updates summary: "4 OPEN items (~3.5h)"
- Commits changes

ROI

  • Token Savings: ~1-5K tokens per session (no loading completed tasks)
  • Clarity: Always know exactly what's pending
  • Momentum: Quick wins highlighted for easy progress
  • History: Completed items preserved for reference

Native Task Management (v2.1.16+)

Claude Code includes built-in task management tools:

Tool Purpose
TaskCreate Create a task with subject, description, activeForm
TaskUpdate Update status (pending -> in_progress -> completed), add dependencies
TaskList View all tasks with status and blockers
TaskGet Get full task details by ID

Dependency tracking: Use addBlockedBy and addBlocks to define task ordering.

Multi-agent collaboration: Share task lists across sessions via CLAUDE_CODE_TASK_LIST_ID.

This is separate from the manual roadmap/feature tracking described in this chapter -- TaskCreate is for within-session work tracking, while the roadmap system is for cross-session project management.

Related Chapters

  • Chapter 12: Memory Bank Hierarchy (4-tier structure)
  • Chapter 23: Session Documentation Skill (automated docs)
  • Chapter 29: Branch Context System (per-branch loading) 🆕
  • Chapter 31: Branch-Aware Development (ROADMAP templates) 🆕

Pattern Source: Production (Entry #163 - claude-code-guide-patterns.md)
Status: Production validated December 2025
Last Updated: 2026-01-19 License: MIT