Mike Swanson
68ad1dbd40
Task 5 one-line registry descriptions on the 8 biggest skills (remediation-tool,
gc-audit, packetdial, memory-dream, human-flow, self-check, impeccable,
mailprotector); skill-description injection ~3320 -> ~2123 tokens (~36%),
keyword triggers preserved, frontmatter valid.
Task 7 thinned /save + /sync bodies to point at sync.sh (single source) instead of
re-documenting internals; Phase 0 save-vs-sync, cross-user notes, exit-75
reporting kept verbatim; mechanical sync never depends on an LLM step.
Task 10 session-logs/YYYY-MM/ forward convention for new logs (scoped-grep recall,
no monolithic index); existing flat logs untouched (grep covers both).
Bash now-phoenix.sh helper (fixed UTC-7 epoch math; replaces unreliable
TZ=America/Phoenix date that silently returns UTC on Git-Bash).
P0 (1.2.0) + Task 6 CLAUDE split + Task 9 delegation (1.3.0) already shipped.
Spec: specs/claudetools-harness-optimization/plan.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
143 lines
6.7 KiB
Markdown
143 lines
6.7 KiB
Markdown
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
|
||
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
|
||
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.
|