claims-documentation

What this skill does

# Claims Documentation

## Overview

Document and manage construction claims for schedule delays, cost impacts, and scope disputes. Track contractual notice requirements, compile supporting evidence, calculate damages, and prepare comprehensive claim packages.

## Claims Process

```
┌─────────────────────────────────────────────────────────────────┐
│                    CLAIMS PROCESS                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Notice  →  Document  →  Quantify  →  Submit  →  Negotiate     │
│  ──────     ────────     ────────     ──────     ─────────     │
│  📋 Identify  📂 Collect   💰 Calculate  📤 Package  🤝 Resolve │
│  📧 Timely    📸 Evidence  ⏱️ Time       📋 Format   ⚖️ Settle  │
│  📝 Written   📄 Chain     📊 Cost       ✓ Review   💵 Payment  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

## Technical Implementation

```python
from dataclasses import dataclass, field
from typing import List, Dict, Optional
from datetime import datetime, timedelta
from enum import Enum

class ClaimType(Enum):
    DELAY = "delay"
    DISRUPTION = "disruption"
    ACCELERATION = "acceleration"
    DIFFERING_CONDITIONS = "differing_conditions"
    OWNER_CHANGE = "owner_change"
    SUSPENSION = "suspension"
    TERMINATION = "termination"
    DEFECTIVE_SPECS = "defective_specs"

class ClaimStatus(Enum):
    DRAFT = "draft"
    NOTICE_SENT = "notice_sent"
    DOCUMENTING = "documenting"
    SUBMITTED = "submitted"
    UNDER_REVIEW = "under_review"
    NEGOTIATING = "negotiating"
    SETTLED = "settled"
    DISPUTED = "disputed"
    LITIGATION = "litigation"
    WITHDRAWN = "withdrawn"

class EvidenceType(Enum):
    DAILY_REPORT = "daily_report"
    PHOTO = "photo"
    VIDEO = "video"
    EMAIL = "email"
    LETTER = "letter"
    MEETING_MINUTES = "meeting_minutes"
    SCHEDULE = "schedule"
    COST_RECORD = "cost_record"
    INVOICE = "invoice"
    TIMESHEET = "timesheet"
    WEATHER_DATA = "weather_data"
    DELIVERY_TICKET = "delivery_ticket"
    INSPECTION_REPORT = "inspection_report"
    RFI = "rfi"
    SUBMITTAL = "submittal"

@dataclass
class Evidence:
    id: str
    evidence_type: EvidenceType
    description: str
    date: datetime
    file_path: str
    source: str
    relevance: str
    authenticated: bool = False

@dataclass
class NoticeRequirement:
    notice_type: str
    deadline_days: int
    recipient: str
    method: str  # Written, certified mail, etc.
    contract_reference: str
    sent: bool = False
    sent_date: Optional[datetime] = None
    confirmation: str = ""

@dataclass
class DamageCalculation:
    category: str
    description: str
    amount: float
    basis: str  # How calculated
    supporting_docs: List[str] = field(default_factory=list)

@dataclass
class Claim:
    id: str
    claim_type: ClaimType
    title: str
    description: str
    status: ClaimStatus

    # Event details
    event_date: datetime
    discovery_date: datetime
    responsible_party: str
    contract_references: List[str] = field(default_factory=list)

    # Notice
    notice_requirements: List[NoticeRequirement] = field(default_factory=list)
    notice_compliant: bool = False

    # Documentation
    evidence: List[Evidence] = field(default_factory=list)
    narrative: str = ""

    # Damages
    time_claimed_days: int = 0
    cost_claimed: float = 0.0
    damage_calculations: List[DamageCalculation] = field(default_factory=list)

    # Resolution
    time_awarded_days: int = 0
    amount_awarded: float = 0.0
    settlement_date: Optional[datetime] = None
    settlement_notes: str = ""

class ClaimsDocumentor:
    """Document and manage construction claims."""

    # Common notice requirements
    DEFAULT_NOTICE_REQUIREMENTS = {
        ClaimType.DELAY: [
            {"notice_type": "Intent to Claim", "deadline_days": 21, "method": "Written"},
            {"notice_type": "Detailed Claim", "deadline_days": 45, "method": "Written"},
        ],
        ClaimType.DIFFERING_CONDITIONS: [
            {"notice_type": "Immediate Notice", "deadline_days": 2, "method": "Written/Verbal"},
            {"notice_type": "Written Notice", "deadline_days": 7, "method": "Written"},
        ],
        ClaimType.OWNER_CHANGE: [
            {"notice_type": "Notice of Impact", "deadline_days": 14, "method": "Written"},
        ],
    }

    def __init__(self, project_name: str, contract_date: datetime):
        self.project_name = project_name
        self.contract_date = contract_date
        self.claims: Dict[str, Claim] = {}

    def create_claim(self, claim_type: ClaimType, title: str,
                    description: str, event_date: datetime,
                    responsible_party: str) -> Claim:
        """Create new claim."""
        claim_id = f"CLM-{datetime.now().strftime('%Y%m%d%H%M%S')}"

        claim = Claim(
            id=claim_id,
            claim_type=claim_type,
            title=title,
            description=description,
            status=ClaimStatus.DRAFT,
            event_date=event_date,
            discovery_date=datetime.now(),
            responsible_party=responsible_party
        )

        # Add default notice requirements
        for req in self.DEFAULT_NOTICE_REQUIREMENTS.get(claim_type, []):
            notice = NoticeRequirement(
                notice_type=req["notice_type"],
                deadline_days=req["deadline_days"],
                recipient=responsible_party,
                method=req["method"],
                contract_reference=""
            )
            claim.notice_requirements.append(notice)

        self.claims[claim_id] = claim
        return claim

    def record_notice_sent(self, claim_id: str, notice_type: str,
                          confirmation: str = "") -> NoticeRequirement:
        """Record that notice was sent."""
        if claim_id not in self.claims:
            raise ValueError(f"Claim {claim_id} not found")

        claim = self.claims[claim_id]

        for notice in claim.notice_requirements:
            if notice.notice_type == notice_type:
                notice.sent = True
                notice.sent_date = datetime.now()
                notice.confirmation = confirmation

                # Check overall notice compliance
                claim.notice_compliant = all(n.sent for n in claim.notice_requirements)

                if claim.status == ClaimStatus.DRAFT:
                    claim.status = ClaimStatus.NOTICE_SENT

                return notice

        raise ValueError(f"Notice type {notice_type} not found")

    def check_notice_deadlines(self, claim_id: str) -> List[Dict]:
        """Check status of notice deadlines."""
        if claim_id not in self.claims:
            raise ValueError(f"Claim {claim_id} not found")

        claim = self.claims[claim_id]
        status = []

        for notice in claim.notice_requirements:
            deadline = claim.event_date + timedelta(days=notice.deadline_days)
            days_remaining = (deadline - datetime.now()).days

            status.append({
                "notice_type": notice.notice_type,
                "deadline": deadline,
                "days_remaining": days_remaining,
                "sent": notice.sent,
                "overdue": days_remaining < 0 and not notice.sent,
                "status": "Sent" if notice.sent else ("OVERDUE" if days_remaining < 0 else f"{days_remaining} days left")
            })

        return status

    def add_evidence(self, claim_id: str, evidence_type: EvidenceType,
                    description: str, date: datetime, file_path: str,
                    source: str, relevance: str) -> Evidence:
        """Add evidence to claim."""
        if claim_id not in self.claims:
            raise ValueError(f"Claim {claim_id} not found")

        evidence_id = f"EVD-{len(self.cl