Review Telemetry

---
name: review-telemetry
description: Review a telemetry plan for completeness, actionability, measurability, and consistency with the specification.
---

# Review Telemetry

Audits a telemetry plan for completeness, actionability, measurability, and consistency with the specification and requirements.

## Prerequisites

- Apply the shared SDLC conventions in `skills/sdlc/references/shared.md`.
- If no argument is provided, locate the feature directory under `.sdlc/features/` whose frontmatter `issue` field references `$ISSUE_NUMBER`.
- `.sdlc/features/N-<slug>/telemetry.md`, or a telemetry document provided in context or as a file path
- `.sdlc/features/N-<slug>/specification.md` (for cross-referencing)
- `.sdlc/features/N-<slug>/requirements.md` (optional, for cross-referencing acceptance criteria)

## Steps

1. Read the telemetry document from `.sdlc/features/N-<slug>/telemetry.md` if present, otherwise from context or as a file path.
2. Cross-reference against the specification and requirements.
3. Identify issues in each of the five categories below.
4. Report findings. Omit any category that has no findings.
5. Write the findings to `.sdlc/features/N-<slug>/review-telemetry.md` with frontmatter `artifact: telemetry`, `verdict` (`approved` if there are no blocking findings, `changes-requested` if the author must address findings, `rejected` for a fundamental flaw), and `reviewed_at: <ISO date>`, and the findings as the body, per `skills/sdlc/references/shared.md`. Record any unresolved open questions in the findings body.

## Review Checklist

### Completeness
- Does every key user flow from the specification have corresponding events?
- Does every functional requirement with user-facing behavior have at least one event or metric?
- Is every funnel rendered as a Mermaid `flowchart TD` with one node per step, and are the steps complete (no gaps between entry and desired outcome, no unreachable nodes)?
- Are counter metrics defined for features that could cause harm or degrade experience?

### Measurability
- Is every success metric tied to a concrete number, ratio, or threshold (not subjective)?
- Is the measurement method specified (how the metric is computed)?
- Are timeframes specified for each success metric?
- Can each event be reliably emitted from the identified location in the codebase?

### Actionability
- If a metric moves in the wrong direction, is it clear what action to take?
- Are alert thresholds reasonable (not too many alerts, not too few)?
- Do counter metrics have clear investigation triggers?

### Consistency
- Do event names follow the naming convention (snake_case, entity_action_status)?
- Are event properties typed and required/optional status marked?
- Do events reference entities and actions that match the specification's terminology?

### Coverage Gaps
- Are error states instrumented (not just happy paths)?
- Are background processes and async operations tracked where relevant?
- Is the telemetry infrastructure sufficient to support the defined events?
- Are dashboards and alerts specified for metrics that matter?

## Output Format

```markdown
## Completeness

<Findings or "No issues found.">

## Measurability

<Findings or "No issues found.">

## Actionability

<Findings or "No issues found.">

## Consistency

<Findings or "No issues found.">

## Coverage Gaps

<Findings or "No issues found.">
```

## Outcome

If `$OUTCOME_YAML` is set, emit your verdict there per `skills/sdlc/references/shared.md`:

| Verdict | When |
|---|---|
| `approved` | No blocking findings; the subject passes review |
| `changes-requested` | Findings the author must address before it passes |
| `rejected` | Fundamental flaw requiring rework or stopping |

In the same emission, list the findings file under `artifacts:` (`.sdlc/features/N-<slug>/review-telemetry.md`).

## Example Usage

**Scenario 1: Missing error events**
Specification defines a file upload flow with validation, upload, and processing steps.
Telemetry plan only has events for `upload_started` and `upload_completed`.
Report under Coverage Gaps: no events for upload failure, validation rejection, or processing timeout.

**Scenario 2: Vague metric**
Success metric says "users should find the feature useful."
Report under Measurability: no concrete threshold, no measurement method, no timeframe.

**Scenario 3: Naming inconsistency**
Specification calls the entity "invoice" but events use "bill" prefix.
Report under Consistency: event names should use `invoice_` not `bill_` to match specification terminology.

## Next Step

Once the findings verdict is `approved`, continue with `/create-plan`.

## Useful Commands Reference

| Command | Description |
|---|---|
| `mmdc -i <diagram.mmd>` or `npx -y @mermaid-js/mermaid-cli` | Best-effort Mermaid render check for the funnel flowcharts |