diff options
| -rw-r--r-- | docs/design/2026-06-02-flush-promotion.org | 24 | ||||
| -rw-r--r-- | flush/SKILL.md | 6 | ||||
| -rwxr-xr-x | hooks/session-clear-resume.sh | 12 |
3 files changed, 39 insertions, 3 deletions
diff --git a/docs/design/2026-06-02-flush-promotion.org b/docs/design/2026-06-02-flush-promotion.org index d34ad89..9d9d8a3 100644 --- a/docs/design/2026-06-02-flush-promotion.org +++ b/docs/design/2026-06-02-flush-promotion.org @@ -207,3 +207,27 @@ points the fresh session at startup. - Promotion: this workflow + the hook are candidates for the rulesets templates (the wrap/restart-rhythm task predicted this). Validate here, then file to the rulesets inbox. + +* Refinement — notes.org-before-anchor on resume (work handoff, 2026-06-02 21:06) + +A follow-up handoff from work, implemented the same evening. On a flush resume, +read notes.org key sections BEFORE the session-context anchor. + +Motivating failure (work project, 2026-06-02): right after a flush resume, the +agent went to start a dashboard chore and concluded the dashboard repo wasn't +cloned — hunting =~/code= with shallow finds — when notes.org's code-locations +section documented the exact path. The resume had the anchor but not notes.org, +so it lacked the standing context and floundered. The anchor carries +session-specific state; notes.org carries the project's standing knowledge +(code-repo paths, conventions, key contacts) a resumed session needs to act +correctly. + +Changes landed: +- =hooks/session-clear-resume.sh= — anchor-present branch now injects "read + .ai/notes.org key sections (Project-Specific Context, Active Reminders, + Pending Decisions; skip About This File), then the anchor." Runtime-guarded on + notes.org presence: absent → resume from the anchor alone. +- =flush/SKILL.md= — Phase 2 (post-clear resume) documents the same read order + so the skill text and the hook agree. + +A small ordering/scope addition, not a redesign. diff --git a/flush/SKILL.md b/flush/SKILL.md index d46c18b..4c2709a 100644 --- a/flush/SKILL.md +++ b/flush/SKILL.md @@ -72,9 +72,11 @@ That is the wrap/restart rhythm. When both conditions hold, run Phase 1 and end This half is driven by the `SessionStart(clear)` hook, not by this skill — but it is documented here so the loop is legible. -1. The user types `/clear`. The hook `~/.claude/hooks/session-clear-resume.sh` fires and injects "read the anchor, reply 'flushed.', resume" into the fresh context. +1. The user types `/clear`. The hook `~/.claude/hooks/session-clear-resume.sh` fires and injects the resume instruction into the fresh context. 2. The user sends any message (e.g. "go", "resume"). The injected context loads at `/clear` but the model waits for the user's next message before acting — that one keystroke is expected, not a bug. -3. The fresh agent reads the anchor, replies `flushed.` on its own line, restates the Active Goal and immediate Next Step, and continues. It does NOT run startup or re-sync anything — this is a resume, not a fresh start. +3. The fresh agent reads `.ai/notes.org` key sections (Project-Specific Context, Active Reminders, Pending Decisions) first, then the anchor, replies `flushed.` on its own line, restates the Active Goal and immediate Next Step, and continues. It does NOT run startup or re-sync anything — this is a resume, not a fresh start. + +The notes.org-before-anchor order matters: the anchor carries session-specific state, but notes.org carries the project's standing knowledge — code-repo paths, conventions, key contacts — that a resumed session needs to act correctly. Reading the anchor alone has led a resumed session to flounder on context notes.org already documents. When notes.org is absent, the hook resumes from the anchor alone. If the anchor is absent (a stray `/clear` with no prior flush), the hook instead points the fresh session at the startup workflow. diff --git a/hooks/session-clear-resume.sh b/hooks/session-clear-resume.sh index 6692f54..56b7b2f 100755 --- a/hooks/session-clear-resume.sh +++ b/hooks/session-clear-resume.sh @@ -45,7 +45,17 @@ else fi if [ -f "$sc" ]; then - ctx="A context flush just happened (/clear). The session-context anchor is at ${sc}. Read it now — the * Summary (Active Goal, Next Steps) plus the most recent * Session Log entries — then reply with 'flushed.' on its own line, followed by one line restating the Active Goal and the immediate Next Step, and resume that work. This is a mid-session resume, NOT a fresh start: do not run the startup workflow, do not re-pull rulesets or re-sync templates." + # On resume, read notes.org standing knowledge (code-repo paths, + # conventions, key contacts) BEFORE the anchor — the anchor carries + # session state, notes.org carries the project context a resumed session + # needs to act correctly. Same "key sections" scope startup uses. Only + # when notes.org is present; otherwise resume from the anchor alone. + if [ -f ".ai/notes.org" ]; then + read_order="First read .ai/notes.org key sections (Project-Specific Context, Active Reminders, Pending Decisions; skip About This File) for the project's standing knowledge — code-repo paths, conventions, key contacts. Then read the session-context anchor at ${sc}" + else + read_order="Read the session-context anchor at ${sc}" + fi + ctx="A context flush just happened (/clear). ${read_order} — the * Summary (Active Goal, Next Steps) plus the most recent * Session Log entries. Then reply with 'flushed.' on its own line, followed by one line restating the Active Goal and the immediate Next Step, and resume that work. This is a mid-session resume, NOT a fresh start: do not run the startup workflow, do not re-pull rulesets or re-sync templates." else ctx="Session started with no session-context anchor present (.ai/session-context.org absent). Run the startup workflow at .ai/workflows/startup.org." fi |