Save Context

Save current session state to CONTEXT-{stream}-llm.md in the session directory with LLM-optimized format.

.context/session/
  INDEX.md                        index of streams
  CONTEXT-llm.md                  default stream
  CONTEXT-{name}-llm.md           named stream
  done/CONTEXT-{name}-llm.md      archived stream (status done or parked)

Target: 1200-1500 tokens MAX | Speed: 3-5 seconds

AskUserQuestion Guard

CRITICAL: After EVERY AskUserQuestion call, check if answers are empty/blank. Known harness bug affecting several agentic CLIs: outside Plan Mode, the AskUserQuestion tool can silently return empty answers without showing UI.

If answers are empty: DO NOT proceed with assumptions. Instead:

1. Output: "Questions didn't display (known AskUserQuestion bug outside Plan Mode)."
2. Present the options as a numbered text list and ask user to reply with their choice number.
3. WAIT for user reply before continuing.

Performance Rules

1. Use rtk for shell commands when it is installed (a harness hook may already rewrite them; bare commands are also fine)
2. Parallel tool calls — ALL independent calls in one message
3. Minimize round-trips — gather all data phase 1, reason phase 2, write phase 3

Workflow

Phase 1: Gather Data (parallel)

Bash: ls .context/session/ + ls -t .context/session/CONTEXT-*llm.md

Stream resolution: First word of $ARGUMENTS = stream name (^[a-zA-Z0-9_-]{1,50}$), rest = description. Empty → reuse prior /load-context stream or AskUserQuestion.

Phase 2: Analyze & Synthesize (single pass)

From conversation (last 15-20 messages):

1. Next — infer 3 tasks from conversation (IMPORTANT: use heading "Next" — several agentic CLIs' compaction routines grep-match next/todo/pending/remaining keywords for survival priority)
2. Session — progression, decisions, thinking, unexpected (780 tokens max)
3. Hot Files — max 10 discussed/edited
4. Focus & Goal — 1-2 sentence focus + goal

Phase 3: Write & Report

Write CONTEXT file using template, then upsert INDEX.md in the session directory:

./scripts/upsert-index.sh repos my-project auth-refactor "building" "JWT middleware extracted" 2026-09-30

Stream naming: default → CONTEXT-llm.md, {name} → CONTEXT-{name}-llm.md

Phase 3b: Auto-archive to done/

If status is done or parked → move the file to the done/ subfolder of the session directory:

Bash: mkdir -p .context/session/done && mv .context/session/CONTEXT-{stream}-llm.md .context/session/done/

Report:

Archived to .context/session/done/ (status: {status})

See references/reference.md for CONTEXT file template, quality self-check, status mapping, done/ archival rules, and INDEX.md upsert logic.

Philosophy

• Context saves are checkpoints, not archives — they capture the current state of intent and decisions, not a full transcript.
• Meaningful milestones over time intervals — save when something worth remembering happens, not on a schedule.
• Traceability over brevity — a save that omits the "why" behind a decision is incomplete.
• Reversible by design — saves accumulate; nothing is overwritten without explicit archival.

When to Use

• Before ending a multi-hour session — preserve decisions and next steps before the conversation closes.
• Before a context window reset or compaction — most agentic CLIs compact long conversations; save first to survive the reset.
• After completing a discrete milestone — a working feature, a passing test suite, a completed PR review.
• When switching streams or workspaces — checkpoint the current stream before pivoting to a different task.
• When you've made non-obvious architectural decisions — lock in the reasoning so future sessions don't relitigate it.

When Not to Use

• For trivial changes with obvious git history — a single-line fix with a clear commit message needs no context file.
• At the very start of a session — there is nothing meaningful to summarise yet; save at checkpoints, not at startup.
• As a substitute for proper documentation — context files are ephemeral session aids, not design docs or ADRs.
• When no meaningful work has occurred — an empty or near-empty context file creates noise and misleads future sessions.
• More than once per hour on short tasks — over-saving dilutes the signal; one file per meaningful checkpoint is enough.
• When another session or person will pick the work up: a quick checkpoint is not a handover. Use the handover-document-creator skill, which writes a structured, validated handover with evidence for what landed and links for what is outstanding.

Anti-Patterns

• NEVER overwrite an existing context file without reading it first — Silent overwrites lose prior session decisions. WHY: The INDEX.md may reference decisions that inform current architecture; discarding them breaks traceability.

  # BAD - blind overwrite, prior decisions gone with no diff
  echo "$new_summary" > .context/session/CONTEXT-llm.md
  
  # GOOD - read first, merge forward, then write
  old=$(cat .context/session/CONTEXT-llm.md 2>/dev/null || echo "")
  # ...fold decisions still relevant from $old into the new summary...
  echo "$merged_summary" > .context/session/CONTEXT-llm.md

• NEVER save with a generic or missing stream name when multiple streams are active — Ambiguous names cause the wrong file to be loaded next session. WHY: CONTEXT-llm.md collides across unrelated workstreams and forces manual disambiguation.

  # BAD - two unrelated workstreams both save to the default stream
  /save-context                 # auth-refactor work lands in CONTEXT-llm.md
  /save-context                 # billing-migration work overwrites it minutes later
  
  # GOOD - each workstream gets its own named stream
  /save-context auth-refactor "JWT middleware extraction done"
  /save-context billing-migration "Stripe webhook handler drafted"

• NEVER skip the INDEX.md upsert step — Omitting it leaves the index out of sync. WHY: load-context relies on INDEX.md to discover the latest file; a stale index means the wrong snapshot is loaded.
• NEVER archive to done/ prematurely — Moving an active context to done/ hides it from future loads. WHY: Auto-archive is only correct when status is explicitly done or parked; applying it to in-progress work severs continuity.
• NEVER exceed the 1500-token budget — Bloated context files slow down load and waste model capacity. WHY: The target is 1200-1500 tokens; beyond that the signal-to-noise ratio degrades and compaction may truncate critical sections.

Usage Examples

Saving context before ending a long session:

# Invocation (default stream)
/save-context

# Files written to .context/session/
# .context/session/CONTEXT-llm.md        ← session snapshot
# .context/session/INDEX.md              ← updated index entry

Saving context under a named stream:

# Invocation with explicit stream name
/save-context auth-refactor "completed JWT middleware extraction"

# Files written to .context/session/
# .context/session/CONTEXT-auth-refactor-llm.md   ← named snapshot
# .context/session/INDEX.md                        ← updated index entry

Archiving a completed stream:

# When status resolves to "done" the skill auto-archives
/save-context auth-refactor "all tests green, PR merged" --status done

# Result
# .context/session/done/CONTEXT-auth-refactor-llm.md  ← archived
# .context/session/INDEX.md                            ← updated with archived status

References