m038andClaude Opus 5
9ec2349cd6
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>
53 lines
3.2 KiB
Markdown
53 lines
3.2 KiB
Markdown
# 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'
|
|
```
|