Three Endorsements Per Layer: How InsightUW Filters the Picker by Attachment Point Without Hiding Anything

From "I attached the wrong endorsement to the second layer; the bound DOCX is missing the manuscript wording the broker negotiated; we're issuing an endorsement to fix the endorsement" to "the picker shows the right options for the layer I'm working on, the finalized PDF includes every attached endorsement as a numbered appendix, and I can still see the off-window options if I really mean to attach one" — through one column on the junction table, a ±20% slack window, and the deliberate refusal to filter out 'wrong' rows.

The Problem

A UW is composing an excess casualty quote with three layers: $5M primary, $5M xs $5M, $10M xs $10M. They open the endorsement picker on the primary form and see every endorsement in the library: primary-attaching exclusions, mid-layer aggregate caps, top-layer reinstatement provisions, ISO standard endorsements, manuscript wordings — all in one flat list. They tap "Hostile Fire Exclusion" thinking it applies to the primary, but the master form's attachment_point=$5M quietly tells the system this endorsement is for the first-excess layer. Nothing flags it. The form finalizes. The bound DOCX has the exclusion attached to the wrong layer.

Three weeks later legal flags the discrepancy. The fix is a mid-term endorsement to retract the wrong attachment and issue the right one — paper-trail noise for a problem the picker should have caught.

The usual fixes don't fix:

• Hard-filter the picker by attachment_point. Now the UW can't attach an endorsement that should go on a different layer in an unusual structure. The system thinks it knows; it doesn't.
• Manual layer assignment after attach. Six clicks where one would do, and the renderer has no way to know which endorsement ended up on which layer.
• Force a separate Quote Form per layer. Triples the form count for layered programs; references between layers become broken cross-form links.
• Skip the rendering problem. "Endorsements are metadata" — but the broker's broker says "where's the wording?" and "metadata" isn't a defensible answer.

The root cause: the junction between a quote form and an endorsement carries the attachment override, but never said which layer. So the picker can't filter, the renderer can't section, the audit can't reconstruct.

The InsightUW Approach

One nullable column on Quote Form Endorsement — layer number — and a picker that ranks rather than filters.

The ±20% slack window

The picker, given a layer number, computes the layer's natural window as [ap × 0.8, (ap + limit) × 1.2]. For Layer 2 (ap=5M, limit=5M) that's [$4M, $12M]. Endorsements whose master attachment point falls inside the window get a small score bump and a "fits layer 2" reason chip. Outside the window, they get a "out of layer window" warning chip and drop within their bucket — but they're still visible. The UW can attach knowingly.

Why ±20%? Industry endorsements rarely sit exactly on a layer boundary. A "general aggregate cap" endorsement might be authored at $5M but practically attach to anything with primary near that mark. The slack catches the messy reality without turning the picker into a guessing game.

Three picker behaviours that compose

The picker is the same surface for capability #6's ranking, capability #7's layer awareness, and capability #1's basic scope. They stack:

