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) <noreply@anthropic.com>
This commit is contained in:
+1
-1
@@ -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)
|
||||
|
||||
@@ -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-<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` | 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 — <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'
|
||||
```
|
||||
Reference in New Issue
Block a user