context-health-check

name	context-health-check
description	Context window health check. Trigger with /ctx or phrases like "context check", "do I need a new conversation", "how much context left". Evaluates current context consumption and recommends whether to start a new conversation.

Context Health Check

When this skill is triggered, perform the following assessment and output a report.

Token Estimation Method

LLMs cannot directly read consumed token counts. Use these proxy formulas:

Estimation Formula

Consumed ≈ System Overhead + Σ(Per-turn Consumption)

System Overhead ≈ 15K-25K tokens (system prompt + skills metadata + workspace info)

Per-turn Consumption ≈ User message (~200-500) 
           + Tool call results (each ~500-5000, large file reads ~3000-8000)
           + Assistant response (~500-2000)

High-Consumption Operation Reference

Operation	Estimated Tokens
Read <100 line file	~500-1500
Read 200-500 line file	~3000-5000
Read 500+ line file (e.g. STATUS.md)	~5000-10000
grep search results (50 matches)	~3000-5000
Long command output	~2000-8000
Generate/edit a file	~1000-3000
Browser operations (with DOM)	~5000-15000

Model Context Windows

Model	Total Window	Available (minus overhead)	Safety Threshold (80%)
Claude Opus/Sonnet (Anthropic)	200K	~175K	140K
GPT-4o (OpenAI)	128K	~105K	84K
Gemini Pro (Google)	1M+	~950K+	Unlikely to overflow

⚠️ MUST read USER.md model preference field first. If found, use that model's window size. If not found, default to Claude 200K. Do NOT default to Gemini 1M or other models.

Assessment Process

1. Identify current model (read USER.md → model preference field. If not found, default to Claude 200K. Do not guess, do not use Gemini 1M)
2. Count conversation turns (user↔assistant interaction count)
3. Estimate tool call token consumption (accumulate per the table above)
4. Calculate total estimated consumption
5. Calculate remaining percentage = (available window - consumed) / available window
6. Assign health level

Health Levels

Level	Remaining %	Recommendation
🟢 Healthy	>50% remaining	Continue working, no concerns
🟡 Caution	20-50% remaining	Finish current task then start a new conversation. Avoid loading more large files. Avoid long output commands
🔴 Danger	<20% remaining	⚠️ Immediately update status files and start a new conversation. Continuing will likely cause forgetting/repetition/quality degradation

