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

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

Filename + append behavior

• Filename: YYYY-MM-DD-session.md (today's local date)
• If file exists, append a ## Update: HH:MM PT — <topic> section. Do not overwrite.
• If two users worked on the same date, namespace: YYYY-MM-DD-<user>-<topic>.md (e.g. 2026-05-01-howard-syncro-billing-batch.md)

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 Refresh (before sync)

Keep the worked-on wiki article current so it ships in the same commit as the session log. This runs before sync. Refresh only — it never re-synthesizes narrative (that is /wiki-compile --full, run on demand).

1. Derive the slug from the session-log path written in Phase 2:

   • clients/<slug>/session-logs/... → client <slug>
   • projects/<project>/session-logs/... → project article slug (e.g. guru-rmm, guru-connect)
   • Root session-logs/... → skip this phase entirely (no single article is implied)

2. Article exists (wiki/clients/<slug>.md or wiki/projects/<slug>.md) → apply the surgical refresh from /wiki-compile Phase 4 "Refresh Mode":

   • Frontmatter: set last_compiled (today) and compiled_by (<MACHINE>/claude-main); append the new session-log path to sources: (dedupe).
   • Clients only: refresh "Hours remaining" and the "Active Work" ticket list from live Syncro (read-only GET; customer id from the article frontmatter). Softfail if Syncro is unreachable — still bump last_compiled + sources.
   • Never touch Patterns, History, or Summary — those require --full or human review.

3. No article yet → do not auto-seed here (seeding is a full Ollama synthesis, too heavy for every save). Emit:

   [INFO] No wiki article for '<slug>' yet. Run /wiki-compile client:<slug> to seed it.
   

Softfail: a wiki-refresh failure must NEVER block the save. Log it and continue to sync. The refreshed article + wiki/index.md are picked up by sync.sh's git add -A and committed alongside the session log.

---

Phase 4 — Sync

bash .claude/scripts/sync.sh

sync.sh handles: reconcile this machine's git config user.name/email to .claude/identity.json (so commit authorship can't drift), stage all changes with git add -A (after purging garbled Windows path-as-filename cruft), auto-commit, fetch + rebase, push, then the same flow for the vault repo, then surface cross-user ## Note for <user> blocks.

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.