1. Scope filter (cap #1) — exclude endorsements that don't match the quote's lob / broker / NAICS / account_tier.
2. Score (cap #6) — order by broker-specific, NAICS-depth, tier-match, is_default, pinned.
3. Layer fit (cap #7) — bonus when in window, warning chip when out, never a hard exclusion.

Adding layer number to the picker call doesn't replace the other two — it adjusts the ordering on top of them.

Already-attached: flag, don't filter

Pass quote form guid and the picker also flags rows already attached to that form (is_attached: true + attached endorsement guid). The UI disables the row instead of letting the UW try a 409. Same row stays visible — the UW knows it's already there, doesn't have to dig through "Attached" tabs to find out.

The compliance fix: render the appendix

Before capability #7, the bound DOCX was the form body alone. The endorsements lived in Quote Form Endorsement rows — metadata, not document. When the broker's broker asked "what wording is attached?" the answer was "open the system." Not great.

Now render endorsement appendix runs at finalize time:

In sort order. With deviation text under each. Bound to the form via attached document guid exactly the same way before. The audit-time artefact and the live Attached endorsements panel now match.

Worked Example: Acme Construction, $20M Excess Casualty

Sarah is composing the layered excess form on QT-2026-EX-0442. The quote has three layers:

Step 1 — Picker on the primary form

She opens the endorsement-picker dropdown on QT-2026-EX-0442/primary-form, picks Layer 1 from the dropdown.

Server-side: list attachable endorsements.
- Layer 1 window: [0, $6M] (0×0.8=0; (0+5M)×1.2=6M)
- 47 endorsements pass scope filters
- 12 fit in window (score bump + "fits layer 1" chip)
- 35 outside window (warning chip + dropped to bottom of bucket)
- 2 already attached (disabled in UI; "in use" chip)

She picks "Manuscript W-308 — Acme Carve-Back," server-side attaches with layer_number=1. The form's attached endorsements list updates with a green L1 chip alongside the form-number/name.

Step 2 — Picker on Layer 2

She opens the same dropdown, picks Layer 2. Window: [$4M, $12M].

The "Hostile Fire Exclusion" she would have grabbed earlier (master attachment_point=$5M) now sits at the top of Recommended with a green "fits layer 2" chip. She attaches with layer_number=2. The dropdown closes, the form-strip refreshes, the Forms strip card on the quote shows endorsement_count=2.

Step 3 — Knowingly attach an off-window endorsement

For Layer 3 she wants to attach a "punitive damages exclusion" that's in the library at attachment_point=$15M (the master form is authored for top-layer programs of a different shape). Layer 3 window is [$8M, $24M] — $15M fits. But what if she wanted to attach the same endorsement to Layer 2 as a fallback? The picker would show a "out of layer window" chip; she could attach anyway, with eyes open. The system doesn't pretend she made a mistake — it surfaces the misfit and lets her decide.

Step 4 — Reorder

The form's "Attached endorsements" list lets her drag the Manuscript W-308 to the top (it's the most negotiated wording; brokers want it first). Drag-handle on the row; on drop, the optimistic UI updates, then the /forms/{guid}/endorsements/reorder endpoint persists with one POST. The backend renumbers sort order 0..N for active rows.

Step 5 — Inline edit a deviation

She clicks the edit pencil on the Manuscript W-308 row. Inline form opens: attachment-point override, label, layer, deviation text. She types: "$2M sublimit applies to D-class claims; 30-day notice instead of 60." Click save → PATCH /endorsements/{guid} → bump form after endorsement change writes audit, marks sibling forms stale, version goes 4→5.

Step 6 — Finalize

She clicks "Finalize and lock." Quote Form Service.finalize:
1. Renders form body markdown → HTML (Acme Construction — Excess Casualty Manuscript Wording, version 5).
2. render endorsement appendix runs: 6 attached endorsements, sorted by sort order, each rendered with master content + per-quote deviation under "Deviations" sub-heading.
3. Body HTML + appendix HTML → html to docx bytes → Submission Document row written, attached as attached document guid.

Sarah opens the bound DOCX. Section 1: form body, all 7 sections she authored. Section 2: "Endorsement schedule" with 6 numbered entries. Section "Deviations" under the Manuscript W-308 entry shows her $2M sublimit text. The compliance question "what wording bound?" has a one-document answer.

Step 7 — Refer if needed (cap #9)

The deviation text on Manuscript W-308 was 200+ characters. A manuscript review rule with condition_json={"deviation_text_min_chars": 50} fires on attach (capability #9) — referral row created, requires_legal=true, Legal queue gets the row, finalize is gated until Legal clears or a manager overrides. The picker still works; the finalize refuses with 409 + the open referral payload.

What This Means for Underwriters

1. The picker is layer-aware. Pick a layer; the picker scores accordingly. The right endorsements rise to the top.
2. Off-window options stay visible. Real-world structures don't always sit on standard windows; the picker surfaces misfits with a chip, never hides them.
3. Already-attached rows are flagged, not filtered. The UW knows what's already on the form without flipping tabs.
4. The finalized DOCX/PDF tells the truth. Endorsement schedule rendered as a numbered appendix; deviation text under each entry. Audit-time question "what wording bound?" has a one-document answer.
5. Drag-to-reorder + inline edit. No more "detach then re-attach in the right order"; sort_order persists with one POST.
6. Attach / detach / patch are audited mutations. Each move bumps form.version, writes a Audit Entry, marks sibling forms is_stale (their auto-seeded sections may cite endorsement counts that no longer hold).
7. Bulk attach for the boring cases. "Property starter pack: 5 endorsements." One POST /forms/{guid}/endorsements/bulk call; the response tells you which spawned vs. which were skipped (already-attached, missing, non-endorsement form_type).

What's Next

Next: Idempotency Keys and policy admin system Envelopes: How InsightUW Pushes Manuscripts to the Policy Admin System Without Creating Phantom Records

Want to see how an inline picker, a layer-aware filter, and a finalized appendix close the "what wording bound?" gap in your underwriting workflow? Request a demo.