execution-tracking

What this skill does

# Execution Tracking

Status file management and progress reporting for the implementation plugin.

## Overview

This skill provides comprehensive execution tracking capabilities including status file initialization, task completion tracking, progress calculation, report generation, and metrics aggregation. Manages execution state in `.claude/execution/` directory with JSON-based status files.

## When to Use This Skill

Use this skill when:
- Initializing execution tracking for a feature implementation
- Updating task completion status during execution
- Generating progress reports showing current state
- Calculating completion metrics and percentages
- Tracking layer-by-layer execution progress
- Monitoring overall feature implementation status
- Identifying next actions and pending tasks
- Logging execution errors and warnings

## Core Capabilities

### 1. Initialize Execution Tracking

**Script:** `scripts/update-status.sh init <spec-id>`

Creates new execution status file from layered tasks specification.

**What it does:**
- Reads `specs/<spec>/layered-tasks.md` to extract task structure
- Creates `.claude/execution/<spec>.json` status file
- Initializes all layers with "pending" status
- Sets up task tracking for each layer
- Calculates total task count

**Example:**
```bash
bash scripts/update-status.sh init F001
# Creates: .claude/execution/F001.json
```

### 2. Update Task Status

**Script:** `scripts/update-status.sh update <spec> <layer> <task-index> <status>`

Updates individual task completion status.

**Supported statuses:**
- `complete` - Task successfully completed
- `failed` - Task execution failed
- `skipped` - Task skipped (dependency issue)
- `in_progress` - Task currently executing

**What it does:**
- Updates task status and timestamp
- Records execution duration (if complete)
- Recalculates layer metrics
- Recalculates overall progress
- Updates `last_updated` timestamp

**Example:**
```bash
bash scripts/update-status.sh update F001 L1 2 complete
# Marks third task in L1 as complete
```

### 3. Mark Layer Complete

**Script:** `scripts/update-status.sh complete-layer <spec> <layer>`

Marks entire layer as complete and advances to next layer.

**What it does:**
- Verifies all layer tasks are complete
- Sets layer status to "complete"
- Records layer completion timestamp
- Advances `current_layer` to next layer
- Recalculates overall metrics

**Example:**
```bash
bash scripts/update-status.sh complete-layer F001 L0
# Marks L0 complete, advances to L1
```

### 4. Log Execution Error

**Script:** `scripts/update-status.sh error <spec> <layer> <task-index> <error-message>`

Logs execution errors for troubleshooting.

**What it does:**
- Adds error to errors array
- Records layer, task, and timestamp
- Categorizes error severity
- Updates task status to "failed"
- Generates error report

**Example:**
```bash
bash scripts/update-status.sh error F001 L1 3 "API endpoint creation failed: invalid path syntax"
```

### 5. Generate Progress Report

**Script:** `scripts/update-status.sh report <spec>`

Creates comprehensive progress report from status file.

**Report includes:**
- Overall progress percentage
- Layer-by-layer status breakdown
- Current executing task
- Next pending tasks
- Recent errors (if any)
- Estimated time remaining
- Next recommended action

**Output:**
```
Feature F001: AI Chat Interface
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Overall Progress: 38% (5/13 tasks)
Time Elapsed: 30 minutes
Estimated Remaining: 49 minutes

Layer 0 (Infrastructure):  ✅ Complete (2/2 tasks)
Layer 1 (Core Services):   🔄 In Progress (3/5 tasks)
Layer 2 (Features):        ⏳ Pending (0/4 tasks)
Layer 3 (Integration):     ⏳ Pending (0/2 tasks)

Currently Executing:
- Create message API endpoint (fastapi-agent, medium) - Started 5m ago

Next 3 Pending Tasks:
1. [L1] Implement chat storage (supabase-agent, easy)
2. [L1] Add user authentication (auth-agent, medium)
3. [L2] Build chat UI component (react-agent, hard)

Errors: 0

Next Action: Continue L1 execution with /implementation:execute F001 --layer=L1
```

## Status File Schema

### Location
`.claude/execution/<spec>.json` (e.g., `.claude/execution/F001.json`)

