Save a comprehensive session log to the appropriate `session-logs/` directory, then sync the repo. `/save` and `/sync` share `bash .claude/scripts/sync.sh` as the canonical driver for git operations. The only difference: `/save` writes a session log first, then calls sync. `/sync` calls sync directly (no log). --- ## Phase 1 — Generate the narrative Claude writes all sections directly. Be concise, factual, technical. No filler phrases. Past tense. No emojis. | Author | Sections | |---|---| | Claude | All sections | ### Narrative sections (Claude writes directly) **Session Summary** — 3-5 paragraphs: what was accomplished, in what order, why. **Key Decisions** — bullet list of non-obvious decisions and their rationale. **Problems Encountered** — bullet list of problems hit and how each was resolved. Omit section if none. --- ## Phase 2 — Write to disk ### Location | Work scope | Path | |---|---| | Single project | `projects//session-logs/YYYY-MM-DD-session.md` | | Client | `clients//session-logs/YYYY-MM-DD-session.md` | | Multi-project / general | `session-logs/YYYY-MM-DD-session.md` | ### Filename + append behavior **Per-session-unique filenames are mandatory** — 3–4 Claude sessions can run against this one working tree at once, and a shared `YYYY-MM-DD-session.md` lets them overwrite each other's logs. Never use the bare `YYYY-MM-DD-session.md`. - Default: `YYYY-MM-DD--.md` — `` from the User block (identity.json), `` a short kebab slug of this session's main work (e.g. `2026-06-05-mike-gururmm-platform-day.md`). The topic naturally separates concurrent sessions. - Collision guard: if that exact filename already exists and belongs to a **different** session (different work), append a discriminator — `YYYY-MM-DD---2.md` (increment until free). Never overwrite another session's file. - Same-session continuation (re-saving your own ongoing work): **append** a `## Update: HH:MM PT — ` section to this session's own file. Do not overwrite. ### Required sections (in order) 1. **User block** — generate it deterministically; do NOT hand-write or infer it. Run: ```bash bash .claude/scripts/whoami-block.sh ``` Paste its output verbatim as this section. The script reads `.claude/identity.json` (+ `users.json` for role) — the only authoritative attribution sources. Never derive the user from the hostname, the `# userEmail` context hint, or memory. If the script emits a `[WARNING]` about a stale machine/hostname mismatch, stop and fix `identity.json` before saving. 2. **Session Summary** (Ollama) 3. **Key Decisions** (Ollama) 4. **Problems Encountered** (Ollama) 5. **Configuration Changes** — files modified / created / deleted (with paths) 6. **Credentials & Secrets** — UNREDACTED if newly discovered or created. Vault paths if vaulted. Never half-redact a value future-Claude might need. 7. **Infrastructure & Servers** — IPs, hostnames, ports, tenant IDs, container names, DNS, certs 8. **Commands & Outputs** — important one-liners, key outputs, error messages with resolution 9. **Pending / Incomplete Tasks** — what's left, blockers, next steps 10. **Reference Information** — URLs, endpoints, commit SHAs, ticket IDs, routine IDs, file paths When in doubt, include MORE detail — future sessions search these logs to recover context. --- ## Phase 3 — Wiki: DECOUPLED (do NOT recompile inline) Wiki synthesis is **decoupled from `/save`** (harness v1.2.0+, Task 2). Running a full Sonnet recompile inline on every save, on every machine, caused concurrent-recompile rebase conflicts — and once committed unresolved conflict markers into a wiki article. So **`/save` no longer touches the wiki**: it writes the session log and syncs, nothing more. Do NOT recompile the wiki here, and never block/delay the sync on wiki work. To refresh the wiki for this session's work, run `/wiki-compile` **separately** — it is now **serialized** (per-article coord lock) and **staged** (writes a proposed update to `.claude/wiki_staging/` for review before it touches the live article). After the sync completes, derive the slug from the session-log path (Phase 2) and emit the exact command for the operator to run when ready: - `clients//session-logs/...` → `[INFO] Wiki decoupled — run: /wiki-compile client: --full (serialized + staged)` - `projects//session-logs/...` → `[INFO] Wiki decoupled — run: /wiki-compile project: --full (serialized + staged)` - Root `session-logs/...` → no single article implied; emit nothing. The session log + `sync.sh` are the durable record; the wiki is refreshed deliberately, not on every save. --- ## Phase 4 — Sync ```bash bash .claude/scripts/sync.sh ``` `sync.sh` is **serialized by a per-machine lock** (`.git/claudetools-sync.lock`) so concurrent sessions or the scheduled-task sync cannot interleave commits/rebases; if another sync is mid-flight it waits up to ~120s, then **exits 75 (deferred)** rather than racing — the next sync catches up. On a 75, do NOT print a success summary; report "**sync deferred — another sync is running; your session log is written locally and will sync on the next run**". Otherwise it: reconciles this machine's `git config user.name/email` to `.claude/identity.json` (so commit authorship can't drift), stages all changes with `git add -A` (after purging garbled Windows path-as-filename cruft), auto-commits, fetch + rebase, push, then the same flow for the vault repo, then surfaces cross-user `## Note for ` blocks. > Note: `git add -A` is still the catch-all sweep, so a save run will also pick up any *other* dirty files in the shared tree. The lock prevents two syncs from racing, and per-session-unique log filenames prevent log overwrites — but the bare-`add -A` capture means full per-session commit isolation is a later step (see the isolation plan: drop blind `add -A` in favour of explicit per-session staging). For now, avoid running `/save` from two sessions at the exact same moment. After sync, emit a **Post-commit Summary**: ``` ## Post-commit Summary Commit: Author: <> Push: .. main -> main (origin) File: (+N lines, appended/created) Wiki updates (if any): articles updated (clients/projects/systems/patterns) ``` --- ## Cross-user note handling (CRITICAL) If `sync.sh` surfaces a `## Note for ` or `## Message for ` block from an incoming session log, display it **prominently at the top of the response, before the sync summary**: ``` ============================================================ MESSAGE FROM () ============================================================ ============================================================ ``` Explicitly address each action item or question before moving on.