skilldrop-cli 1.3.0 → 1.4.0

package/packs/ai-engineering/skills/ai-usage-report/scripts/build_report.py

@@ -1,453 +0,0 @@
-#!/usr/bin/env python3
-"""Build an AI usage report from a usage-event log.
-
-Reads a CSV or JSONL file of usage events and writes a markdown report.
-See ../templates/usage-event-schema.md for the input schema.
-
-Usage:
-    python3 build_report.py events.csv --view per-user --period week -o report.md
-    python3 build_report.py events.jsonl --view team-rollup --from 2026-05-01 --to 2026-05-31 -o report.md
-    python3 build_report.py events.csv --view effectiveness --period week -o report.md
-"""
-
-from __future__ import annotations
-
-import argparse
-import csv
-import json
-import math
-import sys
-from collections import Counter, defaultdict
-from datetime import datetime, timedelta, timezone
-from pathlib import Path
-from statistics import median
-
-VIEWS = ("per-user", "team-rollup", "effectiveness")
-MIN_USERS_FOR_ROLLUP = 5
-
-
-def load_events(path: Path) -> list[dict]:
-    suffix = path.suffix.lower()
-    try:
-        if suffix == ".csv":
-            with path.open(newline="", encoding="utf-8-sig") as f:
-                return list(csv.DictReader(f))
-        if suffix in (".jsonl", ".ndjson"):
-            events = []
-            with path.open(encoding="utf-8-sig") as f:
-                for n, line in enumerate(f, 1):
-                    s = line.strip()
-                    if s:
-                        try:
-                            event = json.loads(s)
-                        except ValueError as exc:
-                            raise SystemExit(f"error: {path.name} line {n} is not valid JSON ({exc.msg}); fix or remove that line")
-                        if not isinstance(event, dict):
-                            raise SystemExit(f"error: {path.name} line {n} is not a JSON object; each line must be one event object")
-                        events.append(event)
-            return events
-    except UnicodeDecodeError:
-        raise SystemExit(f"error: {path.name} is not UTF-8 text; save it as UTF-8 and re-run")
-    raise SystemExit(f"error: unsupported file type {suffix!r} (use .csv or .jsonl)")
-
-
-def parse_ts(s) -> datetime | None:
-    if not s:
-        return None
-    if isinstance(s, datetime):
-        return s if s.tzinfo else s.replace(tzinfo=timezone.utc)
-    s = str(s).strip()
-    if not s:
-        return None
-    if s.endswith("Z"):
-        s = s[:-1] + "+00:00"
-    try:
-        dt = datetime.fromisoformat(s)
-    except ValueError:
-        # Try date-only
-        try:
-            dt = datetime.fromisoformat(s + "T00:00:00+00:00")
-        except ValueError:
-            return None
-    return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
-
-
-def parse_bool(v):
-    if v is None or v == "":
-        return None
-    if isinstance(v, bool):
-        return v
-    s = str(v).strip().lower()
-    if s in ("1", "true", "yes", "y", "t"):
-        return True
-    if s in ("0", "false", "no", "n", "f"):
-        return False
-    return None
-
-
-def resolve_period(period: str, from_arg: str | None, to_arg: str | None):
-    if from_arg or to_arg:
-        if not (from_arg and to_arg):
-            raise SystemExit("error: --from and --to must be used together")
-        start = parse_ts(from_arg)
-        end = parse_ts(to_arg)
-        if start is None or end is None:
-            raise SystemExit(f"error: could not parse --from / --to dates")
-        # If user passed date-only for --to, push to end of day
-        if len(to_arg) <= 10:
-            end = end + timedelta(days=1, seconds=-1)
-        return start, end
-    now = datetime.now(timezone.utc)
-    if period == "week":
-        return now - timedelta(days=7), now
-    if period == "month":
-        return now - timedelta(days=30), now
-    raise SystemExit(f"error: unknown --period {period!r} (use week, month, or --from/--to)")
-
-
-def detect_signals(events: list[dict]) -> dict:
-    """Which optional fields are populated in the input."""
-    keys_present = set()
-    for e in events[:1000]:  # sample
-        for k, v in e.items():
-            if v not in (None, ""):
-                keys_present.add(k)
-    return {
-        "session_id": "session_id" in keys_present,
-        "output_consumed": "output_consumed" in keys_present,
-        "consumed_at": "consumed_at" in keys_present,
-        "outcome": "outcome" in keys_present,
-    }
-
-
-def filter_to_period(events: list[dict], start: datetime, end: datetime) -> list[dict]:
-    out = []
-    for e in events:
-        ts = parse_ts(e.get("timestamp"))
-        if ts and start <= ts <= end:
-            out.append({**e, "_ts": ts})
-    return out
-
-
-def aggregate(events: list[dict], signals: dict):
-    per_user = defaultdict(lambda: {
-        "invocations": 0,
-        "sessions": set(),
-        "tools": set(),
-        "session_counts": defaultdict(int),
-        "consumed_known": 0,
-        "consumed_yes": 0,
-    })
-    tool_counter: Counter = Counter()
-
-    for e in events:
-        u = e.get("user")
-        if not u:
-            continue
-        d = per_user[u]
-        d["invocations"] += 1
-        tool = e.get("tool") or "(unknown)"
-        d["tools"].add(tool)
-        tool_counter[tool] += 1
-
-        if signals["session_id"]:
-            sid = e.get("session_id")
-            if sid:
-                d["sessions"].add(sid)
-                d["session_counts"][sid] += 1
-
-        if signals["output_consumed"]:
-            b = parse_bool(e.get("output_consumed"))
-            if b is not None:
-                d["consumed_known"] += 1
-                if b:
-                    d["consumed_yes"] += 1
-
-    return per_user, tool_counter
-
-
-def fmt_pct(num, denom) -> str:
-    if not denom:
-        return "—"
-    return f"{100 * num / denom:.0f}%"
-
-
-def per_user_metrics(d: dict, signals: dict) -> dict:
-    n_sessions = len(d["sessions"]) if signals["session_id"] else None
-    avg_per_session = (d["invocations"] / n_sessions) if n_sessions else None
-    single_shot = sum(1 for c in d["session_counts"].values() if c == 1) if n_sessions else None
-    eff_rate_pct = (
-        100 * d["consumed_yes"] / d["consumed_known"]
-        if signals["output_consumed"] and d["consumed_known"]
-        else None
-    )
-    single_rate_pct = (100 * single_shot / n_sessions) if (n_sessions and single_shot is not None) else None
-    return {
-        "invocations": d["invocations"],
-        "sessions": n_sessions,
-        "avg_per_session": avg_per_session,
-        "distinct_tools": len(d["tools"]),
-        "effectiveness_rate_pct": eff_rate_pct,
-        "single_shot_rate_pct": single_rate_pct,
-    }
-
-
-def build_data_caveats_line(signals: dict) -> str:
-    missing = [k for k, v in signals.items() if not v]
-    if not missing:
-        return "**Data signals available:** all optional fields present — full report."
-    return (
-        "**Data caveats:** input is missing "
-        + ", ".join(f"`{m}`" for m in missing)
-        + " — affected metrics shown as `—`."
-    )
-
-
-def build_missing_signals_section(signals: dict) -> str:
-    lines = []
-    if not signals["session_id"]:
-        lines.append("- `session_id` absent → **session count, avg/session, and single-shot rate** could not be computed.")
-    if not signals["output_consumed"]:
-        lines.append("- `output_consumed` absent → **effectiveness rate** could not be computed.")
-    if not signals["consumed_at"]:
-        lines.append("- `consumed_at` absent → **output-to-shipped lag** could not be computed.")
-    if not signals["outcome"]:
-        lines.append("- `outcome` absent → cannot filter out errored invocations; raw counts include errors.")
-    if not lines:
-        return "All optional signals were present; the report contains all available columns."
-    return "\n".join(lines)
-
-
-def load_template(name: str, script_dir: Path) -> str:
-    p = script_dir.parent / "templates" / name
-    if not p.exists():
-        raise SystemExit(f"error: template not found: {p}")
-    return p.read_text(encoding="utf-8")
-
-
-# --------------------------------------------------------------------- views
-
-
-def render_per_user(per_user, tool_counter, signals, ctx, sort_for_effectiveness=False):
-    template = load_template(
-        "report-per-user.md" if not sort_for_effectiveness else "report-per-user.md",
-        ctx["script_dir"],
-    )
-
-    metrics_by_user = {u: per_user_metrics(d, signals) for u, d in per_user.items()}
-
-    if sort_for_effectiveness:
-        # Highest single-shot rate first (most theatrical pattern); tie-break by lowest effectiveness
-        def key(u):
-            m = metrics_by_user[u]
-            ss = m["single_shot_rate_pct"] if m["single_shot_rate_pct"] is not None else -1
-            er = m["effectiveness_rate_pct"] if m["effectiveness_rate_pct"] is not None else 101
-            return (-ss, er)
-        users_sorted = sorted(metrics_by_user.keys(), key=key)
-    else:
-        users_sorted = sorted(metrics_by_user.keys())
-
-    rows = []
-    for u in users_sorted:
-        m = metrics_by_user[u]
-        sessions_str = str(m["sessions"]) if m["sessions"] is not None else "—"
-        avg_str = f"{m['avg_per_session']:.1f}" if m["avg_per_session"] is not None else "—"
-        eff_str = f"{m['effectiveness_rate_pct']:.0f}%" if m["effectiveness_rate_pct"] is not None else "—"
-        ss_str = f"{m['single_shot_rate_pct']:.0f}%" if m["single_shot_rate_pct"] is not None else "—"
-        rows.append(
-            f"| {u} | {m['invocations']} | {sessions_str} | {avg_str} | "
-            f"{m['distinct_tools']} | {eff_str} | {ss_str} |"
-        )
-
-    total_invocations = sum(tool_counter.values())
-    top_tools_rows = "\n".join(
-        f"| {t} | {c} | {100 * c / total_invocations:.0f}% |"
-        for t, c in tool_counter.most_common(10)
-    )
-
-    return template.format(
-        team_name=ctx["team_name"],
-        start_date=ctx["start"].date().isoformat(),
-        end_date=ctx["end"].date().isoformat(),
-        n_days=ctx["n_days"],
-        n_users=len(per_user),
-        n_invocations=total_invocations,
-        n_distinct_tools=len(tool_counter),
-        data_caveats_line=ctx["caveats_line"],
-        per_user_rows="\n".join(rows),
-        top_tools_rows=top_tools_rows,
-        missing_signals_section=ctx["missing_section"],
-        generated_at=ctx["generated_at"],
-        input_file=ctx["input_file"],
-    )
-
-
-def render_team_rollup(per_user, tool_counter, signals, ctx):
-    if len(per_user) < MIN_USERS_FOR_ROLLUP:
-        raise SystemExit(
-            f"error: team-rollup requires ≥{MIN_USERS_FOR_ROLLUP} users in scope; "
-            f"got {len(per_user)}. Aggregate views aren't anonymous at that size. "
-            f"Use --view per-user and treat the output as identifying."
-        )
-
-    template = load_template("report-team-rollup.md", ctx["script_dir"])
-    n_days = max(1, ctx["n_days"])
-
-    invocations_per_user_per_day = [
-        d["invocations"] / n_days for d in per_user.values()
-    ]
-    distinct_tools_per_user = [len(d["tools"]) for d in per_user.values()]
-
-    # Effectiveness (team avg, weighted by known events)
-    total_known = sum(d["consumed_known"] for d in per_user.values())
-    total_yes = sum(d["consumed_yes"] for d in per_user.values())
-    team_eff = (
-        f"{100 * total_yes / total_known:.0f}%"
-        if signals["output_consumed"] and total_known
-        else "—"
-    )
-
-    # Single-shot (team avg, weighted by sessions)
-    total_sessions = sum(len(d["sessions"]) for d in per_user.values())
-    total_single_shot = sum(
-        sum(1 for c in d["session_counts"].values() if c == 1)
-        for d in per_user.values()
-    )
-    team_ss = (
-        f"{100 * total_single_shot / total_sessions:.0f}%"
-        if signals["session_id"] and total_sessions
-        else "—"
-    )
-
-    # Engagement tiers (normalized to weekly thresholds)
-    week_scale = 7 / n_days
-    tiers = {"heavy": 0, "moderate": 0, "light": 0, "inactive": 0}
-    for d in per_user.values():
-        weekly = d["invocations"] * week_scale
-        if weekly == 0:
-            tiers["inactive"] += 1
-        elif weekly > 20:
-            tiers["heavy"] += 1
-        elif weekly >= 5:
-            tiers["moderate"] += 1
-        else:
-            tiers["light"] += 1
-
-    n_active = sum(1 for d in per_user.values() if d["invocations"] > 0)
-
-    if signals["output_consumed"] and total_known:
-        eff_block = (
-            f"Team-wide, **{100 * total_yes / total_known:.0f}%** of invocations "
-            f"with a known outcome had their output consumed in a shipped artifact "
-            f"({total_yes:,} of {total_known:,}). The remaining "
-            f"{total_known - total_yes:,} invocations produced output that was either "
-            f"discarded, never reviewed, or not yet tracked as consumed."
-        )
-    else:
-        eff_block = (
-            "**Effectiveness signal is unavailable** — the input lacks `output_consumed` "
-            "data. Volume and engagement-tier metrics above are still valid, but the "
-            "performative-vs-effective distinction cannot be computed from this input."
-        )
-
-    total_invocations = sum(tool_counter.values())
-    top_tools_rows = "\n".join(
-        f"| {t} | {c} | {100 * c / total_invocations:.0f}% |"
-        for t, c in tool_counter.most_common(10)
-    )
-
-    return template.format(
-        team_name=ctx["team_name"],
-        start_date=ctx["start"].date().isoformat(),
-        end_date=ctx["end"].date().isoformat(),
-        n_days=n_days,
-        n_users=len(per_user),
-        n_invocations=total_invocations,
-        data_caveats_line=ctx["caveats_line"],
-        median_invocations_per_user_per_day=f"{median(invocations_per_user_per_day):.1f}" if invocations_per_user_per_day else "0",
-        median_distinct_tools_per_user=f"{median(distinct_tools_per_user):.0f}" if distinct_tools_per_user else "0",
-        team_effectiveness_rate=team_eff,
-        team_single_shot_rate=team_ss,
-        n_active_users=n_active,
-        n_heavy=tiers["heavy"],
-        n_moderate=tiers["moderate"],
-        n_light=tiers["light"],
-        n_inactive=tiers["inactive"],
-        top_tools_rows=top_tools_rows,
-        effectiveness_block=eff_block,
-        missing_signals_section=ctx["missing_section"],
-        generated_at=ctx["generated_at"],
-        input_file=ctx["input_file"],
-    )
-
-
-# --------------------------------------------------------------------- driver
-
-
-def main(argv) -> int:
-    ap = argparse.ArgumentParser(
-        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
-    )
-    ap.add_argument("input", help="Path to events file (.csv or .jsonl)")
-    ap.add_argument("--view", choices=VIEWS, default="per-user")
-    ap.add_argument("--period", choices=("week", "month"), default="week")
-    ap.add_argument("--from", dest="from_arg", default=None, help="ISO date — overrides --period")
-    ap.add_argument("--to", dest="to_arg", default=None, help="ISO date — overrides --period")
-    ap.add_argument("--team-name", default="Team")
-    ap.add_argument("-o", "--out", default=None, help="Output markdown path")
-    args = ap.parse_args(argv)
-
-    input_path = Path(args.input).expanduser().resolve()
-    if not input_path.exists():
-        sys.stderr.write(f"error: input file not found: {input_path}\n")
-        return 1
-
-    events = load_events(input_path)
-    if not events:
-        sys.stderr.write("error: input file has no events\n")
-        return 1
-    missing = [k for k in ("timestamp", "user", "tool") if not any(k in e for e in events)]
-    if missing:
-        sys.stderr.write(f"error: input is missing required field(s): {', '.join(missing)} "
-                         f"(see templates/usage-event-schema.md)\n")
-        return 1
-
-    signals = detect_signals(events)
-    start, end = resolve_period(args.period, args.from_arg, args.to_arg)
-    events = filter_to_period(events, start, end)
-    if not events:
-        sys.stderr.write(f"error: no events fell within {start.isoformat()} → {end.isoformat()}\n")
-        return 1
-
-    per_user, tool_counter = aggregate(events, signals)
-
-    script_dir = Path(__file__).resolve().parent
-    ctx = {
-        "team_name": args.team_name,
-        "start": start,
-        "end": end,
-        # a partial day counts, so a date-only --to (pushed to 23:59:59) covers its whole day
-        "n_days": math.ceil((end - start).total_seconds() / 86400),
-        "caveats_line": build_data_caveats_line(signals),
-        "missing_section": build_missing_signals_section(signals),
-        "generated_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
-        "input_file": str(input_path.name),
-        "script_dir": script_dir,
-    }
-
-    if args.view == "per-user":
-        out = render_per_user(per_user, tool_counter, signals, ctx)
-    elif args.view == "effectiveness":
-        out = render_per_user(per_user, tool_counter, signals, ctx, sort_for_effectiveness=True)
-    else:  # team-rollup
-        out = render_team_rollup(per_user, tool_counter, signals, ctx)
-
-    out_path = Path(args.out).expanduser().resolve() if args.out else input_path.with_suffix(".report.md")
-    out_path.parent.mkdir(parents=True, exist_ok=True)
-    out_path.write_text(out, encoding="utf-8")
-    print(f"wrote {out_path} ({len(events)} events, {len(per_user)} users, view={args.view})")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main(sys.argv[1:]))

