From 421b17a15219c7061ee92c07451993965fad88ea Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Fri, 15 May 2026 15:05:37 -0500 Subject: docs: codify depth-based completion rule + DRY the skill reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Todo-format.md gets a "Completion — depth-based" section that codifies what was implicit before: top-level (* and **) DONE tasks stay task-shaped (DONE + CLOSED line), sub-tasks (*** and deeper) flip to dated event-log entries, and VERIFY is the documented exception (always dated-rewrite regardless of depth). The section includes worked examples and the rationale for depth-based over keyword-based. The cj-comments skill's completion section now references the canonical rule instead of restating the depth-based rules inline. The three-bullet recap in the skill stays as a quick scan, but the details and examples live in one place. --- claude-rules/todo-format.md | 57 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 52 insertions(+), 5 deletions(-) (limited to 'claude-rules') 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 YYYY-MM-DD Day @ HH:MM:SS -ZZZZ `. +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 -- cgit v1.2.3