tkolleh save-zk
Run only on explicit invoke: save-zk or /save-zk. No other phrases.
Phases A → I in order. Never skip or reorder. After Phase A, write immediately (no second confirm). Dry-run only if the user asked.
Load references on demand: references/note-template.md, references/living-head.md, references/session-context.md.
Phase A — Note Key gate
- Suggest candidates from branch name, open PR/issue, or session materials when present.
- Human supplies or confirms the Note Key (tracker id) or a ≤8-word slug.
- Never invent or silently pick a key. Stop until confirmed.
Done when: confirmed Note Key/slug in hand.
Phase B — Gather Session Context
This session only. Fan out reads in parallel when independent.
| In | Out |
|---|---|
| Session memories, touched markdown/allium, new/updated diagram fences or charts | Whole-repo docs crawl |
| Decisions stated in-session | Secrets, tokens, credentials |
| Branch / PR / issue metadata when available | Unrelated history |
Mark each source present or unavailable. Details: references/session-context.md.
Done when: every candidate source is present or marked unavailable.
Phase C — Note Lookup
Prefer tag match on the issue key; filename match is fallback.
| Hits | Action |
|---|---|
| 0 | Create |
| 1 | Update that note |
| >1 | Update most recently modified match — do not ask; do not merge files |
Issue-key Note Keys must be (or become) frontmatter tags.
Done when: create vs update decided and target path known (or create path planned).
Phase D — Daily Note resolve
zk daily
Record Daily Note path, or mark unavailable (do not invent a path).
Done when: path known or explicitly unavailable.
Phase E — Distill
Compose per references/note-template.md + references/living-head.md.
- Create: full Living Head + top-level Deep Context
<details>. No Update section. - Update: replacement Living Head + one new
## Update: YYYY-MM-DDdelta only. Do not rewrite prior Updates or frozen create-time Deep Context. - Concision: shortest form that still carries meaning. No Task Matrix section.
Done when: markdown body ready to write.
Phase F — Visual Section
Include in Living Head only when multi-component structure/flow or numeric metrics apply:
- Reuse
d2/mermaidfences already in Session Context. - Else draft a minimal fence or metric table in-note.
- Omit or clear when N/A.
No asset files, no base64, no hard dependency on diagram/visualize CLIs.
Done when: Visual present, cleared, or omitted with reason N/A.
Phase G — Related Links
Best-effort real [[wikilinks]] from notebook search + link to today's Daily Note. Never invent titles. Omit non-daily related links if none.
Done when: links list final (may be Daily-only).
Phase H — Write
- Session Note (primary)
- Create: prefer
zk newinto the single Session Note Location (key-agnostic; parameterize with Note Key). Onzk newfailure, write markdown under the notebook projects path and report fallback. - Update: replace only the Living Head; append the new Update at the bottom.
- Create: prefer
- Daily Note (best-effort): append one back-link line that the Session Note was created or updated. On Daily failure: keep Session Note, warn. On Session Note failure: skip Daily.
Done when: Session Note write attempted; Daily attempted if Session succeeded.
Phase I — Report
Paths written + BLUF + any Daily warning. If user asked dry-run, show composed markdown and paths only — no writes.
Done when: human sees report.
Safety contract
- May replace only the Living Head.
- Must not alter, delete, or reorder prior Updates or frozen create-time Deep Context.
- Must not delete Session Note, Daily Note, or session sources.
- If unsure content already exists → append or mark
<!-- possibly duplicate — review -->. - No worktree removal, git cleanup, tracker transitions, or other notebook edits.