Task Planning and Execution

Part of the three-tier planning system. See /plan for an overview.

This skill guides implementation of a single task, from initial planning through completion. It maintains an execution log that captures problems, decisions, and learnings along the way.

Inputs

Before starting, read:

• The milestone plan containing this task
• docs/plan/learnings.md - to incorporate lessons from previous work
• Any relevant decision documents in docs/plan/decisions/

Output

Two files in docs/plan/milestones/{milestone}/tasks/{task}/:

• task.md - The plan and final outcome (living document, update as things change)
• execution-log.md - Running log updated during implementation (captures the journey)

The task plan is a living document. Update scope, approach, and checklist as things evolve. The execution log preserves history, so there's no need to treat the plan as a snapshot.

Lifecycle

A task moves through three phases:

Phase 1: Planning

Before writing code, understand what we're building and how. Planning is iterative - expect to refine the approach through discussion before it's finalized.

This phase requires your approval before proceeding to execution.

1.1 Context Review

• Review the task's summary, scope, and acceptance criteria from the milestone plan
• Review applicable learnings from previous tasks
• Confirm understanding of what "done" looks like

1.2 Codebase Exploration

• Identify the files and systems involved
• Understand existing patterns and conventions
• Note integration points with other code

1.3 Approach Design

• Outline the implementation approach
• Identify changes needed (new files, modifications, deletions)
• Consider edge cases and error handling
• Flag uncertainties that need resolution

Capture the plan in the task document. Review and iterate until the approach is solid, then get explicit approval before proceeding to implementation.

Phase 2: Execution

During implementation:

• Keep the implementation steps checklist in task.md current as steps are completed
• Maintain the execution log in execution-log.md

When to Update the Log

Update the execution log whenever:

• A new issue is encountered - describe the issue and its solution
• A key decision is made - capture the choice and rationale
• A lesson is learned - note insights that apply to future work
• 10 minutes have passed since the last update - review and capture any salient information

Do not let updates accumulate. Frequent, small updates are more valuable than infrequent summaries.

What to Capture

• Issues and solutions: Problems encountered and how they were resolved
• Decisions: Technical choices and their rationale
• Scope changes: Anything that changed from the original plan and why
• Observations: Things noticed that might be relevant later

Checkpoints

At natural breakpoints, review progress:

• Is the approach still sound?
• Have we discovered anything that changes the plan?
• Are there decisions that should be recorded formally in docs/plan/decisions/?
• Does the implementation steps checklist need updating (new steps, changed steps, removed steps)?

Phase 3: Completion

When the task is done:

3.1 Acceptance Verification

• Verify each acceptance criterion is met
• Confirm tests are passing
• Ensure the PR is ready for review

3.2 Learning Capture

Review the execution log and extract learnings from this task:

• What would we do differently next time?
• What worked well that we should repeat?
• What did we learn that applies to future tasks?

Consolidate and distill insights from the execution log entries into docs/plan/learnings.md.

3.3 Cleanup

• Update the milestone plan if this task revealed new information
• Create decision documents for any significant decisions made
• Note if downstream tasks are affected

Task Document Template

Create at docs/plan/milestones/{milestone}/tasks/{task}/task.md:

# Task: {identifier} - {name}

## Summary

{From milestone plan}

## Scope

{From milestone plan, updated if changed}

## Acceptance Criteria

{From milestone plan}
- [ ] {Criterion 1}
- [ ] {Criterion 2}

## Applicable Learnings

{Lessons from previous work that apply to this task}

## Plan

### Files Involved

{List of files to create, modify, or delete}

### Approach

{How we're going to implement this}

### Implementation Steps

- [ ] {Step 1}
- [ ] {Step 2}
- [ ] {Step 3}

### Open Questions

{Uncertainties to resolve during implementation}

## Outcome

### Acceptance Verification

- [x] {Criterion 1 - verified}
- [x] {Criterion 2 - verified}

### Learnings

{What we learned from this task - also append to docs/plan/learnings.md}

### Follow-up Items

{Anything discovered that affects other tasks or the milestone plan}

Execution Log Template

Create at docs/plan/milestones/{milestone}/tasks/{task}/execution-log.md.

Entries are in reverse chronological order - newest at the top, so the latest activity is always visible first.

# Execution Log: {identifier} - {name}

## {Timestamp} - Latest entry

{Entry describing what happened}

**Issue:** {If applicable - describe the problem}
**Solution:** {How it was resolved}

**Decision:** {If applicable - what was decided and why}

**Learning:** {If applicable - insight for future work}

## {Timestamp} - Previous entry

{Earlier entry}