### Complete Schema
```json
{
  "feature": "F001",
  "feature_name": "AI Chat Interface",
  "started_at": "2025-11-17T12:00:00Z",
  "last_updated": "2025-11-17T12:30:00Z",
  "status": "in_progress",
  "current_layer": "L1",
  "total_tasks": 13,
  "completed_tasks": 5,
  "failed_tasks": 0,
  "skipped_tasks": 0,
  "completion_percentage": 38,
  "average_task_duration_ms": 1450,
  "estimated_remaining_ms": 11600,
  "layers": {
    "L0": {
      "name": "Infrastructure",
      "status": "complete",
      "total_tasks": 2,
      "completed_tasks": 2,
      "failed_tasks": 0,
      "started_at": "2025-11-17T12:00:00Z",
      "completed_at": "2025-11-17T12:10:00Z",
      "duration_ms": 600000,
      "tasks": [
        {
          "index": 0,
          "description": "Setup database schema",
          "command": "/supabase:create-schema chat",
          "agent": "supabase-agent",
          "complexity": "easy",
          "status": "complete",
          "started_at": "2025-11-17T12:00:00Z",
          "completed_at": "2025-11-17T12:05:00Z",
          "duration_ms": 300000,
          "output": "Created schema successfully",
          "files_created": ["supabase/migrations/001_chat_schema.sql"]
        },
        {
          "index": 1,
          "description": "Initialize API structure",
          "command": "/fastapi-backend:init api",
          "agent": "fastapi-agent",
          "complexity": "easy",
          "status": "complete",
          "started_at": "2025-11-17T12:05:00Z",
          "completed_at": "2025-11-17T12:10:00Z",
          "duration_ms": 300000,
          "output": "API structure initialized",
          "files_created": ["backend/app/main.py", "backend/app/routers/__init__.py"]
        }
      ]
    },
    "L1": {
      "name": "Core Services",
      "status": "in_progress",
      "total_tasks": 5,
      "completed_tasks": 3,
      "failed_tasks": 0,
      "started_at": "2025-11-17T12:10:00Z",
      "tasks": [...]
    },
    "L2": {
      "name": "Features",
      "status": "pending",
      "total_tasks": 4,
      "completed_tasks": 0,
      "failed_tasks": 0,
      "tasks": [...]
    },
    "L3": {
      "name": "Integration",
      "status": "pending",
      "total_tasks": 2,
      "completed_tasks": 0,
      "failed_tasks": 0,
      "tasks": [...]
    }
  },
  "errors": [],
  "warnings": [],
  "next_action": "Continue L1: 2 tasks remaining"
}
```

## Metrics Calculation Formulas

### Overall Progress
```
completion_percentage = (completed_tasks / total_tasks) * 100
```

### Layer Progress
```
layer_percentage = (layer.completed_tasks / layer.total_tasks) * 100
```

### Average Task Duration
```
avg_task_duration = sum(all_completed_task_durations) / completed_tasks
```

### Estimated Time Remaining
```
remaining_tasks = total_tasks - completed_tasks
estimated_remaining = avg_task_duration * remaining_tasks
```

### Success Rate
```
attempted_tasks = completed_tasks + failed_tasks + skipped_tasks
success_rate = (completed_tasks / attempted_tasks) * 100
```

### Layer Duration
```
layer_duration = layer.completed_at - layer.started_at
```

## Status Indicators

### Layer Status Icons
- ✅ **Complete** - 100% tasks complete, layer finished
- 🔄 **In Progress** - 1-99% tasks complete, actively working
- ⏳ **Pending** - 0% complete, not yet started
- ❌ **Failed** - Has failed tasks, execution blocked

### Overall Status Values
- `pending` - Not started (0% complete)
- `in_progress` - Some tasks complete (1-99%)
- `paused` - Execution paused (manual intervention needed)
- `complete` - All tasks done (100% complete)
- `failed` - Critical error, cannot continue

### Task Status Values
- `pending` - Not yet started
- `in_progress` - Currently executing
- `complete` - Successfully finished
- `failed` - Execution failed
- `skipp