# docs/working/ — work in flight

Everything here is a live working document: specs being built from, plans being executed, notes from sessions in progress. Once something is finished it stays (as a record) rather than being deleted — the `**Status:**` line is how you tell the difference.

Stable facts belong in [`../reference/`](../reference/); how-to procedures in [`../guides/`](../guides/); write-ups of bugs already solved in [`../solutions/`](../solutions/).

> ⚠️ **Everything here is written in the past tense, even when it reads present-tense.** A completed
> plan describes the code *as it was when the plan landed* — that is what makes it a useful record,
> and it is not a defect when it no longer matches. Several documents here describe features that were
> later deliberately reversed: there is no `/map` page, no `/stats` page, no `/tracker`, no Leaflet, no
> light theme, and no `hero_image` on entries.
>
> **Before re-creating anything you find in this folder, check
> [`../reference/superseded-decisions.md`](../reference/superseded-decisions.md).** Superseded sections
> also carry an inline `> **Superseded …**` note pointing there. For the site as it is, read
> [`../reference/architecture.md`](../reference/architecture.md).

---

## What's in here

| Path | Contents |
|---|---|
| `specs/` | Design docs — the *what* and *why*, written before a plan. Named `YYYY-MM-DD-<topic>-design.md` |
| `plans/` | Implementation plans — the ordered *how*, with a status line. Named `YYYY-MM-DD-<topic>.md` |
| `milestones/` | Milestone scope documents (`milestone-1.md` … ) |
| `qa/` | Test plans, QA results, readiness audits |
| `handovers/` | Session handover notes — context for picking up unfinished work |
| `learnings/` | Retrospective notes worth keeping but not yet promoted to `../solutions/` |
| `backlog.md` | Unscheduled ideas and wishes |
| `bugs-and-fixes.md` | Running log of bugs found and what fixed them |
| `summary.md` | **Historical** wrap-up of the original four-milestone branch (2026-06-21). *Not* the current state — for that read [`../reference/architecture.md`](../reference/architecture.md) |
| `pm-analysis.md`, `git-sync-notes.md`, dated one-offs | Standalone notes, kept for reference |

---

## Plan status convention

Every plan in `plans/` carries a `**Status:**` line immediately after its title heading. This is the single place a plan's state is recorded — there is no separate tracker.

| Status | Meaning |
|---|---|
| `📋 Not started` | Plan written and reviewed; no work begun yet |
| `🔄 In progress — <note>` | Actively being worked on. The note says where it stopped, so anyone (or any session) can resume |
| `⏸️ Deferred — <reason>` | Intentionally postponed. Still valid, just not now — the reason matters more than the status |
| `✅ Complete (YYYY-MM-DD)` | Done and shipped. The date is when it landed, not when the plan was written |
| `❌ Abandoned — <reason>` | Won't be implemented. Kept so the decision (and its reasoning) is not re-litigated later |

Notes on using it:

- **A trailing note after `✅ Complete` is normal and encouraged** for anything non-trivial — what actually shipped, what was deferred, which commit or environment it landed in. Several plans here carry a paragraph.
- **`Deferred` is not `Abandoned`.** Deferred means "still want this"; abandoned means "decided against it". Keeping them distinct is the whole point of having both.
- **Update the status when the work lands**, not later. A plan whose status lags reality is worse than no plan, because it is trusted.

### Asking Claude what's open

Claude reads these statuses directly (the convention is also in [`../../CLAUDE.md`](../../CLAUDE.md), so it applies without being asked). When asked what's open it will surface `Not started` and `In progress`, show `Deferred` items with the label made explicit, and leave out `Complete` and `Abandoned` unless you ask for them. It sets the status to `✅ Complete (YYYY-MM-DD)` on finishing a plan.

A quick manual sweep of the same thing:

```bash
grep -rH '^\*\*Status:\*\*' docs/working/plans/ | grep -v 'Complete\|Abandoned'
```