package/packs/ai-engineering/skills/ai-usage-report/templates/report-per-user.md

@@ -1,42 +0,0 @@
-# AI Usage Report — {team_name}
-
-**Period:** {start_date} → {end_date} ({n_days} days)
-**Users in scope:** {n_users}
-**Total invocations:** {n_invocations}
-**Distinct tools / skills observed:** {n_distinct_tools}
-
-> {data_caveats_line}
-
-## Per-user breakdown
-
-| User | Invocations | Sessions | Avg / session | Distinct tools | Effectiveness rate | Single-shot rate |
-|---|---:|---:|---:|---:|---:|---:|
-{per_user_rows}
-
-**Reading the table:**
-- *Effectiveness rate* — % of this user's invocations whose output was consumed in a shipped artifact. `—` means the input lacked the `output_consumed` field.
-- *Single-shot rate* — % of this user's sessions with exactly one invocation. `—` means the input lacked `session_id`.
-- *High single-shot + low effectiveness* is a starting place to ask about engagement — not a verdict.
-
-## Top tools / skills used (across team)
-
-| Tool | Invocations | % of total |
-|---|---:|---:|
-{top_tools_rows}
-
-## Where signals are missing
-
-{missing_signals_section}
-
-## How to read this report
-
-This report shows **patterns**, not verdicts. A user with a low effectiveness rate may be:
-
-- Exploring (high volume of throwaway prompts while learning a tool)
-- Solving in one shot (one prompt is enough — no follow-up needed)
-- Doing AI theater (invoking to be seen invoking)
-
-The data alone cannot distinguish these. Use the report to surface conversations, not to grade individuals.
-
----
-*Generated by `ai-usage-report` on {generated_at}. Input file: `{input_file}`. View: `per-user`.*

