feat(knowledge): data-fields.md Phase 3 — characterization report shapes

[jonathaneoliver]

Why

Phase 1 of .claude/standards/data-fields.md (issue #512) covers session_events, network_requests, control_events, plays summary, and label vocabulary — enough for typical play-level investigations. Characterization-test investigations need more: the per-test report shapes (runner.Report, Step, StartupCycleResult, AbortCycleResult, RetryCycleResult, variant_activity, Summary) drive the analysis but aren't field-documented in one place yet.

Today, .claude/standards/*-characterization-test.md (startup, abort) cover their own test mode's fields well, but there's no cross-cutting reference for the shared types (the per-Step envelope, the variant_activity[] shape that appears across modes, the Summary aggregate).

What

Extend .claude/standards/data-fields.md with §6 — characterization report shapes. Same format as Phases 1+2 (entry per field: name, type, units, populated, meaning, gotchas, see).

Cover:

• runner.Report top-level (mode, platform, device, player_id, play_ids, started_at, ended_at, variants, steps, samples, summary, abort_cycles, startup_cycles, retry_cycles)
• Step (per-step envelope used by smooth/steps/pyramid/rampup/rampdown)
• StartupCycleResult (cold-start / channel-change observations)
• AbortCycleResult (abort behavior observations)
• RetryCycleResult (persistent-fault retry observations)
• variant_activity[] (per-variant fetch tracking — playlist_fetches, segment_fetches, first/last_segment_at_s, active_duration_s, peeked_but_never_used, avg/peak_mbps)
• Summary (per-run aggregates)
• Sample (per-sample telemetry: video_resolution, network_bitrate_mbps, buffer_depth_s, etc.)

Cross-reference (don't duplicate) the per-test standards docs ([[startup-characterization-test]], [[abort-characterization-test]], [[retry-backoff-characterization-test]], [[characterization-principles]]).

Acceptance

• §6 of data-fields.md is no longer a stub; covers the shapes above with entry-per-field format.
• Bot can explain variant_activity[i].peeked_but_never_used without inferring from raw JSON.

Out of scope

• Auto-generation from Go struct tags. Tempting but the prose semantics (e.g. "first_variant_picked is the first variant playlist the player fetched — NOT the first variant whose frames actually rendered, which is variant_at_5s") are the value, and those aren't in the struct tags.

[jonathaneoliver]

Triage

• Points: 3 — pure prose, ~80 fields across runner.Report + nested types. Smaller than feat(knowledge): canonical data-fields.md — single LLM/Claude Code field reference #512 because Phase 1 established the template and per-test standards already cover some content (just need cross-cutting roll-up).
• Effort: ~half a day. Most of the work is reading the Go struct tags + per-test standards and writing prose semantics that aren't in either.
• Priority: P2. Only matters for characterization investigations. Phase 1 (feat(knowledge): canonical data-fields.md — single LLM/Claude Code field reference #512) was the broader-impact one — it covers play-level investigations which are most chats. Worth doing after feat(knowledge): canonical data-fields.md — single LLM/Claude Code field reference #512 lands and we see actual characterization-chat usage to confirm the gaps.
• Value: medium. Bot already does OK on characterization thanks to per-test standards ([[startup-characterization-test]], [[abort-characterization-test]]); this fills cross-cutting gaps (the variant_activity[] shape, the Summary aggregate) but it isn't preventing meaningful answers today.

[jonathaneoliver]

Shipped + synced to test-dev.

.claude/standards/data-fields.md §6 replaced the Phase 3 stub with full coverage of the runner.Report shape and all nested types. Same entry-per-field format + tag rollup as §1-5.

Sections added (10 subsections, ~740 lines):

• §6.a Report — top-level shape, including which mode populates which cycle array
• §6.b VariantRate — variant ladder entry (resolution, bandwidth attributes, computed cap)
• §6.c Step — per-step envelope for linear modes (buffer envelope, stalls/profile_shifts deltas, variant-tracking fields)
• §6.d Summary — run-wide aggregates (lowest_sustainable_cap, bottom_variant_floor, variant_sample_counts)
• §6.e Sample — per-second telemetry (including the variant_idx vs displayed_variant_idx leading/lagging distinction)
• §6.f StartupCycleResult — cold-start/channel-change observations (with cross-ref to [[startup-characterization-test]])
• §6.g VariantActivity — per-variant fetch tracking, including peeked_but_never_used semantics
• §6.h AbortCycleResult — server-driven abort recovery
• §6.i RetryCycleResult — persistent-fault retry observations
• §6.j URLRetryInfo — per-URL retry history with backoff intervals

Cross-references to per-test standards ([[startup-characterization-test]], [[abort-characterization-test]], [[retry-backoff-characterization-test]], [[characterization-principles]]) — each *CycleResult section explicitly says "interpretation belongs in [the per-test standard]" so this file stays as the data dictionary and per-test standards stay as the interpretation guide. No content duplication.

Total state of data-fields.md after Phase 3

• 2126 lines / 95KB on disk / ~24K tokens
• Loaded once per chat via read_standard(name="data-fields"); lands in context for the rest of the conversation
• Combined with the Anthropic prompt caching from feat(chat): Anthropic prompt caching on system prompt + tools block #511, the per-turn cost of carrying this in context drops ~90% after the first read

Acceptance criteria

• §6 covers Report + Step + StartupCycleResult + AbortCycleResult + RetryCycleResult + variant_activity + Summary + Sample with entry-per-field format
• Cross-references existing per-test standards (no duplication of interpretation)
• Sample.variant_idx vs Sample.displayed_variant_idx (leading vs lagging) distinction explicitly called out
• VariantActivity.peeked_but_never_used semantics documented
• Tag rollup at top of §6 marks [hot] / [char] / [forensics] / [debug] entries

Closing.