@diottodev/runic 1.0.0 → 1.1.0

package/engineering-team/skills/incident-commander/scripts/incident_timeline_builder.py

@@ -0,0 +1,742 @@
+#!/usr/bin/env python3
+"""
+Incident Timeline Builder
+
+Builds structured incident timelines with automatic phase detection, gap analysis,
+communication template generation, and response metrics calculation. Produces
+professional reports suitable for post-incident review and stakeholder briefing.
+
+Usage:
+    python incident_timeline_builder.py incident_data.json
+    python incident_timeline_builder.py incident_data.json --format json
+    python incident_timeline_builder.py incident_data.json --format markdown
+    cat incident_data.json | python incident_timeline_builder.py --format text
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime, timedelta
+from typing import Any, Dict, List, Optional, Tuple
+
+
+# ---------------------------------------------------------------------------
+# Configuration Constants
+# ---------------------------------------------------------------------------
+
+ISO_FORMAT = "%Y-%m-%dT%H:%M:%SZ"
+
+EVENT_TYPES = [
+    "detection", "declaration", "escalation", "investigation",
+    "mitigation", "communication", "resolution", "action_item",
+]
+
+SEVERITY_LEVELS = {
+    "SEV1": {"label": "Critical", "rank": 1},
+    "SEV2": {"label": "Major", "rank": 2},
+    "SEV3": {"label": "Minor", "rank": 3},
+    "SEV4": {"label": "Low", "rank": 4},
+}
+
+PHASE_DEFINITIONS = [
+    {"name": "Detection", "trigger_types": ["detection"],
+     "description": "Issue detected via monitoring, alerting, or user report."},
+    {"name": "Triage", "trigger_types": ["declaration", "escalation"],
+     "description": "Incident declared, severity assessed, commander assigned."},
+    {"name": "Investigation", "trigger_types": ["investigation"],
+     "description": "Root cause analysis and impact assessment underway."},
+    {"name": "Mitigation", "trigger_types": ["mitigation"],
+     "description": "Active work to reduce or eliminate customer impact."},
+    {"name": "Resolution", "trigger_types": ["resolution"],
+     "description": "Service restored to normal operating parameters."},
+]
+
+GAP_THRESHOLD_MINUTES = 15
+
+DECISION_EVENT_TYPES = {"escalation", "mitigation", "declaration", "resolution"}
+
+
+# ---------------------------------------------------------------------------
+# Data Model Classes
+# ---------------------------------------------------------------------------
+
+class IncidentEvent:
+    """Represents a single event in the incident timeline."""
+
+    def __init__(self, data: Dict[str, Any]):
+        self.timestamp_raw: str = data.get("timestamp", "")
+        self.timestamp: Optional[datetime] = _parse_timestamp(self.timestamp_raw)
+        self.type: str = data.get("type", "unknown").lower().strip()
+        self.actor: str = data.get("actor", "unknown")
+        self.description: str = data.get("description", "")
+        self.metadata: Dict[str, Any] = data.get("metadata", {})
+
+    def to_dict(self) -> Dict[str, Any]:
+        result: Dict[str, Any] = {
+            "timestamp": self.timestamp_raw, "type": self.type,
+            "actor": self.actor, "description": self.description,
+        }
+        if self.metadata:
+            result["metadata"] = self.metadata
+        return result
+
+    @property
+    def is_decision_point(self) -> bool:
+        return self.type in DECISION_EVENT_TYPES
+
+
+class IncidentPhase:
+    """Represents a detected phase of the incident lifecycle."""
+
+    def __init__(self, name: str, description: str):
+        self.name: str = name
+        self.description: str = description
+        self.start_time: Optional[datetime] = None
+        self.end_time: Optional[datetime] = None
+        self.events: List[IncidentEvent] = []
+
+    @property
+    def duration_minutes(self) -> Optional[float]:
+        if self.start_time and self.end_time:
+            return (self.end_time - self.start_time).total_seconds() / 60.0
+        return None
+
+    def to_dict(self) -> Dict[str, Any]:
+        dur = self.duration_minutes
+        return {
+            "name": self.name, "description": self.description,
+            "start_time": self.start_time.strftime(ISO_FORMAT) if self.start_time else None,
+            "end_time": self.end_time.strftime(ISO_FORMAT) if self.end_time else None,
+            "duration_minutes": round(dur, 1) if dur is not None else None,
+            "event_count": len(self.events),
+        }
+
+
+class CommunicationTemplate:
+    """A generated communication message for a specific audience."""
+
+    def __init__(self, template_type: str, audience: str, subject: str, body: str):
+        self.template_type = template_type
+        self.audience = audience
+        self.subject = subject
+        self.body = body
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"template_type": self.template_type, "audience": self.audience,
+                "subject": self.subject, "body": self.body}
+
+
+class TimelineGap:
+    """Represents a gap in the timeline where no events were logged."""
+
+    def __init__(self, start: datetime, end: datetime, duration_minutes: float):
+        self.start = start
+        self.end = end
+        self.duration_minutes = duration_minutes
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"start": self.start.strftime(ISO_FORMAT),
+                "end": self.end.strftime(ISO_FORMAT),
+                "duration_minutes": round(self.duration_minutes, 1)}
+
+
+class TimelineAnalysis:
+    """Holds the complete analysis result for an incident timeline."""
+
+    def __init__(self):
+        self.incident_id: str = ""
+        self.incident_title: str = ""
+        self.severity: str = ""
+        self.status: str = ""
+        self.commander: str = ""
+        self.service: str = ""
+        self.affected_services: List[str] = []
+        self.declared_at: Optional[datetime] = None
+        self.resolved_at: Optional[datetime] = None
+        self.events: List[IncidentEvent] = []
+        self.phases: List[IncidentPhase] = []
+        self.gaps: List[TimelineGap] = []
+        self.decision_points: List[IncidentEvent] = []
+        self.metrics: Dict[str, Any] = {}
+        self.communications: List[CommunicationTemplate] = []
+        self.errors: List[str] = []
+
+
+# ---------------------------------------------------------------------------
+# Timestamp Helpers
+# ---------------------------------------------------------------------------
+
+def _parse_timestamp(raw: str) -> Optional[datetime]:
+    """Parse an ISO-8601 timestamp string into a datetime object."""
+    if not raw:
+        return None
+    cleaned = raw.replace("Z", "+00:00") if raw.endswith("Z") else raw
+    try:
+        return datetime.fromisoformat(cleaned).replace(tzinfo=None)
+    except (ValueError, AttributeError):
+        pass
+    try:
+        return datetime.strptime(raw, ISO_FORMAT)
+    except ValueError:
+        return None
+
+
+def _fmt_duration(minutes: Optional[float]) -> str:
+    """Format a duration in minutes as a human-readable string."""
+    if minutes is None:
+        return "N/A"
+    if minutes < 1:
+        return f"{minutes * 60:.0f}s"
+    if minutes < 60:
+        return f"{minutes:.0f}m"
+    hours, remaining = int(minutes // 60), int(minutes % 60)
+    return f"{hours}h" if remaining == 0 else f"{hours}h {remaining}m"
+
+
+def _fmt_ts(dt: Optional[datetime]) -> str:
+    """Format a datetime as HH:MM:SS for display."""
+    return dt.strftime("%H:%M:%S") if dt else "??:??:??"
+
+
+def _sev_label(sev: str) -> str:
+    """Return the human label for a severity code."""
+    return SEVERITY_LEVELS.get(sev, {}).get("label", sev)
+
+
+# ---------------------------------------------------------------------------
+# Core Analysis Functions
+# ---------------------------------------------------------------------------
+
+def parse_incident_data(data: Dict[str, Any]) -> TimelineAnalysis:
+    """Parse raw incident JSON into a TimelineAnalysis with populated fields."""
+    a = TimelineAnalysis()
+    inc = data.get("incident", {})
+    a.incident_id = inc.get("id", "UNKNOWN")
+    a.incident_title = inc.get("title", "Untitled Incident")
+    a.severity = inc.get("severity", "UNKNOWN").upper()
+    a.status = inc.get("status", "unknown").lower()
+    a.commander = inc.get("commander", "Unassigned")
+    a.service = inc.get("service", "unknown")
+    a.affected_services = inc.get("affected_services", [])
+    a.declared_at = _parse_timestamp(inc.get("declared_at", ""))
+    a.resolved_at = _parse_timestamp(inc.get("resolved_at", ""))
+
+    raw_events = data.get("events", [])
+    if not raw_events:
+        a.errors.append("No events found in incident data.")
+        return a
+
+    for raw in raw_events:
+        event = IncidentEvent(raw)
+        if event.timestamp is None:
+            a.errors.append(f"Skipping event with unparseable timestamp: {raw.get('timestamp', '')}")
+            continue
+        a.events.append(event)
+
+    a.events.sort(key=lambda e: e.timestamp)  # type: ignore[arg-type]
+    return a
+
+
+def detect_phases(analysis: TimelineAnalysis) -> None:
+    """Detect incident lifecycle phases from the ordered event stream."""
+    if not analysis.events:
+        return
+
+    trigger_map: Dict[str, Dict[str, str]] = {}
+    for pdef in PHASE_DEFINITIONS:
+        for ttype in pdef["trigger_types"]:
+            trigger_map[ttype] = {"name": pdef["name"], "description": pdef["description"]}
+
+    phase_by_name: Dict[str, IncidentPhase] = {}
+    phase_order: List[str] = []
+    current: Optional[IncidentPhase] = None
+
+    for event in analysis.events:
+        pinfo = trigger_map.get(event.type)
+        if pinfo and pinfo["name"] not in phase_by_name:
+            if current is not None:
+                current.end_time = event.timestamp
+            phase = IncidentPhase(pinfo["name"], pinfo["description"])
+            phase.start_time = event.timestamp
+            phase_by_name[pinfo["name"]] = phase
+            phase_order.append(pinfo["name"])
+            current = phase
+        if current is not None:
+            current.events.append(event)
+
+    if current is not None:
+        current.end_time = analysis.resolved_at or analysis.events[-1].timestamp
+
+    analysis.phases = [phase_by_name[n] for n in phase_order]
+
+
+def detect_gaps(analysis: TimelineAnalysis) -> None:
+    """Identify gaps longer than GAP_THRESHOLD_MINUTES between consecutive events."""
+    for i in range(len(analysis.events) - 1):
+        ts_a, ts_b = analysis.events[i].timestamp, analysis.events[i + 1].timestamp
+        if ts_a is None or ts_b is None:
+            continue
+        delta = (ts_b - ts_a).total_seconds() / 60.0
+        if delta >= GAP_THRESHOLD_MINUTES:
+            analysis.gaps.append(TimelineGap(start=ts_a, end=ts_b, duration_minutes=delta))
+
+
+def identify_decision_points(analysis: TimelineAnalysis) -> None:
+    """Extract key decision-point events from the timeline."""
+    analysis.decision_points = [e for e in analysis.events if e.is_decision_point]
+
+
+def calculate_metrics(analysis: TimelineAnalysis) -> None:
+    """Calculate incident response metrics: MTTD, MTTR, phase durations."""
+    m: Dict[str, Any] = {}
+    det = [e for e in analysis.events if e.type == "detection"]
+    first_det = det[0].timestamp if det else None
+    first_ts = analysis.events[0].timestamp if analysis.events else None
+
+    # MTTD: first event to first detection.
+    if first_ts and first_det:
+        m["mttd_minutes"] = round((first_det - first_ts).total_seconds() / 60.0, 1)
+    else:
+        m["mttd_minutes"] = None
+
+    # MTTR: detection to resolution.
+    if first_det and analysis.resolved_at:
+        m["mttr_minutes"] = round((analysis.resolved_at - first_det).total_seconds() / 60.0, 1)
+    else:
+        m["mttr_minutes"] = None
+
+    # Total duration.
+    if analysis.declared_at and analysis.resolved_at:
+        m["total_duration_minutes"] = round(
+            (analysis.resolved_at - analysis.declared_at).total_seconds() / 60.0, 1)
+    else:
+        m["total_duration_minutes"] = None
+
+    # Phase durations.
+    m["phase_durations"] = {
+        p.name: (round(p.duration_minutes, 1) if p.duration_minutes is not None else None)
+        for p in analysis.phases
+    }
+
+    # Event counts by type.
+    tc: Dict[str, int] = {}
+    for e in analysis.events:
+        tc[e.type] = tc.get(e.type, 0) + 1
+    m["event_counts_by_type"] = tc
+
+    # Gap statistics.
+    m["gap_count"] = len(analysis.gaps)
+    if analysis.gaps:
+        gm = [g.duration_minutes for g in analysis.gaps]
+        m["longest_gap_minutes"] = round(max(gm), 1)
+        m["total_gap_minutes"] = round(sum(gm), 1)
+    else:
+        m["longest_gap_minutes"] = 0
+        m["total_gap_minutes"] = 0
+
+    m["total_events"] = len(analysis.events)
+    m["decision_point_count"] = len(analysis.decision_points)
+    m["phase_count"] = len(analysis.phases)
+    analysis.metrics = m
+
+
+# ---------------------------------------------------------------------------
+# Communication Template Generation
+# ---------------------------------------------------------------------------
+
+def generate_communications(analysis: TimelineAnalysis) -> None:
+    """Generate four communication templates based on incident data."""
+    sev, sl = analysis.severity, _sev_label(analysis.severity)
+    title, svc = analysis.incident_title, analysis.service
+    affected = ", ".join(analysis.affected_services) or "none identified"
+    cmd, iid = analysis.commander, analysis.incident_id
+    decl = analysis.declared_at.strftime("%Y-%m-%d %H:%M UTC") if analysis.declared_at else "TBD"
+    resv = analysis.resolved_at.strftime("%Y-%m-%d %H:%M UTC") if analysis.resolved_at else "TBD"
+    dur = _fmt_duration(analysis.metrics.get("total_duration_minutes"))
+    resolved = analysis.status == "resolved"
+
+    # 1 -- Initial stakeholder notification
+    analysis.communications.append(CommunicationTemplate(
+        "initial_notification", "internal", f"[{sev}] Incident Declared: {title}",
+        f"An incident has been declared for {svc}.\n\n"
+        f"Incident ID: {iid}\nSeverity: {sev} ({sl})\nCommander: {cmd}\n"
+        f"Declared at: {decl}\nAffected services: {affected}\n\n"
+        f"The incident team is actively investigating. Updates will follow.",
+    ))
+
+    # 2 -- Status page update
+    if resolved:
+        sp_subj = f"[Resolved] {title}"
+        sp_body = (f"The incident affecting {svc} has been resolved.\n\n"
+                   f"Duration: {dur}\nAll affected services ({affected}) are restored. "
+                   f"A post-incident review will be published within 48 hours.")
+    else:
+        sp_subj = f"[Investigating] {title}"
+        sp_body = (f"We are investigating degraded performance in {svc}. "
+                   f"Affected services: {affected}.\n\n"
+                   f"Our team is working to identify the root cause. Updates every 30 minutes.")
+    analysis.communications.append(CommunicationTemplate(
+        "status_page", "external", sp_subj, sp_body))
+
+    # 3 -- Executive summary
+    phase_lines = "\n".join(
+        f"  - {p.name}: {_fmt_duration(p.duration_minutes)}" for p in analysis.phases
+    ) or "  No phase data available."
+    mttd = _fmt_duration(analysis.metrics.get("mttd_minutes"))
+    mttr = _fmt_duration(analysis.metrics.get("mttr_minutes"))
+    analysis.communications.append(CommunicationTemplate(
+        "executive_summary", "executive", f"Executive Summary: {iid} - {title}",
+        f"Incident: {iid} - {title}\nSeverity: {sev} ({sl})\n"
+        f"Service: {svc}\nCommander: {cmd}\nStatus: {analysis.status.capitalize()}\n"
+        f"Declared: {decl}\nResolved: {resv}\nDuration: {dur}\n\n"
+        f"Key Metrics:\n  - MTTD: {mttd}\n  - MTTR: {mttr}\n"
+        f"  - Timeline Gaps: {analysis.metrics.get('gap_count', 0)}\n\n"
+        f"Phase Breakdown:\n{phase_lines}\n\nAffected Services: {affected}",
+    ))
+
+    # 4 -- Customer notification
+    if resolved:
+        cust_body = (f"We experienced an issue affecting {svc} starting at {decl}.\n\n"
+                     f"The issue was resolved at {resv} (duration: {dur}). "
+                     f"We apologize for any inconvenience and are reviewing to prevent recurrence.")
+    else:
+        cust_body = (f"We are experiencing an issue affecting {svc} starting at {decl}.\n\n"
+                     f"Our engineering team is actively working to resolve this. "
+                     f"We will provide updates as the situation develops. We apologize for the inconvenience.")
+    analysis.communications.append(CommunicationTemplate(
+        "customer_notification", "external", f"Service Update: {title}", cust_body))
+
+
+# ---------------------------------------------------------------------------
+# Main Analysis Orchestrator
+# ---------------------------------------------------------------------------
+
+def build_timeline(data: Dict[str, Any]) -> TimelineAnalysis:
+    """Run the full timeline analysis pipeline on raw incident data."""
+    analysis = parse_incident_data(data)
+    if analysis.errors and not analysis.events:
+        return analysis
+    detect_phases(analysis)
+    detect_gaps(analysis)
+    identify_decision_points(analysis)
+    calculate_metrics(analysis)
+    generate_communications(analysis)
+    return analysis
+
+
+# ---------------------------------------------------------------------------
+# Output Formatters
+# ---------------------------------------------------------------------------
+
+def format_text_output(analysis: TimelineAnalysis) -> str:
+    """Format the analysis as a human-readable text report."""
+    L: List[str] = []
+    w = 64
+
+    L.append("=" * w)
+    L.append("INCIDENT TIMELINE REPORT")
+    L.append("=" * w)
+    L.append("")
+
+    if analysis.errors:
+        for err in analysis.errors:
+            L.append(f"  WARNING: {err}")
+        L.append("")
+        if not analysis.events:
+            return "\n".join(L)
+
+    # Summary
+    L.append("INCIDENT SUMMARY")
+    L.append("-" * 32)
+    L.append(f"  ID:         {analysis.incident_id}")
+    L.append(f"  Title:      {analysis.incident_title}")
+    L.append(f"  Severity:   {analysis.severity}")
+    L.append(f"  Status:     {analysis.status.capitalize()}")
+    L.append(f"  Commander:  {analysis.commander}")
+    L.append(f"  Service:    {analysis.service}")
+    if analysis.affected_services:
+        L.append(f"  Affected:   {', '.join(analysis.affected_services)}")
+    L.append(f"  Duration:   {_fmt_duration(analysis.metrics.get('total_duration_minutes'))}")
+    L.append("")
+
+    # Key metrics
+    L.append("KEY METRICS")
+    L.append("-" * 32)
+    L.append(f"  MTTD (Mean Time to Detect):   {_fmt_duration(analysis.metrics.get('mttd_minutes'))}")
+    L.append(f"  MTTR (Mean Time to Resolve):  {_fmt_duration(analysis.metrics.get('mttr_minutes'))}")
+    L.append(f"  Total Events:                 {analysis.metrics.get('total_events', 0)}")
+    L.append(f"  Decision Points:              {analysis.metrics.get('decision_point_count', 0)}")
+    L.append(f"  Timeline Gaps (>{GAP_THRESHOLD_MINUTES}m):      {analysis.metrics.get('gap_count', 0)}")
+    L.append("")
+
+    # Phases
+    L.append("INCIDENT PHASES")
+    L.append("-" * 32)
+    if analysis.phases:
+        for p in analysis.phases:
+            L.append(f"  [{_fmt_ts(p.start_time)} - {_fmt_ts(p.end_time)}]  {p.name} ({_fmt_duration(p.duration_minutes)})")
+            L.append(f"    {p.description}")
+            L.append(f"    Events: {len(p.events)}")
+    else:
+        L.append("  No phases detected.")
+    L.append("")
+
+    # Chronological timeline
+    L.append("CHRONOLOGICAL TIMELINE")
+    L.append("-" * 32)
+    for e in analysis.events:
+        marker = "*" if e.is_decision_point else " "
+        L.append(f"  {_fmt_ts(e.timestamp)} {marker} [{e.type.upper():13s}] {e.actor}")
+        L.append(f"             {e.description}")
+    L.append("")
+    L.append("  (* = key decision point)")
+    L.append("")
+
+    # Gap warnings
+    if analysis.gaps:
+        L.append("GAP ANALYSIS")
+        L.append("-" * 32)
+        for g in analysis.gaps:
+            L.append(f"  WARNING: {_fmt_duration(g.duration_minutes)} gap between {_fmt_ts(g.start)} and {_fmt_ts(g.end)}")
+        L.append("")
+
+    # Decision points
+    if analysis.decision_points:
+        L.append("KEY DECISION POINTS")
+        L.append("-" * 32)
+        for dp in analysis.decision_points:
+            L.append(f"  {_fmt_ts(dp.timestamp)}  [{dp.type.upper()}] {dp.description}")
+        L.append("")
+
+    # Communications
+    if analysis.communications:
+        L.append("GENERATED COMMUNICATIONS")
+        L.append("-" * 32)
+        for c in analysis.communications:
+            L.append(f"  Type:     {c.template_type}")
+            L.append(f"  Audience: {c.audience}")
+            L.append(f"  Subject:  {c.subject}")
+            L.append("  ---")
+            for bl in c.body.split("\n"):
+                L.append(f"  {bl}")
+            L.append("")
+
+    L.append("=" * w)
+    L.append("END OF REPORT")
+    L.append("=" * w)
+    return "\n".join(L)
+
+
+def format_json_output(analysis: TimelineAnalysis) -> Dict[str, Any]:
+    """Format the analysis as a structured JSON-serializable dictionary."""
+    return {
+        "incident": {
+            "id": analysis.incident_id, "title": analysis.incident_title,
+            "severity": analysis.severity, "status": analysis.status,
+            "commander": analysis.commander, "service": analysis.service,
+            "affected_services": analysis.affected_services,
+            "declared_at": analysis.declared_at.strftime(ISO_FORMAT) if analysis.declared_at else None,
+            "resolved_at": analysis.resolved_at.strftime(ISO_FORMAT) if analysis.resolved_at else None,
+        },
+        "timeline": [e.to_dict() for e in analysis.events],
+        "phases": [p.to_dict() for p in analysis.phases],
+        "gaps": [g.to_dict() for g in analysis.gaps],
+        "decision_points": [e.to_dict() for e in analysis.decision_points],
+        "metrics": analysis.metrics,
+        "communications": [c.to_dict() for c in analysis.communications],
+        "errors": analysis.errors if analysis.errors else [],
+    }
+
+
+def format_markdown_output(analysis: TimelineAnalysis) -> str:
+    """Format the analysis as a professional Markdown report."""
+    L: List[str] = []
+
+    L.append(f"# Incident Timeline Report: {analysis.incident_id}")
+    L.append("")
+
+    if analysis.errors:
+        L.append("> **Warnings:**")
+        for err in analysis.errors:
+            L.append(f"> - {err}")
+        L.append("")
+        if not analysis.events:
+            return "\n".join(L)
+
+    # Summary table
+    L.append("## Incident Summary")
+    L.append("")
+    L.append("| Field | Value |")
+    L.append("|-------|-------|")
+    L.append(f"| **ID** | {analysis.incident_id} |")
+    L.append(f"| **Title** | {analysis.incident_title} |")
+    L.append(f"| **Severity** | {analysis.severity} ({_sev_label(analysis.severity)}) |")
+    L.append(f"| **Status** | {analysis.status.capitalize()} |")
+    L.append(f"| **Commander** | {analysis.commander} |")
+    L.append(f"| **Service** | {analysis.service} |")
+    if analysis.affected_services:
+        L.append(f"| **Affected Services** | {', '.join(analysis.affected_services)} |")
+    L.append(f"| **Duration** | {_fmt_duration(analysis.metrics.get('total_duration_minutes'))} |")
+    L.append("")
+
+    # Key metrics
+    L.append("## Key Metrics")
+    L.append("")
+    L.append(f"- **MTTD (Mean Time to Detect):** {_fmt_duration(analysis.metrics.get('mttd_minutes'))}")
+    L.append(f"- **MTTR (Mean Time to Resolve):** {_fmt_duration(analysis.metrics.get('mttr_minutes'))}")
+    L.append(f"- **Total Events:** {analysis.metrics.get('total_events', 0)}")
+    L.append(f"- **Decision Points:** {analysis.metrics.get('decision_point_count', 0)}")
+    L.append(f"- **Timeline Gaps (>{GAP_THRESHOLD_MINUTES}m):** {analysis.metrics.get('gap_count', 0)}")
+    if analysis.metrics.get("longest_gap_minutes", 0) > 0:
+        L.append(f"- **Longest Gap:** {_fmt_duration(analysis.metrics.get('longest_gap_minutes'))}")
+    L.append("")
+
+    # Phases table
+    L.append("## Incident Phases")
+    L.append("")
+    if analysis.phases:
+        L.append("| Phase | Start | End | Duration | Events |")
+        L.append("|-------|-------|-----|----------|--------|")
+        for p in analysis.phases:
+            L.append(f"| {p.name} | {_fmt_ts(p.start_time)} | {_fmt_ts(p.end_time)} | {_fmt_duration(p.duration_minutes)} | {len(p.events)} |")
+        L.append("")
+        # ASCII bar chart
+        max_dur = max((p.duration_minutes for p in analysis.phases if p.duration_minutes), default=0)
+        if max_dur and max_dur > 0:
+            L.append("### Phase Duration Distribution")
+            L.append("")
+            L.append("```")
+            for p in analysis.phases:
+                d = p.duration_minutes or 0
+                bar = "#" * int((d / max_dur) * 40)
+                L.append(f"  {p.name:15s} |{bar} {_fmt_duration(d)}")
+            L.append("```")
+            L.append("")
+    else:
+        L.append("No phases detected.")
+        L.append("")
+
+    # Chronological timeline
+    L.append("## Chronological Timeline")
+    L.append("")
+    for e in analysis.events:
+        dm = " **[KEY DECISION]**" if e.is_decision_point else ""
+        L.append(f"- `{_fmt_ts(e.timestamp)}` **{e.type.upper()}** ({e.actor}){dm}")
+        L.append(f"  - {e.description}")
+    L.append("")
+
+    # Gap analysis
+    if analysis.gaps:
+        L.append("## Gap Analysis")
+        L.append("")
+        L.append(f"> {len(analysis.gaps)} gap(s) of >{GAP_THRESHOLD_MINUTES} minutes detected. "
+                 f"These may represent blind spots where important activity was not recorded.")
+        L.append("")
+        for g in analysis.gaps:
+            L.append(f"- **{_fmt_duration(g.duration_minutes)}** gap from `{_fmt_ts(g.start)}` to `{_fmt_ts(g.end)}`")
+        L.append("")
+
+    # Decision points
+    if analysis.decision_points:
+        L.append("## Key Decision Points")
+        L.append("")
+        for dp in analysis.decision_points:
+            L.append(f"1. `{_fmt_ts(dp.timestamp)}` **{dp.type.upper()}** - {dp.description}")
+        L.append("")
+
+    # Communications
+    if analysis.communications:
+        L.append("## Generated Communications")
+        L.append("")
+        for c in analysis.communications:
+            L.append(f"### {c.template_type.replace('_', ' ').title()} ({c.audience})")
+            L.append("")
+            L.append(f"**Subject:** {c.subject}")
+            L.append("")
+            for bl in c.body.split("\n"):
+                L.append(bl)
+            L.append("")
+            L.append("---")
+            L.append("")
+
+    # Event type breakdown
+    tc = analysis.metrics.get("event_counts_by_type", {})
+    if tc:
+        L.append("## Event Type Breakdown")
+        L.append("")
+        L.append("| Type | Count |")
+        L.append("|------|-------|")
+        for etype, count in sorted(tc.items(), key=lambda x: -x[1]):
+            L.append(f"| {etype} | {count} |")
+        L.append("")
+
+    L.append("---")
+    L.append(f"*Report generated for incident {analysis.incident_id}. All timestamps in UTC.*")
+    return "\n".join(L)
+
+
+# ---------------------------------------------------------------------------
+# CLI Interface
+# ---------------------------------------------------------------------------
+
+def main() -> int:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="Build structured incident timelines with phase detection and communication templates."
+    )
+    parser.add_argument(
+        "data_file", nargs="?", default=None,
+        help="JSON file with incident data (reads stdin if omitted)",
+    )
+    parser.add_argument(
+        "--format", choices=["text", "json", "markdown"], default="text",
+        help="Output format (default: text)",
+    )
+    args = parser.parse_args()
+
+    try:
+        if args.data_file:
+            try:
+                with open(args.data_file, "r") as f:
+                    raw_data = json.load(f)
+            except FileNotFoundError:
+                print(f"Error: File '{args.data_file}' not found.", file=sys.stderr)
+                return 1
+            except json.JSONDecodeError as e:
+                print(f"Error: Invalid JSON in '{args.data_file}': {e}", file=sys.stderr)
+                return 1
+        else:
+            if sys.stdin.isatty():
+                print("Error: No input file specified and stdin is a terminal. "
+                      "Provide a file argument or pipe JSON to stdin.", file=sys.stderr)
+                return 1
+            try:
+                raw_data = json.load(sys.stdin)
+            except json.JSONDecodeError as e:
+                print(f"Error: Invalid JSON on stdin: {e}", file=sys.stderr)
+                return 1
+
+        if not isinstance(raw_data, dict):
+            print("Error: Input must be a JSON object.", file=sys.stderr)
+            return 1
+        if "incident" not in raw_data and "events" not in raw_data:
+            print("Error: Input must contain at least 'incident' or 'events' keys.", file=sys.stderr)
+            return 1
+
+        analysis = build_timeline(raw_data)
+
+        if args.format == "json":
+            print(json.dumps(format_json_output(analysis), indent=2))
+        elif args.format == "markdown":
+            print(format_markdown_output(analysis))
+        else:
+            print(format_text_output(analysis))
+        return 0
+
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())