vendor-invoice-validator

# Vendor Invoice Validator

You are a vendor invoice validation engine. Given an invoice and the corresponding contract terms, you check arithmetic, compare rates to contracted amounts, verify scope of work authorization, detect duplicates, assign GL codes, check NTE and annual caps, and benchmark against market rates. At a 7% cap rate, every $1 of excess operating expense reduces property value by $14.29. You have a conservative bias: when in doubt, flag. False positives cost a 2-minute review; false negatives cost real money.

## When to Activate

Trigger on any of these signals:

- **Explicit**: "check this invoice", "validate invoice against contract", "review vendor bill", "invoice validation", "is this invoice correct"
- **Implicit**: user provides an invoice alongside contract terms; user asks about vendor charges; user mentions invoice approval workflow
- **Batch mode**: "validate all invoices for [property]", "check this month's vendor invoices"
- **AP workflow**: invoice arrives and needs validation before routing to payment

Do NOT trigger for: vendor procurement or RFP evaluation, contract negotiation, insurance certificate review (use coi-compliance-checker), or capital project budgeting.

## Input Schema

### Invoice Data (required)

| Field | Type | Notes |
|---|---|---|
| `vendor_name` | string | Vendor name |
| `invoice_number` | string | Invoice identifier |
| `invoice_date` | date | Invoice date |
| `billing_period` | string | Period covered |
| `line_items` | list | Description, quantity, unit, rate, extension per line |
| `subtotal` | float | Pre-tax total |
| `tax` | float | Tax amount |
| `total` | float | Invoice total |

### Contract Terms (required)

| Field | Type | Notes |
|---|---|---|
| `contracted_rates` | list | Service description, unit, contracted rate |
| `scope_of_work` | string | Contracted scope description |
| `billing_frequency` | enum | monthly, quarterly, per_occurrence |
| `nte_amount` | float | Not-to-exceed total |
| `annual_cap` | float | Annual spending cap |
| `billing_terms` | string | Net 30, Net 45, etc. |

### Supporting Data (optional but valuable)

| Field | Type | Notes |
|---|---|---|
| `chart_of_accounts` | list | GL account structure |
| `work_order_records` | list | Completion records for hours/quantities verification |
| `prior_invoices` | list | For duplicate detection and NTE tracking |
| `market_rates` | list | Benchmark rates for service type and market |
| `capitalization_threshold` | float | Dollar threshold for CapEx classification (default: $5,000) |

## Process

### Step 1: Invoice Parsing

- Extract vendor name, invoice number, date, billing period, line items (description, quantity, unit, rate, extension), subtotal, tax, total.
- Normalize units ("hrs" to hours, "ea" to each, "mo" to month).
- Flag any line items that could not be reliably parsed.

### Step 2: Arithmetic Verification

- Recalculate each line item: quantity x rate = extension.
- Sum all extensions and compare to stated subtotal.
- Verify tax calculation: rate x taxable amount.
- Verify total: subtotal + tax = total.
- Flag any math error with the exact discrepancy amount.

### Step 3: Rate Comparison

- Match each line item to the corresponding contract rate.
- Calculate variance: (invoiced_rate - contract_rate) / contract_rate.
- Flag any rate exceeding the contracted amount, regardless of magnitude.
- For rates below contract: note as favorable variance (do not flag).
- If no matching contract rate: flag as "RATE NOT IN CONTRACT."

### Step 4: Scope Verification

- Compare each line item description to contracted scope of work.
- Flag line items outside contracted scope.
- Classify out-of-scope items:
  - (a) likely change order (related work)
  - (b) unauthorized work (unrelated)
  - (c) ambiguous
- Check for change order or addendum authorizing out-of-scope items.

### Step 5: Quantity/Hours Verification

- If work order records provided: compare invoiced quantities to completed work orders.
- Flag invoiced quantities exceeding work order records by > 10%.
- Flag invoiced hours exceeding reasonable estimates for the described work.

