| name | Qcompact |
| description | Context preservation and session handoff. Use when the user wants to save state, handoff, save context, end session, or continue later. |
| invocation_trigger | When the context window is full or under pressure (Orange/Red zone). |
| recommendedModel | haiku |
Qcompact — Context Preservation & Handoff
Role
A skill that automatically preserves context under context window pressure, and generates detailed handoff documents on user request.
Per-Session Layout (Auto-Named)
Multiple terminals on the same project save into separate sessions/{sid}/ directories so they never clobber each other. The 8-char sid is auto-derived from the Claude session id by the SessionStart hook and surfaced as [Session] sid:XXXXXXXX in additionalContext — there is no manual --name flag. When no sid is available the _unknown bucket is used; pre-partition flat files were one-shot migrated into _legacy.
SessionStart may also surface [Session State] ... with the active plan,
resume source, and Codex background job status. Treat that line as an advisory
shortcut only; the resolver functions below remain the source of truth.
Operating Modes
Automatic Mode (Background Call)
Ecompact-executor detects context pressure and runs automatically in the background.
- Saves quietly without notifying the user
- Triggered when entering the
CONTEXT_BUDGET.md warning zone (70%+ of the active context window by default)
- Saves current state to
.qe/context/sessions/{sid}/snapshot.md
- Accumulates decisions in
.qe/context/sessions/{sid}/decisions.md
Manual Mode (User Invocation)
Calling {adapter.commandPrefix}Qcompact directly generates a detailed handoff document.
- Delegates to Ehandoff-executor sub-agent
- Creates
.qe/handoffs/sessions/{sid}/HANDOFF_{date}_{time}.md
- Displays saved context + handoff summary to the user
Automatic Mode Details
Save Location
.qe/context/sessions/{sid}/ (auto-named per Claude session)
Saved Content
snapshot.md — Context Snapshot
Overwritten on each save (only the latest state is retained):
# Context Snapshot
> Saved at: 2026-03-14 10:30
## Current Task
- In-progress task UUID and title
- Checklist progress (completed/total)
- Checklist item currently being worked on
## Key Decisions
- Major decisions made this session
- Directions explicitly instructed by the user
## Changed Files
- Files created/modified/deleted this session
## Pending Items
- Work not yet finished
- What to do next
## Notes
- Constraints or requirements to remember specifically
decisions.md — Accumulated Decision History
Accumulated per session (reverse order, newest first):
## [2026-03-14] Session
- Decided to separate framework data into .qe/ folder
- Changed agent prefix from A → E
- Branded as QE framework (Query Executor)
Manual Mode Details
CREATE Workflow
Step 1: Delegate to Ehandoff-executor
Call the Ehandoff-executor sub-agent to generate the handoff document.
- Create
.qe/handoffs/ directory (if not present)
- Create
HANDOFF_{date}_{time}.md file
- Auto-collect current task state, git changes, and decisions
Step 2: Write Handoff Document
- Current status summary — what the situation is right now
- Important context — key information the next agent must know
- Immediate next steps — clear, actionable first step
- Decisions — choices that include not just the outcome but the reason
Step 3: Verify
- No
[TODO: ...] placeholders remain
- Required sections exist and are filled in
- No potentially confidential information (API keys, passwords, tokens)
- Referenced files exist
Step 4: Report to User
- Handoff file location
- Summary of captured context
- First action item for the next session
RESUME Workflow
Step 1: Look Up Handoff
Use the shared resolver — resolveResumeContext(projectRoot, overrideSid) in hooks/scripts/lib/session-resolver.mjs — the same function {adapter.commandPrefix}Qresume uses, so handoff lookup here and restore there cannot diverge. It scans the active sid across both .qe/context/ and .qe/handoffs/ first, and when the active sid is empty in both, falls back to the newest other bucket (durable handoffs are unioned in, so a handoff saved under a prior sid is reachable). Read latestHandoff from the returned descriptor; when source: 'fallback', tell the user which bucket was loaded.
On Codex, render the same workflow as $Qresume / $Qresume --from {sid} in
handoffs. Do not emit Claude-only slash commands in Codex-facing text.
Step 2: Check Freshness
| Level | Meaning |
|---|
| FRESH | Safe to resume — minimal changes |
| SLIGHTLY_STALE | Review changes before resuming |
| STALE | Carefully verify context |
| VERY_STALE | Consider creating a new handoff |
Step 3: Load Handoff and Start Work
- Read the handoff document and start from item #1 of "Immediate next steps"
- If there are chained handoffs, also reference previous ones
Handoff Chaining
In long-running projects, link handoffs to each other to maintain context lineage:
HANDOFF_1.md → HANDOFF_2.md → HANDOFF_3.md
Save Location Summary
| Mode | Location | Purpose |
|---|
| Automatic | .qe/context/sessions/{sid}/snapshot.md | Latest context for this terminal (overwrite) |
| Automatic | .qe/context/sessions/{sid}/decisions.md | Accumulated decisions for this terminal |
| Manual | .qe/handoffs/sessions/{sid}/HANDOFF_*.md | Detailed handoff document for this terminal |
Will
- Automatic: save context snapshot, accumulate decisions
- Manual: generate detailed handoff document, verify, chain
- Delegate to Ecompact-executor (automatic)
- Delegate to Ehandoff-executor (manual)
Will Not
- Save entire conversation (extract key points only)
- Copy entire code (record file paths only)
- Notify user (during automatic execution)
- Include confidential information
