session-checkpoint

What this skill does

# Session Checkpoint

## Problem

Context compaction and session boundaries destroy working memory. Agents spend 10-15 minutes per session re-reading files and re-discovering state. Across a project, this compounds into hours of wasted effort.

## When to Write a Checkpoint

- **End of session**: Before the user ends a conversation
- **Before context gets long**: If you've been working for a while and the conversation is deep, proactively write a checkpoint
- **Before switching tasks**: Capture current state before moving to a different area
- **When asked**: User says "save checkpoint", "capture state", "I'm done for now"

## When to Read a Checkpoint

- **Start of every session**: Read `docs/checkpoints/latest.md` before reading tasks.md or other project docs
- **After context compaction**: If you notice you've lost context, check for a checkpoint
- **When resuming work**: User says "where were we?", "continue", "pick up where we left off"

## Checkpoint Format

Write to `docs/checkpoints/latest.md` (always overwritten) and optionally archive to `docs/checkpoints/YYYY-MM-DD-HHMM.md`:

```markdown
# Session Checkpoint
**Date**: YYYY-MM-DD HH:MM
**Branch**: <current git branch>
**PR**: <PR number if applicable>

## Current Task
<Task ID and description from tasks.md, or freeform description>

## Status
- **Done this session**: <bullet list of what was accomplished>
- **In progress**: <what's partially complete>
- **Blocked on**: <any blockers>

## Key Decisions
- <Decision>: <rationale> (important — these are lost in compaction)

## Open Questions
- <Question that needs user input or research>

## Next Steps
1. <Most important next action>
2. <Second priority>
3. <Third priority>

## Hot Files (modified this session)
- `path/to/file.ts`: <what changed and why>

## Context the Next Session Needs
<Anything non-obvious that would take time to re-discover. E.g., "The streaming endpoint returns correlation_id in the last SSE event, not as a header" or "Integration tests need AGENT_PORT=3031 to avoid conflicts">
```

## How to Use

### Writing (proactive)
When the session is wrapping up or getting long:
1. Create `docs/checkpoints/` directory if it doesn't exist
2. Write `docs/checkpoints/latest.md` with the format above
3. Optionally archive: copy to `docs/checkpoints/YYYY-MM-DD-HHMM.md`
4. Commit the checkpoint: `git add docs/checkpoints/ && git commit -m "chore: session checkpoint"`

### Reading (at session start)
1. Check if `docs/checkpoints/latest.md` exists
2. If yes, read it FIRST — before tasks.md, before exploring the codebase
3. Use it to orient: pick up the current task, understand decisions made, avoid re-reading hot files
4. If the checkpoint is stale (>3 days old or branch has changed significantly), note this and do fresh orientation instead

### Lead with state — don't make the user ask "where are we?"

When resuming a multi-session project, **open the session by stating the current state** (from the checkpoint) before the user has to ask. A recurring tax signal is the user opening 5+ consecutive sessions with *"remind me where we're at?"* — that means the agent was waiting to be asked instead of leading. Begin with a 3-line orientation: *current task · what's done/verified · the single next action.*

**Status must reflect verified reality, not what `tasks.md` claims.** If tasks.md says a task is ✅ but its instrumentation/runtime behavior was never verified (see the autonomous-execution "Instrumented-Task Verification Gate"), the checkpoint should say so — e.g., *"T11 marked done in tasks.md but event-firing unverified."* A status surface that launders unverified claims into "done" is worse than none.

## Proactive Invocation

This skill should be suggested (not auto-invoked) when:
- The session has been active for ~1 hour or more
- 5+ tasks have been completed without a checkpoint
- The conversation is getting deep and context compaction may be approaching

Suggested format:
> "Want me to write a checkpoint before we continue? It'll help if we need to resume later."

## Key Principles

- **Brevity over completeness**: A 20-line checkpoint that captures the right things is better than a 100-line dump
- **Decisions are the highest-value content**: Code changes are in git. Decisions and rationale are lost in context compaction.
- **Next steps should be actionable**: "Continue with Task 5.3" is better than "Keep working on the feature"
- **Don't duplicate git**: The checkpoint captures context that git diff/log doesn't — decisions, blockers, non-obvious knowledge