Merge pull request #111 from AdaWorldAPI/claude/ledger-efficiency-epiphany

docs: EPIPHANIES.md — ledger efficiency + ambient arc-knowledge loss findings

Author: AdaWorldAPI

.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 `<prompt file> | #N <title>`. ~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.