Incremental Summarization

This skill manages a structured session state file (.claude/session-state.md) that preserves critical context across context compression events. It prevents "context amnesia" — the loss of decisions, rationale, and non-obvious context when long sessions are compacted.

Schema Reference

The session state file follows the schema defined in references/state_schema.md. Always read this schema before creating or updating a state file.

Load the schema from: ${CLAUDE_PLUGIN_ROOT}/skills/incremental-summarization/references/state_schema.md

When to Summarize

Trigger a state file update in these situations:

1. PreCompact (automatic): The PreCompact hook fires before context compression. This is the most critical trigger — it is the last chance to capture state before information is lost.

2. Manual checkpoint (/checkpoint): The user explicitly requests a snapshot. May include a free-text note that should be appended to the User Notes section.

3. Milestone completion: After completing a significant unit of work (e.g., finishing a feature, fixing a complex bug, completing a refactor), proactively suggest a checkpoint.

What to Capture

Each section of the state file serves a specific purpose:

Section	Purpose	Update Rule
Session Goal	High-level objective for the session	Set once, update only if the user changes direction
Decisions Made	Every decision with rationale and alternatives	Append only — never remove past decisions
Issues Found	Bugs, blockers, and observations with severity	Append new; check off resolved; never remove
Work Completed	Finished tasks with files touched	Append only — never remove completed work
Current Task	What is in progress right now	Replace entirely on each update
Next Steps	Priority-ordered upcoming work	Replace entirely on each update
Key Context	Non-obvious info that cannot be derived from code	Accumulate; remove only if explicitly invalidated
User Notes	Free-text notes from /checkpoint invocations	Append only

How to Structure Updates

First Checkpoint (no existing state file)

1. Create .claude/ directory if it does not exist
2. Read the schema from references/state_schema.md
3. Populate all sections based on the current session state
4. Use "None yet" for empty sections — never omit section headers
5. Set the Session Goal based on the user's initial request or conversation context
6. Write to .claude/session-state.md

Subsequent Checkpoints (state file exists)

1. Read the existing .claude/session-state.md
2. Read the schema from references/state_schema.md for format reference
3. Append new entries to: Decisions Made, Issues Found, Work Completed, User Notes
4. Replace entirely: Current Task, Next Steps
5. Accumulate Key Context: add new items, remove only items the user explicitly invalidated
6. Update the Last Updated timestamp
7. Write the updated file back to .claude/session-state.md

After Context Compression (resuming with state file)

1. Read .claude/session-state.md in full — this is now the single source of truth
2. Trust its contents completely; do not second-guess recorded decisions
3. Resume from the Current Task section
4. Follow the Next Steps priority order
5. Continue appending to append-only sections as work progresses

File Location

The state file is always at: .claude/session-state.md (relative to project root)

Create the .claude/ directory if it does not exist. Do not use any other location.

Important Rules

1. Never lose information. Append-only sections must never have entries removed. If a decision was reversed, add a new decision entry explaining the reversal — do not delete the original.

2. Be thorough before compression. When the PreCompact hook fires, capture everything that would be lost. Err on the side of including too much rather than too little.

3. Be concise during manual checkpoints. Users invoke /checkpoint for quick saves. Capture the delta since the last checkpoint, not a full rewrite.

4. Timestamps are mandatory. Every entry that has a timestamp field must include one. Use YYYY-MM-DD HH:MM format (24-hour clock).

5. Severity must be exact. Issues use exactly one of: critical, warning, info (lowercase).

6. Respect the schema. The section headers in state_schema.md are the canonical format. Do not rename, reorder, or add new top-level sections.

7. Key Context is for the non-obvious. Do not record things that can be easily determined by reading the code or git log. Focus on implicit knowledge, environment quirks, user preferences, and undocumented behaviors.