# ExecPlan Guide

ExecPlans are living implementation docs for complex features/refactors.

## Active ExecPlan
- `docs/execplans/auth-phone-first-hardening.md`

## Other ExecPlans
- `docs/execplans/booking-notifications.md` (completed)
- `docs/execplans/booking-integrity.md` (completed)
- `docs/execplans/payments-moyasar.md` (completed)
- `docs/execplans/arabic-localization.md` (foundations completed)

## When To Use
Create/update an ExecPlan when work is cross-app, risky, or multi-step.

## Required Sections (all ExecPlans)
- `Purpose / Big Picture`
- `Progress` (checkboxes with timestamps)
- `Surprises & Discoveries`
- `Decision Log`
- `Outcomes & Retrospective`
- `Context and Orientation`
- `Plan of Work`
- `Validation and Acceptance`
- `Idempotence and Recovery`

## Operating Rules
- Keep plan self-contained and repo-path specific.
- Update the plan as you implement; do not treat it as static.
- Acceptance must be observable (API response/test/user-visible behavior).
- Include exact commands and working directory for validation.

## Minimal Skeleton
Use this structure for new plans:

```
# <Feature Name>

## Purpose / Big Picture
## Progress
- [ ] ...

## Surprises & Discoveries
- Observation: ...
  Evidence: ...

## Decision Log
- Decision: ...
  Rationale: ...
  Date/Author: ...

## Outcomes & Retrospective
## Context and Orientation
## Plan of Work
## Validation and Acceptance
## Idempotence and Recovery
```