critic-instrumentation

name	critic-instrumentation
description	Critic that ensures every behavior carries an analytics event and that success metrics map to a fireable event. The keystone for post-launch verification. Invoked by contract-verify.

Instrumentation coverage critic

Protocol: Follow reference/CRITIC-RULES.md (the compact runtime rules) at the plugin root for severity definitions (the closed enum blocker/warning/info), the output JSON schema, ID prefixes, and shared anti-patterns. This skill defines only WHAT to look for. Do not invent severities like "high"/"medium" — the validator rejects them. Do not re-check anything the deterministic validator (scripts/validate.mjs) already covers; add the judgment layer on top.

The single most important critic. If this doesn't pass, the post-launch report cannot run, and you can't say whether the feature landed.

What to check

1. Every behavior has a measurement plan

Each ### B<N> block must declare ONE of the following — the plan for how this behavior will be measured post-launch:

# Option A: Client-side analytics event (preferred when project has
# Firebase Analytics, Amplitude, etc.)
- instrumentation:
    source: firebase-analytics       # or amplitude / segment
    eventName: snake_case_name
    properties: [prop_a, prop_b]
    expectedRatePerDay: <integer>

# Option B: Server-side structured log event (when no client analytics)
- instrumentation:
    source: server-log
    logger: "audit"                   # logger name / channel
    eventName: snake_case_name
    fields: [user_id, action, ...]
    expectedRatePerDay: <integer>

# Option C: Database-derived metric (for record-count behaviors)
- instrumentation:
    source: database
    dbQuery: "SELECT count(*) FROM payment_methods WHERE created_at > NOW() - INTERVAL '1 day'"
    expectedRatePerDay: <integer>

# Option D: Sentry release adoption (for "no regression" metrics)
- instrumentation:
    source: sentry-release
    releaseTag: <release-id>
    metric: error_rate | adoption_pct | p95_latency
    target: < 0.5%                    # or whatever budget

# Option E: Manual reporting (lowest-quality fallback)
- instrumentation:
    source: manual
    rationale: "No measurement infra; PM reports weekly in Slack thread"
    cadence: weekly

If missing → blocker with suggestion. The suggestion should default to the source the project actually has — read the project's .manifest/repos.yml to learn what's connected. Don't propose Firebase Analytics if the project doesn't use it.

The measurement plan is what the launch-report reads to know how to verify the feature post-launch. Manual reporting is acceptable but lower-quality — the launch report will note that the verdict is based on manual input.

2. Every success metric maps to a real eventName

Each entry in ## Success metrics must reference an eventName that exists in at least one behavior's instrumentation. Cross-reference and flag any orphan metrics.

3. The event isn't already in use for something else

If you have access to the repository, grep for the proposed eventName across the codebase. If it already exists with different semantics, flag it as a blocker — the team must rename or reuse intentionally.

# Example grep patterns (via Bash tool):
rg "track\(['\"]<eventName>" --type ts --type js
rg "logEvent\(['\"]<eventName>" --type swift --type kotlin
rg "amplitude\.logEvent\(['\"]<eventName>"

4. Properties follow conventions

• All snake_case.
• Required identity property if user-scoped (user_id should be auto-set by the SDK; don't ask the behavior to set it).
• For revenue / conversion events, include amount and currency.

5. Expected rate is reasonable

If expectedRatePerDay is unrealistically high or low relative to the product's traffic (use Amplitude/Firebase Analytics MCP to ballpark current event volumes if available), warn.

Severity

• blocker — missing instrumentation on a behavior, or success metric with no matching event.
• warning — naming collision, non-conformant properties, missing identity property.
• info — naming style nits, suggested additional properties.

Output

Same JSON array shape as other critics.

Why this critic is special

The orchestrator (contract-verify) treats every blocker from this critic as a hard gate. A contract cannot reach verified without instrumentation on every behavior. This is intentional — it forces the discipline that makes post-launch verification possible.