claude-code-arcane 1.0.0

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

@@ -0,0 +1,1638 @@
+#!/usr/bin/env python3
+"""
+PIR (Post-Incident Review) Generator
+
+Generates comprehensive Post-Incident Review documents from incident data, timelines,
+and actions taken. Applies multiple RCA frameworks including 5 Whys, Fishbone diagram,
+and Timeline analysis.
+
+This tool creates structured PIR documents with root cause analysis, lessons learned,
+action items, and follow-up recommendations.
+
+Usage:
+    python pir_generator.py --incident incident.json --timeline timeline.json --output pir.md
+    python pir_generator.py --incident incident.json --rca-method fishbone --action-items
+    cat incident.json | python pir_generator.py --format markdown
+"""
+
+import argparse
+import json
+import sys
+import re
+from datetime import datetime, timezone, timedelta
+from typing import Dict, List, Optional, Any, Tuple
+from collections import defaultdict, Counter
+
+
+class PIRGenerator:
+    """
+    Generates comprehensive Post-Incident Review documents with multiple
+    RCA frameworks, lessons learned, and actionable follow-up items.
+    """
+    
+    def __init__(self):
+        """Initialize the PIR generator with templates and frameworks."""
+        self.rca_frameworks = self._load_rca_frameworks()
+        self.pir_templates = self._load_pir_templates()
+        self.severity_guidelines = self._load_severity_guidelines()
+        self.action_item_types = self._load_action_item_types()
+        self.lessons_learned_categories = self._load_lessons_learned_categories()
+    
+    def _load_rca_frameworks(self) -> Dict[str, Dict]:
+        """Load root cause analysis framework definitions."""
+        return {
+            "five_whys": {
+                "name": "5 Whys Analysis",
+                "description": "Iterative questioning technique to explore cause-and-effect relationships",
+                "steps": [
+                    "State the problem clearly",
+                    "Ask why the problem occurred",
+                    "For each answer, ask why again",
+                    "Continue until root cause is identified",
+                    "Verify the root cause addresses the original problem"
+                ],
+                "min_iterations": 3,
+                "max_iterations": 7
+            },
+            "fishbone": {
+                "name": "Fishbone (Ishikawa) Diagram",
+                "description": "Systematic analysis across multiple categories of potential causes",
+                "categories": [
+                    {
+                        "name": "People",
+                        "description": "Human factors, training, communication, experience",
+                        "examples": ["Training gaps", "Communication failures", "Skill deficits", "Staffing issues"]
+                    },
+                    {
+                        "name": "Process",
+                        "description": "Procedures, workflows, change management, review processes",
+                        "examples": ["Missing procedures", "Inadequate reviews", "Change management gaps", "Documentation issues"]
+                    },
+                    {
+                        "name": "Technology",
+                        "description": "Systems, tools, architecture, automation",
+                        "examples": ["Architecture limitations", "Tool deficiencies", "Automation gaps", "Infrastructure issues"]
+                    },
+                    {
+                        "name": "Environment",
+                        "description": "External factors, dependencies, infrastructure",
+                        "examples": ["Third-party dependencies", "Network issues", "Hardware failures", "External service outages"]
+                    }
+                ]
+            },
+            "timeline": {
+                "name": "Timeline Analysis",
+                "description": "Chronological analysis of events to identify decision points and missed opportunities",
+                "focus_areas": [
+                    "Detection timing and effectiveness",
+                    "Response time and escalation paths",
+                    "Decision points and alternative paths",
+                    "Communication effectiveness",
+                    "Mitigation strategy effectiveness"
+                ]
+            },
+            "bow_tie": {
+                "name": "Bow Tie Analysis",
+                "description": "Analysis of both preventive and protective measures around an incident",
+                "components": [
+                    "Hazards (what could go wrong)",
+                    "Top events (what actually went wrong)",
+                    "Threats (what caused it)",
+                    "Consequences (what was the impact)",
+                    "Barriers (what preventive/protective measures exist or could exist)"
+                ]
+            }
+        }
+    
+    def _load_pir_templates(self) -> Dict[str, str]:
+        """Load PIR document templates for different severity levels."""
+        return {
+            "comprehensive": """# Post-Incident Review: {incident_title}
+
+## Executive Summary
+{executive_summary}
+
+## Incident Overview
+- **Incident ID:** {incident_id}
+- **Date & Time:** {incident_date}
+- **Duration:** {duration}
+- **Severity:** {severity}
+- **Status:** {status}
+- **Incident Commander:** {incident_commander}
+- **Responders:** {responders}
+
+### Customer Impact
+{customer_impact}
+
+### Business Impact  
+{business_impact}
+
+## Timeline
+{timeline_section}
+
+## Root Cause Analysis
+{rca_section}
+
+## What Went Well
+{what_went_well}
+
+## What Didn't Go Well
+{what_went_wrong}
+
+## Lessons Learned
+{lessons_learned}
+
+## Action Items
+{action_items}
+
+## Follow-up and Prevention
+{prevention_measures}
+
+## Appendix
+{appendix_section}
+
+---
+*Generated on {generation_date} by PIR Generator*
+""",
+            "standard": """# Post-Incident Review: {incident_title}
+
+## Summary
+{executive_summary}
+
+## Incident Details
+- **Date:** {incident_date}
+- **Duration:** {duration}  
+- **Severity:** {severity}
+- **Impact:** {customer_impact}
+
+## Timeline
+{timeline_section}
+
+## Root Cause
+{rca_section}
+
+## Action Items
+{action_items}
+
+## Lessons Learned
+{lessons_learned}
+
+---
+*Generated on {generation_date}*
+""",
+            "brief": """# Incident Review: {incident_title}
+
+**Date:** {incident_date} | **Duration:** {duration} | **Severity:** {severity}
+
+## What Happened
+{executive_summary}
+
+## Root Cause
+{rca_section}
+
+## Actions
+{action_items}
+
+---
+*{generation_date}*
+"""
+        }
+    
+    def _load_severity_guidelines(self) -> Dict[str, Dict]:
+        """Load severity-specific PIR guidelines."""
+        return {
+            "sev1": {
+                "required_sections": ["executive_summary", "timeline", "rca", "action_items", "lessons_learned"],
+                "required_attendees": ["incident_commander", "technical_leads", "engineering_manager", "product_manager"],
+                "timeline_requirement": "Complete timeline with 15-minute intervals",
+                "rca_methods": ["five_whys", "fishbone", "timeline"],
+                "review_deadline_hours": 24,
+                "follow_up_weeks": 4
+            },
+            "sev2": {
+                "required_sections": ["summary", "timeline", "rca", "action_items"],
+                "required_attendees": ["incident_commander", "technical_leads", "team_lead"],
+                "timeline_requirement": "Key milestone timeline",
+                "rca_methods": ["five_whys", "timeline"],
+                "review_deadline_hours": 72,
+                "follow_up_weeks": 2
+            },
+            "sev3": {
+                "required_sections": ["summary", "rca", "action_items"],
+                "required_attendees": ["technical_lead", "team_member"],
+                "timeline_requirement": "Basic timeline",
+                "rca_methods": ["five_whys"],
+                "review_deadline_hours": 168,  # 1 week
+                "follow_up_weeks": 1
+            },
+            "sev4": {
+                "required_sections": ["summary", "action_items"],
+                "required_attendees": ["assigned_engineer"],
+                "timeline_requirement": "Optional",
+                "rca_methods": ["brief_analysis"],
+                "review_deadline_hours": 336,  # 2 weeks
+                "follow_up_weeks": 0
+            }
+        }
+    
+    def _load_action_item_types(self) -> Dict[str, Dict]:
+        """Load action item categorization and templates."""
+        return {
+            "immediate_fix": {
+                "priority": "P0",
+                "timeline": "24-48 hours",
+                "description": "Critical bugs or security issues that need immediate attention",
+                "template": "Fix {issue_description} to prevent recurrence of {incident_type}",
+                "owners": ["engineer", "team_lead"]
+            },
+            "process_improvement": {
+                "priority": "P1",
+                "timeline": "1-2 weeks",
+                "description": "Process gaps or communication issues identified",
+                "template": "Improve {process_area} to address {gap_description}",
+                "owners": ["team_lead", "process_owner"]
+            },
+            "monitoring_alerting": {
+                "priority": "P1",
+                "timeline": "1 week",
+                "description": "Missing monitoring or alerting capabilities",
+                "template": "Implement {monitoring_type} for {system_component}",
+                "owners": ["sre", "engineer"]
+            },
+            "documentation": {
+                "priority": "P2",
+                "timeline": "2-3 weeks", 
+                "description": "Documentation gaps or runbook updates",
+                "template": "Update {documentation_type} to include {missing_information}",
+                "owners": ["technical_writer", "engineer"]
+            },
+            "training": {
+                "priority": "P2",
+                "timeline": "1 month",
+                "description": "Training needs or knowledge gaps",
+                "template": "Provide {training_type} training on {topic}",
+                "owners": ["training_coordinator", "subject_matter_expert"]
+            },
+            "architectural": {
+                "priority": "P1-P3",
+                "timeline": "1-3 months",
+                "description": "System design or architecture improvements",
+                "template": "Redesign {system_component} to improve {quality_attribute}",
+                "owners": ["architect", "engineering_manager"]
+            },
+            "tooling": {
+                "priority": "P2",
+                "timeline": "2-4 weeks",
+                "description": "Tool improvements or new tool requirements",
+                "template": "Implement {tool_type} to support {use_case}",
+                "owners": ["devops", "engineer"]
+            }
+        }
+    
+    def _load_lessons_learned_categories(self) -> Dict[str, List[str]]:
+        """Load categories for organizing lessons learned."""
+        return {
+            "detection_and_monitoring": [
+                "Monitoring gaps identified",
+                "Alert fatigue issues",
+                "Detection timing improvements",
+                "Observability enhancements"
+            ],
+            "response_and_escalation": [
+                "Response time improvements",
+                "Escalation path optimization",
+                "Communication effectiveness",
+                "Resource allocation lessons"
+            ],
+            "technical_systems": [
+                "Architecture resilience",
+                "Failure mode analysis",
+                "Performance bottlenecks",
+                "Dependency management"
+            ],
+            "process_and_procedures": [
+                "Runbook effectiveness",
+                "Change management gaps",
+                "Review process improvements",
+                "Documentation quality"
+            ],
+            "team_and_culture": [
+                "Training needs identified",
+                "Cross-team collaboration",
+                "Knowledge sharing gaps",
+                "Decision-making processes"
+            ]
+        }
+    
+    def generate_pir(self, incident_data: Dict[str, Any], timeline_data: Optional[Dict] = None,
+                    rca_method: str = "five_whys", template_type: str = "comprehensive") -> Dict[str, Any]:
+        """
+        Generate a comprehensive PIR document from incident data.
+        
+        Args:
+            incident_data: Core incident information
+            timeline_data: Optional timeline reconstruction data
+            rca_method: RCA framework to use
+            template_type: PIR template type (comprehensive, standard, brief)
+            
+        Returns:
+            Dictionary containing PIR document and metadata
+        """
+        # Extract incident information
+        incident_info = self._extract_incident_info(incident_data)
+        
+        # Generate root cause analysis
+        rca_results = self._perform_rca(incident_data, timeline_data, rca_method)
+        
+        # Generate lessons learned
+        lessons_learned = self._generate_lessons_learned(incident_data, timeline_data, rca_results)
+        
+        # Generate action items
+        action_items = self._generate_action_items(incident_data, rca_results, lessons_learned)
+        
+        # Create timeline section
+        timeline_section = self._create_timeline_section(timeline_data, incident_info["severity"])
+        
+        # Generate document sections
+        sections = self._generate_document_sections(
+            incident_info, rca_results, lessons_learned, action_items, timeline_section
+        )
+        
+        # Build final document
+        template = self.pir_templates[template_type]
+        pir_document = template.format(**sections)
+        
+        # Generate metadata
+        metadata = self._generate_metadata(incident_info, rca_results, action_items)
+        
+        return {
+            "pir_document": pir_document,
+            "metadata": metadata,
+            "incident_info": incident_info,
+            "rca_results": rca_results,
+            "lessons_learned": lessons_learned,
+            "action_items": action_items,
+            "generation_timestamp": datetime.now(timezone.utc).isoformat()
+        }
+    
+    def _extract_incident_info(self, incident_data: Dict) -> Dict[str, Any]:
+        """Extract and normalize incident information."""
+        return {
+            "incident_id": incident_data.get("incident_id", "INC-" + datetime.now().strftime("%Y%m%d-%H%M")),
+            "title": incident_data.get("title", incident_data.get("description", "Incident")[:50]),
+            "description": incident_data.get("description", "No description provided"),
+            "severity": incident_data.get("severity", "unknown").lower(),
+            "start_time": self._parse_timestamp(incident_data.get("start_time", incident_data.get("timestamp", ""))),
+            "end_time": self._parse_timestamp(incident_data.get("end_time", "")),
+            "duration": self._calculate_duration(incident_data),
+            "affected_services": incident_data.get("affected_services", []),
+            "customer_impact": incident_data.get("customer_impact", "Unknown impact"),
+            "business_impact": incident_data.get("business_impact", "Unknown business impact"),
+            "incident_commander": incident_data.get("incident_commander", "TBD"),
+            "responders": incident_data.get("responders", []),
+            "status": incident_data.get("status", "resolved")
+        }
+    
+    def _parse_timestamp(self, timestamp_str: str) -> Optional[datetime]:
+        """Parse timestamp string to datetime object."""
+        if not timestamp_str:
+            return None
+        
+        formats = [
+            "%Y-%m-%dT%H:%M:%S.%fZ",
+            "%Y-%m-%dT%H:%M:%SZ",
+            "%Y-%m-%d %H:%M:%S",
+            "%m/%d/%Y %H:%M:%S"
+        ]
+        
+        for fmt in formats:
+            try:
+                dt = datetime.strptime(timestamp_str, fmt)
+                if dt.tzinfo is None:
+                    dt = dt.replace(tzinfo=timezone.utc)
+                return dt
+            except ValueError:
+                continue
+        
+        return None
+    
+    def _calculate_duration(self, incident_data: Dict) -> str:
+        """Calculate incident duration in human-readable format."""
+        start_time = self._parse_timestamp(incident_data.get("start_time", ""))
+        end_time = self._parse_timestamp(incident_data.get("end_time", ""))
+        
+        if start_time and end_time:
+            duration = end_time - start_time
+            total_minutes = int(duration.total_seconds() / 60)
+            
+            if total_minutes < 60:
+                return f"{total_minutes} minutes"
+            elif total_minutes < 1440:  # Less than 24 hours
+                hours = total_minutes // 60
+                minutes = total_minutes % 60
+                return f"{hours}h {minutes}m"
+            else:
+                days = total_minutes // 1440
+                hours = (total_minutes % 1440) // 60
+                return f"{days}d {hours}h"
+        
+        return incident_data.get("duration", "Unknown duration")
+    
+    def _perform_rca(self, incident_data: Dict, timeline_data: Optional[Dict], method: str) -> Dict[str, Any]:
+        """Perform root cause analysis using specified method."""
+        if method == "five_whys":
+            return self._five_whys_analysis(incident_data, timeline_data)
+        elif method == "fishbone":
+            return self._fishbone_analysis(incident_data, timeline_data)
+        elif method == "timeline":
+            return self._timeline_analysis(incident_data, timeline_data)
+        elif method == "bow_tie":
+            return self._bow_tie_analysis(incident_data, timeline_data)
+        else:
+            return self._five_whys_analysis(incident_data, timeline_data)  # Default
+    
+    def _five_whys_analysis(self, incident_data: Dict, timeline_data: Optional[Dict]) -> Dict[str, Any]:
+        """Perform 5 Whys root cause analysis."""
+        problem_statement = incident_data.get("description", "Incident occurred")
+        
+        # Generate why questions based on incident data
+        whys = []
+        current_issue = problem_statement
+        
+        # Generate systematic why questions
+        why_patterns = [
+            f"Why did {current_issue}?",
+            "Why wasn't this detected earlier?",
+            "Why didn't existing safeguards prevent this?",
+            "Why wasn't there a backup mechanism?",
+            "Why wasn't this scenario anticipated?"
+        ]
+        
+        # Try to infer answers from incident data
+        potential_answers = self._infer_why_answers(incident_data, timeline_data)
+        
+        for i, why_question in enumerate(why_patterns):
+            answer = potential_answers[i] if i < len(potential_answers) else "Further investigation needed"
+            whys.append({
+                "question": why_question,
+                "answer": answer,
+                "evidence": self._find_supporting_evidence(answer, incident_data, timeline_data)
+            })
+        
+        # Identify root causes from the analysis
+        root_causes = self._extract_root_causes(whys)
+        
+        return {
+            "method": "five_whys",
+            "problem_statement": problem_statement,
+            "why_analysis": whys,
+            "root_causes": root_causes,
+            "confidence": self._calculate_rca_confidence(whys, incident_data)
+        }
+    
+    def _fishbone_analysis(self, incident_data: Dict, timeline_data: Optional[Dict]) -> Dict[str, Any]:
+        """Perform Fishbone (Ishikawa) diagram analysis."""
+        problem_statement = incident_data.get("description", "Incident occurred")
+        
+        # Analyze each category
+        categories = {}
+        for category_info in self.rca_frameworks["fishbone"]["categories"]:
+            category_name = category_info["name"]
+            contributing_factors = self._identify_category_factors(
+                category_name, incident_data, timeline_data
+            )
+            categories[category_name] = {
+                "description": category_info["description"],
+                "factors": contributing_factors,
+                "examples": category_info["examples"]
+            }
+        
+        # Identify primary contributing factors
+        primary_factors = self._identify_primary_factors(categories)
+        
+        # Generate root cause hypothesis
+        root_causes = self._synthesize_fishbone_root_causes(categories, primary_factors)
+        
+        return {
+            "method": "fishbone",
+            "problem_statement": problem_statement,
+            "categories": categories,
+            "primary_factors": primary_factors,
+            "root_causes": root_causes,
+            "confidence": self._calculate_rca_confidence(categories, incident_data)
+        }
+    
+    def _timeline_analysis(self, incident_data: Dict, timeline_data: Optional[Dict]) -> Dict[str, Any]:
+        """Perform timeline-based root cause analysis."""
+        if not timeline_data:
+            return {"method": "timeline", "error": "No timeline data provided"}
+        
+        # Extract key decision points
+        decision_points = self._extract_decision_points(timeline_data)
+        
+        # Identify missed opportunities
+        missed_opportunities = self._identify_missed_opportunities(timeline_data)
+        
+        # Analyze response effectiveness
+        response_analysis = self._analyze_response_effectiveness(timeline_data)
+        
+        # Generate timeline-based root causes
+        root_causes = self._extract_timeline_root_causes(
+            decision_points, missed_opportunities, response_analysis
+        )
+        
+        return {
+            "method": "timeline",
+            "decision_points": decision_points,
+            "missed_opportunities": missed_opportunities,
+            "response_analysis": response_analysis,
+            "root_causes": root_causes,
+            "confidence": self._calculate_rca_confidence(timeline_data, incident_data)
+        }
+    
+    def _bow_tie_analysis(self, incident_data: Dict, timeline_data: Optional[Dict]) -> Dict[str, Any]:
+        """Perform Bow Tie analysis."""
+        # Identify the top event (what went wrong)
+        top_event = incident_data.get("description", "Service failure")
+        
+        # Identify threats (what caused it)
+        threats = self._identify_threats(incident_data, timeline_data)
+        
+        # Identify consequences (impact)
+        consequences = self._identify_consequences(incident_data)
+        
+        # Identify existing barriers
+        existing_barriers = self._identify_existing_barriers(incident_data, timeline_data)
+        
+        # Recommend additional barriers
+        recommended_barriers = self._recommend_additional_barriers(threats, consequences)
+        
+        return {
+            "method": "bow_tie",
+            "top_event": top_event,
+            "threats": threats,
+            "consequences": consequences,
+            "existing_barriers": existing_barriers,
+            "recommended_barriers": recommended_barriers,
+            "confidence": self._calculate_rca_confidence(threats, incident_data)
+        }
+    
+    def _infer_why_answers(self, incident_data: Dict, timeline_data: Optional[Dict]) -> List[str]:
+        """Infer potential answers to why questions from available data."""
+        answers = []
+        
+        # Look for clues in incident description
+        description = incident_data.get("description", "").lower()
+        
+        # Common patterns and their inferred answers
+        if "database" in description and ("timeout" in description or "slow" in description):
+            answers.append("Database connection pool was exhausted")
+            answers.append("Connection pool configuration was insufficient for peak load")
+            answers.append("Load testing didn't include realistic database scenarios")
+        elif "deployment" in description or "release" in description:
+            answers.append("New deployment introduced a regression")
+            answers.append("Code review process missed the issue")
+            answers.append("Testing environment didn't match production")
+        elif "network" in description or "connectivity" in description:
+            answers.append("Network infrastructure had unexpected load")
+            answers.append("Network monitoring wasn't comprehensive enough")
+            answers.append("Redundancy mechanisms failed simultaneously")
+        else:
+            # Generic answers based on common root causes
+            answers.extend([
+                "System couldn't handle the load/request volume",
+                "Monitoring didn't detect the issue early enough",
+                "Error handling mechanisms were insufficient",
+                "Dependencies failed without proper circuit breakers",
+                "System lacked sufficient redundancy/resilience"
+            ])
+        
+        return answers[:5]  # Return up to 5 answers
+    
+    def _find_supporting_evidence(self, answer: str, incident_data: Dict, timeline_data: Optional[Dict]) -> List[str]:
+        """Find supporting evidence for RCA answers."""
+        evidence = []
+        
+        # Look for supporting information in incident data
+        if timeline_data and "timeline" in timeline_data:
+            events = timeline_data["timeline"].get("events", [])
+            for event in events:
+                event_message = event.get("message", "").lower()
+                if any(keyword in event_message for keyword in answer.lower().split()):
+                    evidence.append(f"Timeline event: {event['message']}")
+        
+        # Check incident metadata for supporting info
+        metadata = incident_data.get("metadata", {})
+        for key, value in metadata.items():
+            if isinstance(value, str) and any(keyword in value.lower() for keyword in answer.lower().split()):
+                evidence.append(f"Incident metadata: {key} = {value}")
+        
+        return evidence[:3]  # Return top 3 pieces of evidence
+    
+    def _extract_root_causes(self, whys: List[Dict]) -> List[Dict]:
+        """Extract root causes from 5 Whys analysis."""
+        root_causes = []
+        
+        # The deepest "why" answers are typically closest to root causes
+        if len(whys) >= 3:
+            for i, why in enumerate(whys[-2:]):  # Look at last 2 whys
+                if "further investigation needed" not in why["answer"].lower():
+                    root_causes.append({
+                        "cause": why["answer"],
+                        "category": self._categorize_root_cause(why["answer"]),
+                        "evidence": why["evidence"],
+                        "confidence": "high" if len(why["evidence"]) > 1 else "medium"
+                    })
+        
+        return root_causes
+    
+    def _categorize_root_cause(self, cause: str) -> str:
+        """Categorize a root cause into standard categories."""
+        cause_lower = cause.lower()
+        
+        if any(keyword in cause_lower for keyword in ["process", "procedure", "review", "change management"]):
+            return "Process"
+        elif any(keyword in cause_lower for keyword in ["training", "knowledge", "skill", "experience"]):
+            return "People"
+        elif any(keyword in cause_lower for keyword in ["system", "architecture", "code", "configuration"]):
+            return "Technology"
+        elif any(keyword in cause_lower for keyword in ["network", "infrastructure", "dependency", "third-party"]):
+            return "Environment"
+        else:
+            return "Unknown"
+    
+    def _identify_category_factors(self, category: str, incident_data: Dict, timeline_data: Optional[Dict]) -> List[Dict]:
+        """Identify contributing factors for a Fishbone category."""
+        factors = []
+        description = incident_data.get("description", "").lower()
+        
+        if category == "People":
+            if "misconfigured" in description or "human error" in description:
+                factors.append({"factor": "Configuration error", "likelihood": "high"})
+            if timeline_data and self._has_delayed_response(timeline_data):
+                factors.append({"factor": "Delayed incident response", "likelihood": "medium"})
+            
+        elif category == "Process":
+            if "deployment" in description:
+                factors.append({"factor": "Insufficient deployment validation", "likelihood": "high"})
+            if "code review" in incident_data.get("context", "").lower():
+                factors.append({"factor": "Code review process gaps", "likelihood": "medium"})
+            
+        elif category == "Technology":
+            if "database" in description:
+                factors.append({"factor": "Database performance limitations", "likelihood": "high"})
+            if "timeout" in description or "latency" in description:
+                factors.append({"factor": "System performance bottlenecks", "likelihood": "high"})
+            
+        elif category == "Environment":
+            if "network" in description:
+                factors.append({"factor": "Network infrastructure issues", "likelihood": "medium"})
+            if "third-party" in description or "external" in description:
+                factors.append({"factor": "External service dependencies", "likelihood": "medium"})
+        
+        return factors
+    
+    def _identify_primary_factors(self, categories: Dict) -> List[Dict]:
+        """Identify primary contributing factors across all categories."""
+        primary_factors = []
+        
+        for category_name, category_data in categories.items():
+            high_likelihood_factors = [
+                f for f in category_data["factors"] 
+                if f.get("likelihood") == "high"
+            ]
+            primary_factors.extend([
+                {**factor, "category": category_name} 
+                for factor in high_likelihood_factors
+            ])
+        
+        return primary_factors
+    
+    def _synthesize_fishbone_root_causes(self, categories: Dict, primary_factors: List[Dict]) -> List[Dict]:
+        """Synthesize root causes from Fishbone analysis."""
+        root_causes = []
+        
+        # Group primary factors by category
+        category_factors = defaultdict(list)
+        for factor in primary_factors:
+            category_factors[factor["category"]].append(factor)
+        
+        # Create root causes from categories with multiple factors
+        for category, factors in category_factors.items():
+            if len(factors) > 1:
+                root_causes.append({
+                    "cause": f"Multiple {category.lower()} issues contributed to the incident",
+                    "category": category,
+                    "contributing_factors": [f["factor"] for f in factors],
+                    "confidence": "high"
+                })
+            elif len(factors) == 1:
+                root_causes.append({
+                    "cause": factors[0]["factor"],
+                    "category": category,
+                    "confidence": "medium"
+                })
+        
+        return root_causes
+    
+    def _has_delayed_response(self, timeline_data: Dict) -> bool:
+        """Check if timeline shows delayed response patterns."""
+        if not timeline_data or "gap_analysis" not in timeline_data:
+            return False
+        
+        gaps = timeline_data["gap_analysis"].get("gaps", [])
+        return any(gap.get("type") == "phase_transition" for gap in gaps)
+    
+    def _extract_decision_points(self, timeline_data: Dict) -> List[Dict]:
+        """Extract key decision points from timeline."""
+        decision_points = []
+        
+        if "timeline" in timeline_data and "phases" in timeline_data["timeline"]:
+            phases = timeline_data["timeline"]["phases"]
+            
+            for i, phase in enumerate(phases):
+                if phase["name"] in ["escalation", "mitigation"]:
+                    decision_points.append({
+                        "timestamp": phase["start_time"],
+                        "decision": f"Initiated {phase['name']} phase",
+                        "phase": phase["name"],
+                        "duration": phase["duration_minutes"]
+                    })
+        
+        return decision_points
+    
+    def _identify_missed_opportunities(self, timeline_data: Dict) -> List[Dict]:
+        """Identify missed opportunities from gap analysis."""
+        missed_opportunities = []
+        
+        if "gap_analysis" in timeline_data:
+            gaps = timeline_data["gap_analysis"].get("gaps", [])
+            
+            for gap in gaps:
+                if gap.get("severity") == "critical":
+                    missed_opportunities.append({
+                        "opportunity": f"Earlier {gap['type'].replace('_', ' ')}",
+                        "gap_minutes": gap["gap_minutes"],
+                        "potential_impact": "Could have reduced incident duration"
+                    })
+        
+        return missed_opportunities
+    
+    def _analyze_response_effectiveness(self, timeline_data: Dict) -> Dict[str, Any]:
+        """Analyze the effectiveness of incident response."""
+        effectiveness = {
+            "overall_rating": "unknown",
+            "strengths": [],
+            "weaknesses": [],
+            "metrics": {}
+        }
+        
+        if "metrics" in timeline_data:
+            metrics = timeline_data["metrics"]
+            duration_metrics = metrics.get("duration_metrics", {})
+            
+            # Analyze response times
+            time_to_mitigation = duration_metrics.get("time_to_mitigation_minutes", 0)
+            time_to_resolution = duration_metrics.get("time_to_resolution_minutes", 0)
+            
+            if time_to_mitigation <= 30:
+                effectiveness["strengths"].append("Quick mitigation response")
+            else:
+                effectiveness["weaknesses"].append("Slow mitigation response")
+            
+            if time_to_resolution <= 120:
+                effectiveness["strengths"].append("Fast resolution")
+            else:
+                effectiveness["weaknesses"].append("Extended resolution time")
+            
+            effectiveness["metrics"] = {
+                "time_to_mitigation": time_to_mitigation,
+                "time_to_resolution": time_to_resolution
+            }
+        
+        # Overall rating based on strengths vs weaknesses
+        if len(effectiveness["strengths"]) > len(effectiveness["weaknesses"]):
+            effectiveness["overall_rating"] = "effective"
+        elif len(effectiveness["weaknesses"]) > len(effectiveness["strengths"]):
+            effectiveness["overall_rating"] = "needs_improvement"
+        else:
+            effectiveness["overall_rating"] = "mixed"
+        
+        return effectiveness
+    
+    def _extract_timeline_root_causes(self, decision_points: List, missed_opportunities: List, 
+                                    response_analysis: Dict) -> List[Dict]:
+        """Extract root causes from timeline analysis."""
+        root_causes = []
+        
+        # Root causes from missed opportunities
+        for opportunity in missed_opportunities:
+            if opportunity["gap_minutes"] > 60:  # Significant gaps
+                root_causes.append({
+                    "cause": f"Delayed response: {opportunity['opportunity']}",
+                    "category": "Process",
+                    "evidence": f"{opportunity['gap_minutes']} minute gap identified",
+                    "confidence": "high"
+                })
+        
+        # Root causes from response effectiveness
+        for weakness in response_analysis.get("weaknesses", []):
+            root_causes.append({
+                "cause": weakness,
+                "category": "Process",
+                "evidence": "Timeline analysis",
+                "confidence": "medium"
+            })
+        
+        return root_causes
+    
+    def _identify_threats(self, incident_data: Dict, timeline_data: Optional[Dict]) -> List[Dict]:
+        """Identify threats for Bow Tie analysis."""
+        threats = []
+        description = incident_data.get("description", "").lower()
+        
+        if "deployment" in description:
+            threats.append({"threat": "Defective code deployment", "likelihood": "medium"})
+        if "load" in description or "traffic" in description:
+            threats.append({"threat": "Unexpected load increase", "likelihood": "high"})
+        if "database" in description:
+            threats.append({"threat": "Database performance degradation", "likelihood": "medium"})
+        
+        return threats
+    
+    def _identify_consequences(self, incident_data: Dict) -> List[Dict]:
+        """Identify consequences for Bow Tie analysis."""
+        consequences = []
+        
+        customer_impact = incident_data.get("customer_impact", "").lower()
+        business_impact = incident_data.get("business_impact", "").lower()
+        
+        if "all users" in customer_impact or "complete outage" in customer_impact:
+            consequences.append({"consequence": "Complete service unavailability", "severity": "critical"})
+        
+        if "revenue" in business_impact:
+            consequences.append({"consequence": "Revenue loss", "severity": "high"})
+        
+        return consequences
+    
+    def _identify_existing_barriers(self, incident_data: Dict, timeline_data: Optional[Dict]) -> List[Dict]:
+        """Identify existing preventive/protective barriers."""
+        barriers = []
+        
+        # Look for evidence of existing controls
+        if timeline_data and "timeline" in timeline_data:
+            events = timeline_data["timeline"].get("events", [])
+            
+            for event in events:
+                message = event.get("message", "").lower()
+                if "alert" in message or "monitoring" in message:
+                    barriers.append({
+                        "barrier": "Monitoring and alerting system",
+                        "type": "detective",
+                        "effectiveness": "partial"
+                    })
+                elif "rollback" in message:
+                    barriers.append({
+                        "barrier": "Rollback capability", 
+                        "type": "corrective",
+                        "effectiveness": "effective"
+                    })
+        
+        return barriers
+    
+    def _recommend_additional_barriers(self, threats: List[Dict], consequences: List[Dict]) -> List[Dict]:
+        """Recommend additional barriers based on threats and consequences."""
+        recommendations = []
+        
+        for threat in threats:
+            if "deployment" in threat["threat"].lower():
+                recommendations.append({
+                    "barrier": "Enhanced pre-deployment testing",
+                    "type": "preventive",
+                    "justification": "Prevent defective deployments reaching production"
+                })
+            elif "load" in threat["threat"].lower():
+                recommendations.append({
+                    "barrier": "Auto-scaling and load shedding",
+                    "type": "preventive",
+                    "justification": "Handle unexpected load increases automatically"
+                })
+        
+        return recommendations
+    
+    def _calculate_rca_confidence(self, analysis_data: Any, incident_data: Dict) -> str:
+        """Calculate confidence level for RCA results."""
+        # Simple heuristic based on available data
+        confidence_score = 0
+        
+        # More detailed incident data increases confidence
+        if incident_data.get("description") and len(incident_data["description"]) > 50:
+            confidence_score += 1
+        
+        if incident_data.get("timeline") or incident_data.get("events"):
+            confidence_score += 2
+        
+        if incident_data.get("logs") or incident_data.get("monitoring_data"):
+            confidence_score += 2
+        
+        # Analysis data completeness
+        if isinstance(analysis_data, list) and len(analysis_data) > 3:
+            confidence_score += 1
+        elif isinstance(analysis_data, dict) and len(analysis_data) > 5:
+            confidence_score += 1
+        
+        if confidence_score >= 4:
+            return "high"
+        elif confidence_score >= 2:
+            return "medium"
+        else:
+            return "low"
+    
+    def _generate_lessons_learned(self, incident_data: Dict, timeline_data: Optional[Dict], 
+                                rca_results: Dict) -> Dict[str, List[str]]:
+        """Generate categorized lessons learned."""
+        lessons = defaultdict(list)
+        
+        # Lessons from RCA
+        root_causes = rca_results.get("root_causes", [])
+        for root_cause in root_causes:
+            category = root_cause.get("category", "technical_systems").lower()
+            category_key = self._map_to_lessons_category(category)
+            
+            lesson = f"Identified: {root_cause['cause']}"
+            lessons[category_key].append(lesson)
+        
+        # Lessons from timeline analysis
+        if timeline_data and "gap_analysis" in timeline_data:
+            gaps = timeline_data["gap_analysis"].get("gaps", [])
+            for gap in gaps:
+                if gap.get("severity") == "critical":
+                    lessons["response_and_escalation"].append(
+                        f"Response time gap: {gap['type'].replace('_', ' ')} took {gap['gap_minutes']} minutes"
+                    )
+        
+        # Generic lessons based on incident characteristics
+        severity = incident_data.get("severity", "").lower()
+        if severity in ["sev1", "critical"]:
+            lessons["detection_and_monitoring"].append(
+                "Critical incidents require immediate detection and alerting"
+            )
+        
+        return dict(lessons)
+    
+    def _map_to_lessons_category(self, category: str) -> str:
+        """Map RCA category to lessons learned category."""
+        mapping = {
+            "people": "team_and_culture",
+            "process": "process_and_procedures", 
+            "technology": "technical_systems",
+            "environment": "technical_systems",
+            "unknown": "process_and_procedures"
+        }
+        return mapping.get(category, "technical_systems")
+    
+    def _generate_action_items(self, incident_data: Dict, rca_results: Dict, 
+                             lessons_learned: Dict) -> List[Dict]:
+        """Generate actionable follow-up items."""
+        action_items = []
+        
+        # Actions from root causes
+        root_causes = rca_results.get("root_causes", [])
+        for root_cause in root_causes:
+            action_type = self._determine_action_type(root_cause)
+            action_template = self.action_item_types[action_type]
+            
+            action_items.append({
+                "title": f"Address: {root_cause['cause'][:50]}...",
+                "description": root_cause["cause"],
+                "type": action_type,
+                "priority": action_template["priority"],
+                "timeline": action_template["timeline"],
+                "owner": "TBD",
+                "success_criteria": f"Prevent recurrence of {root_cause['cause'][:30]}...",
+                "related_root_cause": root_cause
+            })
+        
+        # Actions from lessons learned
+        for category, lessons in lessons_learned.items():
+            if len(lessons) > 1:  # Multiple lessons in same category indicate systematic issue
+                action_items.append({
+                    "title": f"Improve {category.replace('_', ' ')}",
+                    "description": f"Address multiple issues identified in {category}",
+                    "type": "process_improvement",
+                    "priority": "P1",
+                    "timeline": "2-3 weeks",
+                    "owner": "TBD",
+                    "success_criteria": f"Comprehensive review and improvement of {category}"
+                })
+        
+        # Standard actions based on severity
+        severity = incident_data.get("severity", "").lower()
+        if severity in ["sev1", "critical"]:
+            action_items.append({
+                "title": "Conduct comprehensive post-incident review",
+                "description": "Schedule PIR meeting with all stakeholders",
+                "type": "process_improvement",
+                "priority": "P0",
+                "timeline": "24-48 hours",
+                "owner": incident_data.get("incident_commander", "TBD"),
+                "success_criteria": "PIR completed and documented"
+            })
+        
+        return action_items
+    
+    def _determine_action_type(self, root_cause: Dict) -> str:
+        """Determine action item type based on root cause."""
+        cause_text = root_cause.get("cause", "").lower()
+        category = root_cause.get("category", "").lower()
+        
+        if any(keyword in cause_text for keyword in ["bug", "error", "failure", "crash"]):
+            return "immediate_fix"
+        elif any(keyword in cause_text for keyword in ["monitor", "alert", "detect"]):
+            return "monitoring_alerting"
+        elif any(keyword in cause_text for keyword in ["process", "procedure", "review"]):
+            return "process_improvement"
+        elif any(keyword in cause_text for keyword in ["document", "runbook", "knowledge"]):
+            return "documentation"
+        elif any(keyword in cause_text for keyword in ["training", "skill", "knowledge"]):
+            return "training"
+        elif any(keyword in cause_text for keyword in ["architecture", "design", "system"]):
+            return "architectural"
+        else:
+            return "process_improvement"  # Default
+    
+    def _create_timeline_section(self, timeline_data: Optional[Dict], severity: str) -> str:
+        """Create timeline section for PIR document."""
+        if not timeline_data:
+            return "No detailed timeline available."
+        
+        timeline_content = []
+        
+        if "timeline" in timeline_data and "phases" in timeline_data["timeline"]:
+            timeline_content.append("### Phase Timeline")
+            timeline_content.append("")
+            
+            phases = timeline_data["timeline"]["phases"]
+            for phase in phases:
+                timeline_content.append(f"**{phase['name'].title()} Phase**")
+                timeline_content.append(f"- Start: {phase['start_time']}")
+                timeline_content.append(f"- Duration: {phase['duration_minutes']} minutes")
+                timeline_content.append(f"- Events: {phase['event_count']}")
+                timeline_content.append("")
+        
+        if "metrics" in timeline_data:
+            metrics = timeline_data["metrics"]
+            duration_metrics = metrics.get("duration_metrics", {})
+            
+            timeline_content.append("### Key Metrics")
+            timeline_content.append("")
+            timeline_content.append(f"- Total Duration: {duration_metrics.get('total_duration_minutes', 'N/A')} minutes")
+            timeline_content.append(f"- Time to Mitigation: {duration_metrics.get('time_to_mitigation_minutes', 'N/A')} minutes")
+            timeline_content.append(f"- Time to Resolution: {duration_metrics.get('time_to_resolution_minutes', 'N/A')} minutes")
+            timeline_content.append("")
+        
+        return "\n".join(timeline_content)
+    
+    def _generate_document_sections(self, incident_info: Dict, rca_results: Dict, 
+                                  lessons_learned: Dict, action_items: List[Dict], 
+                                  timeline_section: str) -> Dict[str, str]:
+        """Generate all document sections for PIR template."""
+        sections = {}
+        
+        # Basic information
+        sections["incident_title"] = incident_info["title"]
+        sections["incident_id"] = incident_info["incident_id"]
+        sections["incident_date"] = incident_info["start_time"].strftime("%Y-%m-%d %H:%M:%S UTC") if incident_info["start_time"] else "Unknown"
+        sections["duration"] = incident_info["duration"]
+        sections["severity"] = incident_info["severity"].upper()
+        sections["status"] = incident_info["status"].title()
+        sections["incident_commander"] = incident_info["incident_commander"]
+        sections["responders"] = ", ".join(incident_info["responders"]) if incident_info["responders"] else "TBD"
+        sections["generation_date"] = datetime.now().strftime("%Y-%m-%d")
+        
+        # Impact sections
+        sections["customer_impact"] = incident_info["customer_impact"]
+        sections["business_impact"] = incident_info["business_impact"]
+        
+        # Executive summary
+        sections["executive_summary"] = self._create_executive_summary(incident_info, rca_results)
+        
+        # Timeline
+        sections["timeline_section"] = timeline_section
+        
+        # RCA section
+        sections["rca_section"] = self._create_rca_section(rca_results)
+        
+        # What went well/wrong
+        sections["what_went_well"] = self._create_what_went_well_section(incident_info, rca_results)
+        sections["what_went_wrong"] = self._create_what_went_wrong_section(rca_results, lessons_learned)
+        
+        # Lessons learned
+        sections["lessons_learned"] = self._create_lessons_learned_section(lessons_learned)
+        
+        # Action items
+        sections["action_items"] = self._create_action_items_section(action_items)
+        
+        # Prevention and appendix
+        sections["prevention_measures"] = self._create_prevention_section(rca_results, action_items)
+        sections["appendix_section"] = self._create_appendix_section(incident_info)
+        
+        return sections
+    
+    def _create_executive_summary(self, incident_info: Dict, rca_results: Dict) -> str:
+        """Create executive summary section."""
+        summary_parts = []
+        
+        # Incident description
+        summary_parts.append(f"On {incident_info['start_time'].strftime('%B %d, %Y') if incident_info['start_time'] else 'an unknown date'}, we experienced a {incident_info['severity']} incident affecting {incident_info.get('affected_services', ['our services'])}.")
+        
+        # Duration and impact
+        summary_parts.append(f"The incident lasted {incident_info['duration']} and had the following impact: {incident_info['customer_impact']}")
+        
+        # Root cause summary
+        root_causes = rca_results.get("root_causes", [])
+        if root_causes:
+            primary_cause = root_causes[0]["cause"]
+            summary_parts.append(f"Root cause analysis identified the primary issue as: {primary_cause}")
+        
+        # Resolution
+        summary_parts.append(f"The incident has been {incident_info['status']} and we have identified specific actions to prevent recurrence.")
+        
+        return " ".join(summary_parts)
+    
+    def _create_rca_section(self, rca_results: Dict) -> str:
+        """Create RCA section content."""
+        rca_content = []
+        
+        method = rca_results.get("method", "unknown")
+        rca_content.append(f"### Analysis Method: {self.rca_frameworks.get(method, {}).get('name', method)}")
+        rca_content.append("")
+        
+        if method == "five_whys" and "why_analysis" in rca_results:
+            rca_content.append("#### Why Analysis")
+            rca_content.append("")
+            
+            for i, why in enumerate(rca_results["why_analysis"], 1):
+                rca_content.append(f"**Why {i}:** {why['question']}")
+                rca_content.append(f"**Answer:** {why['answer']}")
+                if why["evidence"]:
+                    rca_content.append(f"**Evidence:** {', '.join(why['evidence'])}")
+                rca_content.append("")
+        
+        elif method == "fishbone" and "categories" in rca_results:
+            rca_content.append("#### Contributing Factor Analysis")
+            rca_content.append("")
+            
+            for category, data in rca_results["categories"].items():
+                if data["factors"]:
+                    rca_content.append(f"**{category}:**")
+                    for factor in data["factors"]:
+                        rca_content.append(f"- {factor['factor']} (likelihood: {factor.get('likelihood', 'unknown')})")
+                    rca_content.append("")
+        
+        # Root causes summary
+        root_causes = rca_results.get("root_causes", [])
+        if root_causes:
+            rca_content.append("#### Identified Root Causes")
+            rca_content.append("")
+            
+            for i, cause in enumerate(root_causes, 1):
+                rca_content.append(f"{i}. **{cause['cause']}**")
+                rca_content.append(f"   - Category: {cause.get('category', 'Unknown')}")
+                rca_content.append(f"   - Confidence: {cause.get('confidence', 'Unknown')}")
+                if cause.get("evidence"):
+                    rca_content.append(f"   - Evidence: {cause['evidence']}")
+                rca_content.append("")
+        
+        return "\n".join(rca_content)
+    
+    def _create_what_went_well_section(self, incident_info: Dict, rca_results: Dict) -> str:
+        """Create what went well section."""
+        positives = []
+        
+        # Generic positive aspects
+        if incident_info["status"] == "resolved":
+            positives.append("The incident was successfully resolved")
+        
+        if incident_info["incident_commander"] != "TBD":
+            positives.append("Incident command was established")
+        
+        if len(incident_info.get("responders", [])) > 1:
+            positives.append("Multiple team members collaborated on resolution")
+        
+        # Analysis-specific positives
+        if rca_results.get("confidence") == "high":
+            positives.append("Root cause analysis provided clear insights")
+        
+        if not positives:
+            positives.append("Incident response process was followed")
+        
+        return "\n".join([f"- {positive}" for positive in positives])
+    
+    def _create_what_went_wrong_section(self, rca_results: Dict, lessons_learned: Dict) -> str:
+        """Create what went wrong section."""
+        issues = []
+        
+        # Issues from RCA
+        root_causes = rca_results.get("root_causes", [])
+        for cause in root_causes[:3]:  # Show top 3
+            issues.append(cause["cause"])
+        
+        # Issues from lessons learned
+        for category, lessons in lessons_learned.items():
+            if lessons:
+                issues.append(f"{category.replace('_', ' ').title()}: {lessons[0]}")
+        
+        if not issues:
+            issues.append("Analysis in progress")
+        
+        return "\n".join([f"- {issue}" for issue in issues])
+    
+    def _create_lessons_learned_section(self, lessons_learned: Dict) -> str:
+        """Create lessons learned section."""
+        content = []
+        
+        for category, lessons in lessons_learned.items():
+            if lessons:
+                content.append(f"### {category.replace('_', ' ').title()}")
+                content.append("")
+                
+                for lesson in lessons:
+                    content.append(f"- {lesson}")
+                
+                content.append("")
+        
+        if not content:
+            content.append("Lessons learned to be documented following detailed analysis.")
+        
+        return "\n".join(content)
+    
+    def _create_action_items_section(self, action_items: List[Dict]) -> str:
+        """Create action items section."""
+        if not action_items:
+            return "Action items to be defined."
+        
+        content = []
+        
+        # Group by priority
+        priority_groups = defaultdict(list)
+        for item in action_items:
+            priority_groups[item.get("priority", "P3")].append(item)
+        
+        for priority in ["P0", "P1", "P2", "P3"]:
+            items = priority_groups.get(priority, [])
+            if items:
+                content.append(f"### {priority} - {self._get_priority_description(priority)}")
+                content.append("")
+                
+                for item in items:
+                    content.append(f"**{item['title']}**")
+                    content.append(f"- Owner: {item.get('owner', 'TBD')}")
+                    content.append(f"- Timeline: {item.get('timeline', 'TBD')}")
+                    content.append(f"- Success Criteria: {item.get('success_criteria', 'TBD')}")
+                    content.append("")
+        
+        return "\n".join(content)
+    
+    def _get_priority_description(self, priority: str) -> str:
+        """Get human-readable priority description."""
+        descriptions = {
+            "P0": "Critical - Immediate Action Required",
+            "P1": "High Priority - Complete Within 1-2 Weeks", 
+            "P2": "Medium Priority - Complete Within 1 Month",
+            "P3": "Low Priority - Complete When Capacity Allows"
+        }
+        return descriptions.get(priority, "Unknown Priority")
+    
+    def _create_prevention_section(self, rca_results: Dict, action_items: List[Dict]) -> str:
+        """Create prevention and follow-up section."""
+        content = []
+        
+        content.append("### Prevention Measures")
+        content.append("")
+        content.append("Based on the root cause analysis, the following preventive measures have been identified:")
+        content.append("")
+        
+        # Extract prevention-focused action items
+        prevention_items = [item for item in action_items if "prevent" in item.get("description", "").lower()]
+        
+        if prevention_items:
+            for item in prevention_items:
+                content.append(f"- {item['title']}: {item.get('description', '')}")
+        else:
+            content.append("- Implement comprehensive testing for similar scenarios")
+            content.append("- Improve monitoring and alerting coverage")  
+            content.append("- Enhance error handling and resilience patterns")
+        
+        content.append("")
+        content.append("### Follow-up Schedule")
+        content.append("")
+        content.append("- 1 week: Review action item progress")
+        content.append("- 1 month: Evaluate effectiveness of implemented changes")
+        content.append("- 3 months: Conduct follow-up assessment and update preventive measures")
+        
+        return "\n".join(content)
+    
+    def _create_appendix_section(self, incident_info: Dict) -> str:
+        """Create appendix section."""
+        content = []
+        
+        content.append("### Additional Information")
+        content.append("")
+        content.append(f"- Incident ID: {incident_info['incident_id']}")
+        content.append(f"- Severity Classification: {incident_info['severity']}")
+        
+        if incident_info.get("affected_services"):
+            content.append(f"- Affected Services: {', '.join(incident_info['affected_services'])}")
+        
+        content.append("")
+        content.append("### References")
+        content.append("")
+        content.append("- Incident tracking ticket: [Link TBD]")
+        content.append("- Monitoring dashboards: [Link TBD]")
+        content.append("- Communication thread: [Link TBD]")
+        
+        return "\n".join(content)
+    
+    def _generate_metadata(self, incident_info: Dict, rca_results: Dict, action_items: List[Dict]) -> Dict[str, Any]:
+        """Generate PIR metadata for tracking and analysis."""
+        return {
+            "pir_id": f"PIR-{incident_info['incident_id']}",
+            "incident_severity": incident_info["severity"],
+            "rca_method": rca_results.get("method", "unknown"),
+            "rca_confidence": rca_results.get("confidence", "unknown"),
+            "total_action_items": len(action_items),
+            "critical_action_items": len([item for item in action_items if item.get("priority") == "P0"]),
+            "estimated_prevention_timeline": self._estimate_prevention_timeline(action_items),
+            "categories_affected": list(set(item.get("type", "unknown") for item in action_items)),
+            "review_completeness": self._assess_review_completeness(incident_info, rca_results, action_items)
+        }
+    
+    def _estimate_prevention_timeline(self, action_items: List[Dict]) -> str:
+        """Estimate timeline for implementing all prevention measures."""
+        if not action_items:
+            return "unknown"
+        
+        # Find the longest timeline among action items
+        max_weeks = 0
+        for item in action_items:
+            timeline = item.get("timeline", "")
+            if "week" in timeline:
+                try:
+                    weeks = int(re.findall(r'\d+', timeline)[0])
+                    max_weeks = max(max_weeks, weeks)
+                except (IndexError, ValueError):
+                    pass
+            elif "month" in timeline:
+                try:
+                    months = int(re.findall(r'\d+', timeline)[0])
+                    max_weeks = max(max_weeks, months * 4)
+                except (IndexError, ValueError):
+                    pass
+        
+        if max_weeks == 0:
+            return "1-2 weeks"
+        elif max_weeks <= 4:
+            return f"{max_weeks} weeks"
+        else:
+            return f"{max_weeks // 4} months"
+    
+    def _assess_review_completeness(self, incident_info: Dict, rca_results: Dict, action_items: List[Dict]) -> float:
+        """Assess completeness of the PIR (0-1 score)."""
+        score = 0.0
+        
+        # Basic information completeness
+        if incident_info.get("description"):
+            score += 0.1
+        if incident_info.get("start_time"):
+            score += 0.1
+        if incident_info.get("customer_impact"):
+            score += 0.1
+        
+        # RCA completeness
+        if rca_results.get("root_causes"):
+            score += 0.2
+        if rca_results.get("confidence") in ["medium", "high"]:
+            score += 0.1
+        
+        # Action items completeness
+        if action_items:
+            score += 0.2
+        if any(item.get("owner") and item["owner"] != "TBD" for item in action_items):
+            score += 0.1
+        
+        # Additional factors
+        if incident_info.get("incident_commander") != "TBD":
+            score += 0.1
+        if len(action_items) >= 3:  # Multiple action items show thorough analysis
+            score += 0.1
+        
+        return min(score, 1.0)
+
+
+def format_json_output(result: Dict) -> str:
+    """Format result as pretty JSON."""
+    return json.dumps(result, indent=2, ensure_ascii=False)
+
+
+def format_markdown_output(result: Dict) -> str:
+    """Format result as Markdown PIR document."""
+    return result.get("pir_document", "Error: No PIR document generated")
+
+
+def format_text_output(result: Dict) -> str:
+    """Format result as human-readable summary."""
+    if "error" in result:
+        return f"Error: {result['error']}"
+    
+    metadata = result.get("metadata", {})
+    incident_info = result.get("incident_info", {})
+    rca_results = result.get("rca_results", {})
+    action_items = result.get("action_items", [])
+    
+    output = []
+    output.append("=" * 60)
+    output.append("POST-INCIDENT REVIEW SUMMARY")  
+    output.append("=" * 60)
+    output.append("")
+    
+    # Basic info
+    output.append("INCIDENT INFORMATION:")
+    output.append(f"  PIR ID: {metadata.get('pir_id', 'Unknown')}")
+    output.append(f"  Severity: {incident_info.get('severity', 'Unknown').upper()}")
+    output.append(f"  Duration: {incident_info.get('duration', 'Unknown')}")
+    output.append(f"  Status: {incident_info.get('status', 'Unknown').title()}")
+    output.append("")
+    
+    # RCA summary
+    output.append("ROOT CAUSE ANALYSIS:")
+    output.append(f"  Method: {rca_results.get('method', 'Unknown')}")
+    output.append(f"  Confidence: {rca_results.get('confidence', 'Unknown').title()}")
+    
+    root_causes = rca_results.get("root_causes", [])
+    if root_causes:
+        output.append(f"  Root Causes Identified: {len(root_causes)}")
+        for i, cause in enumerate(root_causes[:3], 1):
+            output.append(f"    {i}. {cause.get('cause', 'Unknown')[:60]}...")
+    output.append("")
+    
+    # Action items summary
+    output.append("ACTION ITEMS:")
+    output.append(f"  Total Actions: {len(action_items)}")
+    output.append(f"  Critical (P0): {metadata.get('critical_action_items', 0)}")
+    output.append(f"  Prevention Timeline: {metadata.get('estimated_prevention_timeline', 'Unknown')}")
+    
+    if action_items:
+        output.append("  Top Actions:")
+        for item in action_items[:3]:
+            output.append(f"    - {item.get('title', 'Unknown')[:50]}...")
+    output.append("")
+    
+    # Completeness
+    completeness = metadata.get("review_completeness", 0) * 100
+    output.append(f"REVIEW COMPLETENESS: {completeness:.0f}%")
+    output.append("")
+    
+    output.append("=" * 60)
+    
+    return "\n".join(output)
+
+
+def main():
+    """Main function with argument parsing and execution."""
+    parser = argparse.ArgumentParser(
+        description="Generate Post-Incident Review documents with RCA and action items",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python pir_generator.py --incident incident.json --output pir.md
+  python pir_generator.py --incident incident.json --rca-method fishbone
+  cat incident.json | python pir_generator.py --format markdown
+  
+Incident JSON format:
+  {
+    "incident_id": "INC-2024-001",
+    "title": "Database performance degradation",
+    "description": "Users experiencing slow response times",
+    "severity": "sev2",
+    "start_time": "2024-01-01T12:00:00Z",
+    "end_time": "2024-01-01T14:30:00Z",
+    "customer_impact": "50% of users affected by slow page loads",
+    "business_impact": "Moderate user experience degradation",
+    "incident_commander": "Alice Smith",
+    "responders": ["Bob Jones", "Carol Johnson"]
+  }
+        """
+    )
+    
+    parser.add_argument(
+        "--incident", "-i",
+        help="Incident data file (JSON) or '-' for stdin"
+    )
+    
+    parser.add_argument(
+        "--timeline", "-t",
+        help="Timeline reconstruction file (JSON)"
+    )
+    
+    parser.add_argument(
+        "--output", "-o",
+        help="Output file path (default: stdout)"
+    )
+    
+    parser.add_argument(
+        "--format", "-f",
+        choices=["json", "markdown", "text"],
+        default="markdown",
+        help="Output format (default: markdown)"
+    )
+    
+    parser.add_argument(
+        "--rca-method",
+        choices=["five_whys", "fishbone", "timeline", "bow_tie"],
+        default="five_whys",
+        help="Root cause analysis method (default: five_whys)"
+    )
+    
+    parser.add_argument(
+        "--template-type",
+        choices=["comprehensive", "standard", "brief"],
+        default="comprehensive",
+        help="PIR template type (default: comprehensive)"
+    )
+    
+    parser.add_argument(
+        "--action-items",
+        action="store_true",
+        help="Generate detailed action items"
+    )
+    
+    args = parser.parse_args()
+    
+    generator = PIRGenerator()
+    
+    try:
+        # Read incident data
+        if args.incident == "-" or (not args.incident and not sys.stdin.isatty()):
+            # Read from stdin
+            input_text = sys.stdin.read().strip()
+            if not input_text:
+                parser.error("No incident data provided")
+            incident_data = json.loads(input_text)
+        elif args.incident:
+            # Read from file
+            with open(args.incident, 'r') as f:
+                incident_data = json.load(f)
+        else:
+            parser.error("No incident data specified. Use --incident or pipe data to stdin.")
+        
+        # Read timeline data if provided
+        timeline_data = None
+        if args.timeline:
+            with open(args.timeline, 'r') as f:
+                timeline_data = json.load(f)
+        
+        # Validate incident data
+        if not isinstance(incident_data, dict):
+            parser.error("Incident data must be a JSON object")
+        
+        if not incident_data.get("description") and not incident_data.get("title"):
+            parser.error("Incident data must contain 'description' or 'title'")
+        
+        # Generate PIR
+        result = generator.generate_pir(
+            incident_data=incident_data,
+            timeline_data=timeline_data,
+            rca_method=args.rca_method,
+            template_type=args.template_type
+        )
+        
+        # Format output
+        if args.format == "json":
+            output = format_json_output(result)
+        elif args.format == "markdown":
+            output = format_markdown_output(result)
+        else:
+            output = format_text_output(result)
+        
+        # Write output
+        if args.output:
+            with open(args.output, 'w') as f:
+                f.write(output)
+                f.write('\n')
+        else:
+            print(output)
+    
+    except FileNotFoundError as e:
+        print(f"Error: File not found - {e}", file=sys.stderr)
+        sys.exit(1)
+    except json.JSONDecodeError as e:
+        print(f"Error: Invalid JSON - {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()