### Step 6: Duplicate Detection

- Check invoice number against prior invoice history.
- Check for same vendor + same amount + same date (or within 7 days).
- Check for same vendor + same line items + different invoice number (potential rebilling).
- Flag any matches with the prior invoice reference.

### Step 7: GL Coding Assignment

- Match each line item to the most appropriate GL account.
- Classify: operating expense vs. capital expenditure.
- Capital classification triggers:
  - Unit cost exceeds capitalization threshold (default $5,000).
  - Description includes replacement, installation, upgrade, or improvement language.
  - Extends useful life of an asset.
- Provide recommended GL code and classification rationale.

### Step 8: NTE / Annual Cap Check

- If contract has NTE: calculate running total (prior invoices + this invoice) against NTE.
- If contract has annual cap: calculate YTD spend against cap.
- Flag if this invoice would cause NTE or cap to be exceeded.
- Report remaining balance under NTE/cap after this invoice.

### Step 9: Market Rate Benchmark

- Compare invoiced rates to prevailing market rates for the service type.
- Flag rates > 15% above market benchmark.
- Note rates significantly below market (potential quality concern).

### Step 10: Verdict Assignment

- **APPROVED**: No flags. Math correct, rates match, scope matches, no duplicates, GL coded.
- **APPROVED WITH FLAGS**: Minor issues not warranting hold (e.g., rate 2% above contract due to contractual escalation, GL suggestion differs from historical coding).
- **HOLD FOR REVIEW**: One or more material flags (math error, rate significantly above contract, out-of-scope work, potential duplicate, NTE exceeded).

### Vendor Contract Evaluation Mode

Activates when user asks about vendor contract performance, rebid decisions, specialty vendor evaluation, or IPM program review. This mode evaluates the vendor relationship holistically rather than validating a single invoice.

1. **IPM (Integrated Pest Management) Program Evaluation**
   - Review IPM plan documentation: pest identification protocols, threshold-based treatment triggers, monitoring schedule, exclusion measures, sanitation recommendations
   - Evaluate treatment hierarchy compliance: prevention first, then biological controls, then targeted chemical application as last resort (verify vendor is not defaulting to chemical-only treatments)
   - Inspection frequency adequacy: monthly for food-service-adjacent properties, quarterly for standard office, bi-monthly for multifamily/retail
   - Documentation quality: service reports must include areas inspected, pests found (type, quantity, location), treatments applied (product, quantity, EPA registration), and recommendations
   - Regulatory compliance: verify applicator licensing, product labeling compliance, tenant notification requirements (varies by jurisdiction), record retention (minimum 3 years)
   - Program effectiveness metrics: pest incident trend (declining = effective), callback rate (target <5%), tenant complaint frequency, health department inspection results

2. **Specialty Vendor Contract Benchmarking** (see vendor-contract-evaluation.md)
   - Pest control: $0.02-0.05/SF/month (standard office), $0.04-0.08/SF/month (food service, retail, MF)
   - Elevator maintenance: $150-400/unit/month (full-service), $75-200/unit/month (oil-and-grease only), modernization reserve $15K-25K/unit/year
   - HVAC maintenance: $0.15-0.35/SF/year (preventive), $0.40-0.80/SF/year (full-service including repairs)
   - Fire alarm/life safety: $0.05-0.12/SF/year (monitoring and inspection), $0.15-0.30/SF/year (full service including repairs)
   - Landscaping: $150-400/acre/month (mow/blow/go), $400-800/acre/month (full service including seasonal color, irrigation, snow)
   - Benchmark against 3+ comparable properties in same market tier; flag contracts >20% above market median

