feat(knowledge): canonical data-fields.md — single LLM/Claude Code field reference

[jonathaneoliver]

Why

Today the dashboard chat bot (and Claude Code) infer field semantics from examples — read a find_plays row, see video_quality_pct: 3.35, guess it's a percentage. There's no anchor explaining what each field means, what units it's in, how it's populated, or what's a known gotcha.

Real symptom from issue #497 chat handoffs: the bot kept saying things like "Let me check the actual schema first" and re-running query to inspect columns mid-investigation — burning tool budget on metadata it should already have. It also got field semantics wrong (e.g. interpreted transfer_ms as wall-clock when it's actually proxy→upstream socket time, while the wire-shaped time has to be derived from ts deltas).

What

One canonical standard at .claude/standards/data-fields.md — read via read_standard(\"data-fields\") — with sections per data source and one entry per field:

• Name (qualified path — network_requests.bytes_out or session_events.player_metrics.video_quality_pct)
• Type / units (UInt32, ms, KB, bool, IANA tz, ratio 0-1, …)
• Description — what it semantically represents
• How populated — live by player SDK / derived by forwarder / proxy synthesised / operator-set
• Known gotchas — e.g. "0 means unknown, not zero throughput"; "missing on iOS before first frame decoded"; "forwarder writes proxy→upstream timing, not wire timing"
• Cross-references — links to standards / findings / skills that interpret it

Sources to cover

Source	Approx fields	Doc lives where today
session_events table (and the nested player_metrics / current_play.player_metrics / server_metrics blobs)	~60	01-schema.sql comments + ad-hoc inference
network_requests table	~25	01-schema.sql
control_events table	~12	01-schema.sql + chat.md hints
characterization_runs table + report shape (runner.Report / Step / Cycle / StartupCycleResult / variant_activity)	~60 across the nested types	Go struct tags in tests/characterization/runner/report.go + the per-test standards docs
Plays summary (the find_plays return shape)	~25	None — derived in plays/find.go
Label vocabulary	~50 known strings + the synthesis rules	labels.go source + scattered system-prompt hints

Rough total: 200-250 field entries. Estimated 1500-3000 lines of markdown.

How

Phased delivery so the doc is useful early:

1. Phase 1 (~2h) — session_events + network_requests field tables. These are the most-used in every chat investigation; gets the highest-impact coverage live first.
2. Phase 2 (~1h) — control_events + plays summary + label vocabulary (cross-referencing existing system-prompt hints rather than duplicating).
3. Phase 3 (~1-2h) — characterization shapes. Carry forward the per-test standards' field reasoning where it exists; fill the gaps.

Each phase ships independently; doc is incrementally useful. The bot starts benefiting from Phase 1 immediately (most investigations only touch events + network requests).

How to ensure the bot actually uses it

Update prompts/chat.md with one sentence: "Before reasoning about the meaning of a specific field, call read_standard(name=\\\"data-fields\\\") once and look up the entry." Bot reads it on first field-question, then has it in context for the rest of the conversation.

Acceptance

• .claude/standards/data-fields.md exists and covers Phase-1 fields with the schema-per-entry format above.
• prompts/chat.md references it.
• A spot-check chat conversation that asks "what does video_quality_pct mean" returns the answer without re-inspecting CH schema.
• (Future) phases 2 + 3 close their own follow-up issues that link back here.

Out of scope

• Auto-generation from CH schema / Go struct tags. Tempting but the doc's value is the prose semantics, not the type info. Worth revisiting if the doc gets too out-of-date to maintain by hand.
• A field-level browser UI. Out of scope; the standards file is the substrate, UI can come later.

[jonathaneoliver]

Triage

• Points: 5 — multi-source coverage (~200-250 field entries across 6 sources), phased delivery, no code risk but significant prose work. Bigger than the caching issue (feat(chat): Anthropic prompt caching on system prompt + tools block #511, points:3) because the surface is wider.
• Effort: ~half a day to a full day end-to-end. Phase 1 (events + network_requests) is ~2h on its own and unlocks most of the value; Phases 2 + 3 can ship later as separate PRs.
• Priority: P1 (this sprint). Bumped above feat(chat): Anthropic prompt caching on system prompt + tools block #511 because this is fixing real answer-quality bugs (see the transfer_ms misinterpretation in the recent chat handoff that confused proxy→upstream timing for wire timing), not just cost. Wrong answers compound; wrong cost is just $$.
• Value: high. Every future investigation benefits; also benefits Claude Code (handoff skill explicitly references standards), and removes a category of "let me check the schema first" wasted tool calls.

[jonathaneoliver]

Phase 1 shipped (commits to follow on the branch this lands on).

.claude/standards/data-fields.md now covers:

• §1 session_events table + nested player_metrics / server_metrics / current_play blobs (~50 fields with units, gotchas, cross-refs)
• §2 network_requests table (~25 fields, including the transfer_ms gotcha called out at top of the section)
• §3 control_events table including the closed-set event vocabulary (16 event types with semantic descriptions, info JSON shapes, and the synth labels each produces)
• §4 Plays summary (the find_plays return shape — ~25 fields including the relationship between last_event filtering and the *_count columns)
• §5 Label vocabulary — direct vs synthesized, severity precedence, the wildcard-match semantics, examples of every common label

Each section starts with a tag rollup ([hot], [forensics], [ops], [debug]) so the bot can quickly identify which fields to prioritise citing.

System prompt (analytics/go-forwarder/prompts/chat.md) updated to instruct the bot: "call read_standard(name=\"data-fields\") once per chat when a field's meaning is non-obvious — don't guess (that's how transfer_ms got misinterpreted)." Forwarder rebuilt + redeployed to test-dev with the change embedded.

Doc size: 1388 lines, 62KB on disk, ~15K tokens. The bot loads it once via read_standard (a Tier-2 tool call) and it sits in context for the rest of the chat. Combined with the prompt-caching work tracked in #511, the per-turn cost of having this in context will drop ~90% once that lands.

Follow-ups filed:

• feat(knowledge): data-fields.md Phase 3 — characterization report shapes #514 — Phase 3: characterization report shapes (runner.Report, Step, StartupCycleResult, variant_activity[], Summary, Sample). Points: 3, priority: P2.

Closing once verified against a real chat investigation.

[jonathaneoliver]

Closing — .claude/standards/data-fields.md is live (~2143 lines / 96KB) covering all six planned sections: session_events, network_requests, control_events, plays summary, label vocabulary, and characterization shapes. prompts/chat.md:63 cites read_standard(name="data-fields") so the bot picks it up.