diff --git a/.claude/board/EPIPHANIES.md b/.claude/board/EPIPHANIES.md new file mode 100644 index 00000000..901e49f9 --- /dev/null +++ b/.claude/board/EPIPHANIES.md @@ -0,0 +1,47 @@ +# ndarray — Epiphanies (append-only) + +## 2026-04-19 — Prompt↔PR ledger is 10⁷× cheaper than code grep +**Status:** FINDING +**Scope:** @workspace-primer domain:bookkeeping + +To answer "what did we ship for topic X": + +- **Grep across code:** ~100 MB of Rust across N crates, ~25M tokens of context, minutes of agent turns. +- **Grep the ledger:** one `grep X .claude/board/PROMPTS_VS_PRS.md` returns ` | #N `. ~25 tokens, sub-second. + +Seven orders of magnitude cheaper. The pairing **prompt-file ↔ PR** is the +minimum addressable record of "this artifact was built to answer this +brief" — the hyperlink that replaces re-discovery by full-text scan. + +The line is mechanical bookkeeping (Haiku-level, no synthesis). The +value accumulates on every subsequent "what about X" query thereafter: +ledger-first, code-never-unless-necessary. + +Cross-ref: PR #213 (lance-graph, 41 prompts × merged PRs), PR #110 +(ndarray, 25 prompts × merged PRs). Both shipped in ~90s on a dumb +enumerate+match+append loop. No code reads, no MCP, no synthesis. + +## 2026-04-19 — Code-arc knowledge loss is 30-50% of session tokens (ambient) +**Status:** FINDING +**Scope:** @workspace-primer domain:bookkeeping + +Empirical (per user, 2026-04-19): **30-50% of session tokens** burn on +rediscovering what code paths exist, what was tried, what got reverted, +what decisions led to the current shape. This is **orthogonal** to the +20-30-turn cold-start tax — it's the *ambient* loss across every query, +every subagent spawn, every refactor. + +The ledger closes three channels at once: + +| Channel | Before | After | Discount | +|---|---|---|---| +| Cold-start (once per session) | 20-30 turns | 3-5 turns | ~6× | +| Find-code (per query) | ~25M tokens (grep codebase) | ~25 tokens (grep ledger) | 10⁷× | +| **Ambient arc knowledge (every turn)** | **30-50% of session budget** | **~0%** | **2×-eternal** | + +All three channels collapse to two text-file reads: PROMPTS_VS_PRS.md + +PR_ARC_INVENTORY.md. The second file is read only when arc detail is +needed (Knowledge Activation trigger), so the routine cost is 0. + +Cross-ref: PR #110 (ndarray ledger), PR #213 (lance-graph ledger). +EPIPHANIES.md 10⁷× finding above.