Implementation Planning skill for Codex

A plan is good when someone else could execute it without asking what you meant, every step leaves the system working and has its own check, the risky parts are named with a mitigation, and the user approved the approach before code was written. The plan is grounded in the actual code: it cites files and functions, not hypothetical layers.

When to plan (and when not to)

Request	Plan?
One-file fix with an obvious cause and a test	No; just do it and report
Touches more than ~3 files, or several modules	Short plan (goal, steps, checks)
Ambiguous requirements, or more than one reasonable approach	Plan with options and a recommendation; ask before building
Data migrations, auth, payments, public API, infra	Full plan with risks, rollout and rollback; explicit approval
Spans days or several PRs	Full plan, saved to a file and updated as you go

If the user said “just do it”, keep the plan to a few lines in chat, but still name any destructive or irreversible step and ask before it.

Workflow

- [ ] 1. Restate the goal, success criteria and non-goals in your own words
- [ ] 2. Read AGENTS.md and the code involved; record file paths and current behaviour
- [ ] 3. List open questions; ask the ones that change the approach
- [ ] 4. Choose an approach (compare 2-3 only if they differ materially)
- [ ] 5. Break into small steps, each with a verification
- [ ] 6. Identify risks, rollout and rollback
- [ ] 7. Write the plan (template below) and ask for approval
- [ ] 8. Execute step by step; update the plan when reality differs

Step 1: restate

Write the goal as an observable outcome: “Admins can export invoices for a date range as CSV from the billing page; exports over 50k rows are emailed.” Then non-goals: “No PDF export; no changes to invoice generation.” Non-goals prevent the scope creep that wrecks estimates.

Step 2: ground it in the code

Read before planning. Find the entry points, the data model, similar existing features to copy, and the tests that cover the area:

rg -n "invoice" --type py -l | head -30
rg -n "def export_|class .*Export" -t py
git log --oneline -10 -- src/billing/          # recent changes and their authors

Record current behaviour with file:line references. A plan that says “update the service layer” without naming the file has not been grounded.

Step 3: questions

Separate questions into:

• Blocking: answers change the design (e.g. “Must exports respect row-level permissions per region?”). Ask before going further.
• Assumable: pick a sensible default, write it in the plan as an assumption, and let the user correct it.

Ask blocking questions in one batch, not one at a time.

Step 4: approach

Default to the approach that matches existing patterns in the codebase. Present alternatives only when they differ in cost, risk or capability:

| Option | Pros | Cons | Effort |
|---|---|---|---|
| A. Sync CSV stream from API (recommended) | Reuses streaming helper in api/streaming.py; no new infra | Long requests for big ranges | S |
| B. Background job + email link | Handles any size | Needs job queue setup, storage, expiry | M |

Step 5: steps that can be verified

Rules for steps:

• Each step is small enough to review in one sitting and ends with the system working.
• Each step has a concrete check: a test name, a command, an observable behaviour.
• Order steps to retire risk early: spike the unknown part first, then build around it.
• Prefer additive steps (new code path behind a flag, new column nullable) before switching behaviour, then cleanup steps last.
• Mark which steps are separate commits or PRs.

Step 6: risks, rollout, rollback

For each risk: likelihood, impact, mitigation, and how you will detect it. Typical sources: data migrations on large tables, concurrency, permissions, performance on real volumes, third-party limits, backward compatibility of APIs and stored data.

Plan template

Save as docs/plans/<date>-<slug>.md or PLAN.md if the work spans sessions and the user agrees; otherwise post it in chat.

# Plan: Invoice CSV export

## Goal
Admins export invoices for a date range as CSV from Billing > Invoices.
**Done when:** export of 10k invoices downloads in < 10 s and matches the on-screen totals.
**Non-goals:** PDF export; changes to invoice numbering.

## Current state
- Invoices listed by `InvoiceListView` (src/billing/views.py:120), query in `InvoiceRepo.search` (src/billing/repo.py:45)
- Streaming helper exists: `stream_csv` (src/api/streaming.py:10), used by orders export

## Assumptions and open questions
- Assumed: admins only (existing `billing.view_all` permission)
- **Blocking:** should amounts be in invoice currency or converted to EUR?

## Approach
Option A (sync streaming); B considered and rejected for now (see table).

## Steps
1. Add `InvoiceRepo.iter_for_export(range)` using server-side cursor. Check: unit test with 3 fixtures; `EXPLAIN` uses `invoices_created_at_idx`.
2. Add `GET /billing/invoices/export.csv` behind flag `billing-invoice-export`. Check: API test for headers, auth (403 for non-admin), CSV columns.
3. Add Export button in UI behind same flag. Check: component test; manual check in dev.
4. Load test with 50k rows in staging. Check: < 10 s, memory flat.
5. Enable flag for internal admins, then all. Check: error rate, request duration.
6. Remove flag after one release. Check: rg finds no flag references.

## Risks
| Risk | Impact | Mitigation | Detection |
|---|---|---|---|
| Long query locks or slows primary | High | Read replica; statement timeout 30 s | DB dashboard during step 4 |
| Exposes invoices across tenants | Critical | Reuse tenant-scoped repo method; explicit test | Test in step 2 |

## Rollout and rollback
Flag-gated; rollback = flag off. No schema changes.

## Test plan
Unit (repo), API (auth, format), component (button), load (50k rows), manual check of totals.

## Progress
- [ ] Step 1 ...

Executing the plan

• Get approval before step 1. Approval of the plan is not approval for destructive actions inside it; confirm those again when you reach them (migrations on shared data, deploys, deleting data, sending messages).
• After each step, run its check, tick it in the plan, and note surprises.
• When reality contradicts the plan (an assumption was wrong, a step is twice as big), stop, update the plan, and tell the user what changed before continuing. Silent deviation is how plans lose trust.
• For long tasks, keep the plan file as the source of truth so work survives a context reset or handoff.

Gotchas

• Plans written before reading the code are guesses with headings. Ground every step in real files.
• Ten-step plans where step 9 is “integrate everything” hide the risk at the end. Integrate early with a thin end-to-end slice.
• Estimates without the riskiest unknown spiked are optimistic by default; say so.
• Do not pad plans with generic steps (“write clean code”, “add tests”). Name which tests.
• Overlong plans go unread. Keep steps to one or two lines each; detail goes into the PRs.

Verification

• Every step has a check that can pass or fail.
• Every blocking question is answered or explicitly assumed with the user’s agreement.
• At the end, the “Done when” criteria are demonstrated, and the plan’s progress section matches what was actually done.