executing-plans

Executing Analysis Plans

Run a written analysis plan, task by task, with discipline. Every task goes through two mandatory review gates before being marked complete. No exceptions.

Why structured execution matters: Plans are approximations. Execution is where statistical errors, silent data leaks, and code quality debt are introduced. The two-stage review gate exists to catch these problems while they are still cheap to fix — before downstream tasks depend on corrupted outputs.

Iron Law

NO TASK MAY BE MARKED COMPLETE WITHOUT PASSING STATISTICAL REVIEW FIRST.

When to Use

Use this skill when:

• A plan exists at docs/datapowers/plans/
• Tasks are sequential or tightly coupled (for independent tasks, prefer subagent-driven-analysis)
• You are personally executing each task (not dispatching subagents)

Task State Machine

Every task in the plan moves through these states only:

PENDING → IN_PROGRESS → STAT_REVIEW → CODE_REVIEW → DONE
                              ↓                ↓
                         STAT_BLOCKED    CODE_BLOCKED
                              ↓                ↓
                         (fix and re-run) (fix and re-review)

Rules:

• Only one task may be IN_PROGRESS at a time
• A task in STAT_BLOCKED must be fixed before the next task begins
• CODE_REVIEW only begins after STAT_REVIEW passes
• DONE is final — re-opening requires documenting why in the manifest

Step-by-Step Procedure

Step 1 — Load the Plan

from pathlib import Path
import json

# Identify the plan file
plan_path = "docs/datapowers/plans/YYYY-MM-DD-<topic>-plan.md"
manifest_path = "artifacts/analysis_manifest.json"

# Read current manifest state
manifest = json.loads(Path(manifest_path).read_text())
print(f"Project: {manifest['project']}")
print(f"Last updated: {manifest['last_updated']}")

# List completed stages to avoid re-running
completed = [k for k, v in manifest.items() if isinstance(v, dict) and v.get("completed")]
print(f"Already completed: {completed}")