docs: compress CLAUDE.md + ticket 0002 diagnosis + cross-refs

CLAUDE.md "Audio jitter buffering" section was the longest in the file
(~70 lines of restated rules). Collapse to a 5-rule list with pointers
to memory + tickets for the deep dives. The old structure restated
content that already lived in feedback_audio_jitter_buffer_strategy
and the per-defect tickets.

Telemetry + tickets sections compressed similarly. Same content,
fewer words, plus explicit pointers so a future session knows where
to look for the canonical version of each rule.

Ticket 0001 grows a Cross-references section pointing back to
CLAUDE.md + memory + the pinning test.

Ticket 0002 (firefox camera) updated with the signal-log diagnosis:
every attempt shows "The request is not allowed by the user agent or
the platform in the current context." = NotAllowedError fired
instantly, no permission prompt. Conclusion: firefox has a remembered
"Block" for the origin. picked.cam= is empty so it isn't the saved-
deviceId case. Lays out two prongs: user-side permission reset
(immediate) and code-side NotAllowedError handling (next pass) so the
page surfaces a user-friendly notice instead of just logging the error
text. Cross-refs to CLAUDE.md telemetry section + the catch site.

docs/tickets/README.md gets a "See also: CLAUDE.md" pointer up top so
the loop closes from the ticket index back to the shared context.

Memory side wired bidirectionally: chromium-decoder-anchor and
audio-jitter-buffer-strategy now point at CLAUDE.md + ticket 0001.

2026-06-07 20:19:33 -04:00

2.8 KiB

Raw Permalink Blame History

Tickets

Defect tracker for zebra-report. Anything that takes more than 15 minutes or needs to be reproduced across browsers, devices, or sessions lives here as a numbered markdown file.

See also: ../../CLAUDE.md "Audio pipeline — load-bearing invariants" and "Telemetry — signal-server CLIENT_LOG" for the shared context every ticket here references.

File format

Each ticket is docs/tickets/NNNN-slug.md where NNNN is monotonically increasing. New tickets get the next number.

# NNNN: Short title

**Status:** open | in-progress | blocked | fixed | won't-fix
**Priority:** P0 (silent regression / data loss) | High | Medium | Low
**Surface:** browser / OS / role (e.g. "fedora chrome listener")
**First seen:** YYYY-MM-DD (reporter's local date)
**Reporter:** handle

## Symptom
What the user sees. Plain language, no implementation details.

## Telemetry / Repro
What the signal log / browser console / pcap shows. Concrete lines if
available. How to reproduce.

## Hypothesis
What we think is going on. List candidates if not yet narrowed.

## Fix
What was tried, what landed, what commit. Empty until something ships.

## Status notes
Running log of attempts, observations, retests. Newest at the top.

Priority

P0 — silent regression: the app appears to work but doesn't (no error surfaced, audio routes nowhere, video goes black). Trust-eroding because the user can't tell what's wrong.
High — feature unavailable (can't share camera, can't enter room). Visible error or empty state.
Medium — degraded UX with workaround (slight latency, wrong tile order).
Low — cosmetic, log noise, tooling.

How tickets are resolved

Reproduce or grab telemetry from the signal-server log (/var/log/zebra-spaces-signal.log — grep CLIENT_LOG + the reporter's handle).
Write a failing test in test/ that pins the contract the defect violates. The test failing IS the diagnosis.
Fix the code so the test passes. Commit with the test name in the message body.
make stamp, push both zebra-report and the deploy repo (www.unturf.com/zebra-report/).
Update the ticket Status to fixed, link the commit, note what to re-test in production.

Open

#	Title	Priority	Surface	Status
0002	fedora firefox cannot share camera	High	fedora firefox (speaker/host)	open

Fixed

#	Title	Fix
0001	fedora chrome cannot hear speakers (P0)	Hidden muted `<audio>` decoder-anchor alongside MediaStreamSource (`dad697d` / deploy `1f27b89`). Plus en-route improvements: always-SFU receive, 0.7s cushion, audioCtx sinkId re-apply, session-fingerprint + mesh.recv telemetry.

2.8 KiB Raw Permalink Blame History