custom-claude-skills/skills/log/SKILL.md

---
name: log
description: >
  End-of-session logging. Captures key decisions, gotchas, open questions, and discussion
  points into memory/log/ for later reflection. Run before ending a session to preserve
  context. Fast and low-friction -- just run /log.
allowed-tools: Read, Write, Glob, Agent, Bash(date *), Bash(pwd), Bash(ls *), Bash(cat *), Bash(find *), Bash(rm *), Bash(mkdir *), Bash(python3 *), Bash(bash *)
---

# Session Log Skill

You are capturing key points from the current session into a structured log file.

## Pre-gathered context

### Current date and session timestamp
!`date +%Y-%m-%d`
!`date +%Y%m%d-%H%M%S`

### Current project directory
!`pwd`

### Existing log files
!`ls -1 memory/log/ 2>/dev/null || echo "No log directory yet"`

### Settings
(Read `~/dev/claude/projects/claude-foundations/settings.yaml` using the Read tool. If not found, use defaults: retention_days=7, warn_unreflected_days=14)

### Reflection state (to check what has been reflected)
!`cat .reflection-state.json 2>/dev/null || echo "No reflection state yet"`

### Current MEMORY.md index
!`cat MEMORY.md 2>/dev/null || echo "No MEMORY.md found"`

### Unprocessed transcript backups for this project (metadata only)
!`bash ~/.claude/scripts/list-transcripts-here.sh 2>/dev/null || echo "[]"`

## Instructions

Review the **full conversation history** in your context window and extract key points worth preserving. Not every session needs a log — if the session was trivial (a typo fix, a quick question), say so and skip.

The "Unprocessed transcript backups" above shows metadata (filenames, timestamps) for any pre-compaction snapshots not yet captured in a log. **Do NOT read the transcript content yourself** — that is handled by a subagent in Step 2 to avoid context overflow.

### Step 1: Create the log directory and write the in-context log

If `memory/log/` does not exist, create it with `mkdir -p memory/log/`.

Generate the filename as `memory/log/YYYY-MM-DD.<HHMMSS>.md` using the pre-gathered date and timestamp values.

Write the file using this format:

```markdown
# Session Log — YYYY-MM-DD

## Summary
<!-- 1-2 sentence overview of what was accomplished or discussed -->

## Decisions
<!-- Bulleted list of decisions made and brief rationale. Omit section if none. -->
- Decision: <what> — Rationale: <why>

## Gotchas Discovered
<!-- Symptom + fix format, tagged by topic area. Omit section if none. -->
- **[topic]** Symptom: <what happened> — Fix: <what resolved it>

## Open Questions
<!-- Things unresolved that need follow-up. Omit section if none. -->
- <question>

## Key Context
<!-- Important facts, configurations, or patterns worth remembering. Omit section if none. -->
- <fact>

## Process Notes
<!-- What went well, what was slow, what to do differently. Omit section if none. -->
- <note>
```

**Guidelines:**
- Omit empty sections entirely rather than leaving them blank
- The `[topic]` tag on gotchas should match existing memory topic names where possible (e.g., `[k8s]`, `[cilium]`, `[ansible]`, `[sops]`, `[helm]`)
- Keep entries concise — this is raw material for `/reflect-logs`, not a polished document
- Include enough context that each entry makes sense without the full conversation

### Step 2: Dispatch transcript analysis subagent (if unprocessed transcripts exist)

If the pre-gathered transcript list is non-empty and contains backup files that `exists: true`:

Spawn a **Sonnet** subagent (model: sonnet) with the following prompt. Sonnet is used (not Haiku) because gotcha detection requires judgment about backtracking, failed attempts, and domain-specific failure modes — Haiku tends to miss these. Fill in the bracketed values from the pre-gathered data:

---
**Subagent prompt template:**

You are processing pre-compaction transcript backups into a structured session log.

**Project directory:** [CWD from pre-gathered context]
**Log directory:** memory/log/ (relative to project dir — write files there using absolute path)
**Log filename:** [SAME HHMMSS timestamp as Step 1, but with suffix -transcripts, e.g. memory/log/YYYY-MM-DD.HHMMSS-transcripts.md]
**Transcripts to process:** [paste the JSON array from the pre-gathered list]

## Your task

For each backup file listed above (where `exists: true`):

1. Extract the conversation using:
   ```
   python3 ~/.claude/scripts/extract-transcripts.py --extract <backup_name>
   ```
   Run this as a Bash command and read the output.

2. If the transcript has >40 turns, process it in two passes:
   - First half of turns in one read
   - Second half in a second run (re-run --extract and skip to turn N)
   Note: the --extract command outputs all turns; read the full output but focus analysis on substance.

3. After reading all transcripts, write a single log file at the absolute path:
   `[PROJECT_ABS_PATH]/memory/log/YYYY-MM-DD.HHMMSS-transcripts.md`

   Use this format:
   ```markdown
   # Transcript Log — YYYY-MM-DD (pre-compaction backups)

   ## Sources
   - <backup_name> (session <session_id>, saved <saved_at>)

   ## Summary
   <!-- What was worked on across the captured sessions -->

   ## Decisions
   - Decision: <what> — Rationale: <why>

   ## Gotchas Discovered
   - **[topic]** Symptom: <what happened> — Fix: <what resolved it>

   ## Open Questions
   - <question>

   ## Key Context
   - <fact>

   ## Process Notes
   - <note>
   ```

4. After writing the log, mark all processed transcripts:
   ```
   python3 ~/.claude/scripts/extract-transcripts.py --mark-all-processed "[CWD]" --log-file "memory/log/YYYY-MM-DD.HHMMSS-transcripts.md"
   ```

5. Report: transcript(s) processed, log file written, any issues encountered.

**Allowed tools for the subagent:** Read, Write, Bash(python3 *), Bash(mkdir *)

---

Spawn this subagent with `model: sonnet` and wait for it to complete before continuing.

### Step 3: Prune old logs

After writing the log file, check for old logs that should be pruned:

1. Read `retention_days` and `warn_unreflected_days` from the settings (defaults: 7 and 14)
2. Read `.reflection-state.json` to know which logs have been reflected on
3. For each file in `memory/log/`:
   - Parse the date from the filename (first 10 characters: `YYYY-MM-DD`)
   - If **older than `retention_days`** AND **present in `.reflection-state.json`** → delete it and note the deletion
   - If **older than `warn_unreflected_days`** AND **NOT in `.reflection-state.json`** → print a warning: `WARNING: <filename> is N days old and has NOT been reflected on. Run /reflect-logs.`
   - Otherwise → leave it alone

### Step 4: Summary

Print a brief summary:
- In-context log file created (with path)
- Whether a transcript analysis subagent was dispatched (and which backups it processed)
- Any files pruned or warnings issued