claims-documentation

name	claims-documentation
title	Claims Documentation
description	Document construction claims for disputes and recovery. Compile evidence, calculate damages, track notice requirements, and prepare claim packages.
author	datadrivenconstruction
author_url	https://github.com/datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction/tree/main/4_DDC_Curated/Contract-Legal/claims-documentation
license	MIT
version	0.1.0
execution_mode	open
jurisdiction	general
practice	construction
language	en

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

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 = 
    NEGOTIATING = 
    SETTLED = 
    DISPUTED = 
    LITIGATION = 
    WITHDRAWN = 

 ():
    DAILY_REPORT = 
    PHOTO = 
    VIDEO = 
    EMAIL = 
    LETTER = 
    MEETING_MINUTES = 
    SCHEDULE = 
    COST_RECORD = 
    INVOICE = 
    TIMESHEET = 
    WEATHER_DATA = 
    DELIVERY_TICKET = 
    INSPECTION_REPORT = 
    RFI = 
    SUBMITTAL = 


 :
    : 
    evidence_type: EvidenceType
    description: 
    date: datetime
    file_path: 
    source: 
    relevance: 
    authenticated:  = 


 :
    notice_type: 
    deadline_days: 
    recipient: 
    method:   
    contract_reference: 
    sent:  = 
    sent_date: [datetime] = 
    confirmation:  = 


 :
    category: 
    description: 
    amount: 
    basis:   
    supporting_docs: [] = field(default_factory=)


 :
    : 
    claim_type: ClaimType
    title: 
    description: 
    status: ClaimStatus

    
    event_date: datetime
    discovery_date: datetime
    responsible_party: 
    contract_references: [] = field(default_factory=)

    
    notice_requirements: [NoticeRequirement] = field(default_factory=)
    notice_compliant:  = 

    
    evidence: [Evidence] = field(default_factory=)
    narrative:  = 

    
    time_claimed_days:  = 
    cost_claimed:  = 
    damage_calculations: [DamageCalculation] = field(default_factory=)

    
    time_awarded_days:  = 
    amount_awarded:  = 
    settlement_date: [datetime] = 
    settlement_notes:  = 

 :
    

    
    DEFAULT_NOTICE_REQUIREMENTS = {
        ClaimType.DELAY: [
            {: , : , : },
            {: , : , : },
        ],
        ClaimType.DIFFERING_CONDITIONS: [
            {: , : , : },
            {: , : , : },
        ],
        ClaimType.OWNER_CHANGE: [
            {: , : , : },
        ],
    }

     ():
        .project_name = project_name
        .contract_date = contract_date
        .claims: [, Claim] = {}

     () -> Claim:
        
        claim_id = 

        claim = Claim(
            =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
        )

        
         req  .DEFAULT_NOTICE_REQUIREMENTS.get(claim_type, []):
            notice = NoticeRequirement(
                notice_type=req[],
                deadline_days=req[],
                recipient=responsible_party,
                method=req[],
                contract_reference=
            )
            claim.notice_requirements.append(notice)

        .claims[claim_id] = claim
         claim

     () -> NoticeRequirement:
        
         claim_id   .claims:
             ValueError()

        claim = .claims[claim_id]

         notice  claim.notice_requirements:
             notice.notice_type == notice_type:
                notice.sent = 
                notice.sent_date = datetime.now()
                notice.confirmation = confirmation

                
                claim.notice_compliant = (n.sent  n  claim.notice_requirements)

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

                 notice

         ValueError()

     () -> []:
        
         claim_id   .claims:
             ValueError()

        claim = .claims[claim_id]
        status = []

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

            status.append({
                : notice.notice_type,
                : deadline,
                : days_remaining,
                : notice.sent,
                : days_remaining <    notice.sent,
                :   notice.sent  (  days_remaining <   )
            })

         status

     () -> Evidence:
        
         claim_id   .claims:
             ValueError()

        evidence_id = 

        evidence = Evidence(
            =evidence_id,
            evidence_type=evidence_type,
            description=description,
            date=date,
            file_path=file_path,
            source=source,
            relevance=relevance
        )

        .claims[claim_id].evidence.append(evidence)

         .claims[claim_id].status == ClaimStatus.NOTICE_SENT:
            .claims[claim_id].status = ClaimStatus.DOCUMENTING

         evidence

     () -> DamageCalculation:
        
         claim_id   .claims:
             ValueError()

        calc = DamageCalculation(
            category=category,
            description=description,
            amount=amount,
            basis=basis,
            supporting_docs=supporting_docs  []
        )

        claim = .claims[claim_id]
        claim.damage_calculations.append(calc)

        
        claim.cost_claimed = (c.amount  c  claim.damage_calculations)

         calc

     () -> :
        
         claim_id   .claims:
             ValueError()

        claim = .claims[claim_id]

        
        extended_general_conditions = delay_days * daily_rate

        
        .add_damage_calculation(
            claim_id, ,
            ,
            extended_general_conditions,
            
        )

        
        escalation = 
         include_escalation:
            escalation = extended_general_conditions *   
            .add_damage_calculation(
                claim_id, ,
                ,
                escalation,
                
            )

        claim.time_claimed_days = delay_days

         {
            : delay_days,
            : daily_rate,
            : extended_general_conditions,
            : escalation,
            : claim.cost_claimed
        }

     ():
        
         claim_id   .claims:
             ValueError()

        .claims[claim_id].narrative = narrative

     () -> Claim:
        
         claim_id   .claims:
             ValueError()

        claim = .claims[claim_id]
        claim.status = ClaimStatus.SUBMITTED
         claim

     () -> Claim:
        
         claim_id   .claims:
             ValueError()

        claim = .claims[claim_id]
        claim.status = ClaimStatus.SETTLED
        claim.time_awarded_days = time_awarded
        claim.amount_awarded = amount_awarded
        claim.settlement_date = datetime.now()
        claim.settlement_notes = notes

         claim

     () -> :
        
         claim_id   .claims:
             

        claim = .claims[claim_id]

        lines = [
            ,
            ,
            ,
            ,
            ,
            ,
            
        ]

         i, ev  ((claim.evidence, key= e: e.date), ):
            lines.append(
                
                
            )

         .join(lines)

     () -> :
        
         claim_id   .claims:
             

        claim = .claims[claim_id]

        lines = [
            ,
            ,
            ,
            ,
            ,
            ,
            ,
            ,
            ,
            ,
            ,
            ,
            ,
            ,
            claim.description,
            ,
            ,
            ,
            ,
            ,
            ,
            claim.narrative  claim.narrative  ,
            ,
            ,
            ,
        ]

         ref  claim.contract_references:
            lines.append()

        lines.extend([
            ,
            ,
            ,
            ,
            
        ])

         notice  claim.notice_requirements:
            deadline = claim.event_date + timedelta(days=notice.deadline_days)
            status =   notice.sent  
            sent = notice.sent_date.strftime()  notice.sent_date  
            lines.append()

        lines.extend([
            ,
            ,
            ,
            ,
            
        ])

         calc  claim.damage_calculations:
            lines.append()

        lines.extend([
            ,
            ,
            ,
            ,
            ,
            ,
            
        ])

        
        by_type = {}
         ev  claim.evidence:
            t = ev.evidence_type.value
            by_type[t] = by_type.get(t, ) + 

         t, count  (by_type.items()):
            lines.append()

         .join(lines)