insurance-domain - SKILL.md Agent Skill

name: insurance-domain description: "Use when modifying domain/models/, domain/services/, adaptor/llm/, or any business logic involving insurance terms, coverages, or risk rules. Also use when adding new fields, endorsements, or coverage types."

Insurance Domain Knowledge (ACORD-Based)

ACORD (Association for Cooperation in Operations Research and Development) defines the insurance industry's data standards. This project covers Personal Lines — Auto (ACORD 90) and Homeowners (ACORD 80).

Core Terminology

Term	Definition	ACORD Context
Renewal	Policy renewal. Comparing Prior vs Renewal is the core workflow	ACORD 80/90 Status: `Renew`
Endorsement	Mid-term policy change or rider. Expands/restricts coverage scope	ACORD 70 (HO), 71 (Auto): change type A/C/D
Premium	Insurance premium. Rate of change at renewal is the primary risk indicator	ACORD `WrittenAmt`
Deductible	Amount the insured pays first before a claim is covered	ACORD `DeductibleAmt`
Liability Limit	Liability cap. A protected field that must never be auto-reduced	ACORD `BI`, `PD`, Coverage E
Coverage Dropped	Coverage item removed. Flagged when True→False or amount decreases	DiffFlag.COVERAGE_DROPPED
Material Change	A change with substantial impact on coverage scope	LLM endorsement_comparison target
Risk Signal	Risk factors extracted from renewal notes (claims history, property condition, etc.)	LLM risk_signal_extractor output
Bundle	Auto + Home package for the same customer. Discount eligible; risk when unbundled	Core concept in Portfolio analysis
SR-22	High-risk driver certificate. Minimum insurance proof required by the state	ACORD Driver field

Coverage Types (ACORD Code Mapping)

Auto Coverages

ACORD Code	Name	Current Model Field	Notes
`BI`	Bodily Injury	`bodily_injury_limit`	split limit "100/300"
`PD`	Property Damage	`property_damage_limit`
`COLL`	Collision	`collision_deductible`
`COMP`	Comprehensive	`comprehensive_deductible`
`UM`	Uninsured Motorist	`uninsured_motorist`
`MEDPM`	Medical Payments	`medical_payments`
`TL`	Towing/Roadside	`roadside_assistance`	bool only — ACORD uses amount
`RENTAL`	Rental Reimbursement	`rental_reimbursement`	bool only — ACORD uses daily/max limit
`UNDUM`	Underinsured Motorist	not implemented	separate from UM, required in many states
`PIP`	Personal Injury Protection	not implemented	required in no-fault states
`UMPD`	UM Property Damage	not implemented	separate coverage in some states

Home Coverages

ACORD Code	Name	Current Model Field	Notes
`DWELL`	Coverage A (Dwelling)	`coverage_a_dwelling`	protected field
`OTSTR`	Coverage B (Other Structures)	`coverage_b_other_structures`	typically 10% of A
`PP`	Coverage C (Personal Property)	`coverage_c_personal_property`
`ALE`	Coverage D (Loss of Use)	`coverage_d_loss_of_use`
`PL`	Coverage E (Liability)	`coverage_e_liability`	protected field
`MEDPM`	Coverage F (Medical)	`coverage_f_medical`
`WIND`	Wind/Hail	`wind_hail_deductible`	deductible only
—	Water Backup	`water_backup`	bool only — ACORD uses limit amount
`EQ`	Earthquake	not implemented	near-mandatory in CA/WA/OR
`FLOOD`	Flood	not implemented	separate NFIP policy

ACORD Gap Analysis — Known Limitations of Current Models

High Priority (Directly impacts renewal review)

UIM/PIP/UMPD not implemented — Cannot compare state-required coverages
No amounts on boolean coverages — Cannot compare limits for rental($30/day), roadside($75/occ), water_backup($5K), etc.
No Loss History — ACORD 80/90 Prior Loss section. Key factor in renewal premium determination
No HO Form Type — HO-3(broad), HO-5(open), HO-6(condo), etc. Fundamentally different coverage scopes
No Territory Code — Basic variable in premium calculation

Medium Priority (Improves analysis precision)

Driver DOB — ACORD standard uses DOB instead of age. Enables exact age calculation
Vehicle annual mileage — EstimatedAnnualDistance. Major premium factor
Driver relationship/marital status — RelationshipToInsured, MaritalStatus. Discount factors
Endorsement limit/deductible — Cannot compare endorsement coverage limits
Prior Carrier — ACORD 80 Prior Coverage section. Renewal context

Protected Fields — Never auto-modify

Per ACORD standards, reducing these fields carries legal/contractual risk:

bodily_injury_limit — Bodily injury liability limit
property_damage_limit — Property damage liability limit
uninsured_motorist — Uninsured motorist coverage
coverage_a_dwelling — Dwelling reconstruction cost
coverage_e_liability — Personal liability

Endorsement Form System

ACORD uses a Form Number system rather than a single code list:

Auto: PP series (PP 03 06, PP 03 22, PP 03 23, etc.)
Home: HO series (HO 04 10, HO 04 61, HO 04 90, HO 04 95, etc.)
Change Request: ACORD 70 (HO), ACORD 71 (Auto) — type A(Add)/C(Change)/D(Delete)

Currently Endorsement.code is free text. Validation can be added when ISO/AAIS form number mapping is implemented.

Application Rules

When adding new coverage fields: Reference the ACORD code mapping tables above for naming
When adding DiffFlags: Consider the industry importance of the coverage (liability types → URGENT)
When modifying LLM prompts: Verify the exact meaning of insurance terms before use
When adding Quote strategies: Re-verify the protected fields list. Protected fields cannot be changed in any strategy