claude-code-arcane 1.0.0

package/skills/incident-commander/scripts/postmortem_generator.py

@@ -0,0 +1,804 @@
+#!/usr/bin/env python3
+"""
+Postmortem Generator - Generate structured postmortem reports with 5-Whys analysis.
+
+Produces comprehensive incident postmortem documents from structured JSON input,
+including root cause analysis, contributing factor classification, action item
+validation, MTTD/MTTR metrics, and customer impact summaries.
+
+Usage:
+    python postmortem_generator.py incident_data.json
+    python postmortem_generator.py incident_data.json --format markdown
+    python postmortem_generator.py incident_data.json --format json
+    cat incident_data.json | python postmortem_generator.py
+
+Input:
+    JSON object with keys: incident, timeline, resolution, action_items, participants.
+    See SKILL.md for the full input schema.
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
+
+
+# ---------- Constants and Configuration ----------
+
+VERSION = "1.0.0"
+SEVERITY_ORDER = {"SEV0": 0, "SEV1": 1, "SEV2": 2, "SEV3": 3, "SEV4": 4}
+FACTOR_CATEGORIES = ("process", "tooling", "human", "environment", "external")
+ACTION_TYPES = ("detection", "prevention", "mitigation", "process")
+PRIORITY_ORDER = {"P0": 0, "P1": 1, "P2": 2, "P3": 3, "P4": 4}
+POSTMORTEM_TARGET_HOURS = 72
+
+# Industry benchmarks for incident response (minutes, except postmortem)
+BENCHMARKS = {
+    "SEV0": {"mttd": 5, "mttr": 60, "mitigate": 30, "declare": 5},
+    "SEV1": {"mttd": 10, "mttr": 120, "mitigate": 60, "declare": 10},
+    "SEV2": {"mttd": 30, "mttr": 480, "mitigate": 120, "declare": 30},
+    "SEV3": {"mttd": 60, "mttr": 1440, "mitigate": 240, "declare": 60},
+    "SEV4": {"mttd": 120, "mttr": 2880, "mitigate": 480, "declare": 120},
+}
+
+CAT_TO_ACTION = {"process": "process", "tooling": "detection", "human": "prevention",
+                 "environment": "mitigation", "external": "prevention"}
+CAT_WEIGHT = {"process": 1.0, "tooling": 0.9, "human": 0.8, "environment": 0.7, "external": 0.6}
+
+# Keywords used to classify contributing factors into categories
+FACTOR_KEYWORDS = {
+    "process": ["process", "procedure", "workflow", "review", "approval", "checklist",
+                 "runbook", "documentation", "policy", "standard", "protocol", "canary",
+                 "deployment", "rollback", "change management"],
+    "tooling": ["tool", "monitor", "alert", "threshold", "automation", "test", "pipeline",
+                "ci/cd", "observability", "dashboard", "logging", "infrastructure",
+                "configuration", "config"],
+    "human": ["training", "knowledge", "experience", "communication", "handoff", "fatigue",
+              "oversight", "mistake", "error", "misunderstand", "assumption", "awareness"],
+    "environment": ["load", "traffic", "scale", "capacity", "resource", "network", "hardware",
+                    "region", "latency", "timeout", "connection", "performance", "spike"],
+    "external": ["vendor", "third-party", "upstream", "downstream", "provider", "api",
+                 "dependency", "partner", "dns", "cdn", "certificate"],
+}
+
+# 5-Whys templates per category (each list is 5 why->answer steps)
+WHY_TEMPLATES = {
+    "process": [
+        "Why did this process gap exist? -> The existing process did not account for this scenario.",
+        "Why was the scenario not accounted for? -> It was not identified during the last process review.",
+        "Why was the process review incomplete? -> Reviews focus on known failure modes, not emerging risks.",
+        "Why are emerging risks not surfaced? -> No systematic mechanism to capture lessons from near-misses.",
+        "Why is there no near-miss capture mechanism? -> Incident learning is ad-hoc rather than systematic."],
+    "tooling": [
+        "Why did the tooling fail to catch this? -> The relevant metric was not monitored or the threshold was misconfigured.",
+        "Why was the threshold misconfigured? -> It was set during initial deployment and never revisited.",
+        "Why was it never revisited? -> There is no scheduled review of monitoring configurations.",
+        "Why is there no scheduled review? -> Monitoring ownership is diffuse across teams.",
+        "Why is ownership diffuse? -> No clear operational runbook assigns monitoring review responsibilities."],
+    "human": [
+        "Why did the human factor contribute? -> The individual lacked context needed to prevent the issue.",
+        "Why was context lacking? -> Knowledge was siloed and not documented accessibly.",
+        "Why was knowledge siloed? -> No structured onboarding or knowledge-sharing process for this area.",
+        "Why is there no knowledge-sharing process? -> Team capacity has been focused on feature delivery.",
+        "Why is capacity skewed toward features? -> Operational excellence is not weighted equally in planning."],
+    "environment": [
+        "Why did the environment cause this failure? -> System capacity was insufficient for the load pattern.",
+        "Why was capacity insufficient? -> Load projections did not account for this traffic pattern.",
+        "Why were projections inaccurate? -> Load testing does not replicate production-scale variability.",
+        "Why doesn't load testing replicate production? -> Test environments lack realistic traffic generators.",
+        "Why are traffic generators missing? -> Investment in production-like test infrastructure was deferred."],
+    "external": [
+        "Why did the external factor cause an incident? -> The system had a hard dependency with no fallback.",
+        "Why was there no fallback? -> The integration was assumed to be highly available.",
+        "Why was high availability assumed? -> SLA review of the external dependency was not performed.",
+        "Why was SLA review skipped? -> No standard checklist for evaluating third-party dependencies.",
+        "Why is there no evaluation checklist? -> Vendor management practices are informal and undocumented."],
+}
+
+THEME_RECS = {
+    "process": ["Establish a quarterly process review cadence covering change management and deployment procedures.",
+                "Implement a near-miss tracking system to surface latent risks before they become incidents.",
+                "Create pre-deployment checklists that require sign-off from the service owner."],
+    "tooling": ["Schedule quarterly reviews of alerting thresholds and monitoring coverage.",
+                "Assign explicit monitoring ownership per service in operational runbooks.",
+                "Invest in synthetic monitoring and canary analysis for critical paths."],
+    "human": ["Build structured onboarding that covers incident-prone areas and past postmortems.",
+              "Implement blameless knowledge-sharing sessions after each incident.",
+              "Balance operational excellence work alongside feature delivery in sprint planning."],
+    "environment": ["Conduct periodic capacity planning reviews using production traffic replays.",
+                    "Invest in production-like load-testing infrastructure with realistic traffic profiles.",
+                    "Implement auto-scaling policies with validated upper-bound thresholds."],
+    "external": ["Perform formal SLA reviews for all third-party dependencies annually.",
+                 "Implement circuit breakers and fallbacks for external service integrations.",
+                 "Maintain a dependency registry with risk ratings and contingency plans."],
+}
+
+MISSING_ACTION_TEMPLATES = {
+    "process": "Create or update runbook/checklist to prevent recurrence of this process gap",
+    "detection": "Add monitoring and alerting to detect this class of issue earlier",
+    "mitigation": "Implement auto-scaling or circuit-breaker to reduce blast radius",
+    "prevention": "Add automated safeguards (canary deploy, load test gate) to prevent recurrence",
+}
+
+
+# ---------- Data Model Classes ----------
+
+class IncidentData:
+    """Parsed incident metadata."""
+    def __init__(self, data: Dict[str, Any]) -> None:
+        self.id: str = data.get("id", "UNKNOWN")
+        self.title: str = data.get("title", "Untitled Incident")
+        self.severity: str = data.get("severity", "SEV3").upper()
+        self.commander: str = data.get("commander", "Unassigned")
+        self.service: str = data.get("service", "unknown-service")
+        self.affected_services: List[str] = data.get("affected_services", [])
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"id": self.id, "title": self.title, "severity": self.severity,
+                "commander": self.commander, "service": self.service,
+                "affected_services": self.affected_services}
+
+
+class TimelineMetrics:
+    """MTTD, MTTR, and other timing metrics computed from raw timestamps."""
+    def __init__(self, timeline: Dict[str, str], severity: str) -> None:
+        self.severity = severity
+        self.issue_started = self._parse(timeline.get("issue_started"))
+        self.detected_at = self._parse(timeline.get("detected_at"))
+        self.declared_at = self._parse(timeline.get("declared_at"))
+        self.mitigated_at = self._parse(timeline.get("mitigated_at"))
+        self.resolved_at = self._parse(timeline.get("resolved_at"))
+        self.postmortem_at = self._parse(timeline.get("postmortem_at"))
+
+    @staticmethod
+    def _parse(ts: Optional[str]) -> Optional[datetime]:
+        if ts is None:
+            return None
+        for fmt in ("%Y-%m-%dT%H:%M:%SZ", "%Y-%m-%dT%H:%M:%S%z", "%Y-%m-%dT%H:%M:%S"):
+            try:
+                dt = datetime.strptime(ts, fmt)
+                return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+            except ValueError:
+                continue
+        return None
+
+    def _delta_min(self, start: Optional[datetime], end: Optional[datetime]) -> Optional[float]:
+        if start is None or end is None:
+            return None
+        return round((end - start).total_seconds() / 60.0, 1)
+
+    @property
+    def mttd(self) -> Optional[float]:
+        return self._delta_min(self.issue_started, self.detected_at)
+
+    @property
+    def mttr(self) -> Optional[float]:
+        return self._delta_min(self.detected_at, self.resolved_at)
+
+    @property
+    def time_to_mitigate(self) -> Optional[float]:
+        return self._delta_min(self.detected_at, self.mitigated_at)
+
+    @property
+    def time_to_declare(self) -> Optional[float]:
+        return self._delta_min(self.detected_at, self.declared_at)
+
+    @property
+    def postmortem_timeliness_hours(self) -> Optional[float]:
+        m = self._delta_min(self.resolved_at, self.postmortem_at)
+        return round(m / 60.0, 1) if m is not None else None
+
+    @property
+    def postmortem_on_time(self) -> Optional[bool]:
+        h = self.postmortem_timeliness_hours
+        return h <= POSTMORTEM_TARGET_HOURS if h is not None else None
+
+    def benchmark_comparison(self) -> Dict[str, Dict[str, Any]]:
+        bench = BENCHMARKS.get(self.severity, BENCHMARKS["SEV3"])
+        results: Dict[str, Dict[str, Any]] = {}
+        for name, actual, target in [("mttd", self.mttd, bench["mttd"]),
+                                     ("mttr", self.mttr, bench["mttr"]),
+                                     ("time_to_mitigate", self.time_to_mitigate, bench["mitigate"]),
+                                     ("time_to_declare", self.time_to_declare, bench["declare"])]:
+            if actual is not None:
+                results[name] = {"actual_minutes": actual, "benchmark_minutes": target,
+                                 "met_benchmark": actual <= target,
+                                 "delta_minutes": round(actual - target, 1)}
+        h = self.postmortem_timeliness_hours
+        if h is not None:
+            results["postmortem_timeliness"] = {
+                "actual_hours": h, "target_hours": POSTMORTEM_TARGET_HOURS,
+                "met_target": self.postmortem_on_time, "delta_hours": round(h - POSTMORTEM_TARGET_HOURS, 1)}
+        return results
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"mttd_minutes": self.mttd, "mttr_minutes": self.mttr,
+                "time_to_mitigate_minutes": self.time_to_mitigate,
+                "time_to_declare_minutes": self.time_to_declare,
+                "postmortem_timeliness_hours": self.postmortem_timeliness_hours,
+                "postmortem_on_time": self.postmortem_on_time,
+                "benchmarks": self.benchmark_comparison()}
+
+
+class ContributingFactor:
+    """A classified contributing factor with weight and action-type mapping."""
+    def __init__(self, description: str, index: int) -> None:
+        self.description = description
+        self.index = index
+        self.category = self._classify()
+        self.weight = round(max(1.0 - index * 0.15, 0.3) * CAT_WEIGHT.get(self.category, 0.8), 2)
+        self.mapped_action_type = CAT_TO_ACTION.get(self.category, "process")
+
+    def _classify(self) -> str:
+        lower = self.description.lower()
+        scores = {cat: sum(1 for kw in kws if kw in lower) for cat, kws in FACTOR_KEYWORDS.items()}
+        best = max(scores, key=lambda k: scores[k])
+        return best if scores[best] > 0 else "process"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"description": self.description, "category": self.category,
+                "weight": self.weight, "mapped_action_type": self.mapped_action_type}
+
+
+class FiveWhysAnalysis:
+    """Structured 5-Whys chain for a contributing factor."""
+    def __init__(self, factor: ContributingFactor) -> None:
+        self.factor = factor
+        self.systemic_theme: str = factor.category
+        self.chain: List[str] = [f"Why? {factor.description}"] + \
+            WHY_TEMPLATES.get(factor.category, WHY_TEMPLATES["process"])
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"factor": self.factor.description, "category": self.factor.category,
+                "chain": self.chain, "systemic_theme": self.systemic_theme}
+
+
+class ActionItem:
+    """Parsed and validated action item."""
+    def __init__(self, data: Dict[str, Any]) -> None:
+        self.title: str = data.get("title", "")
+        self.owner: str = data.get("owner", "")
+        self.priority: str = data.get("priority", "P3")
+        self.deadline: str = data.get("deadline", "")
+        self.type: str = data.get("type", "process")
+        self.status: str = data.get("status", "open")
+        self.validation_issues: List[str] = []
+        self.quality_score: int = 0
+        self._validate()
+
+    def _validate(self) -> None:
+        self.validation_issues = []
+        if not self.title:
+            self.validation_issues.append("Missing title")
+        if not self.owner:
+            self.validation_issues.append("Missing owner")
+        if not self.deadline:
+            self.validation_issues.append("Missing deadline")
+        if self.priority not in PRIORITY_ORDER:
+            self.validation_issues.append(f"Invalid priority: {self.priority}")
+        if self.type not in ACTION_TYPES:
+            self.validation_issues.append(f"Invalid type: {self.type}")
+        self.quality_score = self._score_quality()
+
+    def _score_quality(self) -> int:
+        """Score 0-100: specific, measurable, achievable."""
+        s = 0
+        if len(self.title) > 10: s += 20
+        if self.owner: s += 20
+        if self.deadline: s += 20
+        if self.priority in PRIORITY_ORDER: s += 10
+        if self.type in ACTION_TYPES: s += 10
+        if any(kw in self.title.lower() for kw in ["%", "threshold", "within", "before",
+                                                     "after", "less than", "greater than"]):
+            s += 10
+        if len(self.title.split()) >= 5: s += 10
+        return min(s, 100)
+
+    @property
+    def is_valid(self) -> bool:
+        return len(self.validation_issues) == 0
+
+    @property
+    def is_past_deadline(self) -> bool:
+        if not self.deadline or self.status != "open":
+            return False
+        try:
+            dl = datetime.strptime(self.deadline, "%Y-%m-%d").replace(tzinfo=timezone.utc)
+            return datetime.now(timezone.utc) > dl
+        except ValueError:
+            return False
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"title": self.title, "owner": self.owner, "priority": self.priority,
+                "deadline": self.deadline, "type": self.type, "status": self.status,
+                "is_valid": self.is_valid, "validation_issues": self.validation_issues,
+                "quality_score": self.quality_score, "is_past_deadline": self.is_past_deadline}
+
+
+class PostmortemReport:
+    """Complete postmortem document assembled from all analysis components."""
+
+    def __init__(self, raw: Dict[str, Any]) -> None:
+        self.raw = raw
+        self.incident = IncidentData(raw.get("incident", {}))
+        self.timeline = TimelineMetrics(raw.get("timeline", {}), self.incident.severity)
+        self.resolution: Dict[str, Any] = raw.get("resolution", {})
+        self.participants: List[Dict[str, str]] = raw.get("participants", [])
+        # Derived analysis
+        self.contributing_factors = [ContributingFactor(f, i)
+                                     for i, f in enumerate(self.resolution.get("contributing_factors", []))]
+        self.five_whys = [FiveWhysAnalysis(f) for f in self.contributing_factors]
+        self.action_items = [ActionItem(a) for a in raw.get("action_items", [])]
+        self.factor_distribution = self._compute_factor_distribution()
+        self.coverage_gaps = self._find_coverage_gaps()
+        self.suggested_actions = self._suggest_missing_actions()
+        self.theme_recommendations = self._build_theme_recommendations()
+
+    def _compute_factor_distribution(self) -> Dict[str, float]:
+        dist: Dict[str, float] = {c: 0.0 for c in FACTOR_CATEGORIES}
+        total = sum(f.weight for f in self.contributing_factors) or 1.0
+        for f in self.contributing_factors:
+            dist[f.category] += f.weight
+        return {k: round(v / total * 100, 1) for k, v in dist.items()}
+
+    def _find_coverage_gaps(self) -> List[str]:
+        factor_cats = {f.category for f in self.contributing_factors}
+        action_types = {a.type for a in self.action_items}
+        gaps = []
+        for cat in factor_cats:
+            expected = CAT_TO_ACTION.get(cat)
+            if expected and expected not in action_types:
+                gaps.append(f"No '{expected}' action item to address '{cat}' contributing factor")
+        return gaps
+
+    def _suggest_missing_actions(self) -> List[Dict[str, str]]:
+        factor_cats = {f.category for f in self.contributing_factors}
+        action_types = {a.type for a in self.action_items}
+        suggestions = []
+        for cat in factor_cats:
+            expected = CAT_TO_ACTION.get(cat)
+            if expected and expected not in action_types:
+                suggestions.append({
+                    "type": expected,
+                    "suggestion": MISSING_ACTION_TEMPLATES.get(expected, "Add an action item for this gap"),
+                    "reason": f"No action item addresses the '{cat}' contributing factor"})
+        return suggestions
+
+    def _build_theme_recommendations(self) -> Dict[str, List[str]]:
+        seen: Dict[str, List[str]] = {}
+        for a in self.five_whys:
+            if a.systemic_theme not in seen:
+                seen[a.systemic_theme] = THEME_RECS.get(a.systemic_theme, [])
+        return seen
+
+    def customer_impact_summary(self) -> Dict[str, Any]:
+        impact = self.resolution.get("customer_impact", {})
+        affected = impact.get("affected_users", 0)
+        failed_tx = impact.get("failed_transactions", 0)
+        revenue = impact.get("revenue_impact_usd", 0)
+        data_loss = impact.get("data_loss", False)
+        comm_required = affected > 1000 or data_loss or revenue > 10000
+        sev = "high" if (affected > 10000 or revenue > 50000) else (
+            "medium" if (affected > 1000 or revenue > 5000) else "low")
+        return {"affected_users": affected, "failed_transactions": failed_tx,
+                "revenue_impact_usd": revenue, "data_loss": data_loss,
+                "data_integrity": "compromised" if data_loss else "intact",
+                "customer_communication_required": comm_required, "impact_severity": sev}
+
+    def executive_summary(self) -> str:
+        mttr = self.timeline.mttr
+        ci = self.customer_impact_summary()
+        mttr_str = f"{mttr:.0f} minutes" if mttr is not None else "unknown duration"
+        parts = [
+            f"On {self._fmt_date(self.timeline.issue_started)}, a {self.incident.severity} "
+            f"incident (\"{self.incident.title}\") impacted the {self.incident.service} service.",
+            f"The root cause was identified as: {self.resolution.get('root_cause', 'Unknown root cause')}.",
+            f"The incident was resolved in {mttr_str}, affecting approximately "
+            f"{ci['affected_users']:,} users with an estimated revenue impact of ${ci['revenue_impact_usd']:,.2f}.",
+            "Data loss was confirmed; affected customers must be notified." if ci["data_loss"]
+            else "No data loss occurred during this incident."]
+        return " ".join(parts)
+
+    @staticmethod
+    def _fmt_date(dt: Optional[datetime]) -> str:
+        return dt.strftime("%Y-%m-%d at %H:%M UTC") if dt else "an unknown date"
+
+    def overdue_p1_items(self) -> List[Dict[str, str]]:
+        return [{"title": a.title, "owner": a.owner, "deadline": a.deadline}
+                for a in self.action_items if a.priority in ("P0", "P1") and a.is_past_deadline]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "version": VERSION, "incident": self.incident.to_dict(),
+            "executive_summary": self.executive_summary(),
+            "timeline_metrics": self.timeline.to_dict(),
+            "customer_impact": self.customer_impact_summary(),
+            "root_cause": self.resolution.get("root_cause", ""),
+            "contributing_factors": [f.to_dict() for f in self.contributing_factors],
+            "factor_distribution": self.factor_distribution,
+            "five_whys_analysis": [a.to_dict() for a in self.five_whys],
+            "theme_recommendations": self.theme_recommendations,
+            "mitigation_steps": self.resolution.get("mitigation_steps", []),
+            "permanent_fix": self.resolution.get("permanent_fix", ""),
+            "action_items": [a.to_dict() for a in self.action_items],
+            "action_item_coverage_gaps": self.coverage_gaps,
+            "suggested_actions": self.suggested_actions,
+            "overdue_p1_items": self.overdue_p1_items(),
+            "participants": self.participants}
+
+
+# ---------- Core Analysis Helpers ----------
+
+def _bar(pct: float, width: int = 30) -> str:
+    """Render a text-based horizontal bar chart segment."""
+    filled = int(round(pct / 100 * width))
+    return "[" + "#" * filled + "." * (width - filled) + "]"
+
+
+def _generate_lessons(report: PostmortemReport) -> List[str]:
+    """Derive lessons learned from the analysis."""
+    lessons: List[str] = []
+    bench = BENCHMARKS.get(report.incident.severity, BENCHMARKS["SEV3"])
+    mttd = report.timeline.mttd
+    if mttd is not None and mttd > bench["mttd"]:
+        lessons.append(
+            f"Detection took {mttd:.0f} minutes, exceeding the {bench['mttd']}-minute "
+            f"benchmark for {report.incident.severity}. Invest in earlier detection mechanisms.")
+    dist = report.factor_distribution
+    dominant = max(dist, key=lambda k: dist[k])
+    if dist[dominant] >= 50:
+        lessons.append(
+            f"The '{dominant}' category accounts for {dist[dominant]:.0f}% of contributing factors. "
+            f"Targeted improvements in this area will yield the highest return.")
+    if report.coverage_gaps:
+        lessons.append(
+            f"There are {len(report.coverage_gaps)} action item coverage gap(s). "
+            "Ensure every contributing factor category has a corresponding remediation action.")
+    avg_q = (sum(a.quality_score for a in report.action_items) / len(report.action_items)
+             if report.action_items else 0)
+    if avg_q < 70:
+        lessons.append(
+            f"Average action item quality score is {avg_q:.0f}/100. "
+            "Make action items more specific with measurable targets and clear ownership.")
+    if report.timeline.postmortem_on_time is False:
+        h = report.timeline.postmortem_timeliness_hours
+        lessons.append(
+            f"Postmortem was held {h:.0f} hours after resolution, exceeding the "
+            f"{POSTMORTEM_TARGET_HOURS}-hour target. Schedule postmortems sooner to capture context.")
+    if not lessons:
+        lessons.append("This incident was handled within benchmarks. Continue reinforcing "
+                       "current practices and share this postmortem for organizational learning.")
+    return lessons
+
+
+# ---------- Output Formatters ----------
+
+def format_text(report: PostmortemReport) -> str:
+    """Format the postmortem as plain text."""
+    L: List[str] = []
+    W = 72
+
+    def h1(title: str) -> None:
+        L.append(""); L.append("=" * W); L.append(f"  {title}"); L.append("=" * W)
+
+    def h2(title: str) -> None:
+        L.append(""); L.append(f"--- {title} ---")
+
+    inc = report.incident
+    h1(f"POSTMORTEM: {inc.title}")
+    L.append(f"  ID: {inc.id}  |  Severity: {inc.severity}  |  Service: {inc.service}")
+    L.append(f"  Commander: {inc.commander}")
+    if inc.affected_services:
+        L.append(f"  Affected services: {', '.join(inc.affected_services)}")
+    # Executive Summary
+    h1("EXECUTIVE SUMMARY")
+    L.append("")
+    for sentence in report.executive_summary().split(". "):
+        s = sentence.strip()
+        if s and not s.endswith("."): s += "."
+        if s: L.append(f"  {s}")
+    # Timeline Metrics
+    h1("TIMELINE METRICS")
+    tm = report.timeline
+    L.append("")
+    for label, val, unit in [("MTTD (Time to Detect)", tm.mttd, "min"),
+                             ("MTTR (Time to Resolve)", tm.mttr, "min"),
+                             ("Time to Mitigate", tm.time_to_mitigate, "min"),
+                             ("Time to Declare", tm.time_to_declare, "min"),
+                             ("Postmortem Timeliness", tm.postmortem_timeliness_hours, "hrs")]:
+        L.append(f"  {label:<30s} {f'{val:.1f} {unit}' if val is not None else 'N/A'}")
+    h2("Benchmark Comparison")
+    for name, d in tm.benchmark_comparison().items():
+        if "actual_minutes" in d:
+            st = "PASS" if d["met_benchmark"] else "FAIL"
+            L.append(f"  {name:<25s} actual={d['actual_minutes']}min  benchmark={d['benchmark_minutes']}min  [{st}]")
+        elif "actual_hours" in d:
+            st = "PASS" if d["met_target"] else "FAIL"
+            L.append(f"  {name:<25s} actual={d['actual_hours']}hrs  target={d['target_hours']}hrs  [{st}]")
+    # Customer Impact
+    h1("CUSTOMER IMPACT")
+    ci = report.customer_impact_summary()
+    L.append("")
+    L.append(f"  Affected users:          {ci['affected_users']:,}")
+    L.append(f"  Failed transactions:     {ci['failed_transactions']:,}")
+    L.append(f"  Revenue impact:          ${ci['revenue_impact_usd']:,.2f}")
+    L.append(f"  Data integrity:          {ci['data_integrity']}")
+    L.append(f"  Impact severity:         {ci['impact_severity']}")
+    L.append(f"  Comms required:          {'Yes' if ci['customer_communication_required'] else 'No'}")
+    # Root Cause
+    h1("ROOT CAUSE ANALYSIS")
+    L.append("")
+    L.append(f"  {report.resolution.get('root_cause', 'Unknown')}")
+    h2("Contributing Factors")
+    for f in report.contributing_factors:
+        L.append(f"  [{f.category.upper():<12s} w={f.weight:.2f}] {f.description}")
+    h2("Factor Distribution")
+    for cat, pct in sorted(report.factor_distribution.items(), key=lambda x: -x[1]):
+        if pct > 0:
+            L.append(f"  {cat:<14s} {pct:5.1f}%  {_bar(pct)}")
+    # 5-Whys
+    h1("5-WHYS ANALYSIS")
+    for analysis in report.five_whys:
+        L.append("")
+        L.append(f"  Factor: {analysis.factor.description}")
+        L.append(f"  Theme:  {analysis.systemic_theme}")
+        for i, step in enumerate(analysis.chain):
+            L.append(f"    {i}. {step}")
+    h2("Theme-Based Recommendations")
+    for theme, recs in report.theme_recommendations.items():
+        L.append(f"  [{theme.upper()}]")
+        for rec in recs:
+            L.append(f"    - {rec}")
+    # Mitigation & Fix
+    h1("MITIGATION AND RESOLUTION")
+    h2("Mitigation Steps Taken")
+    for step in report.resolution.get("mitigation_steps", []):
+        L.append(f"  - {step}")
+    h2("Permanent Fix")
+    L.append(f"  {report.resolution.get('permanent_fix', 'TBD')}")
+    # Action Items
+    h1("ACTION ITEMS")
+    L.append("")
+    hdr = f"  {'Priority':<10s} {'Type':<14s} {'Owner':<25s} {'Deadline':<12s} {'Quality':<8s} Title"
+    L.append(hdr)
+    L.append("  " + "-" * (len(hdr) - 2))
+    for a in sorted(report.action_items, key=lambda x: PRIORITY_ORDER.get(x.priority, 99)):
+        flag = " *OVERDUE*" if a.is_past_deadline else ""
+        L.append(f"  {a.priority:<10s} {a.type:<14s} {a.owner:<25s} {a.deadline:<12s} "
+                 f"{a.quality_score:<8d} {a.title}{flag}")
+    if report.coverage_gaps:
+        h2("Coverage Gaps")
+        for gap in report.coverage_gaps:
+            L.append(f"  WARNING: {gap}")
+    if report.suggested_actions:
+        h2("Suggested Additional Actions")
+        for s in report.suggested_actions:
+            L.append(f"  [{s['type'].upper()}] {s['suggestion']}")
+            L.append(f"    Reason: {s['reason']}")
+    overdue = report.overdue_p1_items()
+    if overdue:
+        h2("Overdue P0/P1 Items")
+        for item in overdue:
+            L.append(f"  OVERDUE: {item['title']} (owner: {item['owner']}, deadline: {item['deadline']})")
+    # Participants
+    h1("PARTICIPANTS")
+    L.append("")
+    for p in report.participants:
+        L.append(f"  {p.get('name', 'Unknown'):<25s} {p.get('role', '')}")
+    # Lessons Learned
+    h1("LESSONS LEARNED")
+    L.append("")
+    for i, lesson in enumerate(_generate_lessons(report), 1):
+        L.append(f"  {i}. {lesson}")
+    L.append("")
+    L.append("=" * W)
+    L.append(f"  Generated by postmortem_generator v{VERSION}")
+    L.append("=" * W)
+    L.append("")
+    return "\n".join(L)
+
+
+def format_json(report: PostmortemReport) -> str:
+    """Format the postmortem as JSON."""
+    data = report.to_dict()
+    data["lessons_learned"] = _generate_lessons(report)
+    return json.dumps(data, indent=2, default=str)
+
+
+def format_markdown(report: PostmortemReport) -> str:
+    """Format the postmortem as a Markdown document."""
+    L: List[str] = []
+    inc = report.incident
+    L.append(f"# Postmortem: {inc.title}")
+    L.append("")
+    L.append("| Field | Value |")
+    L.append("|-------|-------|")
+    L.append(f"| **ID** | {inc.id} |")
+    L.append(f"| **Severity** | {inc.severity} |")
+    L.append(f"| **Service** | {inc.service} |")
+    L.append(f"| **Commander** | {inc.commander} |")
+    if inc.affected_services:
+        L.append(f"| **Affected Services** | {', '.join(inc.affected_services)} |")
+    L.append("")
+    # Executive Summary
+    L.append("## Executive Summary\n")
+    L.append(report.executive_summary())
+    L.append("")
+    # Timeline Metrics
+    L.append("## Timeline Metrics\n")
+    L.append("| Metric | Value | Benchmark | Status |")
+    L.append("|--------|-------|-----------|--------|")
+    labels = {"mttd": "MTTD (Time to Detect)", "mttr": "MTTR (Time to Resolve)",
+              "time_to_mitigate": "Time to Mitigate", "time_to_declare": "Time to Declare",
+              "postmortem_timeliness": "Postmortem Timeliness"}
+    for key, label in labels.items():
+        b = report.timeline.benchmark_comparison().get(key)
+        if b and "actual_minutes" in b:
+            st = "PASS" if b["met_benchmark"] else "FAIL"
+            L.append(f"| {label} | {b['actual_minutes']} min | {b['benchmark_minutes']} min | {st} |")
+        elif b and "actual_hours" in b:
+            st = "PASS" if b["met_target"] else "FAIL"
+            L.append(f"| {label} | {b['actual_hours']} hrs | {b['target_hours']} hrs | {st} |")
+    L.append("")
+    # Customer Impact
+    L.append("## Customer Impact\n")
+    ci = report.customer_impact_summary()
+    L.append(f"- **Affected users:** {ci['affected_users']:,}")
+    L.append(f"- **Failed transactions:** {ci['failed_transactions']:,}")
+    L.append(f"- **Revenue impact:** ${ci['revenue_impact_usd']:,.2f}")
+    L.append(f"- **Data integrity:** {ci['data_integrity']}")
+    L.append(f"- **Impact severity:** {ci['impact_severity']}")
+    L.append(f"- **Customer communication required:** {'Yes' if ci['customer_communication_required'] else 'No'}")
+    L.append("")
+    # Root Cause Analysis
+    L.append("## Root Cause Analysis\n")
+    L.append(f"**Root cause:** {report.resolution.get('root_cause', 'Unknown')}")
+    L.append("")
+    L.append("### Contributing Factors\n")
+    L.append("| # | Category | Weight | Description |")
+    L.append("|---|----------|--------|-------------|")
+    for i, f in enumerate(report.contributing_factors, 1):
+        L.append(f"| {i} | {f.category} | {f.weight:.2f} | {f.description} |")
+    L.append("")
+    L.append("### Factor Distribution\n")
+    L.append("```")
+    for cat, pct in sorted(report.factor_distribution.items(), key=lambda x: -x[1]):
+        if pct > 0:
+            L.append(f"  {cat:<14s} {pct:5.1f}%  {_bar(pct, 25)}")
+    L.append("```")
+    L.append("")
+    # 5-Whys
+    L.append("## 5-Whys Analysis\n")
+    for analysis in report.five_whys:
+        L.append(f"### Factor: {analysis.factor.description}")
+        L.append(f"**Systemic theme:** {analysis.systemic_theme}\n")
+        for i, step in enumerate(analysis.chain):
+            L.append(f"{i}. {step}")
+        L.append("")
+    L.append("### Theme-Based Recommendations\n")
+    for theme, recs in report.theme_recommendations.items():
+        L.append(f"**{theme.capitalize()}:**")
+        for rec in recs:
+            L.append(f"- {rec}")
+        L.append("")
+    # Mitigation
+    L.append("## Mitigation and Resolution\n")
+    L.append("### Mitigation Steps Taken\n")
+    for step in report.resolution.get("mitigation_steps", []):
+        L.append(f"- {step}")
+    L.append("")
+    L.append("### Permanent Fix\n")
+    L.append(report.resolution.get("permanent_fix", "TBD"))
+    L.append("")
+    # Action Items
+    L.append("## Action Items\n")
+    L.append("| Priority | Type | Owner | Deadline | Quality | Title |")
+    L.append("|----------|------|-------|----------|---------|-------|")
+    for a in sorted(report.action_items, key=lambda x: PRIORITY_ORDER.get(x.priority, 99)):
+        flag = " **OVERDUE**" if a.is_past_deadline else ""
+        L.append(f"| {a.priority} | {a.type} | {a.owner} | {a.deadline} | {a.quality_score}/100 | {a.title}{flag} |")
+    L.append("")
+    if report.coverage_gaps:
+        L.append("### Coverage Gaps\n")
+        for gap in report.coverage_gaps:
+            L.append(f"> **WARNING:** {gap}")
+        L.append("")
+    if report.suggested_actions:
+        L.append("### Suggested Additional Actions\n")
+        for s in report.suggested_actions:
+            L.append(f"- **[{s['type'].upper()}]** {s['suggestion']}")
+            L.append(f"  - _Reason: {s['reason']}_")
+        L.append("")
+    overdue = report.overdue_p1_items()
+    if overdue:
+        L.append("### Overdue P0/P1 Items\n")
+        for item in overdue:
+            L.append(f"- **{item['title']}** (owner: {item['owner']}, deadline: {item['deadline']})")
+        L.append("")
+    # Participants
+    L.append("## Participants\n")
+    L.append("| Name | Role |")
+    L.append("|------|------|")
+    for p in report.participants:
+        L.append(f"| {p.get('name', 'Unknown')} | {p.get('role', '')} |")
+    L.append("")
+    # Lessons Learned
+    L.append("## Lessons Learned\n")
+    for i, lesson in enumerate(_generate_lessons(report), 1):
+        L.append(f"{i}. {lesson}")
+    L.append("")
+    L.append("---")
+    L.append(f"_Generated by postmortem_generator v{VERSION}_")
+    L.append("")
+    return "\n".join(L)
+
+
+# ---------- Input Loading ----------
+
+def load_input(filepath: Optional[str]) -> Dict[str, Any]:
+    """Load incident data from a file path or stdin."""
+    if filepath:
+        try:
+            with open(filepath, "r", encoding="utf-8") as fh:
+                return json.load(fh)
+        except FileNotFoundError:
+            print(f"Error: File not found: {filepath}", file=sys.stderr)
+            sys.exit(1)
+        except json.JSONDecodeError as exc:
+            print(f"Error: Invalid JSON in {filepath}: {exc}", file=sys.stderr)
+            sys.exit(1)
+    else:
+        if sys.stdin.isatty():
+            print("Error: No input file specified and no data on stdin.", file=sys.stderr)
+            print("Usage: postmortem_generator.py [data_file] or pipe JSON via stdin.", file=sys.stderr)
+            sys.exit(1)
+        try:
+            return json.load(sys.stdin)
+        except json.JSONDecodeError as exc:
+            print(f"Error: Invalid JSON on stdin: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+
+def validate_input(data: Dict[str, Any]) -> List[str]:
+    """Return a list of validation warnings (non-fatal)."""
+    warnings: List[str] = []
+    for key in ("incident", "timeline", "resolution", "action_items"):
+        if key not in data:
+            warnings.append(f"Missing '{key}' section")
+    for ts in ("issue_started", "detected_at", "mitigated_at", "resolved_at"):
+        if ts not in data.get("timeline", {}):
+            warnings.append(f"Missing timeline field: {ts}")
+    res = data.get("resolution", {})
+    if "root_cause" not in res:
+        warnings.append("Missing 'root_cause' in resolution")
+    if not res.get("contributing_factors"):
+        warnings.append("No contributing factors provided")
+    return warnings
+
+
+# ---------- CLI Entry Point ----------
+
+def main() -> None:
+    """CLI entry point for postmortem generation."""
+    parser = argparse.ArgumentParser(
+        description="Generate structured postmortem reports with 5-Whys analysis.",
+        epilog="Reads JSON from a file or stdin. Outputs text, JSON, or markdown.")
+    parser.add_argument("data_file", nargs="?", default=None,
+                        help="JSON file with incident + resolution data (reads stdin if omitted)")
+    parser.add_argument("--format", choices=["text", "json", "markdown"], default="text",
+                        dest="output_format", help="Output format (default: text)")
+    args = parser.parse_args()
+
+    data = load_input(args.data_file)
+    warnings = validate_input(data)
+    for w in warnings:
+        print(f"Warning: {w}", file=sys.stderr)
+
+    report = PostmortemReport(data)
+    formatters = {"text": format_text, "json": format_json, "markdown": format_markdown}
+    print(formatters[args.output_format](report))
+
+
+if __name__ == "__main__":
+    main()