diff options
Diffstat (limited to 'claude-rules')
| -rw-r--r-- | claude-rules/todo-format.md | 57 |
1 files changed, 52 insertions, 5 deletions
diff --git a/claude-rules/todo-format.md b/claude-rules/todo-format.md index 24b5ca2..a8df76a 100644 --- a/claude-rules/todo-format.md +++ b/claude-rules/todo-format.md @@ -57,6 +57,53 @@ When adding a new task: When restructuring an existing entry that's already sentence-shaped, split it: keep the topic as the heading, move the rest to the body. +## Completion — depth-based + +How a finished `TODO` / `DOING` task is closed depends on its depth in the outline. The rule is *depth-based*, not keyword-based, because the agenda truncates beyond level-2 and the visibility tradeoff flips at that boundary. + +### Top-level tasks (`*` and `**`) — stay task-shaped + +A completed `*` section or `**` task keeps its `TODO`/`DOING`-shape so it remains visible in the agenda as a record of what shipped: + +1. Change the keyword to `DONE` (or `CANCELLED` if the task was abandoned rather than completed). +2. Add a `CLOSED: [YYYY-MM-DD Day]` line directly under the heading. Use `date "+%Y-%m-%d %a"` to generate. +3. Leave the original heading text, priority cookie, and tags intact. +4. Optionally add a one-line resolution note in the body. + +The entry is then a candidate for `--archive-done` in the wrap-up cleanup, which moves level-2 `DONE`/`CANCELLED` subtrees from the project's "Open Work" section into "Resolved." + +**Example:** + + ** TODO [#B] Convert <cj structure template to universal yasnippet + +becomes + + ** DONE [#B] Convert <cj structure template to universal yasnippet + CLOSED: [2026-05-15 Fri] + +### Sub-tasks (`***` and deeper) — rewrite to a dated event-log entry + +A completed sub-task disappears as a task and becomes an in-place event-log entry under its parent. The parent's subtree organically grows into a chronological history of what landed without the agenda being cluttered by a long tail of nested `DONE` lines. + +1. Replace the heading with `<same depth> YYYY-MM-DD Day @ HH:MM:SS -ZZZZ <past-tense description>`. +2. Generate the timestamp with `date "+%Y-%m-%d %a @ %H:%M:%S %z"`. +3. Reword the original imperative title into the past-tense action that landed. Trim or restate if the original wording doesn't fit the action. +4. Drop the `TODO`/`DOING` keyword, the priority cookie, and the tags. The body stays as the record of what was done (if useful). + +**Example:** + + *** TODO [#B] Wire yasnippet for universal availability :refactor: + +becomes + + *** 2026-05-15 Fri @ 12:58:08 -0500 Wired yasnippet for universal availability + +### Why depth-based + +The agenda view (`org-agenda`) shows entries at the section + top-task level. Letting `**` tasks stay task-shaped preserves their visibility as "things that recently shipped." Letting `***+` sub-tasks flip to dated entries keeps the agenda from being clogged with a long list of completed sub-tasks at every depth — those become history within their parent instead. + +`VERIFY` is the documented exception: it follows the dated-rewrite rule at **all** depths (including `**`), because a resolved VERIFY is an answered question rather than a finished task. See the VERIFY section below. + ## VERIFY tasks `VERIFY` is the keyword for "waiting on Craig's input" — open questions, @@ -142,11 +189,11 @@ The completed VERIFY becomes an in-place event log entry. The original question is preserved by the dated heading + body shape; anyone scanning the agenda or `git log` can see what was asked and what landed. -**Note on the top-level case.** Regular `**` DONE tasks normally stay -task-shaped with a `DONE` keyword + `CLOSED:` line (so they remain visible -in the agenda). VERIFYs at `**` are the exception — they convert to dated -log entries on completion because a resolved VERIFY isn't a "done task," -it's an answered question. The dated-rewrite rule wins for VERIFYs at all +**Note on the top-level case.** Regular `**` DONE tasks stay task-shaped +with a `DONE` keyword + `CLOSED:` line per *Completion — depth-based* +above. VERIFYs at `**` are the exception — they convert to dated log +entries on completion because a resolved VERIFY isn't a "done task," it's +an answered question. The dated-rewrite rule wins for VERIFYs at all depths. ### Don't leave stale placeholders |