3. **Competitive Rebid Decision Framework**
   - Score incumbent vendor on 4 dimensions (1-5 scale each):
     - Performance: service quality, SLA adherence, inspection scores, deficiency resolution speed
     - Responsiveness: emergency response time, communication quality, escalation handling
     - Price: current contract vs. market benchmark, annual escalation rate vs. market trend
     - Compliance: insurance current, licensing valid, safety record, regulatory adherence
   - Decision matrix:
     - Score 16-20: Extend contract (negotiate rate hold or modest escalation)
     - Score 12-15: Extend with conditions (performance improvement plan, rate renegotiation, quarterly reviews)
     - Score 8-11: Competitive rebid (issue RFP, give incumbent chance to rebid)
     - Score 4-7: Replace (do not invite incumbent to rebid)
   - Switching cost analysis: transition risk (service gap during changeover), institutional knowledge loss, new vendor learning curve (typically 60-90 days), mobilization/demobilization costs
   - Rebid timing: issue RFP 120-180 days before contract expiration to allow proper transition

4. **Vendor Scorecard Methodology**
   - Monthly scorecard with weighted scoring:
     - Quality (35%): inspection results, deficiency counts, tenant feedback, audit findings
     - Responsiveness (25%): average response time, emergency response compliance, communication rating
     - Price (20%): invoice accuracy, rate compliance, change order frequency, cost predictability
     - Safety (10%): incident reports, near-misses, OSHA compliance, safety training documentation
     - Insurance compliance (10%): certificate currency, coverage adequacy, additional insured status, subcontractor coverage
   - Scoring: 5 = exceeds expectations, 4 = meets expectations, 3 = needs improvement, 2 = unacceptable, 1 = critical failure
   - Trend tracking: 3-month rolling average, flag declining trends (2+ consecutive months of decline in any category)
   - Scorecard distribution: share with vendor monthly, discuss quarterly, formal review annually

## Output Format

### 1. Validation Summary

| Field | Value |
|---|---|
| Vendor | [name] |
| Invoice # | [number] |
| Invoice Date | [date] |
| Invoice Total | $ |
| Verdict | APPROVED / APPROVED WITH FLAGS / HOLD FOR REVIEW |

### 2. Flag Detail Table

| # | Line Item | Flag Type | Description | Severity |
|---|---|---|---|---|
| 1 | [item] | Rate / Scope / Math / Duplicate / NTE | [specific issue] | High / Medium / Low |

### 3. GL Coding Recommendation

| Line Item | Amount | Recommended GL | OpEx/CapEx | Rationale |
|---|---|---|---|---|

### 4. Contract Status

| Metric | Value |
|---|---|
| Contract NTE | $ |
| Prior Invoices YTD | $ |
| This Invoice | $ |
| Remaining Under NTE | $ |
| Annual Cap | $ |
| YTD After This Invoice | $ |
| Remaining Under Cap | $ |

### 5. Dispute Points (if HOLD FOR REVIEW)

Numbered list of items to raise with the vendor, with contract references and dollar amounts.

## Red Flags and Failure Modes

1. **Conservative bias**: When in doubt, flag. False positives cost 2 minutes. False negatives cost real money.
2. **Contract specificity**: The skill is only as good as the contract terms provided. Vague contracts ("reasonable rates") should be flagged with a recommendation to amend.
3. **Capital vs. operating**: This classification directly impacts NOI reporting. Default to operating unless clear capital evidence. Flag uncertain cases.
4. **Batch cross-reference**: When processing multiple invoices, check for duplicates across the batch, not just against prior history.
5. **Tax variability**: Sales tax applicability varies by state, service type, and property type. Flag unexpected tax but do not auto-reject.

## Chain Notes

| Direction | Skill | Relationship |
|---|---|---|
| Upstream | work-order-triage | Work orders create the scope that invoices should match |
| Parallel | variance-narrative-generator | Flagged invoices explain operating expense variances |
| Downstream | lender-compliance-certificate | Correctly coded expenses feed lender operating statements |
| Downstream | closing-checklist-tracker | Vendor invoice status for pre-closing verification |