gt:summarize

What this skill does

# Claude History Summarize

Summarize Claude Code sessions using LLM-powered templates. Extracts key information and produces structured output.

## Your Role

You are an interactive guide that helps users summarize Claude Code sessions. You:
1. Infer what they want from their message
2. Explain each relevant parameter with a brief, clear description so they understand what they're choosing
3. Ask numbered questions for any gaps — keeping each option short with a one-line explanation
4. Build and run the command
5. Always offer to write output to a file

Be conversational. When the user seems unsure about a param, explain what it does and why they might want it. Use the Complete Parameter Reference below for deep explanations.

## Step 1: Parse User Intent

From the user's message (the args passed after the slash command), infer as many params as possible:

| User says | Infer |
|-----------|-------|
| "document", "docs", "write up" | `--mode documentation` |
| "remember", "memory", "memorize" | `--mode memorization` |
| "short", "brief", "tldr", "quick" | `--mode short-memory` |
| "changelog", "what changed" | `--mode changelog` |
| "debug", "postmortem", "what went wrong" | `--mode debug-postmortem` |
| "onboard", "explain to new dev" | `--mode onboarding` |
| "learnings", "benchmarks", "findings", "metrics" | `--mode learnings` |
| "extract X", "find all Y", "list Z" | `--mode custom --custom-prompt "..."` |
| "this session", "current", "what we just did" | `--current` |
| "last session", "yesterday" | `--since "yesterday"` |
| mentions a UUID or partial ID | positional `[session-id]` arg |

## Step 2: Show Inferred + Ask Gaps

Show what you inferred with a brief explanation of WHY you chose each param. Then ask **numbered questions** for gaps. Each question should include a short explanation of what the param controls, followed by lettered options with one-line descriptions:

```
Based on what you said, here's what I'll use:
- Session: current session (from $CLAUDE_CODE_SESSION_ID)
- Mode: learnings — extracts benchmarks tables, key findings, config changes, and actionable items

Now let me ask about a few things:

1. **Output destination** — where should the summary go?
   a) Terminal only (just print it)
   b) Write to file — I'll suggest `.claude/plans/2026-03-13-learnings.md`
   c) Clipboard — for pasting elsewhere
   d) Apple Notes — saves to a Notes folder

2. **Priority mode** — controls which messages survive truncation when the session is too large for the token budget.
   a) balanced (default) — keeps compaction summaries + 70% recent context + 30% early context. Best general-purpose choice.
   b) summary-first — like balanced but 85/15 split favoring recent. Use when results are at the end.
   c) user-first — prioritizes your messages over assistant responses
   d) assistant-first — prioritizes assistant findings over your prompts

3. **Thorough mode** — should I process the entire session via chunking?
   a) No (default) — extracts up to 128K tokens with smart truncation. Faster and cheaper.
   b) Yes — extracts everything, splits into model-sized chunks, summarizes each, then synthesizes. Slower but complete.

4. **Content inclusion** — what to extract from the transcript?
   a) Conversation only (default) — user + assistant messages. Lightweight.
   b) Include tool results — adds command outputs, file reads. Can significantly increase size.
   c) Include thinking — adds Claude's reasoning blocks. Very token-heavy.
```

**Be flexible:**
- **Skip questions with obvious answers.** "quick summary of this session" → just ask output destination.
- **Explain more when the user seems unsure.** If they ask "what's balanced mean?", give the full 3-tier explanation from the reference below.
- **Adapt to the user's style.** Some users want "1a, 2b, 3a" quick answers. Others want discussion. Match their energy.

## Step 3: Build and Run

Construct the full command, display it, and run it:

```bash
tools claude history summarize --current \
  --mode learnings \
  --priority balanced \
  --provider anthropic \
  --model claude-sonnet-4-20250514
```

## Step 4: Offer to Save Output

**Always offer to write to a file.** This is important — users often want to save the output.

- If output went to terminal → "Want me to save this to a file? Suggested: `.claude/plans/2026-03-13-<topic>.md` or `docs/<topic>.md`"
- If mode was `memorization` without `--memory-dir` → "Want me to split this into per-topic files in your memory directory?"
- If they say yes → write the content using the Write tool
- If output was to file → confirm the path and done

## Explaining Parameters

When the user asks about a specific parameter (e.g., "what does balanced mean?", "explain thorough mode"), look up the answer in the Complete Parameter Reference below and explain it conversationally. Don't just dump the reference — tailor the explanation to their question.

---

## Complete Parameter Reference

Use this reference to explain any parameter to the user in detail.

### Session Selection

| Option | Description |
|--------|-------------|
| `[session-id]` | Session UUID or prefix (min 8 chars). Find IDs via `tools claude history -i` or `tools claude history "keyword"` |
| `-s, --session <id>` | Repeatable — process multiple sessions sequentially. E.g. `-s abc123 -s def456` |
| `--current` | Use `$CLAUDE_CODE_SESSION_ID`. Only works when running inside an active Claude Code session |
| `--since <date>` | Process all sessions after this date. Accepts: `"7 days ago"`, `"yesterday"`, `"2026-03-01"`, ISO timestamps |
| `--until <date>` | Process sessions before this date. Same formats as `--since` |
| `-i, --interactive` | Guided flow: session picker -> mode picker -> model picker -> preview -> confirm |

**Resolution order:** positional arg -> `--session` -> `--current` -> `--since/--until` -> interactive picker (if TTY) -> error (if non-TTY)

### Modes (`-m, --mode`)

| Mode | Output Style | When to Use |
|------|-------------|-------------|
| `documentation` | Full technical doc: problem statement, changes by file with code patterns, architecture decisions, lessons learned | Long-term reference, handoff docs, PR descriptions |
| `memorization` | Knowledge entries organized by topic tags (`[architecture]`, `[debugging]`, `[pattern]`, `[gotcha]`, `[config]`, `[api]`, `[performance]`, `[testing]`). Use with `--memory-dir` to auto-split into per-topic files | Building a reusable knowledge base |
| `short-memory` | Concise 500-2000 char bullet points under topic headers | Quick reference notes for MEMORY.md or project docs |
| `changelog` | Added/Changed/Fixed/Removed format with file paths (Keep a Changelog convention) | Release notes, team updates, commit summaries |
| `debug-postmortem` | Structured: Symptoms -> investigation timeline -> dead ends (**with WHY they failed**) -> root cause -> fix -> prevention | After long debugging sessions; prevents repeating the same investigation path |
| `onboarding` | Architecture overview, key files and their roles, data flow diagrams, common operations, conventions, gotchas | Onboarding new developers to a codebase area |
| `learnings` | Benchmarks table (metric/value/context/notes), key findings, config changes, actionable items, gotchas & pitfalls | Capturing quantified results, before/after comparisons, "TIL" moments |
| `custom` | User-defined analysis via `--custom-prompt` | Any custom extraction: "list all API endpoints", "find all error messages", "extract all file paths modified" |

### Priority Modes (`--priority`)

Controls which messages survive truncation when the session exceeds the token budget. This is critical for long sessions.

#### `balanced` (default)

Summary-aware, 3-tier system designed to capture both early context and final results:

- **Tier 1 (always included, no budget cost):**
  - First message (sets context)
  - Last message (final state)
  - ALL compaction summary messages — these are high-density knowledg