claudetools/.claude/commands/save.md

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

New logs go in a YYYY-MM/ month folder under the relevant session-logs/ dir (keeps the flat dir from growing unbounded; recall is scoped grep over the month folders — no monolithic index). mkdir -p the month folder before writing.

Work scope	Path
Single project	projects/<project>/session-logs/YYYY-MM/YYYY-MM-DD-<user>-<topic>.md
Client	clients/<slug>/session-logs/YYYY-MM/YYYY-MM-DD-<user>-<topic>.md
Multi-project / general	session-logs/YYYY-MM/YYYY-MM-DD-<user>-<topic>.md

Existing flat logs (session-logs/*.md) stay where they are — recall grep covers both */*.md (month folders) and *.md (legacy flat), so no mass migration. The month folder is added after session-logs/, so wiki slug derivation (<project>/<slug> captured before session-logs/) is unaffected. Use bash .claude/scripts/now-phoenix.sh --date for the date.

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-<user>-<topic>.md — <user> from the User block (identity.json), <topic> 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-<user>-<topic>-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 — <topic> 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 .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/<slug>/session-logs/... → [INFO] Wiki decoupled — run: /wiki-compile client:<slug> --full (serialized + staged)
• projects/<project>/session-logs/... → [INFO] Wiki decoupled — run: /wiki-compile project:<slug> --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 .claude/scripts/sync.sh

Same driver as /sync — see that command for the full semantics. The two load-bearing points for reporting: exit 75 = deferred (another sync is running; report "sync deferred — your session log is written locally and will sync on the next run", NOT a success summary); and git add -A is a catch-all sweep, so avoid running /save from two sessions at the exact same moment (per-session-unique log filenames prevent log overwrites, the lock prevents racing).

After sync, emit a Post-commit Summary:

## Post-commit Summary
Commit:  <sha>  <subject>
Author:  <name> <<email>>
Push:    <old>..<new>  main -> main  (origin)
File:    <session log path>  (+N lines, appended/created)

Wiki updates (if any): <count> articles updated (clients/projects/systems/patterns)

---

Cross-user note handling (CRITICAL)

If sync.sh surfaces a ## Note for <user> or ## Message for <user> block from an incoming session log, display it prominently at the top of the response, before the sync summary:

============================================================
MESSAGE FROM <author> (<date>)
============================================================
<full note content>
============================================================

Explicitly address each action item or question before moving on.