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:

markdown

# 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.

markdown

# 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}