From c00eb809043a46f22c7e9e35e9dcd2ce3ea8317e Mon Sep 17 00:00:00 2001
From: robinryuk <306148894+robinryuk@users.noreply.github.com>
Date: Wed, 19 Aug 2026 08:41:22 +0700
Subject: [PATCH] =?UTF-8?q?feat(skills):=20context-budget=20=E2=80=94=20ac?=
 =?UTF-8?q?count=20for=20reconnect=20scaffolding?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

context-budget inventories components that load once at startup. On a reconnect the
app re-injects much of that inventory into the session transcript as attachment lines,
and that lands in the same context window.

Measured on a session that had reconnected once: 33,884 of 49,830 bytes was
scaffolding — skill_listing 14.6KB, mcp_instructions_delta 8.1KB, deferred_tools_delta
7.1KB, agent_listing_delta 2.6KB — against 15.9KB of actual conversation.

Adds a measure-it-yourself snippet, a >40% flag, and the consequence for the rest of
the skill: a trimmed skill or MCP server saves tokens once per reconnect, not once per
session. Also notes that transcript size is a poor proxy for context fullness unless
attachment lines are excluded.
---
 skills/context-budget/SKILL.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/skills/context-budget/SKILL.md b/skills/context-budget/SKILL.md
index 1061041c6..d54140263 100644
--- a/skills/context-budget/SKILL.md
+++ b/skills/context-budget/SKILL.md
@@ -43,6 +43,38 @@ Scan all component directories and estimate token consumption:
 - Estimate schema overhead at ~500 tokens per tool
 - Flag: servers with >20 tools, servers that wrap simple CLI commands (`gh`, `git`, `npm`, `supabase`, `vercel`)
 
+**Session scaffolding** (the transcript itself)
+
+Everything above is loaded once at startup. A *reconnect* re-injects a second copy of much of it into
+the session transcript as `attachment` lines, and that cost is charged to the same context window.
+Measure it directly rather than estimating:
+
+```sh
+# on the newest transcript for this project
+f=$(ls -t ~/.claude/projects/"${PWD//\//-}"/*.jsonl | head -1)
+python3 - "$f" <<'EOF'
+import json,sys
+tot=att=0
+for line in open(sys.argv[1]):
+    tot+=len(line)
+    try:
+        if json.loads(line).get('type')=='attachment': att+=len(line)
+    except: pass
+print(f"transcript {tot}B | scaffolding {att}B ({att*100//max(tot,1)}%) | conversation {tot-att}B")
+EOF
+```
+
+Measured on a session that had reconnected once: **33,884 of 49,830 bytes — 68% scaffolding**, broken
+down as `skill_listing` 14.6KB, `mcp_instructions_delta` 8.1KB, `deferred_tools_delta` 7.1KB,
+`agent_listing_delta` 2.6KB. The conversation itself was 15.9KB.
+
+- Flag: scaffolding >40% of the transcript — the session is paying more for its own inventory than for
+  the work
+- This is the strongest argument for the reductions elsewhere in this skill: trimming a skill or an
+  MCP server saves tokens *once per reconnect*, not once per session
+- It also means transcript file size is a poor proxy for how full a context window is. Count only
+  non-`attachment` lines when reporting "how much room is left"
+
 **CLAUDE.md** (project + user-level)
 - Count tokens per file in the CLAUDE.md chain
 - Flag: combined total >300 lines