insurance-contract-review-advisor-agent-skill

Personal Insurance Contract Review Advisor

Structured analysis of personal insurance policy terms (not a substitute for a licensed agent/broker or attorney).

Category: Insurance Literacy / Contract Analysis (Disclaimer Required)

Disclaimer: This skill provides general, educational/analytical information only. It is not insurance advice, a coverage recommendation, a coverage determination, or a legal opinion. It does not replace a licensed insurance agent/broker for coverage decisions or an attorney for coverage- dispute or claims-litigation matters. Ambiguous policy language is not interpreted as a binding legal determination. Always verify with a qualified professional before acting.

Overview

A skill that helps consumers understand and analyze their own personal insurance contracts (health, life, auto, home/renters), grounded in established insurance-literacy education and structured policy-review methodology. It runs as a modular skill-registry agent framework - fully deterministic with no LLM required, with an optional, gracefully-degrading LLM enrichment path.

Core capabilities

• Structured policy-section review (declarations, insuring agreement, exclusions, conditions, endorsements)
• Plain-language insurance terminology explanation (NAIC-aligned glossary)
• Coverage-gap identification (risk-scenario-to-coverage mapping + adequacy score) for health, life, auto, home, renters
• Actual Cash Value vs. Replacement Cost Value computation
• Claims-process structure and documentation best-practices guidance
• Apples-to-apples quote comparison (weighted MCDA, parity enforcement)
• Structured professional-referral flags (licensed agent / attorney)

Research-grounded & provenance-backed

• A runtime provenance system attaches the named methodology and evidence (research keys) to every output and aggregates cited sources into a top-level provenance glossary - so each response is auditable and persuasive.
• RESEARCH-PAPER-KNOWLEDGE-BRAIN.md catalogs 25 peer-reviewed scientific papers, each mapped to a concrete project artifact (e.g. Sydnor 2010 over-insurance check, Kunreuther/Gollier catastrophic-risk emphasis, Abaluck-Gruber health choice-overload, prospect-theory framing of ACV settlements).
• Open-source distribution: LICENSE (MIT), CONTRIBUTING.md, CHANGELOG.md.

Architecture

insurance-contract-review-advisor/
├── SKILL.md                 # Claude Skill definition (name + description + body)
├── SKILL-REGISTRY.md        # Skill registry documentation (register/resolve/execute/validate)
├── config/                  # Type-safe settings + feature flags + yaml defaults
├── references/              # Operationalized knowledge (checklists/templates) from SECOND-BRAIN
├── assets/
│   ├── schemas/             # JSON Schema (Draft 2020-12) for every output
│   └── diagrams/            # Mermaid architecture diagram
├── scripts/                 # run_review, validate_skill, run_tests, seed_knowledge, generate_manifest
├── src/insurance_advisor/   # The package
│   ├── registry.py          # Skill registry + SkillSpec
│   ├── router.py            # Chain-of-thought intent router
│   ├── advisor.py           # Main agent orchestrator
│   ├── sub_advisors/        # document_review, terminology, gap_analysis, claims, shopping
│   ├── tools/               # GlossaryTool, AcvRcvTool, GapAnalysisTool, QuoteComparisonTool
│   ├── hooks/               # Lifecycle bus: Logging, Disclaimer, Lifecycle
│   ├── schemas.py           # Data models + JSON-schema validator (with built-in fallback)
│   ├── llm_client.py        # Optional, fault-tolerant LLM client
│   ├── prompts.py           # LLM prompt templates (named methodologies + disclaimer)
│   └── utils.py             # Logging, disclaimer text, reference loading
└── tests/                   # 60+ unit + e2e tests

See SKILL-REGISTRY.md for how skills are registered, resolved, executed, and validated, and assets/diagrams/architecture.mmd for the visual flow.

Quick start

# Run deterministically (no LLM, no extra deps)
python scripts/run_review.py "What is coinsurance?"

# Policy-type aware gap analysis
python scripts/run_review.py "Do I have enough coverage if my home floods?" --policy-type home

# Quote comparison (provide a quotes JSON file)
python scripts/run_review.py "compare these auto quotes" --quotes-file examples/quotes_auto.json --json

# Validate all skills against their output schemas
python scripts/validate_skill.py

# Run the test suite (stdlib unittest, no pytest required)
python scripts/run_tests.py

Optional LLM enrichment: set INSURANCE_LLM_PROVIDER=anthropic, INSURANCE_LLM_API_KEY_ENV=ANTHROPIC_API_KEY, and export your key. The advisor falls back to deterministic output if the LLM is unavailable.

Configuration

All settings are environment-driven with safe defaults (config/):

Project files

Status

Production-grade and open-source ready. All build phases complete; full test suite passing; all skills validated against their JSON schemas. See PROJECT-DEVELOPMENT-PHASE-TRACKING.md.

License

MIT.