Incident Trend Analyzer

Incident Trend Analyzer

On-demand analysis of historical postmortems from docs/postmortems/. Reads canonical postmortems produced by the incident-analysis skill, extracts normalized incident records, surfaces recurrence patterns, trigger distributions, and timing metrics. Terminal-first output with optional persistence on request.

Step 1: Scan Corpus

If docs/postmortems/ does not exist, report: "No postmortem corpus found. Expected directory: docs/postmortems/. Run incident-analysis to generate postmortems first." and stop.

Read docs/postmortems/*.md — NON-RECURSIVE. Do NOT descend into subdirectories (e.g., docs/postmortems/trends/). Filter to filenames matching YYYY-MM-DD-*.md. Report total files found.

Minimum corpus: 3 recurrence-eligible postmortems. If fewer than 3 qualify after Step 2, stop the entire analysis and report:

Not enough data for trend analysis.
Found N file(s) in docs/postmortems/:
  - <filename> (eligible: yes/no — reason)
Minimum required: 3 recurrence-eligible postmortems.

No partial metrics are reported below this threshold.

Step 2: Parse and Classify Eligibility

For each file matching YYYY-MM-DD-*.md, extract the date from the filename and extract raw section text by heading boundaries. Match sections by heading text, not ordinal position — e.g., any ## N. Summary or ## Summary heading matches "Summary" regardless of its number.

This supports both the canonical 8-section schema (Summary, Impact, Action Items, Root Cause & Trigger, Timeline, Contributing Factors, Lessons Learned, Investigation Notes) and legacy 7-section postmortems (where Timeline was section 3 and Action Items was section 7).

Classify into eligibility tiers:

Parseable timestamps: Absolute only. Accepted formats:

• ISO 8601: 2026-03-15T10:32:00Z
• HH:MM or HH:MM:SS with date inferred from the filename
• YYYY-MM-DD HH:MM

Relative timestamps ("5 minutes later", "+10m") are NOT parseable. They produce low timing confidence and are excluded from MTTR/MTTD computation.

Unparseable files: Listed in coverage report, excluded from analysis. No fuzzy parsing.

Step 3: Build Normalized Incident Records

For each recurrence-eligible postmortem, build one normalized record with these fields. Failure mode and trigger category are extracted independently from the same section text. They answer different questions: failure mode = "what broke" (the symptom), trigger category = "what caused it" (the change type). The same signal words may match in both vocabularies; this is expected and correct. Signal pattern matching is case-insensitive.

Service Extraction (from Summary)

Failure Mode (from Root Cause & Trigger)

Match signal patterns in the Root Cause & Trigger section text against this vocabulary:

Confidence: high (2+ signal words match one key), medium (1 signal word), low → unknown.

Group on vocabulary key only. Show raw Root Cause text as evidence, never as grouping key. Wording differences must not fragment groups.

Trigger Category (from Root Cause & Trigger)

Match signal patterns in the Root Cause & Trigger section text against this vocabulary:

Pick the category with the most signal words. If tied, use unknown.

Timing Extraction (from Timeline)

For timeline-eligible postmortems only. Extract these timestamps from the Timeline section rows (matched by heading text, not position):

timing_confidence: high (3/3 timestamps found), medium (2/3), low (0–1). If a timestamp cannot be identified deterministically, the incident is excluded from the relevant metric and noted in coverage.

Full Record Schema

Step 4: Compute Metrics

Recurrence Grouping

• Group by (service, failure_mode) — both from vocabulary keys, not free text
• Minimum group size for recurrence: 2
• Per cluster, show dominant trigger_category as annotation (NOT part of grouping key)
• Sort by count descending
• unknown-service / unknown failure_mode clusters are excluded from headline recurrence output. They appear in a separate Uncategorized section to avoid surfacing false patterns.

Trigger Distribution

• Count each trigger_category across all recurrence-eligible incidents
• Show count and percentage
• Sort descending by count

MTTR (Mean Time to Recovery)

• Formula: recovered_at - detected_at
• Both timestamps require timing_confidence >= medium
• Report: median (headline), mean, range
• Show eligible count vs total recurrence-eligible

MTTD (Mean Time to Detection)

• Formula: detected_at - incident_start
• Both timestamps require timing_confidence >= medium
• Report: median (headline), mean, range
• Show eligible count vs total recurrence-eligible

Step 5: Generate Output

Terminal Summary (default)

Print this exact structure:

## Incident Trend Analysis

Corpus: N files scanned, X recurrence-eligible, Y MTTR-eligible, Z MTTD-eligible
Period: YYYY-MM-DD to YYYY-MM-DD (N days)

### Recurrence Patterns
  service / failure_mode  — N incidents (dates) | trigger: category
  ...
  N incidents showed no recurrence

### Trigger Distribution
  category  — N (PP%)
  ...

### MTTR (Y of X eligible)
  Median: Xm | Mean: Xm | Range: Xm – Xm

### MTTD (Z of X eligible)
  Median: Xm | Mean: Xm | Range: Xm – Xm

### Coverage Gaps
  (Report any metric with < 60% eligibility)

### Insights
- (2–4 cited observations)

Insights Rules

Generate 2–4 insight bullets by applying these rules:

1. Top recurrence cluster + its dominant trigger → observation
2. Dominant trigger category if > 40% of incidents → systemic observation
3. MTTD outliers > 2x median → detection gap observation
4. Coverage gaps < 60% eligible for any metric → data quality observation

Every insight bullet MUST cite the supporting count or rate (e.g., "3x in 63 days", "4/9 incidents, 44%"). Insights are observations with citations, NOT prescriptions. The skill does NOT prescribe fixes — it surfaces patterns and lets the user decide.

Step 6: Persist (on request only)

Persistence is triggered ONLY when the user explicitly requests it ("save this", "save report", "persist"). Do NOT auto-persist.

1. Create docs/postmortems/trends/ if it does not exist
2. Write to docs/postmortems/trends/YYYY-MM-DD-trend-report.md
3. If a same-day report already exists, append -2, -3, etc. (e.g., 2026-03-21-trend-report-2.md)
4. Content: full terminal summary + per-incident record table for auditability
5. No auto-commit — the user decides when to commit