SuperAPI AI Directory

session-health

Coding & development

View repository

Updated 10-16 02:32

About this skill

Session Health Assessment (Session Health)

In long sessions, assess the trade-offs of "continue vs. start new" and determine whether a new session should be started.Assess only, do not modifyAny session file. Core principles:High compression ratio ≠ should switch;Low window occupancy ≠ economically worry-free. Decision = trade-off between continuation cost (capacity + quality + per-turn token economy) vs. switching cost (loss of early precise details + handoff turns).

When to use

  • Passive: When the user mentions "compression / start a new session / context overhead / context", immediately perform a full assessment.
  • Proactive: During long sessions when the user keeps pushing forward (go / continue / proceed as planned), check once along the way; only whenthe state has clearly deteriorated or a threshold is reachedgive a reminder; otherwise just mention "session health (compression x%)" in passing.

Hard constraints

  1. Read-only assessment—must not modify any tool's session storage (Deep Code:~/.deepcode/projects/;Cursor:~/.cursor/; for other tools, locate via the adapter layer). Session JSONL / SQLite / indexes / snapshots are all read-only.
  2. Do not exaggerate, do not fabricate—numbers come from actual file statistics; if something cannot be found, say so, do not guess.
  3. Do not mechanically recommend switching—must assess the nature of the work and its recoverability; work that depends on early content (refactoring/optimization) may not warrant switching even if compression is high.
  4. Do not expand when threshold is not reached—when healthy, a one-sentence confirmation is enough; give a full report only when a threshold is reached or the user requests it.
  5. When signals are missing, degrade gracefully, do not pretend to be precise—the tool adapter layer declares "what can be measured and what cannot"; missing dimensions are handled according to degradation rules (see "Signal Missing Degradation Rules"), and do not default to healthy or unhealthy just because data is missing.

Tool adapter layer (data source entry point)

This skill does not hard-code the data format of any tool—each tool's reading method is centralized in the tool adapter layer:

  • references/tool-data-sources.md—implemented tool adapter sections (Deep Code / Cursor): session directory location, signal reading commands, recovery capability entry points.
  • references/tool-adapter-template.md—new tool onboarding template: generate an adapter section for a new tool according to the template + detection process.

Prevent dual sources: SKILL.md does not contain specific data commands (commands drift with tool versions—see refresh mechanism); commands exist only in references/tool-data-sources.md. This page keeps only stable methodology.

Tool detection (determine which tool is currently running)

Confirm in the following priority order, taking the first feasible one:

  1. The session context/environment variables already explicitly state the current tool (e.g., the agent knows which tool it is in) → use it directly.
  1. Detect each tool's session storage directory, take the one withthe most recent write(ls -td compare by mtime sorting).
  2. Still uncertain → AskUserQuestion to ask the user which tool they are currently in. After the tool is determined,look up the references/tool-data-sources.md corresponding adapter sectionto perform data acquisition. If the current tool is not included, follow the "new tool onboarding" process (see the end of the document + template).

Signal availability (determines what can be measured / missing signals degrade)

Signal Meaning Handling when missing
Message count Current session messages/turns None → qualitative (based on session feel + nature of work)
Compression/summarization ratio Degree to which early content has been summarized None → skip this dimension (do not default to "uncompressed")
Context usage (absolute value) Historical input token volume per turn None → estimate with degradation (message count × per-message estimate) + annotate
Model window (denominator) Baseline for determining usage ratio Look up references/model-contexts.md; if not listed → ask the user/verify online
Activity/time span Session age, duration None → skip
Session recovery capability Whether a new session can retrieve old context None → evaluate conservatively as "git + handoff document only"
For detailed signal availability of Deep Code / Cursor respectively, see references/tool-data-sources.md summary table.

Nature-of-work assessment (switching cost — must be answered for every assessment)

