session-summary

# session-summary ## When this skill is the preferred path Context fill is high (90%+ of the window) and `/compact` is failing or about to fail. The agent needs to clear and resume without losing the work it has done so far. `gc_session_summary` produces a portable summary the agent can re-inject after `/clear`. This skill is the natural pair to `gc_pre_flight`. When pre_flight returns the `clear_first` verdict, the workflow is: 1. Call `gc_session_summary` with the conversation history. 2. Use `/clear` (Claude Code's built-in). 3. Send the returned `restoration_instructions` as your first user message in the cleared session. 4. Call `gc_pre_flight` again with the next prompt — context fill is now low, you'll get `send_compressed` or `send_as_is`. ## How to use it Call `gc_session_summary` with one of: - `messages` — structured conversation history as a list of `{role, content}` dicts. Roles: `user`, `assistant`, `system`, `tool`. Preferred when available. - `text` — concatenated conversation as a plain string. Use when structured messages aren't available. If both are passed, `messages` wins. Optional: - `keep_facts` — facts the summary MUST preserve verbatim (file paths, decisions, blockers, identifiers). Each item is prepended to the summary as a bullet point and not compressed. - `target_tokens` — max size for the summary. Default 4000. ## What you get back ```json { "summary": "<compressed-summary-string>", "key_facts": ["...", "..."], "tokens_in_original": 184000, "tokens_in_summary": 4200, "compression_ratio": 0.023, "restoration_instructions": "After /clear, send this as your first user message...", "recommendation": "Summary 97.7% smaller than original. Run /clear, then send..." } ``` The `restoration_instructions` field is canonical — copy it into your next user message verbatim and the agent resumes with the compressed context attached. ## Why this skill exists - Auto-compaction can be token-expensive: it tends to resubmit a large bloated context for summarization once the window is nearly full, so a single compaction event can cost tens to hundreds of thousands of tokens. Our summarization runs OUTSIDE the exhausted Claude context — it works when Claude Code's own auto-compact would fail. - A well-known limitation: when nearly all of the 200k-token context window is used, there isn't enough headroom left to compact. This skill runs summarization on separate infra, so it's the recovery path for exactly that situation. - LocalLLaMA pattern: "Treat the context window like RAM and the scratchpad like disk." This skill IS the scratchpad. ## Failure-mode contract Never raises to the agent. If the compression service is degraded, the response returns the truncated head of the conversation as a fallback summary plus a `recommendation` field flagging the degradation. The agent always gets a structured response it can re-inject. ## Plan availability Available on every plan including Free. Volume is governed by your existing per-month compression quota — same posture as `gc_pre_flight`.