> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/obra/superpowers/llms.txt
> Use this file to discover all available pages before exploring further.

# Executing Plans

> Execute written plans in batches with review checkpoints for architect feedback

## Overview

The Executing Plans skill loads a written implementation plan and executes tasks in batches, pausing for review between batches. This creates checkpoints where the architect can provide feedback before continuing.

<Note>
  **Core principle:** Batch execution with checkpoints for architect review.
</Note>

## When to Use

Use when:

* You have a written implementation plan from [Writing Plans](/skills/writing-plans)
* You want to execute in a **separate session** (not the brainstorming session)
* You want review checkpoints between batches

**Alternative:** Use [Subagent-Driven Development](/skills/subagent-driven-development) if you want to stay in the current session with per-task subagents.

## The Process

<Steps>
  <Step title="Step 1: Load and Review Plan">
    1. Read plan file from `docs/plans/YYYY-MM-DD-<feature>.md`
    2. Review critically - identify any questions or concerns
    3. **If concerns:** Raise them with your human partner before starting
    4. **If no concerns:** Create TodoWrite and proceed

    **Announce at start:**

    ```
    I'm using the executing-plans skill to implement this plan.
    ```
  </Step>

  <Step title="Step 2: Execute Batch">
    **Default: First 3 tasks**

    For each task:

    1. Mark as `in_progress` in TodoWrite
    2. Follow each step exactly (plan has bite-sized steps)
    3. Run verifications as specified
    4. Mark as `completed` in TodoWrite

    <Note>
      Plans include TDD steps: write test, run to verify fail, implement, run to verify pass, commit.

      Follow these exactly.
    </Note>
  </Step>

  <Step title="Step 3: Report">
    When batch complete:

    ```
    Batch 1 complete (Tasks 1-3):

    Task 1: Metrics Collector
    - Implemented MetricsCollector class
    - Tests: 3/3 passing
    - Committed: abc123f

    Task 2: Storage Layer  
    - Implemented SQLite storage
    - Tests: 5/5 passing
    - Committed: def456a

    Task 3: Export to JSON
    - Implemented JSON exporter
    - Tests: 4/4 passing
    - Committed: ghi789b

    All tests passing. Ready for feedback.
    ```
  </Step>

  <Step title="Step 4: Continue">
    Based on feedback:

    * **Apply changes if needed** (fix issues, adjust approach)
    * **Execute next batch** (next 3 tasks)
    * **Repeat** until complete
  </Step>

  <Step title="Step 5: Complete Development">
    After all tasks complete and verified:

    1. Announce: "I'm using the finishing-a-development-branch skill to complete this work."
    2. **REQUIRED SUB-SKILL:** Use `superpowers:finishing-a-development-branch`
    3. Follow that skill to verify tests, present options, execute choice
  </Step>
</Steps>

## Visual Workflow

```mermaid theme={null}
graph TD
    A[Load Plan] --> B[Review Critically]
    B --> C{Concerns?}
    C -->|Yes| D[Raise with Human]
    C -->|No| E[Create TodoWrite]
    E --> F[Execute Batch of 3]
    F --> G[Report Results]
    G --> H[Wait for Feedback]
    H --> I{More Tasks?}
    I -->|Yes| F
    I -->|No| J[Finishing Skill]
```

## Batch Size

**Default:** 3 tasks per batch

**Adjust based on:**

* Task complexity (smaller tasks = more per batch)
* Uncertainty (higher uncertainty = fewer per batch)
* Human preference (ask if unsure)

```
"The plan has 12 tasks. I'll execute in batches of 3, 
providing checkpoints after tasks 3, 6, 9, and 12. 
Okay?"
```

## When to Stop and Ask

**STOP executing immediately when:**

* Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
* Plan has critical gaps preventing starting
* You don't understand an instruction
* Verification fails repeatedly

<Warning>
  Ask for clarification rather than guessing. Stop and report the blocker.