# Question Answer "yes" → meaning
1a Does the current work reference/modify content from **early in the session (before the compression line)**? (Large refactoring / optimization / cross-early changes = yes) Depends on early details → switching loses precise context
1b (If 1a is yes) The earlydecision basis/naming conventions/numbersthat it depends on — have they been recorded in the handoff document/git/project documentation? No → tacit context is lost, switching cost is extremely high(code without rationale)
2 Have the early related changes been commit/push? No → switching prohibited(uncommitted = switching loses work results)
3 Do the handoff document / project documentation / the tool's rules system record the early key decisions? Yes → good recoverability (a new session can retrieve them)
4 Roughly how many turns of conversation is the estimated remaining workload? (1-2 turns / 10-20 turns / dozens of turns) Many turns → the per-turn historical input cost of continuing the session accumulates significantly (switching saves money)
  • Switching cost = tacit context (#1b no → extremely high) × recoverability (#2/#3 no → higher) × task interruption (whether at a task boundary — see "switching timing")
  • Independent new task (#1a no) → low switching cost
  • Economic dimension(#4): per-turn input for a newly opened session ≈ only the new task context (a few K tokens); per-turn input for continuing the session ≈ absolute context usage (history) — the gap accumulates when there are many turns
  • Switching within the same tool is not a cold start:Deep Code /resume, the Cursor history panel can list historical sessions to continue, and the recovery cost ≈ handoff turns (reading the handoff document + establishing context in the first turn), not "rebuilding from scratch"

Determination: two-dimensional decision model

Dimension A — Cost of continuing (capacity + quality + economics)

Signal Threshold Cost
Context usage window ratio ≥ 50% window High (capacity pressure)
Context usage window ratio 30%–50% window Medium
Context usage window ratio < 30% window Low (ample capacity—often the case with large windows)
Economic cost (absolute value × number of turns) Usage ≥ 50K/turn and estimated remaining ≥10 turns High (per-turn historical input cost accumulates)
Economic cost Usage ≥ 50K/turn or remaining ≥10 turns Medium
Economic cost Other (small history / wrapping up soon) Low
Compression/summarization ratio ≥ 50% Medium (early details summarized—not a capacity crisis, git traceable)
Compression/summarization ratio 30%–50% Low-Medium
Message count ≥ 800 messages (proxy metric, for reference only) Low-Medium
Take the strictest across multiple signals.Priority: economic cost (absolute value—independent of window, paid every turn) > capacity (window ratio) > compression quality > message count.

The above thresholds aredefault parameters(calibrated to mainstream models and cost structures)—adjustable per project. Difference between window ratio and absolute value (using deepseek-v4-flash as an example, windowsee reference table): under a 1M window, 220K tokens of usage is only 22% (capacity healthy), but each turn's input is still billed at 220K tokens (economic cost—if many turns remain, switching saves significantly; if the server has context caching, the historical portion may be discounted, narrowing the gap but it still exists). Window values are always looked up in references/model-contexts.md, not hardcoded in the text.

Estimation basis:activeTokens is the indexsnapshot; actual per-turn input ≈ the compressed "summary + uncompressed messages" (may be smaller than the snapshot)—use the snapshot as an upper-bound estimate for economic evaluation, and note the basis and direction in the report (e.g., "≤220K/turn").

Signal-missing degradation rules (for tools without token data—e.g., Cursor)

When a tool's adapter layer declares a signal unavailable, degrade as follows,the report must note the basis:

Missing signal Degradation approach Report annotation
Context usage (absolute value) Estimate = message count × per-message estimate (0.5–2K tokens/message, chosen by session content density) ÷ window (lookup) → give only the magnitude (low/medium/high), don't fake precision; when a switching decision is involved, ask the user to check the UI context usage bar to confirm "Estimated value (message count × per-message average), please refer to the UI"
Compression/summarization ratio Skip this dimension; use message count + session duration to qualitatively flag summarization risk "Not quantifiable (tool has no compression markers)"
Economic cost Cannot be quantified → do not calculate; prompt the user that it can be calculated after they provide the UI usage number "Not quantifiable (no token snapshot)"
Activity/time span Skip —
Degradation does not equal default health: the capacity/economic dimension is marked "unknown (estimated)" rather than "low".

Dimension B — Switching cost (nature of work + recoverability)

Scenario Switching cost
Independent new task, early changes already committed Low
Depends on early content, but already committed + recorded in handoff document Medium (recoverable but requires handoff)
Depends on early content, and early changes not committed Extremely high (switching prohibited)

Conclusion matrix

A continuation cost \ B switching cost B low (independent task) B high (depends on early content)
A low(healthy) Continue Continue(switching is actually a loss — use git/session files to trace early details)
A medium Continue Continue, keep an eye on it; if switching is needed, complete the handoff first (handoff document + commit)
A high Switching recommended(handoff harvest) Danger zone: deep handoff (handoff document syncing early state + after commit) then switch, or continue + git trace

Switching timing recommendations (reduce interruption cost)

Switching cost is strongly correlated with "timing":

  • Switching at task boundaries is most worthwhile: a commit / phase completion, no in-progress reasoning chain → interruption loss ≈ 0, lowest handoff cost
  • Switching mid-task is the biggest loss: reasoning chain in progress, half-finished work not landed → switching = interrupting the train of thought + implicit state loss
  • If actively triggered while mid-task: recommend "wrap up first (commit / write handoff document) then switch", do not switch bare

Output format

When threshold is reached (switching recommended/danger zone/keep an eye on it)

## 会话健康度评估
| 指标 | 当前值 | 判定 |
|------|--------|------|
| 压缩比例 | 65%(714/1100)| 概要化(非容量危机——git 可追溯)|
| 消息数 | 1100 条 | 代理指标 |
| 上下文占用 | 221,648(窗口 22%——容量低 / 绝对值高)| 容量 / 经济 |
(Cursor 等无 token 数据的工具:相应行改为「估算值 / 无法量化」并标注,见信号缺失降级规则。)
工作性质评估:
- 依赖早期内容?是/否(重构/优化说明)
- 早期改动已 commit?是/否(未提交 → 禁止切换)
- 交接文档记录?是/否
- 预计剩余轮数?N 轮(× 占用/轮历史输入费 = 继续成本估算;新会话 ≈ 几 K/轮)
→ 切换成本:低/中/极高;经济结论:继续 / 切换省钱
**结论**:(按矩阵——建议切换 / 继续但留意 / 危险区需深度交接)
交接就绪检查(建议切换时):
- [ ] git 工作树干净 / 未提交变更数
- [ ] 关键产出已 push(最新 commit hash)
- [ ] 交接文档存在且同步到最新
- [ ] 运行中进程?(dev server / LSP / 测试服务——切换前说明归属/清理)
- [ ] 会话内临时状态?(临时配置 / 未持久化改动——是否需记录)
- [ ] 测试状态(若项目有质量链)
新会话入口:(按工具——Deep Code:输入「<项目名> 接手」走 project-handoff 或 /resume;Cursor:历史面板 + 项目 rules 文件)

When healthy (continue) or when switching is actually a loss

Session healthy (12% compressed) — continue. Or: 65% compressed but the current refactor depends on early commits (already committed, git-traceable) —switching is actually a loss, recommend continuing。

Handoff readiness check command (when recommending a new session)

git status --short | head -5                     # 未提交变更
git log --oneline -1                              # 最新 commit
ls .handoff/index 2>/dev/null && echo "交接存储在"  # 现行工作存储
ls HANDOFF.md 2>/dev/null && echo "旧模型待迁移"    # 旧交接件,迁移前不算现行

If a check fails (e.g., uncommitted changes) → remind to commit first or explain not switching.

Anti-patterns

  • Modifying/deleting any files under the tool's session storage (read-only evaluation)
  • Recommending a new session based on "feels very long" without looking at actual numbers
  • Mechanically recommending switching without considering the nature of the work (when a refactor depends on early content, switching is actually a loss)
  • Looking only at window percentage and ignoring absolute values (22% capacity under a 1M window is healthy ≠ 220k tokens per turn for free)
  • Still recommending switching with 1-2 turns remaining (the handoff itself costs 1-2 turns, so nothing is saved)
  • Still recommending switching when early changes are not committed to git (losing work results)
  • Switching bare mid-task (reasoning chain in progress — wrap up first, then switch)
  • Recommending switching while ignoring running processes/temporary state (dev/LSP/test ownership unclear)
  • Recommending a new session without providing a handoff readiness check (making the user switch bare)
  • Fabricating token counts / window sizes (if it cannot be found, say "the index has no such field" or note that it is an estimate)
  • Treating token snapshots as exact per-turn cost (should note the "≤ upper bound" basis)
  • Tools like Cursor that have no token data still fabricate usage numbers(should fall back to estimation + labeling, or ask the user to check the UI)
  • Defaulting to uncompressed based on "tool has no compression marker"(should skip the dimension and state that it cannot be quantified)
  • Hardcoding data commands in the SKILL.md body(commands should only be stored in references/tool-data-sources.md to prevent version drift)

Completion criteria

  • Read-only: no session/index/snapshot files modified
  • Numbers come from actual file statistics (wc/jq/sqlite3), not estimates; estimates are clearly labeled with their basis
  • Tool confirmed (tool detection), data executed per the adaptation layer
  • All 5 work-nature questions answered (dependency 1a/record completeness 1b/commit status/handoff document/remaining turns)—switching cost and economics are grounded
  • Conclusion given per the two-dimensional matrix (continue cost × switch cost), not a mechanical threshold
  • Economic assessment: window share (capacity) and absolute value (per-turn cost) judged separately; note the snapshot basis (≤ upper bound) or label "cannot be quantified"
  • Missing signals handled per degradation rules and labeled, no false precision
  • Switching recommendation includes timing judgment (task boundary vs mid-task—whether wrap-up is needed first)
  • When threshold is reached, includes handoff readiness check (including process/temporary state); when healthy or switching would be a net loss, state the reason
  • New session entry guidance is clear (by tool: /resume / project-handoff / history panel + rules)

Onboarding a new tool (using this skill in other tools)

  1. Copy this skill directory to that tool's skills/rules location.
  2. Open references/tool-adapter-template.md, and perform a read-only detection of that tool per the "onboarding process".
  3. Generate that tool's adaptation section per the template, and append it to references/tool-data-sources.md(including lastUpdated + refreshInterval + confidence).
  4. Update the signal availability summary table in references/tool-data-sources.md .
  5. This SKILL.md requires no changes(the methodology is tool-agnostic); if tool behavior changes, only refresh the corresponding adaptation section.

Tip: In the Cursor scenario, besides skills, you can also write the condensed health-check key points into the project .cursor/rules/*.mdc so they trigger persistently—the content can be distilled from "When to use" + "Hard constraints" + "Switching timing".