# Plans HOWTO

Use `Plans/<project>/` for active project planning.
Keep knowledge, active work, completed work, and follow-up separate.

Core files:

- `README.md` — stable project knowledge.
- `TODO.md` — active plan.
- `DONE.md` — completion log.
- `FUTURE.md` — after-project follow-up.
- `QUESTIONS.md` — open-questions scratchpad (optional).
- `DECISIONS.md` — decision log (optional).
- `scripts/` — one-time and support scripts belonging to this project.
- `tmp/` — this project's scratch: temp files and temp scripts (gitignored).
- `done/` — archived artifacts.
- `Plans/done/<project>/` — completed project archive.

## File Roles

### `README.md`

Purpose: what a developer must know to work correctly.

Keep:
- project purpose
- current or target architecture
- contracts and invariants
- data sources, endpoints, jobs, services
- operational rules: where things live, what can change, what must stay stable
- stable layout
- canonical links

Avoid:
- tasks and blockers
- acceptance criteria
- test logs
- rejected attempts
- decision history
- backlog

### `TODO.md`

Purpose: current execution plan.

Keep:
- current objective
- next step
- active wave/task IDs
- dependencies and blockers
- acceptance criteria
- links to active task files/reports/scripts

Avoid:
- encyclopedia content
- completed task detail
- future follow-up
- noisy logs

### `DONE.md`

Purpose: concise completion log.

Keep:
- completed wave/task ID
- short result
- links to archived details
- useful commit/revision refs

Avoid:
- active work
- full logs
- copied task files
- current-state docs

### `FUTURE.md`

Purpose: work after project completion.

Keep:
- out-of-scope follow-up
- future product directions
- work needing a new ticket/project/decision

Avoid:
- active work
- current-scope blockers
- vague ideas

### `QUESTIONS.md`

Purpose: scratchpad for currently-open, unresolved questions (optional).

Keep:
- open questions that block or shape active work

Avoid:
- answered questions — remove each the moment it's decided
- decision records or rationale (those go to `DECISIONS.md`)
- history of any kind

Ideal state: empty — no noise accumulates here.

### `DECISIONS.md`

Purpose: running log of decisions taken during the project (optional).

Keep:
- what was decided, a one-line why, and where it landed
- dated entries

Avoid:
- open/undecided questions (those live in `QUESTIONS.md`)
- restating the full design — the design docs stay the source of truth

A resolved `QUESTIONS.md` item lands here as a one-line entry.

### `scripts/`

Purpose: scripts written for this project — one-time migrations, backfills, probes, DDL,
report generators.

Keep:
- one-time scripts owned by a plan task (`.php`, `.sql`, shell)
- support scripts a task links to from `TODO.md`

Avoid:
- throwaway scratch — that belongs in `tmp/`
- anything the product runs on a schedule or on request; a live script stays in
  the app's own `scripts/`

Name it short: `<task ID>-<slug>.<ext>`, the same form as task files. The directory already
says which ticket this is, so repeating it in every filename only adds noise. The task ID
is what matters — it is what ties the script to the task that owns it.

```
Plans/TCK-000-example-project/scripts/b2-backfill.php
Plans/TCK-000-example-project/scripts/b3-cube-ddl.sql
Plans/TCK-000-example-project/scripts/reconcile-counts.php
```

A script with no task behind it is just the slug, like the third one. A script moved in
from elsewhere drops its ticket prefix on the way.

`app/scripts/one-time/` stays for one-time scripts with no plan behind them. Once a
project has a `Plans/` directory, its scripts live with the plan and move with it to
`Plans/done/<project>/` on close.

### `done/`

Purpose: archived artifacts.

Keep:
- finished task files
- reports
- scripts
- snapshots
- frozen TODO copies, if useful

No active planning here.

### `tmp/`

Purpose: this project's scratch — temp scripts, dumps, one-off output, junk. Create it
when you need it.

Gitignored by the repo-wide `tmp` rule, so nothing here is committed and nothing here
survives review. A script run from here picks up the project bootstrap automatically, so scratch
code has the full app context without arguments.

Keep:
- nothing on purpose

Names are free-form here — the point of the directory is that nothing in it has to be
thought about. Delete freely; a file that turns out to be worth keeping moves to `scripts/`
(or `done/`) and earns a real name there. Junk stays out of `Plans/done/<project>/` — drop
`tmp/` when the project closes.

## Lifecycle

1. Create `README.md` and `TODO.md` for non-trivial work.
2. Add `FUTURE.md` only when needed.
3. Prefix task files with stable IDs: `A.1-name.md`.
4. Update docs when a task closes.
5. Move completed detail out of `TODO.md`.
6. Keep only open work in `TODO.md`.
7. On completion, move project to `Plans/done/<project>/`.

Task close:

- Single item done: add short `DONE.md` entry; keep only a terse `_Done -> DONE.md: <id>_` marker in `TODO.md` if useful.
- Section/wave done: remove it from `TODO.md`; summarize in `DONE.md`; archive detail under `done/`.
- After-project follow-up: move to `FUTURE.md`.
- Question resolved: remove it from `QUESTIONS.md`, log one line in `DECISIONS.md`.
- Active work stays out of `DONE.md`.
- Completed work stays out of `TODO.md`.

Project close:

- Keep `README.md` current.
- Keep `DONE.md` concise.
- Keep `FUTURE.md` only if follow-up exists.
- Archive useful snapshots under `done/`.
- Review current-state docs.
- Move directory to `Plans/done/<project>/`.

## Collapsible Details

Visible content: decisions, next steps, gates, blockers, wins.
Supporting material: `<details>`.

```html
<details>
<summary>**Why we dropped these**</summary>

Markdown works inside:

- lists
- **bold**
- `code`

</details>
```

## Naming

- Project dir for ticket-backed work: `<TICKET>-<short-slug>`, e.g.
  `TCK-630-analytics-charts`. Always include a short descriptive slug; a
  ticket-only directory such as `TCK-630` is not sufficient.
- Project dir for work without a ticket: a short descriptive slug, e.g.
  `search-parser`.
- IDs: `A`, `A.1`, `A.1.2`.
- Task files: `A.1-parse-cities.md`.
- Scripts: `f68b-backfill.php` — task ID and slug; the directory names the ticket already.
- Never renumber IDs.
- Use IDs in `TODO.md`, `DONE.md`, reports, commits, code comments.

## Waves

Use waves only for user-visible iterations.
Small work can use IDs only.

Rules:

- one wave = one deliverable
- review after each wave
- do not mix unrelated waves
- commit every completed wave
- commit complex subtasks when complete
- include docs work
- end with doc review
- push/merge only on explicit instruction
- change stable contracts only when required
- keep rollback possible per wave