From 9ec2349cd667a958a1a41ab93bead2123a5588ed Mon Sep 17 00:00:00 2001 From: Mischa Date: Fri, 24 Jul 2026 21:48:00 +0200 Subject: [PATCH] docs(working): add a human-facing index + plan status reference CLAUDE.md keeps the status convention as a one-line rule (it has to be loaded to be followed). This is the same convention written out for a human reader, with the meanings the trim dropped, plus what each subfolder of docs/working/ is for and a grep one-liner for "what's open". Notes the two distinctions that matter in practice: Deferred is not Abandoned, and a trailing note after "Complete" is normal. Co-Authored-By: Claude Opus 5 (1M context) --- docs/README.md | 2 +- docs/working/README.md | 52 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+), 1 deletion(-) create mode 100644 docs/working/README.md diff --git a/docs/README.md b/docs/README.md index 3f913ad..269e2e2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,7 +8,7 @@ - [Switching to a new trip](guides/trip-switching.md) - [Rebuilding local dev from scratch](guides/local-setup.md) -**Checking project status?** → [`working/`](working/) +**Checking project status?** → [`working/`](working/) — [what's in there + the plan status convention](working/README.md) - [Backlog](working/backlog.md) - [Bugs and fixes](working/bugs-and-fixes.md) - [QA results](working/qa/results.md) diff --git a/docs/working/README.md b/docs/working/README.md new file mode 100644 index 0000000..f5b960d --- /dev/null +++ b/docs/working/README.md @@ -0,0 +1,52 @@ +# 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/). + +--- + +## What's in here + +| Path | Contents | +|---|---| +| `specs/` | Design docs — the *what* and *why*, written before a plan. Named `YYYY-MM-DD--design.md` | +| `plans/` | Implementation plans — the ordered *how*, with a status line. Named `YYYY-MM-DD-.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` | Project summary / current state | +| `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 — ` | Actively being worked on. The note says where it stopped, so anyone (or any session) can resume | +| `⏸️ Deferred — ` | 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 — ` | 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' +```