</Warning>

**Example:**

```
Task 2, Step 3: Blocked

The plan says "Import the validator" but I don't see 
a validator module in the codebase. Should I:
A) Create a new validator module
B) Use an existing validation library
C) Skip validation for now

Waiting for guidance before continuing.
```

## When to Revisit Earlier Steps

**Return to Review (Step 1) when:**

* Partner updates the plan based on your feedback
* Fundamental approach needs rethinking
* Multiple tasks fail in similar ways (plan issue, not implementation issue)

**Don't force through blockers** - stop and ask.

## Example Session

<Accordion title="Complete Execution Example">
  ```
  You: I'm using the executing-plans skill to implement this plan.

  [Read docs/plans/2026-03-09-metrics-tracking.md]

  Reviewing plan... looks good, no concerns. 
  Creating TodoWrite with 12 tasks.

  ---

  Executing Batch 1 (Tasks 1-3):

  Task 1: Metrics Collector
  [Mark in_progress]
  [Follow steps: write test, verify fail, implement, verify pass, commit]
  [Mark completed]

  Task 2: Storage Layer
  [Mark in_progress]  
  [Follow steps: write test, verify fail, implement, verify pass, commit]
  [Mark completed]

  Task 3: Export to JSON
  [Mark in_progress]
  [Follow steps: write test, verify fail, implement, verify pass, commit]
  [Mark completed]

  ---

  Batch 1 complete:

  Task 1: Metrics Collector ✓
  - Implemented track() and get_events()
  - Tests: 3/3 passing
  - src/metrics/collector.py:1
  - Committed: abc123f

  Task 2: Storage Layer ✓
  - SQLite persistence
  - Tests: 5/5 passing  
  - src/metrics/storage.py:1
  - Committed: def456a

  Task 3: Export to JSON ✓
  - JSON exporter with streaming
  - Tests: 4/4 passing
  - src/metrics/exporters/json.py:1
  - Committed: ghi789b

  All tests passing (12/12). Ready for feedback.

  ---

  Human: Looks good, continue

  You: Executing Batch 2 (Tasks 4-6)...

  [Continue until all tasks complete]

  ---

  All tasks complete. Using finishing-a-development-branch skill...
  ```
</Accordion>

## Advantages

**vs. Manual execution:**

* Systematic progress through plan
* TodoWrite tracks state
* Clear checkpoints

**vs. Subagent-Driven Development:**

* Simpler (no subagent dispatch)
* Continuous context (same agent throughout)
* Good for tightly coupled tasks

**Trade-offs:**

* Same agent = context accumulation
* No fresh perspective per task
* Better for linear workflows

## Red Flags

**Never:**

* Start implementation on main/master branch without explicit user consent
* Skip verifications ("I'm sure it works")
* Proceed with failing tests ("I'll fix it later")
* Batch more tasks when blocked
* Guess at unclear instructions
* Force through blockers

**If blocked:**

1. Stop executing
2. Report the blocker clearly
3. Wait for guidance
4. Don't guess or "try something"

## Checklist

Before each batch:

* [ ] Marked tasks as in\_progress
* [ ] Followed plan steps exactly
* [ ] Ran all verifications
* [ ] All tests passing
* [ ] Committed changes
* [ ] Marked tasks as completed

After each batch:

* [ ] Reported what was implemented
* [ ] Showed verification output
* [ ] Noted any issues or concerns
* [ ] Said "Ready for feedback"
* [ ] Waited for feedback before continuing

## Related Skills

* **[Writing Plans](/skills/writing-plans)**: Creates the plan this skill executes
* **[Subagent-Driven Development](/skills/subagent-driven-development)**: Alternative execution with per-task subagents
* **[Test-Driven Development](/skills/test-driven-development)**: Follow TDD for each task

<Tip>
  Checkpoints create opportunities to correct course before investing too much effort in the wrong direction.
</Tip>