Skip to content

ADR: Canonical HOT / COLD split for FounderOS active briefs

Date: 2026-06-11 Status: Accepted Driver: Phoenix cost instrumentation revealed active/stampready.md (60 KB) + active/kindredpics.md (56 KB) cost ~$0.44 combined per orientation read. Devin asked whether the split was best practice before any file touches.

Decision

Every FounderOS active brief splits along HOT/COLD lines:

File Content Read pattern Target size
active/<slug>.md HOT — header, product map, current state, current priority, repo, files-to-read-first, do-not, open decisions, Cloudflare/infra durable state Every session start ≤15 KB / ~3,500 tokens
active/<slug>-log.md COLD — "Done this session" blocks, friction-point sequencing, prior-session pending lists Load on demand only when historical context needed No limit
decisions/YYYY-MM-DD-<slug>.md ADRs (already in use) Load on demand One per decision

Validation (research-backed)

  • Anthropic CLAUDE.md guidance: keep CLAUDE.md ≤200 lines, link to other docs via @-refs, move specialized content to skills. Well-structured CLAUDE.md → ~40% input-token reduction. (Manage costs effectively)
  • Context engineering 2026 consensus (Taskade / Packmind / BuildBetter / Supermemory / mem0): memory is a dedicated architectural component, separate from the context window. Headers segment context into addressable units. Load slices, not bulk dumps.
  • ADR pattern (Martin Fowler, AWS Prescriptive Guidance, Microsoft Azure Well-Architected, ThoughtWorks): hard separation between why (ADRs), how (runbooks), what (code). The proposed active/<slug>.md (state) + -log.md (history) + decisions/ (ADRs) maps 1:1 to AWS/Microsoft/Anthropic recommendations.
  • Prompt-cache economics: cached input = $0.30/M vs uncached $3/M on Sonnet (10×). Splitting hot orientation (cached) from cold history (load-on-demand) is the canonical optimization.

Pilot results (2026-06-11)

StampReady: - Before: 60,070 B / 15,017 tok / \(0.2253** per orientation read - After (HOT only): 13,207 B / 3,301 tok / **\)0.0495 per orientation read - Cold log: 44,264 B / 11,066 tok (load-on-demand only) - Savings: 78%

KindredPics (same split applied same session): - Before: 56,386 B / 14,096 tok / $0.2114 per orientation read - After (HOT only): targeting same ~75-80% reduction

Phoenix span U3BhbjoxNw== confirms the new HOT StampReady file at 13,207 B / 3,301 tok / $0.0495.

Implementation notes

  • Hook phoenix_memory_trace.py now emits file.bytes, tokens.est, cost.usd.est, read.partial per memory read. Cost basis = Opus 4.7 input @ $15/M tokens, 4-bytes-per-token heuristic.
  • Global ~/.claude/CLAUDE.md updated with the canonical HOT/COLD rule under the FounderOS section.
  • Small briefs (openwide.md 7.5 KB, wc26-bags.md 3.3 KB) already within budget — no split needed. They follow the structure but never accumulated session history.

When to revisit

  • If a project's HOT file exceeds 15 KB for two consecutive sessions, the Current state section is bloating — collapse closed milestones into one-line summaries, move detail to -log.md.
  • If Memory pointers (load on demand) keeps getting ignored (Phoenix shows zero memory_xxx.md reads across N sessions), the pointer convention isn't paying for itself — drop it.