# Execution Plans

This directory contains execution plans for complex, multi-step work.

## What is an Execution Plan?

An execution plan (ExecPlan) is a living document that tracks progress on significant work. Unlike implementation specs (which define *what* to build), exec plans track *how* the work is progressing.

## Directory Structure

```
exec-plans/
├── active/           # Currently in progress
├── completed/        # Finished work (for reference)
├── tech-debt-tracker.md  # Known technical debt
└── README.md         # This file
```

## When to Use

Use an execution plan when:
- Work spans multiple sessions or days
- Multiple steps have dependencies
- Progress needs to be visible to humans
- Work involves significant research or discovery

Do NOT use for:
- Simple, single-session features
- Bug fixes
- Routine changes

## ExecPlan Format

See the [OpenAI Exec Plans cookbook](https://developers.openai.com/cookbook/articles/codex_exec_plans) for the full specification.

Key sections:
- **Purpose / Big Picture:** What someone gains after this change
- **Progress:** Checklist with timestamps
- **Surprises & Discoveries:** Unexpected findings
- **Decision Log:** Why choices were made
- **Outcomes & Retrospective:** Summary at completion