Code Review Sources & Telemetry

Summary

Reviewer agents ground their findings in the Zeeq knowledge base. During a review each agent calls the document search tools (search_sections, search_code_snippets, search_documents) and reads documents by path (read_document_by_path). Zeeq captures which documents and snippets those calls surfaced, aggregates them per review, and stores a compact record alongside the review.

This "source telemetry" answers two questions: what guidance shaped this review, and where are the content gaps the knowledge base did not cover.

What Is Captured

For each completed (or failed) review, the snapshot records:

• Documents — each knowledge-base document a reviewer consulted, with its library, path, and title as of review time, a hit count, the distinct usages observed (searched, read), and the reviewer facets that surfaced it.
• Snippets — the individual sections and code samples surfaced within each document, with their heading, kind (section or code sample), fence language for code samples, hit count, and the queries that surfaced them.
• Tool usage — per-tool call, success, and failure counts across all search and read tools used during the review.
• Content gaps — searches that returned nothing. These "missed queries" are the actionable signal: they show where reviewers looked for guidance that the knowledge base did not provide.

Capture never affects the review itself. If telemetry collection or serialization fails, the review still completes and simply stores no (or partial) telemetry.

How Importance Is Derived

Documents and snippets are ordered by importance so the most influential guidance appears first, without any manual ranking:

• Hit count is the primary signal — how many search or read hits surfaced the document or snippet during the review.
• Best rank is the strongest (lowest, 1-based) position the item reached across any search. A best rank of 1 marks a "top hit"; the UI badges these.
• Read after search flags a document that a reviewer searched for and later opened in full, a strong relevance proxy.

The server applies these orderings before storing the snapshot, so every surface (comment, UI, analytics) sees the same importance order.

Where It Appears

The same captured snapshot is surfaced in three places:

• Pull request comment — a collapsed "Documents consulted" section is appended to the review comment, listing the documents, snippet headings, tool usage, and content gaps.
• Review UI — opening a review in the app shows a Sources consulted panel below the findings tabs. Documents are ranked by importance and expand to their snippets; content gaps and tool usage are shown alongside. The panel renders for every review that consulted the knowledge base, including clean reviews with no findings — a clean review that consulted guidance still shows what it read.
• Offline analytics — the stored payload is the durable input for asynchronous ETL that projects organization-wide "which documents matter" datasets. The live record is for display and durable capture; aggregation runs offline rather than as cross-partition queries on the hot table.

Point-in-Time Semantics

The snapshot is a record of a specific review run:

• Document paths, titles, and snippet headings are captured as of review time. If a document is later renamed or re-titled, the stored telemetry keeps the values the reviewer actually saw.
• Stable document and snippet ids are captured so analytics can join a source across document revisions, while the display fields remain point-in-time.
• Queries and facets reflect exactly what the reviewer agents asked for during that run.

Storage and API Shape

The snapshot is stored as compact JSON in the source_telemetry_payload column on the review record. The stored keys are deliberately short to keep the repeated nested arrays small, and the payload carries a schema version so the shape can evolve without breaking stored rows.

The public API never exposes the compact storage keys. The findings endpoint projects the payload into a readable DTO with full field names, so a change to the storage schema version is not an API break. List responses carry only a lightweight hasSourceTelemetry hint; the full payload is fetched with the review findings on demand.