Compact Instructions

Compact Instructions: Context Preservation Strategy

When a Claude Code session approaches context-window limits and performs context compaction (manual /compact or automatic), the agent must balance information density with continuity. This skill defines what to preserve and what to discard.

What to Preserve

• Current objective / phase — one-line statement of what the session is actively working on
• Blockers and open blockers — issues preventing forward progress, with minimal context
• Decisions that remain valid — architectural or planning decisions made in earlier sessions that still apply
• Validation state — which tests are passing, which requirements are met, which gates are open/blocked
• Worktree / branch state — when relevant to resuming work (branch name, uncommitted changes, PR status)
• Next concrete step — what the next AI session should do immediately after loading context

What to Discard

• Resolved conversations — back-and-forth debugging or decision-making that concluded
• Repeated reasoning — the same analysis or explanation presented multiple times across the session
• Discarded attempts — approaches tried and rejected, unless the rejection reason remains strategically important
• Large tool outputs — full log dumps, verbose grep results, API responses in their entirety (keep only the relevant extracted data)
• Intermediate mental models — exploratory reasoning or "let me think through this" passages that didn't lead to decision

Critical Principle

The compact summary is a sketch, not a replacement for durable state. If the project has a session-handoff.md, PROGRESS.md, CHANGELOG.md, or equivalent living documentation, those files remain the source of truth. The compacted context is temporary and lossy — it buys context space in the current session, but it does not eliminate the need to maintain formal handoff documents for the next session.

If compaction is being used to work around missing handoff documentation, that is a symptom — fix the root cause (write the missing session-handoff.md or PROGRESS.md) rather than relying on compaction to carry state.

Trigger Conditions

• Manual invocation: /compact command during an active session
• Automatic invocation: Claude Code's built-in auto-compact mechanism when token usage exceeds threshold
• Proactive: when working on multi-phase projects and ending a phase, consider manual compact + handoff update in parallel

Output Quality Check

Before finalizing a compact summary, ask:

1. Can a blind AI read the preserved state and continue without asking? If the next session would need to ask "what phase are we in?" or "which branch?", add more specificity.
2. Is decision context preserved? If a decision matters for the next steps, include the reasoning in one sentence.
3. Are blockers actionable? "Blocked on X" is better than "something wrong" — the next session should know what to check first.
4. Does it reference durable docs? If PROGRESS.md or session-handoff.md exists, point to it: "see PROGRESS.md for detailed timeline."

See Also

• session-handoff.md pattern — permanent cross-session state
• PROGRESS.md — executive/phase-level tracking
• /compact command documentation — Claude Code reference