edercnj/x-analyze-telemetry

Global Output Policy

• Language: English ONLY.
• Tone: Technical, Direct, and Concise.
• Efficiency: Remove all conversational fillers and greetings to save tokens.

Skill: Telemetry Analyze

Purpose

Transform the append-only NDJSON telemetry logs produced by the telemetry-*.sh hooks into an actionable report. The analysis answers two recurring operator questions:

1. Which skill/phase is the bottleneck for epic X? Per-skill and per-phase tables with total duration, average, P50, P95.
2. How does skill performance change across epics? Cross-epic comparison via --epics (tables stay aligned by epic id).

The report is written to ai/epics/epic-XXXX/reports/telemetry-report-EPIC-XXXX.md by default and follows the layout in _TEMPLATE-TELEMETRY-REPORT.md.

When to Use

• Before a retro to see where a workflow cycle spent its time.
• When a skill "feels slower" and you want evidence.
• Before a refactor to establish a baseline.

Arguments

| Argument | Behaviour | | :--- | :--- | | --epic EPIC-XXXX | Report for a single epic (tables + Gantt). | | --epics A,B,C | Cross-epic comparison report. | | --export json --out path | Write the structured JSON schema (§5.1). | | --export csv --out path | Write the tabular CSV (§5.2). | | --since YYYY-MM-DD | Drop events whose timestamp is earlier than the date. | | --by-tool | Emphasize the tool breakdown in the Markdown report. | | --base-dir path | Override plans/ (useful in tests). |

The default Markdown report lands in ai/epics/epic-XXXX/reports/ — no extra flag required.

Invocation

java -cp target/classes:target/dependency/* \
     dev.iadev.telemetry.analyze.TelemetryAnalyzeCli \
     --epic EPIC-0040

The CLI is intentionally standalone — it does NOT require the full ia-dev-env generator lifecycle. It reads the NDJSON file, aggregates, and writes exactly one output artifact.

Exit Codes

| Code | Meaning | | :--- | :--- | | 0 | Success. Malformed NDJSON lines are silently skipped (warnings go to stderr via SLF4J). | | 2 | Epic has no events.ndjson — message cites the expected path. | | 3 | Reserved for catastrophic parse failure (I/O error during the pre-flight probe). In the default append-only NDJSON mode, single malformed lines are skipped rather than aborting the run — the rationale is that telemetry is append-only and a mid-file corruption should not prevent aggregation of the remaining N-1 events. | | 4 | --export set without --out. |

Performance Contract

• 10 000 events → report in < 5 s (hard SLA, story §3.5).
• 100 000 events → report in < 30 s.

The aggregator streams events through TelemetryReader.streamSkippingInvalid() so memory stays bounded: the largest retained structure is the per-skill duration list, which holds one long per matching event.

Output

Every Markdown report contains the seven canonical sections declared in story-0040-0010 §3.2:

1. Header (epics, generated-at, total events).
2. Resumo geral (duration totals + top-5 skills/phases).
3. Por skill (invocations / total / avg / P50 / P95).
4. Por fase (same columns, keyed by skill/phase).
5. Por tool (invocations / duration per tool — Bash, Write, Edit, Skill, Agent, MCPs).
6. Mermaid Gantt timeline (capped at 50 rows).
7. Observações (outliers, truncation notes).

The JSON export follows the schema in §5.1; the CSV export follows the layout in §5.2 with RFC 4180 quoting.