From cea44a936d895bddde3126740822334a8db5e8ff Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Fri, 15 May 2026 18:09:18 -0500 Subject: docs(start-work): encode follow-up filing placement rules Phase 4 step 5's "Disposition for each candidate" now spells out where to file a "file a ticket" follow-up in todo.org: siblings for epic-style parents (level-2 with level-3 children), new level-2 entries for standalone tasks. Both cases require a "Triggered by:" line so a future reader sees the origin. The placement rule lived in project memory but didn't propagate across projects. Encoding in start-work makes it cross-project default behavior. --- .claude/commands/start-work.md | 7 +++++++ todo.org | 3 ++- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/.claude/commands/start-work.md b/.claude/commands/start-work.md index 935cab5..1da2f89 100644 --- a/.claude/commands/start-work.md +++ b/.claude/commands/start-work.md @@ -215,6 +215,13 @@ Follow the red-green-refactor cycle from `testing.md`. - *Fix now, separate `refactor:` commit on this branch*: related to the surface you touched but larger in scope, or reshaping something non-trivial. Separating it keeps the feature commit focused for review. - *File a ticket or todo.org entry*: the smell is real but unrelated to this task, lives in a touched file outside the task's working set, or was noticed in an untouched file. Filing — not skipping — is the default for anything that does not fit the two "fix now" cases. Capture enough detail that a future session can act on it: file path, line or function, smell category (one of a through h), and a one-line description. + **Where to file in todo.org.** Placement matters because follow-ups nested under a parent task get orphaned when the parent closes. + + - *Epic-style parent task* (level-2 `** TODO` with multiple level-3 `*** TODO` children): file the follow-up as a level-2 *sibling* of the parent, immediately after the parent's last child block. Siblings stay visible after parent closure and don't get archived under one specific child. + - *Standalone task* (level-2 with no children, or a level-3 inside another structure): file as a new level-2 entry in the same `* Open Work` section. Don't nest under the originating task. + - Both cases: include a "Triggered by: YYYY-MM-DD " line in the new task body so a future reader sees what surfaced it. + - Priority on the new task is its own decision, not inherited from the originating task. + If a candidate feels too small to fix and too small to file, it was either not a real smell, or you are talking yourself out of a two-line todo entry. Write the entry. **Stop conditions.** The *audit* is complete when every touched file has been walked and every candidate has a disposition. The *fixing* stops earlier: ask "would a reasonable reviewer flag this?" of the remaining in-scope candidates. If the answer is no, stop fixing and file the rest. Shipping beats polishing, but filing beats forgetting. diff --git a/todo.org b/todo.org index 68afc43..670f2c7 100644 --- a/todo.org +++ b/todo.org @@ -1771,7 +1771,8 @@ The four canonical rules (=commits=, =testing=, =verification=, =subagents=) are The Elisp pair is the most suspicious — three repos using essentially the same rules. Audit: diff these across the projects, check for drift, then decide whether to canonicalize them under =~/code/rulesets/claude-rules/languages//= and symlink, or leave them as project-local. -** TODO [#B] Encode follow-up filing rules into =/start-work= +** DONE [#B] Encode follow-up filing rules into =/start-work= +CLOSED: [2026-05-15 Fri] Phase 4 step 5 of =/start-work= ("refactor audit") says any candidate that isn't fix-now must land in one of three buckets: fold-into-related-commit, separate =refactor:= commit, or "file a ticket or todo.org entry." The third disposition doesn't say *where* — which leaves the orchestrator picking a location ad-hoc. Result: follow-ups buried under children of an epic parent get orphaned when the parent closes, or follow-ups for standalone tasks scatter across the file with no convention. -- cgit v1.2.3