package/packs/ai-engineering/skills/ai-usage-report/templates/report-team-rollup.md

@@ -1,49 +0,0 @@
-# AI Usage Rollup — {team_name}
-
-**Period:** {start_date} → {end_date} ({n_days} days)
-**Team size in scope:** {n_users} users
-**Total invocations:** {n_invocations}
-
-> {data_caveats_line}
-
-This is an **aggregate** view. No individuals are named. If you need a per-user breakdown for a 1:1 or coaching conversation, switch to the `per-user` view — but read the privacy note at the bottom first.
-
-## Headline metrics
-
-| Metric | Value |
-|---|---:|
-| Invocations / user / day (median) | {median_invocations_per_user_per_day} |
-| Distinct tools per user (median) | {median_distinct_tools_per_user} |
-| Effectiveness rate (team avg) | {team_effectiveness_rate} |
-| Single-shot session rate (team avg) | {team_single_shot_rate} |
-| Active users (≥1 invocation in period) | {n_active_users} of {n_users} |
-
-## Adoption distribution
-
-| Engagement tier | Users | What it means |
-|---|---:|---|
-| **Heavy** (>20 invocations/week) | {n_heavy} | Deep adopters; check whether their effectiveness rate is also high |
-| **Moderate** (5–20 / week) | {n_moderate} | The healthy middle |
-| **Light** (1–4 / week) | {n_light} | Sampling but not embedded; surface tool-fit conversations |
-| **Inactive** (0 / week) | {n_inactive} | No usage; check whether tool access is the blocker |
-
-## Top tools / skills (team-wide)
-
-| Tool | Invocations | % of total |
-|---|---:|---:|
-{top_tools_rows}
-
-## Effectiveness signal (if available)
-
-{effectiveness_block}
-
-## Where signals are missing
-
-{missing_signals_section}
-
-## Privacy posture
-
-This view is safe to share with audiences who should not see individual usage data (skip-level meetings, broad team reviews, exec rollups). The headline metrics and tier counts cannot be reverse-engineered to identify individuals **as long as `n_users` ≥ 5**. If your team has fewer than 5 users in scope, the script will refuse to generate this view — switch to `per-user` and treat it accordingly.
-
----
-*Generated by `ai-usage-report` on {generated_at}. Input file: `{input_file}`. View: `team-rollup`.*

