Wayfinder map: Combined token burden taxonomy #9

Destination

Replace /token-burden's flat section model (Base prompt, AGENTS, Skills, Metadata, Tool definitions) with the locked Combined token burden taxonomy: two top-level surfaces — Combined System Prompt and Combined Tool Definitions — each decomposed into source-attributed child rows, with additive accounting (children sum to parents) and honest source attribution. The map is done when every decision needed to implement this test-first is resolved and the way to a TDD handoff is clear.

Notes

• Locked inputs — do not re-litigate: taxonomy in docs/plans/2026-07-08-combined-token-burden-taxonomy.md; primary-source research in docs/research/pi-base-prompt-extension-contributions.md; domain language in CONTEXT.md (Combined System Prompt, Combined Tool Definitions, Budget Section, Source Trace). "Base prompt" / "Preamble" must not appear as user-facing taxonomy.
• Skills every session should consult: /grilling + /domain-modeling for HITL tickets; tdd for the implementation handoff; codegraph before broad grep/read.
• TDD is critical. Implementation is test-first. Tests currently lock the old labels (Base prompt, Skills (N), Metadata (...), Tool definitions (...), SYSTEM.md / APPEND_SYSTEM.md) — see src/parser.test.ts, src/budget-table.test.ts, src/report-view.test.ts, src/e2e/*.
• Additive accounting: counted child rows must sum to their parent; totalTokens = Combined System Prompt + Combined Tool Definitions.
• Honesty: if a source cannot be proven, use an honest fallback label; never guess. Provider before_provider_request rewrites are NOT visible via ctx.getSystemPrompt() — out of scope.
• Separate surfaces: tool prompt text (promptSnippet / promptGuidelines) and tool schemas are different model-facing surfaces; never merge them.
• Decision-depth delegation: for implementation-detail questions comparable to trace anchoring, internal naming, or evidence-bucket mapping, proceed with the agent’s evidence-backed recommendation without repeated confirmation. Continue to ask Will about user-facing behavior and product trade-offs.

Confirmed during charting (orientation; detail lives in the research tickets)

• pi.getAllTools(): ToolInfo[] returns sourceInfo on every tool; sourceInfo.source is builtin (pi core), sdk (SDK/custom), or package/local/etc. (extensions). → Pi Core / SDK-Custom / Extension tool rows are computable exactly now. (Formalized in the "Confirm pi tool sourceInfo → row mapping" ticket.)
• pi.getActiveTools(): string[] returns active tool names → Inactive Available Tools computable now.
• Tool prompt text is measurable from the literal prompt ("Available tools:" + "Guidelines:" bullets); src/base-trace/base-lines.ts already extracts these lines.

Decisions so far

• Extension Prompt Additions accounting — use an honest non-counted Extension Prompt Additions row labeled Not separately measurable; 0 counted tokens; text is included in Pi Core Prompt upper bound rather than guessed.

• Confirm pi tool sourceInfo → Combined Tool Definitions row mapping — source === "builtin" → Pi Core, === "sdk" → SDK/Custom, else → Extension Tools; sourceInfo already on every ToolInfo; active = name ∈ getActiveTools() (no active flag on sourceInfo).

• Baseline prompt / before_agent_start visibility for Extension Prompt Additions — not exactly measurable: baseline string is internal (no ctx accessor), per-extension deltas not exposed (full-replacement chain), no markers; before_provider_request confirmed separate. Extension Prompt Additions accounting should use an honest non-counted row; exact measurement needs a subprocess baseline-diff. Lever for Combined taxonomy data model and Base-span decomposition & DRY with trace: ctx.getSystemPromptOptions() exposes structured baseline inputs.

• Combined taxonomy data model — use recursive PromptSection.children?: PromptSection[], ParsedPrompt.surfaces for the two top-level Budget Sections, preserve ToolInfo["sourceInfo"] for tool grouping, and keep Tool Prompt Text separate from tool schemas with additive reconciliation invariants.

• Brute-force extension burden analysis — support optional deep extension analysis, but lead with structured source attribution; brute-force subprocess diffs are an explicit cached fallback for unexplained deltas, not the default foundation.

• Base-span decomposition & DRY with trace — share literal prompt span extraction in a neutral module; measure Tool Prompt Text from exact prompt spans, Pi Core Prompt as the remainder, and reconcile with Prompt boundary overhead.

• Two-surface drilldown & stacked-bar UX — use Variant A: overview stacked bar has only the two top-level surfaces; contributor bars appear inside surface drilldown; tools and skill-toggle become row capabilities in one recursive drilldown model.

• Tool Envelope Overhead placement — show measurable schema tokens per tool, plus one separate counted Tool Envelope Overhead leaf under Combined Tool Definitions; never invent per-tool or per-source overhead allocations.

• Trace repointing & Base→Combined rename boundary — Source Trace is a Tool Prompt Text row capability; internals use Source Trace naming; buckets preserve Pi Core, SDK/custom, per-extension, shared, and unattributed evidence honestly.

• Label-coupling migration strategy — use a required semantic section-kind enum with centralized labels/capabilities; keep taxonomy labels stable, migrate through one temporary compatibility bridge, and deliver the redesign in eight confirmed vertical TDD slices.

• Inactive Available Tools grouping — group inactive tools by the same non-empty Pi Core / Extension / SDK-Custom source taxonomy; reconcile schema-only counterfactual totals additively and exclude the entire branch from counted burden.

Not yet specified

None — all decisions required for the TDD handoff are resolved.

Out of scope

• Provider before_provider_request rewrites — not measurable via ctx.getSystemPrompt(). (locked)
• The "Actionable insights" milestone (trim suggestions when the budget is tight) — separate effort.
• TUI chrome / visual redesign beyond what the taxonomy requires.