Quick Judgment Rules of Thumb (when you don't want to calculate)

For Claude 200K window:

• ≤5 turns + 1 large file → 🟢
• 10-15 turns + 2-3 large files + multiple code edits → 🟡
• >18 turns or >5 large file reads or starting to forget early content → 🔴

Output Format

## 🧠 Context Health Check

**Model**: [Claude/GPT-4o/Gemini/...] (context window XK)

| Metric | Current Value | Estimated Tokens |
|--------|:------------:|:----------------:|
| System overhead | — | ~20K |
| Conversation turns | X turns | ~YK |
| Large file reads | [list files + line counts] | ~ZK |
| Tool calls | ~N calls | ~WK |
| **Total estimated** | — | **~TK** |
| **Remaining estimated** | — | **~RK (P%)** |

**Health Level**: 🟢/🟡/🔴

**Recommendation**: [specific advice]
**Estimated remaining capacity**: ~M normal turns / ~L large file reads

Defensive Auto-Save

Core problem: 🔴 detection depends on the Agent having an opportunity to execute — when context suddenly overflows, the Agent has no chance to save anything. Solution: Don't wait for 🔴 — proactively save every 10 turns.

Rules

1. Every 10 interaction turns (one user↔assistant round = 1 turn), Agent MUST silently update memory/CRASH_CONTEXT.md
2. Silent = don't interrupt the user. No announcement needed, no confirmation needed. Complete during response or between tool calls
3. Incremental update: Only update changed fields, don't full-rewrite
4. Format matches what's written during 🔴 detection (see Additional Rule #1 below)
5. Delete after recovery: After /resume crash successfully recovers, delete CRASH_CONTEXT.md (avoid stale data)
6. Trigger timing checklist:
   • Turn 10 → First write ✅
   • Turn 20 → Update ✅
   • Turn 30 → Update ✅ (usually approaching 🟡/🔴 by now)
   • 🔴 detection triggered → Final update (including "suggested next steps") ✅

Defense Layers

Layer	Trigger Condition	Reliability
L0 Defense	Silent save every 10 turns	⭐⭐⭐ Most reliable
L1 Warning	Auto-save when /ctx detects 🔴	⭐⭐ Needs detection opportunity
L2 Fallback	/resume crash scans convo/ for _CRASH files	⭐ Safety net

Additional Rules

1. When 🔴 danger is detected, automatically execute memory snapshot + crash recovery file (MUSE compact:before protocol):
   • Write current progress to memory/YYYY-MM-DD.md (don't wait for user /bye)
   • Update task.md progress markers
   • Write memory/CRASH_CONTEXT.md (structured recovery file, auto-read by next /resume crash):

     # Crash Context — YYYY-MM-DD HH:MM
     ## Current Role: [strategy/build/growth/qa]
     ## Current Task: [what was being done]
     ## Unfinished: [list]
     ## Key Decisions: [decisions made this session]
     ## User's Last Question: [if any]
     ## Suggested Next Steps: [what to do after recovery]
     

   • Then notify the user:

     ⚠️ Context is about to overflow! Auto-saved:
     - memory/YYYY-MM-DD.md ✅
     - memory/CRASH_CONTEXT.md ✅
     Please end this conversation. Use `/resume crash` in a new conversation to auto-recover.
     To export this conversation, save to: convo/YYMMDD/YYMMDD-NN-desc_CRASH.md
     

2. If current conversation has not loaded any status files and is ≤3 turns, report 🟢 directly without detailed calculation
3. Natural language triggers also apply ("how much context left?", "context enough?", etc.)
4. If you detect yourself forgetting early conversation content or repeating yourself, even if the formula says there's room left, report 🔴 directly

🆕 Session Checkpoint (v2.14.0 — OpenViking-inspired)

Inspired by OpenViking's session compression — auto-checkpoint mid-conversation to prevent context loss. Complements Defensive Auto-Save (CRASH_CONTEXT.md): Auto-Save = crash recovery safety net, Session Checkpoint = quality preservation.

Why

Long conversations degrade quality because the Agent loses track of early context. By the time /bye runs, the Agent may have already forgotten 50-80% of early work. Session Checkpoint writes compressed mid-session snapshots to preserve context fidelity.

When to Checkpoint

Trigger	Action
Every 15 turns	Silent checkpoint (no user notification)
After a major milestone (commit, deploy, release, version bump)	Silent checkpoint
When /ctx detects 🟡	Checkpoint + notify user
When switching topics (user asks about something unrelated to current work)	Silent checkpoint

What to Write

File: memory/YYYY-MM-DD.md (append, not overwrite)

Format (compressed — use Semantic Compression rules from /bye):

## 📍 Checkpoint (HH:MM, ~turn N)
- 主线: [1-2 sentence summary of work so far]
- 决策: [key decisions if any]
- 状态: [current task status]

Rules

1. Silent: Do NOT announce checkpoints to the user. Do NOT ask for confirmation. Write silently between tool calls
2. Append-only: Never overwrite existing memory content. Always append
3. Compressed: Use the 5:1 compression ratio — max 3-4 lines per checkpoint
4. Idempotent: If the same milestone was already checkpointed, skip (check last checkpoint's content)
5. No performance impact: Checkpoint during response generation or between tool calls, never adding a delay
6. Checkpoint counter: Track _checkpoint_count mentally. First checkpoint = turn ~15, then every ~15 turns after

Interaction with Other Systems

System	Relationship
Defensive Auto-Save (CRASH_CONTEXT.md)	Auto-Save = full structured snapshot for crash recovery. Checkpoint = lightweight append for quality preservation. Both can coexist
/bye Step 1	/bye should READ checkpoints to reconstruct full session history (prevents the 80% forgetting problem)
/bye Step 4	Final memory write should reference checkpoints: "See checkpoints at HH:MM, HH:MM"
/resume	Checkpoints appear as part of daily memory — no special handling needed