package/packs/ai-engineering/skills/ai-usage-report/templates/usage-event-schema.md

@@ -1,76 +0,0 @@
-# usage-event-schema
-
-Input to `ai-usage-report` is a CSV or JSONL file. Each row / each JSON object is one **usage event** — a single invocation of an AI tool or skill by a single user.
-
-## Required fields
-
-| Field | Type | Notes |
-|---|---|---|
-| `timestamp` | ISO 8601 datetime | e.g. `2026-05-21T14:32:11Z` |
-| `user` | string | Stable identifier — email, handle, or employee ID. Use the same value for the same person across events. |
-| `tool` | string | What was invoked — e.g. `claude-code`, `cursor`, `copilot`, or a specific skill name like `slide-outliner` |
-
-If any of these three is missing, the script exits with an error. They are the minimum needed to compute a volume report.
-
-## Optional but recommended fields
-
-| Field | Type | Used for |
-|---|---|---|
-| `session_id` | string | Groups events into sessions. Needed for **session depth** and **single-shot rate**. |
-| `output_consumed` | bool / `0` / `1` / `true` / `false` | Whether the AI output ended up in a shipped artifact. Needed for **effectiveness rate**. |
-| `consumed_at` | ISO 8601 datetime | When the output landed in the shipped artifact. Needed for **output-to-shipped lag**. |
-| `output_size` | int | Tokens or characters of AI output |
-| `prompt_size` | int | Tokens or characters of the user prompt (do **not** include the prompt text itself — see privacy note below) |
-| `outcome` | enum: `success` / `error` / `cancelled` | Filter for errors that distort volume |
-
-## Fields the skill explicitly does NOT want
-
-- ❌ **The prompt text.** Prompts contain code, customer data, and personal context. The skill works from metadata only.
-- ❌ **The output text.** Same reason.
-- ❌ **Free-form user notes** about their session. Redact before passing to the skill.
-
-If your telemetry source captures these, drop them at export time — not after the report is generated.
-
-## Graceful degradation
-
-The script reads what's there and labels missing-signal columns explicitly. The signal-to-field mapping:
-
-| If your input has… | …the report can show |
-|---|---|
-| Just the 3 required fields | Volume + breadth |
-| `+ session_id` | …and session depth + single-shot rate |
-| `+ output_consumed` | …and effectiveness rate + AI-theater flag column |
-| `+ consumed_at` | …and output-to-shipped lag |
-| `+ outcome` | …and an error-filtered version of every metric |
-
-When a column is omitted, the report includes a *"Where signals are missing"* section listing exactly which optional fields were absent and which metrics consequently couldn't be computed. This is the contract: the report never lies about what it knows.
-
-## Example: CSV
-
-```csv
-timestamp,user,tool,session_id,output_consumed,consumed_at,outcome
-2026-05-21T09:14:23Z,alice@acme.example,claude-code,sess-001,1,2026-05-21T11:02:00Z,success
-2026-05-21T09:14:55Z,alice@acme.example,claude-code,sess-001,1,2026-05-21T11:02:00Z,success
-2026-05-21T09:18:02Z,alice@acme.example,slide-outliner,sess-001,1,2026-05-21T14:30:00Z,success
-2026-05-21T10:01:11Z,bob@acme.example,cursor,sess-014,0,,success
-2026-05-21T10:01:30Z,bob@acme.example,cursor,sess-014,0,,success
-2026-05-21T14:22:08Z,carol@acme.example,claude-code,sess-029,1,2026-05-22T08:11:00Z,success
-```
-
-## Example: JSONL
-
-```jsonl
-{"timestamp": "2026-05-21T09:14:23Z", "user": "alice@acme.example", "tool": "claude-code", "session_id": "sess-001", "output_consumed": true, "outcome": "success"}
-{"timestamp": "2026-05-21T09:14:55Z", "user": "alice@acme.example", "tool": "claude-code", "session_id": "sess-001", "output_consumed": true, "outcome": "success"}
-{"timestamp": "2026-05-21T10:01:11Z", "user": "bob@acme.example", "tool": "cursor", "session_id": "sess-014", "output_consumed": false, "outcome": "success"}
-```
-
-## A note on the `output_consumed` signal
-
-This is the field that matters most for the effective-vs-performative distinction. It's also the hardest one to populate accurately. Three common implementations, ranked by signal quality:
-
-1. **Diff-based attribution** (best): the telemetry source tracks whether AI output text appears (or fuzzy-matches) in a subsequent commit / PR / doc within N hours. High signal, hard to game.
-2. **Explicit accept/reject events** (good): the IDE emits "user accepted the suggestion" vs "user rejected it." Medium signal — accepting and then immediately deleting still counts as consumed.
-3. **Self-reported** (weakest): the user checks a box "did you use this?" Low signal — captures intent but easy to game and high reporting burden.
-
-If your telemetry source uses (3), don't pretend the resulting effectiveness rate is more reliable than it is. The report can still be useful for spotting outliers, but the numbers should be read with that grain of salt.