Token-Aware Developer Brief

Token-Aware Developer Brief — Living Skill

Snapshot of a production skill as of 2026-07-25. Instance names are anonymised to instance-a / instance-b on purpose — do not replace them with real names.

Trigger: "token budget" / "context getting full" / "spawn sub-agent" / "advisor tool" / "token-aware brief" / "caveman" / "optimize tokens"

Proactive rule: Activate without being asked whenever a task is expected to consume >10K tokens, involve sub-agents, or use multiple tools. Exempt: short answers, single-turn Q&A.

Session Start

1. Read living-checklist.md — load accumulated patterns from prior sessions
2. Output the Skill Activation Protocol:

SKILL ACTIVATED: token-optimization
Date: YYYY-MM-DD
Checklist read: Yes — [N] active entries, newest: [date of most recent entry]
Active rule: "[verbatim quote of the most recent relevant rule]"
Approach: [2–3 sentences on token strategy for this specific session]

3. Fill out the brief below before starting work

The Brief

Section 1 — Context Window Budget

• Task type: routine / research / multi-source / coding / other: ___
• Estimated consumption: Low 10–15K / Med 15–35K / High 25–50K
• Overflow plan if >80% context used:
  • Compress old context (which parts? how aggressively?)
  • Reference external resources instead of loading into context
  • Spawn sub-agent with isolated context
  • Abort and restart with compressed context

Tool selection:

• Load only the tools you need — not all available tools upfront
• Lazy-load: fetch tool schemas on demand when needed
• Large data (>100KB): filter locally before loading into context
• Sensitive data: process in tool sandbox only, never pass into context

Section 2 — Knowledge Reuse

Living Checklist:

• Relevant checklist loaded? Path: ___________________________
  • Most recent rule (required quote — proves you read it): "___________________________"
  • Estimated tokens saved vs. cold research: ___K

Knowledge Base / Documentation:

• Searched existing docs / knowledge base before researching from scratch?
  • Where + search term: ___________________________

Cross-instance sync:

• git pull done — latest learnings from all instances loaded?
• Relevant team memory / shared folders read? Paths: ___________________________

Remaining knowledge gaps (fresh research needed):

Section 3 — Sub-Agent / Advisor Strategy

Task type: single-turn Q&A / research / coding / agent loop (Advisor pattern fits: research, coding, agent loops — not single-turn Q&A)

Sub-agents needed?

• Explore agent (codebase search, file discovery)
• Plan agent (architecture decisions, implementation design)
• General-purpose agent (complex multi-step tasks)
• Parallelizable? Which agents to spawn simultaneously: ___________________________

Executor + Advisor pattern:

• Worth it at ≥3 iterations — below 3, single-model is usually cheaper
• Executor model: [cheaper/faster model]
• Advisor model: [more capable model]
• Expected advisor calls: ___
• Advisor output budget: <100 words per call (cost control)

Section 4 — Output & Memory Compression

Output mode for this session:

Selected mode: ___

Caveman rules (active when mode ≠ None):

• Strip: articles (a/an/the), filler (just/basically/really), pleasantries (sure!/certainly), hedging (perhaps/I think)
• Keep: code blocks, technical terms, URLs, error messages, numeric values, library names
• Pattern: [thing] [action] [reason]. [next step]. — fragments are ok
• Auto-clarity exceptions (suspend mode temporarily): security warnings, irreversible actions, ambiguous multi-step sequences, user confusion

Input/Memory compression (check before long sessions):

• Context files too large? (CLAUDE.md, config, project notes — compress prose, keep code/URLs/tables)
• Living checklist too long? (>50 entries → archive old ones; compress prose into rules)

Section 5 — Implementation Checklist

• Context budget estimated realistically
• Knowledge reuse documented (checklist path + rule quoted)
• Sub-agent decision made (Y/N + reasoning)
• Output mode chosen (None / Lite / Full / Ultra)
• Memory compression checked
• Overflow plan defined
• Ready to start

Section 6 — Session-End Learning

(Fill out after completion, then write to living-checklist.md)

• Context usage: Estimated ___K / Actual ___K / Delta +/- ___K
• Sub-agent calls: Count ___ / Pattern ___ / Advisor break-even reached? Y/N
• Knowledge reuse: What saved tokens vs. cold research?
• Output mode: Did caveman affect quality? Optimal level for this task type?
• Tool selection: What could have been skipped?
• Rule: (1–2 sentence actionable guideline for next similar task)

Reference: Benchmarks

Caveman benchmarks (from juliusbrussee/caveman):

• Output compression: ~65–75% reduction per response
• Input compression (files): ~46% average (36–60% depending on content type)
• Note: session-total savings ~4–5% (output tokens are ~25% of session total)

Advisor break-even: ≥3 advisor calls — below 3, single-model is cheaper

Session End

After every session: write new learnings to living-checklist.md — what was discovered, why it matters, one concrete rule for next time.