docs(review): document the review telemetry events

Required by the contributor checklist on this page, and the page is a user-facing
contract: it publishes what the CLI collects and what it never collects, so
adding events without listing them makes it untrue.

Also records three things that are easy to misread from the field names alone:

- `degraded` is a fidelity flag, not a warehouse flag. Confirmed end to end — a
  repo with a dbt_project.yml but no compiled manifest reports degraded=true.
- The category breakdown counts surfaced findings, after de-duplication, rubric
  exclusion and the severity threshold, grouped by category rather than by rule.
  `Finding` does not retain a rule key, so rule-level effectiveness is not
  measurable from this.
- The tool path also emits the standard `tool_call` event for the same review, so
  dashboards should count `review_run`, not both.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018SLUQF3xgZHsGZHSjxe7vb

Author: sahrizvi

docs/docs/reference/telemetry.md

@@ -47,6 +47,19 @@ We collect the following categories of events:
 | `schema_complexity` | Warehouse schema structural metrics from introspection — bucketed table, column, and schema counts plus average columns per table. No schema names or content. |
 | `validator_check` | A completion-gate validator ran on session end — validator name, `ok` boolean, step, retry count, `enforced` flag (false in shadow mode), and structured `details` (model counts, elapsed time, concurrency limit — no SQL or model content). Only emitted when `ALTIMATE_VALIDATORS_ENABLED=1` or `ALTIMATE_VALIDATORS_SHADOW=1`. See [Validators](../data-engineering/validators.md). |
 | `validator_retries_exhausted` | A session terminated with unresolved validator failures after exhausting the synthetic-retry budget — names of the failing validators (no failure body content). |
+| `review_run` | A dbt/SQL review completed or failed — `invocation` (`cli` for `altimate-code review`, `tool` for the `dbt_pr_review` tool), status, duration, and on success the verdict, the pre-gating verdict, mode, risk tier, and finding counts by severity and by category. No file paths, model or column names, finding titles or bodies, SQL, diff content, or repository/branch/PR names. |
+| `review_post_outcome` | Whether a review was published to GitHub — `not_requested`, `target_unresolved`, `full`, `partial`, or `summary_failed`, plus duration. No repository, PR, or comment content. |
+
+### Notes on the review events
+
+- `degraded` is a fidelity flag, not a warehouse flag. It is set when a review found no reviewable
+  files, had no usable manifest for the changed models, or surfaced a finding whose analysis was
+  undecidable. It does not mean "no warehouse was connected".
+- The category breakdown counts findings that were actually surfaced — after de-duplication, rubric
+  exclusion, and the severity threshold. It is not a count of raw rule detections, and it is grouped
+  by category rather than by individual rule.
+- Reviews run through the `dbt_pr_review` tool also emit the standard `tool_call` event. They are
+  the same review; count `review_run` rather than both.
 
 Each event includes a timestamp, anonymous session ID, CLI version, and an anonymous machine ID (a random UUID stored in `~/.altimate/machine-id`, generated once and never tied to any personal information).