{ "version": "1.8.0", "slug": "home-warranty-contractor-authorization-desk", "title": "AuthLift — Home Warranty Contractor Payment & Scope Authorization Desk", "vertical": "Home services / warranty recovery", "seed": { "s": "home-warranty-contractor-authorization-desk", "t": "AuthLift — Home Warranty Contractor Payment & Scope Authorization Desk", "v": "Home services / warranty recovery", "r": "Medium-high", "m": "M" }, "product": { "slug": "home-warranty-contractor-authorization-desk", "project_name": "AuthLift", "project_type": "outcome-priced, done-for-you evidence-and-appeal desk workflow application", "vertical": "Home services / warranty recovery", "audience": "independent or small (2-25 tech) HVAC, plumbing, electrical, and appliance-repair contracting businesses enrolled as network vendors for one or more home warranty companies, completing 10+ warranty work orders/month", "geography": "US, contractor-side B2B; no state-by-state consumer-facing expansion until the 50-state licensing-boundary review is complete", "scale_expectation": "5-10 pilot contractors and a 20-case cap in month one, scaling toward 50+ cumulative cases by day 90; per-case volume with seasonal HVAC demand swings", "core_workflows": [ "Work order intake & evidence normalization", "Evidence package drafting & cost-benchmark composition", "Completeness checklist gate & reviewer release", "Portal submission & authorization tracking", "Under-authorization detection & appeal filing", "Auto-Submit enrollment & recurring submission" ], "discovery": { "one_line_purpose": "AuthLift assembles the complete diagnostic evidence package for every home-warranty work order and a trade-qualified reviewer submits it through the warranty company's contractor portal to win the fullest, fastest, correctly-scoped authorization on the first pass -- and files a structured appeal when a warranty company still under-authorizes, scope-limits, or denies.", "primary_users": [ "contractor owners and office/operations managers at independent HVAC, plumbing, electrical, and appliance-repair businesses", "Trade-Qualified Reviewer (or certified claims specialist) on every case", "Warranty company contractor portal (system of record for authorization outcomes)" ], "jobs_to_be_done": [ "When a warranty company authorizes less than the job actually costs me, help me get paid what the job is worth without spending an hour on hold or losing the job entirely.", "When a warranty company approves only a temporary patch instead of the correct repair, give me the documented case I need to get the real fix authorized instead of doing substandard work I'll be blamed for later.", "When I'm deciding whether warranty-channel work is even worth taking anymore, give me a way to make each work order pay fairly so I don't have to walk away from a lead source I can't easily replace." ], "value_prop": "AuthLift turns a bare-minimum portal diagnosis note into a complete, evidence-linked Authorization Boost Package -- assembled by AI, released by a trade-qualified reviewer, submitted to the warranty company's portal, and tracked to a paid resolution -- priced only on the uplift secured, never hourly.", "competitors": [ "Consumer-side denial-appeal law firms (e.g., Louis Law Group) serving homeowners against warranty companies -- different buyer", "Contractor-network onboarding guides (Housecall Pro, ServicePlus) that help contractors join a network but not extract fair pay once inside it", "General field-service software (ServiceTitan-class tools) that manage dispatch/invoicing, not warranty-specific evidence packages or appeals" ], "differentiation": "Done-for-you Authorization Boost Packages, not a portal-filling co-pilot: a completeness checklist gated per warranty company, a trade-qualified reviewer chokepoint on every case, contractor consent required before any appeal is filed in their name, and outcome-only pricing (flat intake fee + contingency on uplift) with no recovery, no fee.", "positioning_statement": "For independent HVAC, plumbing, electrical, and appliance-repair contractors who complete 10+ home-warranty work orders a month, AuthLift is the done-for-you evidence-and-appeal desk that turns a bare-minimum portal submission into a fully-authorized, correctly-scoped work order with faster payment -- unlike consumer-side appeal law firms serving a different buyer, or field-service software that manages dispatch but never fights for fair authorization." }, "assumptions": [ { "id": "home-warranty-contractor-authorization-desk-a1", "statement": "Independent HVAC contractors will pay a $25 flat intake fee plus 28% contingency on secured uplift rather than continue eating under-authorizations or walking away from warranty-channel work.", "confidence": "medium", "impact_if_wrong": "severe", "revisit_trigger": "First 8-10 pilot-contractor cohort in month one -- reject if willingness-to-pay signal is absent after 20 pilot cases." }, { "id": "home-warranty-contractor-authorization-desk-a2", "statement": "A standard Authorization Boost Package can be assembled, reviewed, and submitted within the 4-business-hour MVP SLA using contractor-forwarded photos, meter readings, and diagnosis notes.", "confidence": "medium", "impact_if_wrong": "high", "revisit_trigger": "First 10 real cases fulfilled manually by the founder/first reviewer." }, { "id": "home-warranty-contractor-authorization-desk-a3", "statement": "Warranty companies will accept evidence packages and appeals submitted under the contractor's own portal credentials without changing access rules to block third-party submitters.", "confidence": "medium", "impact_if_wrong": "high", "revisit_trigger": "First 20 submissions across at least 3 warranty companies." }, { "id": "home-warranty-contractor-authorization-desk-a4", "statement": "The B2B, contractor-vendor-representation framing keeps AuthLift outside public-adjuster and insurance-adjuster licensing regimes at MVP scope.", "confidence": "low", "impact_if_wrong": "severe", "revisit_trigger": "Completion of the 50-state licensing-boundary legal review before any consumer-facing expansion." }, { "id": "home-warranty-contractor-authorization-desk-a5", "statement": "Logical per-tenant data isolation with row-level auth is acceptable for the pilot cohort; single-tenant infrastructure is not required.", "confidence": "medium", "impact_if_wrong": "medium", "revisit_trigger": "Any pilot contractor or warranty-company diligence request with a hard single-tenant clause." }, { "id": "home-warranty-contractor-authorization-desk-a6", "statement": "28% contingency on uplift is a workable price point even though no home-warranty-specific published contingency benchmark exists (inferred by analogy to adjacent recovery-desk pricing).", "confidence": "low", "impact_if_wrong": "high", "revisit_trigger": "First 5 pricing conversations with pilot contractors." } ], "unknowns": [ { "id": "home-warranty-contractor-authorization-desk-u1", "question": "Which trade-qualified reviewer(s) or certified claims specialists will staff release on day one, and at what caseload before a second reviewer is needed?", "blocks": "Any commercial claim; cycle-time SLA credibility.", "resolution_path": "Named reviewer + role scope confirmed before pilot launch." }, { "id": "home-warranty-contractor-authorization-desk-u2", "question": "Which warranty companies (beyond American Home Shield, Cinch, Choice Home Warranty) are in scope for the per-provider rule library at launch?", "blocks": "Coverage-rule and denial-pattern library breadth; portal-adapter build order.", "resolution_path": "Owner confirms in-scope warranty-company list from the pilot cohort's actual network enrollments." }, { "id": "home-warranty-contractor-authorization-desk-u3", "question": "What is the actual willingness-to-pay above the $25 + 28% band once a contractor sees a real Authorization Audit gap analysis?", "blocks": "Pricing hypothesis; Auto-Submit tier economics.", "resolution_path": "8-10 pilot-contractor pricing conversations with an explicit Authorization Audit result in hand." }, { "id": "home-warranty-contractor-authorization-desk-u4", "question": "Which existing systems (dispatch/field-service software, warranty-company portals) must intake integrate with on day one?", "blocks": "Architecture module boundaries; portal-adapter data-in/out contracts.", "resolution_path": "Pilot-cohort tech-inventory questionnaire (Housecall Pro / ServiceTitan / Jobber usage)." }, { "id": "home-warranty-contractor-authorization-desk-u5", "question": "Is there a state-by-state constraint on representing a contractor-vendor in an appeal that changes the licensing-boundary posture?", "blocks": "Consumer-facing expansion; appeal-filing scope beyond the pilot states.", "resolution_path": "50-state legal review completed as a build-before-scale checkpoint before scaling past the B2B contractor-side MVP." } ], "expert_panel": [ { "role": "Product Strategy", "key_concern": "Is the ICP narrow enough to earn a first pilot cohort without diluting into full claims-consulting scope?", "recommendation": "Constrain launch to solo/small independent HVAC contractors with 15+ warranty work orders/month; broaden to plumbing/electrical/appliance only after the pilot's 20-case cap is hardened.", "dissent": "May under-price the national contractor-network opportunity and slow the pricing narrative." }, { "role": "Software Architecture", "key_concern": "Are we defaulting to microservices without justification for a document-and-portal-submission workload?", "recommendation": "Single deployable modular monolith with a documented seam for the AI extraction/drafting module, the highest-volume path.", "dissent": "May look unsophisticated to enterprise reviewers expecting a service-mesh diagram." }, { "role": "Frontend / UX", "key_concern": "Is the evidence-to-authorization chain visible and trustable in every workflow screen?", "recommendation": "Every case view renders evidence citation to completeness-checklist status to reviewer release in one glance.", "dissent": "Adds vertical density that non-domain reviewers may call cluttered." }, { "role": "Backend / Data", "key_concern": "Is the case audit trail append-only and reconstructable given the case's role as the basis for a contingency invoice?", "recommendation": "Event-sourced audit log for all case state transitions; hash-stamped evidence snapshots; versioned per-warranty-company rule tables.", "dissent": "Higher write-path complexity than plain CRUD; discipline required as warranty-company portal formats change." }, { "role": "AI / ML", "key_concern": "Are extraction and drafting outputs grounded, cited, and gated against overstated diagnosis certainty?", "recommendation": "Retrieval-first extraction with source-span citations, structured output validation, and a mandatory reviewer release gate before submission.", "dissent": "Slower than open-ended chat; may frustrate contractors expecting instant auto-submission." }, { "role": "Security", "key_concern": "Is the STRIDE surface documented for a system holding contractor-vendor credentials and warranty-company portal access?", "recommendation": "Threat model per module, per-tenant row-level auth, secrets in managed KMS, dependency scanning in CI.", "dissent": "Overhead in early prototype; some controls can wait until first paying contractor." }, { "role": "Privacy / Compliance", "key_concern": "Is the licensing boundary (B2B contractor-vendor representation, not policyholder representation) enforced everywhere, including marketing copy?", "recommendation": "SOC 2 Type I in year one; standing disclaimer on every case and public page; never claim to be an adjuster or attorney.", "dissent": "May slow content velocity and lock out enterprise contractor-group buyers requiring ISO/HITRUST on day one." }, { "role": "DevOps / Reliability", "key_concern": "Is the ops model boring enough to run without a dedicated SRE during seasonal HVAC demand spikes?", "recommendation": "Single production region + managed database + edge delivery; SLO published as availability + p95 latency only.", "dissent": "Single region concentrates risk during a regional outage at peak summer/winter HVAC season." }, { "role": "Data / Analytics", "key_concern": "Are the leading indicators (cycle time, escalation rate, uplift rate) wired before launch?", "recommendation": "Instrument intake-to-authorization cycle time, escalation-to-appeal rate, and average uplift secured; ship dashboards before the pilot cohort starts.", "dissent": "Analytics scope-creep can steal weeks from core extraction and drafting work." }, { "role": "Accessibility", "key_concern": "Does the reviewer release workflow meet WCAG 2.2 AA for every screen a reviewer uses?", "recommendation": "Enforce keyboard-only walkthrough for the evidence-review and release screens; add axe-core to CI on reviewer surfaces.", "dissent": "Density-heavy case UI is hard to ship AA-clean quickly." }, { "role": "SEO / Content", "key_concern": "Is the microsite claim honest and gated on evidence, avoiding any implied guaranteed-authorization claim?", "recommendation": "Trade-fluent topical-authority content only (home warranty statistics, contractor pain, licensing boundary); no fabricated testimonials, no case-outcome claims until the pilot produces real, disclosed data.", "dissent": "Slower content velocity than a generic SaaS blog." }, { "role": "Executive Sponsor", "key_concern": "Is there a written kill criterion given the licensing-boundary and warranty-company-retaliation risks?", "recommendation": "Kill/pivot decision at 90 days if fewer than 5 contractors convert to a second paid case, or if any warranty company blocks third-party submission across its network.", "dissent": "Founders often resist naming kill criteria in writing." } ], "strategy": { "business_model": "Outcome-priced per-case fee (flat intake + contingency on uplift) with a recurring Auto-Submit subscription tier", "revenue_streams": [ "Authorization Boost Package ($25 flat intake fee + 28% contingency on uplift secured)", "Auto-Submit monthly subscription ($99-249/mo by volume, available after 3+ successful cases)" ], "moat": [ "Live per-warranty-company portal knowledge and coverage/exclusion-language library", "Historical case-outcome data feeding the regional parts/labor cost-benchmark library", "Denial-pattern library that pre-empts each provider's common rejection reasons", "Trade-licensed reviewer relationships that keep every technical claim defensible" ], "gtm": [ "Free Authorization Audit lead magnet on one recent underpaid/denied work order, delivered within 24 hours", "Founder-led warm outreach to trade Facebook groups and direct contractor contacts", "SEO/AEO content targeting exact contractor search queries (e.g. \"home warranty authorized amount too low\")" ], "pricing_hypothesis": "Pilot cases priced at the standard $25 + 28% band; Auto-Submit tier validated against a contractor's per-work-order back-office opportunity cost before scaling beyond the pilot cohort.", "kill_criteria": [ "No pilot contractor converts to a second paid case within 30 days", "Authorization Audit-to-paid conversion below 25% after 20 pilot cases", "A major warranty company blocks third-party portal submission across its network", "Rework/escalation rate sustained above 25% for a full quarter" ] }, "security": { "stride": [ { "threat": "Spoofing", "scenario": "Attacker attempts to impersonate a trade-qualified reviewer to release a fabricated evidence package for submission.", "mitigation": "SSO with MFA; release signatures bound to a cryptographic session claim, not a form field." }, { "threat": "Tampering", "scenario": "Historical evidence-package citations edited after the fact to hide an unresolved completeness gap.", "mitigation": "Append-only audit log; hash-chained case-history snapshots; diff view on every reviewer release surface." }, { "threat": "Repudiation", "scenario": "A reviewer or contractor denies approving a submitted evidence package or a filed appeal.", "mitigation": "Signed attestations with server-side timestamp + releaser identity; contractor consent captured before every appeal filing." }, { "threat": "Information Disclosure", "scenario": "Cross-tenant leak of a contractor's warranty-company portal credentials or case evidence through shared retrieval indices or logs.", "mitigation": "Tenant-scoped row-level auth; PII/credential scrubbing in logs; per-tenant retrieval indices." }, { "threat": "Denial of Service", "scenario": "Runaway extraction job or portal-status polling exhausts shared workers during seasonal HVAC demand spikes.", "mitigation": "Per-tenant concurrency + budget caps; circuit breaker on model calls and portal adapters; degrade-gracefully queue." }, { "threat": "Elevation of Privilege", "scenario": "Standard user acquires reviewer-release capability via a workflow shortcut.", "mitigation": "Roles stored in a separate table; capability checks server-side; no client-only role checks." } ], "privacy_posture": "Data-minimization by default; per-tenant isolation; DPA templates on file; contractor-owned case export option to limit any downstream dispute exposure.", "compliance_targets": [ "State service-contract regulatory boundary (CA Dept. of Insurance, Insurance Code Part 7 -- home protection contracts; TX TDLR Occupations Code Ch. 1304) -- AuthLift itself does not register as a service-contract provider", "SOC 2 Type II", "ISO 27001 (year two)" ], "data_classifications": [ "Contractor-account credentials", "PII", "Case evidence (photos, readings, cost data)" ] }, "devops": { "ci_cd": "PR -> typecheck + unit + snapshot tests -> preview deploy -> main auto-deploys to a single production region; per-warranty-company rule-table migrations gated on review.", "environments": [ "local", "preview (per-PR)", "staging (shared)", "production (single region + multi-AZ)" ], "observability": [ "Structured logs with tenant + request IDs", "RED metrics per workflow", "Error tracking with source maps", "Model-call spans with cost + latency", "Weekly SLO review" ], "testing_pyramid": [ "Unit tests on completeness-checklist scoring and hard-gate rule modules", "Component tests on reviewer release surfaces", "Contract tests on warranty-company portal-adapter integrations", "End-to-end smoke test on the intake -> release -> submission path" ], "accessibility_tests": [ "axe-core in CI on reviewer release surfaces", "Keyboard-only walkthrough per workflow", "Prefers-reduced-motion honored" ], "performance_budget": "p95 workflow latency published per module; evidence-package generation cold-path under 30s or shown as a background job." }, "accessibility_i18n_ethics": { "wcag_target": "AA", "locales": [ "en-US" ], "rtl_support": false, "ethical_risks": [ "Package submitted without reviewer review", "Appeal filed without contractor consent", "Portal-facing errors attributed solely to AI", "Mis-selling AuthLift as a licensed adjuster, public adjuster, or attorney" ], "ethical_guardrails": [ "Human reviewer release required before submission; contractor consent required before any appeal is filed in their name", "Per-warranty-company rule-card isolation with dated citations", "Standing disclaimer on every case and public page: \"AuthLift is not a law firm, insurance adjuster, or public adjuster and does not provide legal advice; all technical repair determinations remain those of the contractor's licensed personnel.\"" ] }, "governance": { "ownership": [ { "area": "Product + roadmap", "owner": "Executive Sponsor" }, { "area": "Architecture + platform", "owner": "Engineering Lead" }, { "area": "Evidence package + release workflow", "owner": "Trade-Qualified Reviewer" }, { "area": "Compliance + privacy", "owner": "Compliance Lead" }, { "area": "Design system", "owner": "Design Lead" }, { "area": "SEO + content", "owner": "Content Lead" } ], "docs_required": [ "ADR log (checked in)", "Owner-action ledger", "Evidence register", "STRIDE threat model", "Runbook: incident, restore, breach notification", "Reviewer release playbook + signature policy" ], "naming_conventions": [ "kebab-case slugs for blueprints and routes", "camelCase for TypeScript identifiers", "SCREAMING_SNAKE_CASE for environment variables", "Verb-first action names (e.g., submit-evidence-package)" ], "change_control": "ADR-per-major-decision; warranty-company rule-table migrations require review; production deploys gated on green CI + owner-action ledger check." }, "risk_register": [ { "id": "home-warranty-contractor-authorization-desk-r1", "risk": "Public-adjuster licensing exposure if scope creeps to consumer-side (policyholder) representation", "likelihood": "low", "impact": "severe", "mitigation": "Strict B2B-only scope at launch; explicit disclaimers; 50-state legal review before any consumer-facing expansion", "contingency": "Immediate scope retraction; legal notice; audit-log export within 24 hours", "owner": "legal" }, { "id": "home-warranty-contractor-authorization-desk-r2", "risk": "A warranty company changes portal access rules to block third-party submitters", "likelihood": "medium", "impact": "high", "mitigation": "Always submit under the contractor's own credentials/consent; maintain relationships across multiple providers so no single policy change is fatal", "contingency": "Fall back to contractor-submitted packages with AuthLift providing the completed evidence package only", "owner": "ops" }, { "id": "home-warranty-contractor-authorization-desk-r3", "risk": "AI misextracts diagnostic data, leading to an inaccurate evidence package", "likelihood": "medium", "impact": "high", "mitigation": "Mandatory trade-qualified reviewer review before every submission; red-team accuracy checks", "contingency": "Reviewer-triggered rework + regeneration; incident postmortem shared with the contractor", "owner": "engineering" }, { "id": "home-warranty-contractor-authorization-desk-r4", "risk": "Cross-tenant data leak of case evidence or a contractor's portal credentials", "likelihood": "low", "impact": "severe", "mitigation": "Row-level auth + per-tenant retrieval indices + log-scrubbing", "contingency": "Breach-notification runbook; forced credential rotation; scoped tenant kill switch", "owner": "engineering" }, { "id": "home-warranty-contractor-authorization-desk-r5", "risk": "Reviewer shortage during a seasonal HVAC demand spike (early-demand trap)", "likelihood": "high", "impact": "high", "mitigation": "Hard pilot cap at 20 cases in month one; build-before-scale gates; SOC 2 Type I year one", "contingency": "Pause new-case intake; contract framework carve-out with legal review", "owner": "ops" }, { "id": "home-warranty-contractor-authorization-desk-r6", "risk": "Single-region outage takes production down during a rush-case cycle", "likelihood": "low", "impact": "high", "mitigation": "Multi-AZ managed database; nightly cross-region backup", "contingency": "Documented restore-to-DR runbook; RTO 8h / RPO 1h during pilot", "owner": "engineering" } ], "roadmap": [ { "phase": "Phase 0 - Discovery + pilot recruitment", "weeks": "Weeks 1-4", "outcomes": [ "5-10 independent HVAC contractor pilot signups from warm network and trade Facebook groups", "Authorization Audit gap-analysis pack from each pilot contractor's most recent underpaid work order", "Written ICP + pricing hypothesis" ], "exit_criteria": [ "≥5 pilot contractors signed", "Owner-action ledger populated per contractor", "Trade-qualified reviewer identity confirmed" ], "kill_criteria": [ "<3 pilot contractors after 4 weeks", "No willingness-to-pay signal above the $25 intake baseline" ] }, { "phase": "Phase 1 - Thin vertical slice", "weeks": "Weeks 5-10", "outcomes": [ "Intake -> evidence package -> completeness checklist -> reviewer release -> portal submission working end-to-end for one work order", "Case audit trail wired", "Instrumentation live" ], "exit_criteria": [ "1 real Authorization Boost Package delivered + reviewer-released", "p95 workflow latency published" ], "kill_criteria": [ "Reviewer release cycle exceeds the 4-business-hour MVP SLA on >50% of cases", "Case audit trail cannot be reconstructed on demand" ] }, { "phase": "Phase 2 - Pilot cohort", "weeks": "Weeks 11-20", "outcomes": [ "5-10 contractors completing cases weekly, capped at 20 total pilot cases", "First paid second-case conversion", "SOC 2 Type I scoping" ], "exit_criteria": [ "≥5 contractors converted to a second paid case", "Authorization-Audit-to-paid conversion signal captured", "Postmortem cadence in place" ], "kill_criteria": [ "No second-case conversion by week 20", "Rework/escalation rate exceeds 25% without contract offset" ] }, { "phase": "Phase 3 - Commercial launch", "weeks": "Weeks 21-36", "outcomes": [ "Public commercial launch of the microsite as 'ready'", "Auto-Submit subscription live", "Owner-action ledger closed for launched blueprint" ], "exit_criteria": [ "Zero blocking owner actions for launched blueprint", "Publicly indexable microsite with WebPage+FAQPage schema only" ], "kill_criteria": [ "Public launch not defensible against a plausible licensing-boundary or warranty-company-channel inquiry" ] } ], "metrics": { "north_star": "Average dollar uplift secured per case, with cycle time inside the 4-business-hour MVP / same-business-day standard SLA", "leading": [ "Pilot contractors signed", "Intake -> submission cycle time", "Reviewer release cycle time", "First-pass authorization win rate", "Rework/escalation rate" ], "lagging": [ "Second-case conversion rate", "Auto-Submit subscription attach rate", "Average dollar uplift secured per case", "Warranty-company channel objection count (target: 0)" ], "guardrails": [ "Model spend per tenant per week", "PII/credential exposure in logs (target: 0)", "Cross-tenant access attempts (target: 0)", "p95 workflow latency ceiling" ] }, "executive_review": { "consensus": "Ship a thin, evidence-linked, reviewer-released vertical slice for the Authorization Boost Package MVP. Prefer a boring, single-region modular monolith. Do not launch commercially until owner-action facts close and at least one reviewer-released case has been delivered and paid.", "dissent": "Executive Sponsor and Privacy/Compliance disagree on launch tempo -- Privacy recommends waiting for the 50-state licensing-boundary review before any public commercial claim.", "go_no_go": "conditional-go", "top_3_risks": [ "Public-adjuster licensing exposure if scope creeps to consumer-side representation", "AI misextracts diagnostic data, leading to an inaccurate evidence package", "A warranty company blocks third-party portal submission across its network" ], "first_10_steps": [ "Confirm the named trade-qualified reviewer(s) and role scope on file", "Populate owner-action ledger with entity, jurisdiction, contact inbox, privacy inbox", "Recruit 5-10 independent HVAC pilot contractors from warm network and trade Facebook groups", "Write ICP + kill/pivot criteria in the plan file", "Stand up the intake -> evidence package -> completeness checklist -> reviewer release -> submission loop", "Wire append-only audit log + hash-chained case-history snapshots", "Add row-level auth + tenant-scoped portal-credential storage", "Instrument intake-to-authorization cycle time, escalation rate, and uplift-secured events", "Publish the microsite with WebPage+FAQPage schema only and noindex until owner-facts close", "Schedule the 90-day kill/pivot review with executive sponsor" ] } }, "project_site": { "slug": "home-warranty-contractor-authorization-desk", "app_name": "AuthLift Authorization Desk", "archetype": "filing-dossier", "archetype_label": "authorization case desk", "reader_role": "Contractor Owner/Operator", "one_sentence_app": "AuthLift Authorization Desk is a case desk for independent HVAC, plumbing, electrical, and appliance-repair contractors who need every home-warranty work order tied to a complete, reviewer-released evidence package before a warranty company's first-offer authorization becomes the final word.", "homepage_sequence": [ "scene", "workflow", "instrument", "offer", "proof", "qualification", "objections" ], "hero": { "frame_label": "Home services / warranty recovery · authorization case desk", "eyebrow": "Contractor Owner/Operator / under-authorized or scope-limited work order", "interface_title": "AuthLift case desk", "primary_panel_title": "Case #48213 · HVAC compressor replacement · gap: $640 under first offer", "primary_panel_body": "Open case run: extract the diagnosis photos and meter readings, score against the warranty company's completeness checklist, then stage the Authorization Boost Package for reviewer release.", "side_panel_title": "Before this ships", "side_panel_items": [ "Photo and meter-reading evidence confirmed complete", "Cost benchmark checked against regional parts/labor library", "Contractor consent captured if an appeal is needed" ], "status_metric": "REVIEW", "status_label": "reviewer release pending" }, "language": { "problem_heading": "The under-authorization moment", "mechanism_heading": "Inside the AuthLift case desk", "proof_heading": "Why this wins the first pass", "offer_heading": "What ships on every case", "objection_heading": "The hard questions", "qualification_heading": "Who this is not for", "cta_close": "Start a case from your most recent under-authorized work order -- released by a trade-qualified reviewer, priced only on the uplift secured." }, "modules": [ { "name": "Case intake", "job": "Turns a forwarded work order number, photos, meter readings, and diagnosis notes into a named case with normalized evidence and a completeness gap list.", "artifact": "case record" }, { "name": "Completeness checklist", "job": "Holds the deterministic, per-warranty-company gate comparing every required field and photo count against the evidence on file, flagging gaps before a reviewer ever sees the case.", "artifact": "completeness checklist worksheet" }, { "name": "Authorization Boost Package", "job": "Packages the evidence package, cost benchmark, and appeal narrative (if needed) into the record submitted through the warranty company's contractor portal and tracked to resolution.", "artifact": "submission package" } ], "checkpoints": [ { "label": "completeness checklist item", "pass": "extracted with source citation", "fail": "chased or shipped as explicit gap" }, { "label": "under-authorization rule", "pass": "deterministic gate, evidence-pointer cited", "fail": "blocked before submission" }, { "label": "Authorization Boost Package", "pass": "reviewer releases for submission", "fail": "stays draft" } ], "signature_scene": "You're a contractor owner running a two-truck HVAC shop. A warranty company just authorized $640 less than the compressor replacement actually costs, and the portal form gives you one text box to argue with. Someone needs to know today whether that's worth fighting, and the only paper trail is a phone photo of a nameplate and a diagnosis note you typed in the truck. This page is built like the case desk that person needed before the next work order comes in." }, "design": { "archetypes": [ "compliance/regulatory tool", "workflow tool", "operations system" ], "user_mindset": { "goals": "Prove, in hours not weeks, that a work order deserves the fullest authorization -- often while a warranty company's first-offer deadline is already ticking.", "session_length": "Bursty around new work orders and appeal windows; otherwise a weekly caseload check-in.", "confidence": "Expert users (contractor owners, office/ops managers); will not accept an opaque AI verdict without a cited evidence pointer.", "interface_needs": "Print-parity case layouts, evidence-cited gap rows, submit/track states, a portfolio view across open cases." }, "posture": [ "authoritative", "trustworthy", "operational" ], "density": "compact", "trust_level": { "tier": "high", "sensitive_domains": [ "contractor warranty-company portal credentials", "case evidence (photos, meter readings, cost data)", "authorization and appeal outcome history" ], "implications": [ "Every destructive action confirmed with typed intent, never a single click.", "Errors carry remediation copy + owner, not just a message.", "Focus rings visible on every interactive element (WCAG 2.2 AA minimum).", "Named releaser (reviewer) on any outbound submission.", "Explicit contractor-consent gate before any appeal is filed in their name." ] }, "differentiation": { "avoid": [ "Material Design defaults", "shadcn stock look (unstyled cards + slate ring)", "Purple/indigo gradient heroes", "Stripe/Linear/Notion mimicry", "Vertical cliche: toolbox stock photography and alarm-red penalty banners" ], "strategy": "Anchor on the work-order stamp -- a ledger of cases, each with an authorization status -- as the recurring signature element; every page must include it at least once. Reserve the rust/amber accent for authorization-state and deadline signals only." }, "territories": [ { "name": "Work Order Stamp Desk", "color_mood": "slate-teal + rust indicator", "typography": "Fraunces + Inter", "density": "ledger rows", "component_feel": "stamped work-order log you'd find on a dispatch clipboard", "motion": "row-reveal", "fits": "per-case evidence review and reviewer release", "risks": "could read as too industrial without warm neutrals" }, { "name": "Portfolio Panel Board", "color_mood": "control-panel navy + amber", "typography": "Neue Haas Grotesk", "density": "grid-driven", "component_feel": "dispatch board: one lamp per open case", "motion": "status-pulse on change", "fits": "multi-case Auto-Submit portfolio view", "risks": "grid can overwhelm at high case volume without grouping" }, { "name": "Appeal Timeline", "color_mood": "slate + rust", "typography": "Inter", "density": "timeline", "component_feel": "appeal-thread with dated follow-ups", "motion": "scroll-sync", "fits": "escalation and appeal cycle-time tracking", "risks": "timeline fatigue on long-running appeals" } ], "chosen_territory": "Work Order Stamp Desk", "chosen_rationale": "The Authorization Boost Package is the deliverable and the work order is the unit of work; a stamp/ledger metaphor keeps every screen artifact-shaped -- the way a warranty company's portal or a contractor's own back office would actually track it -- without borrowing another launched business's binder-tab motif.", "prioritized_components": [ { "name": "Warranty-company chip", "why": "every case is scoped by its warranty company and that provider's completeness checklist" }, { "name": "Evidence row with source citation", "why": "every line in the evidence package must show the exact photo, reading, or cost benchmark it cites" }, { "name": "Authorization Boost Package assembler", "why": "the submission output is a bundle: evidence package + cost benchmark + completeness checklist + appeal narrative (if needed)" } ], "patterns": [ { "name": "Warranty-company switcher", "description": "Global warranty-company selector (American Home Shield, Cinch, Choice Home Warranty, and more); every completeness checklist and cost benchmark respects it." }, { "name": "Case release stamp", "description": "Named trade-qualified reviewer attestation on every case; appeals additionally require captured contractor consent before filing." } ], "states": [ "default", "hover", "active", "focus", "disabled", "loading", "skeleton", "empty", "error", "warning", "success", "offline", "permission-denied", "partial-data", "syncing", "unsaved-changes", "ai-generating" ], "localization": [ "Copy budgets assume +35% expansion for future non-English translations.", "RTL mirror not required for the en-US launch scope.", "Dates/times/currencies use Intl APIs, never hardcoded formats.", "Touch targets ≥ 44px; keyboard tab order matches visual order.", "Density modes: comfortable (default), compact (power users), spacious (accessibility)." ], "uniqueness_audit": { "app_specific_decisions": [ "Work-order-stamp motif (ledger rows, not binder tabs)", "Evidence-row-cites-source-or-explicit-gap copy discipline -- never invented data" ], "cliches_avoided": [ "Toolbox / wrench stock photography", "Green-check compliance theatre", "Penalty-scare banners" ], "scale_notes": "New blueprints inherit the network shell but MUST declare their own signature element, accent role, and anti-reference before they can be marked ready. Enforced by the release gate." }, "tokens": { "brand": "199 47% 20%", "brand-fg": "40 33% 96%", "surface": "39 45% 95%", "ink": "213 26% 14%", "muted": "213 8% 42%", "accent": "22 55% 47%" }, "type": { "display": "-apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif", "body": "-apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif", "fonts_url": "" }, "signature": { "motif": "Work-order stamp rows · warranty-company chip", "render": "ledger-rows" }, "slug": "home-warranty-contractor-authorization-desk" }, "canva": { "slug": "home-warranty-contractor-authorization-desk", "territory": "Work Order Stamp Desk", "family": { "id": "home-services-trust", "name": "Home Services / Trade Trust", "motion": "calm" }, "tokens": { "brand": "199 47% 20%", "brand-fg": "40 33% 96%", "surface": "39 45% 95%", "ink": "213 26% 14%", "muted": "213 8% 42%", "accent": "22 55% 47%" }, "type": { "display": "-apple-system, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif", "body": "-apple-system, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif", "fonts_url": "" }, "scale": { "h1": "clamp(2.5rem, 5.5vw, 4.25rem)", "h2": "clamp(1.75rem, 3vw, 2.5rem)", "h3": "clamp(1.25rem, 2vw, 1.5rem)", "body": "clamp(1rem, 1.1vw, 1.125rem)", "small": "0.8125rem", "tracking_display": "-0.01em", "tracking_body": "-0.003em", "weight_display": 650, "weight_body": 430 }, "spacing": { "card_padding": "1.75rem", "card_radius": "0.375rem", "card_shadow": "0 0 0 1px hsl(var(--ink) / 0.08)", "section_gap": "clamp(3.5rem, 8vw, 6.5rem)", "hero_gap": "clamp(1.25rem, 2vw, 2rem)" }, "layout": { "hero": "split-primary", "card": "elevated-soft", "cta": "solid-brand", "archetype": "ledger", "card_silhouette": "flat-outline", "button_geometry": "rounded-sm" }, "background": { "hero_gradient": "radial-gradient(1200px 600px at 10% -10%, hsl(22 55% 47% / 0.16), transparent 60%), radial-gradient(900px 500px at 90% 10%, hsl(199 47% 20% / 0.14), transparent 55%)", "cta_gradient": "linear-gradient(135deg, hsl(199 47% 20%), hsl(22 55% 47%))", "section_wash": "linear-gradient(180deg, hsl(39 45% 95%) 0%, hsl(199 47% 20% / 0.05) 100%)" }, "motif": "Work-order stamp rows + warranty-company chip" }, "vertical_style": { "accent": "rust-indicator", "signature": "Work-order stamp rows with warranty-company chip", "layout": "Case ledger", "anti": "Toolbox stock photography and alarm-red penalty banners" }, "capabilities": { "marketing": true, "portal": true, "ops": true, "chatbot": true, "payments": true }, "evidence": [ { "id": "home-warranty-contractor-authorization-desk-e1", "business_slug": "home-warranty-contractor-authorization-desk", "area": "Identity", "claim_or_finding": "Legal entity, registered address, and jurisdiction of formation are not yet declared.", "status": "owner-action", "evidence": "No owner-supplied facts on file.", "verification_command": "Owner submits entity + jurisdiction pack.", "fix_owner": "owner", "remediation": "Provide entity name, registration number, and jurisdiction of formation.", "severity": "blocker" }, { "id": "home-warranty-contractor-authorization-desk-e2", "business_slug": "home-warranty-contractor-authorization-desk", "area": "Trust boundary", "claim_or_finding": "Public page is a validation microsite for a done-for-you evidence-and-appeal support service; not an insurance adjuster, public adjuster, or law firm.", "status": "verified", "evidence": "Microsite carries the explicit disclaimer: \"AuthLift is not a law firm, insurance adjuster, or public adjuster and does not provide legal advice; all technical repair determinations remain those of the contractor's licensed personnel.\"", "verification_command": "Inspect /microsites/home-warranty-contractor-authorization-desk for trust boundary.", "fix_owner": "engineering", "remediation": "None -- enforced by template.", "severity": "low" }, { "id": "home-warranty-contractor-authorization-desk-e3", "business_slug": "home-warranty-contractor-authorization-desk", "area": "SEO integrity", "claim_or_finding": "No fake review, rating, LocalBusiness, or Organization identity schema is emitted; no guaranteed-authorization or guaranteed-recovery claims without the outcomes-vary caveat.", "status": "verified", "evidence": "Only WebPage + FAQPage schema is generated; marketing compliance gate applied.", "verification_command": "View SEO Factory row for home-warranty-contractor-authorization-desk", "fix_owner": "engineering", "remediation": "None -- enforced by SEO factory.", "severity": "low" }, { "id": "home-warranty-contractor-authorization-desk-e4", "business_slug": "home-warranty-contractor-authorization-desk", "area": "Regulated claims", "claim_or_finding": "Elevated trust burden -- licensing-boundary claims (B2B contractor-vendor representation, not policyholder representation) gated on owner facts: named trade-qualified reviewer engagement, entity identity, and counsel review of engagement terms and disclaimers.", "status": "release-blocker", "evidence": "Trust burden = Medium-high", "verification_command": "Complete owner-action pack.", "fix_owner": "owner", "remediation": "Provide reviewer engagement documentation (role-title until then), professional review, and disclosure facts.", "severity": "high" }, { "id": "home-warranty-contractor-authorization-desk-e5", "business_slug": "home-warranty-contractor-authorization-desk", "area": "Manifest coverage", "claim_or_finding": "Manifest-backed blueprint present in source repository (2026-07-15 build, AuthLift run).", "status": "assumed", "evidence": "manifest.json entry", "verification_command": "Cross-check manifest entry for home-warranty-contractor-authorization-desk in the builds repository.", "fix_owner": "engineering", "remediation": "Attach the manifest run to the evidence register.", "severity": "medium" }, { "id": "home-warranty-contractor-authorization-desk-e6", "business_slug": "home-warranty-contractor-authorization-desk", "area": "Pilot outcomes", "claim_or_finding": "No case outcomes, dollar amounts recovered, testimonials, contractor names, logos, or review stars are on file -- the pilot has not yet run.", "status": "owner-action", "evidence": "No pilot data on file; BRIEF.md §4 flags all outcome claims as [PLACEHOLDER] until the pilot produces real, disclosed data.", "verification_command": "Owner supplies pilot outcome data with consent to publish.", "fix_owner": "owner", "remediation": "Run the 8-10 contractor pilot cohort and log real, disclosed outcomes before any outcome claim is published.", "severity": "high" } ], "seo_pages": { "id": "seo-home-warranty-contractor-authorization-desk", "business_slug": "home-warranty-contractor-authorization-desk", "route": "/microsites/home-warranty-contractor-authorization-desk", "title": "AuthLift — Home Warranty Contractor Payment & Sc… · k7qm", "description": "AuthLift for independent HVAC, plumbing, electrical, and appliance-repair contractors enrolled as home warranty network vendors. Done-for-you evidence packages and appeals, priced on the uplift secure…", "canonical": "/microsites/home-warranty-contractor-authorization-desk", "og_title": "AuthLift — Home Warranty Contractor Payment & Scope Authorization Desk", "og_description": "AuthLift for independent HVAC, plumbing, electrical, and appliance-repair contractors enrolled as home warranty network vendors. Done-for-you evidence packages and appeals, priced on the uplift secure…", "schema_type": "FAQPage", "schema_status": "pending-owner-facts", "sitemap_include": false, "noindex": true }, "ddd_coverage": { "slug": "home-warranty-contractor-authorization-desk", "total": 20, "passed": 20, "pct": 100, "checks": [ { "key": "actors", "label": "Actors", "count": 6, "min": 3, "ok": true, "gate": "domain", "unblock": "Not needed -- check passes at current counts." }, { "key": "glossary", "label": "Glossary", "count": 16, "min": 6, "ok": true, "gate": "domain", "unblock": "Not needed -- check passes at current counts." }, { "key": "decisions", "label": "Business decisions", "count": 5, "min": 4, "ok": true, "gate": "domain", "unblock": "Not needed -- check passes at current counts." }, { "key": "events", "label": "Domain events", "count": 12, "min": 6, "ok": true, "gate": "domain", "unblock": "Not needed -- check passes at current counts." }, { "key": "subdomains", "label": "Subdomains", "count": 14, "min": 8, "ok": true, "gate": "core", "unblock": "Not needed -- check passes at current counts." }, { "key": "bcs", "label": "Bounded contexts", "count": 13, "min": 4, "ok": true, "gate": "boundary", "unblock": "Not needed -- check passes at current counts." }, { "key": "ctx_map", "label": "Context map", "count": 12, "min": 3, "ok": true, "gate": "boundary", "unblock": "Not needed -- check passes at current counts." }, { "key": "event_storm", "label": "Event storm rows", "count": 15, "min": 6, "ok": true, "gate": "boundary", "unblock": "Not needed -- check passes at current counts." }, { "key": "aggregates", "label": "Aggregates", "count": 12, "min": 3, "ok": true, "gate": "invariant", "unblock": "Not needed -- check passes at current counts." }, { "key": "invariants", "label": "Invariants", "count": 10, "min": 4, "ok": true, "gate": "invariant", "unblock": "Not needed -- check passes at current counts." }, { "key": "ai_agents", "label": "AI agents", "count": 3, "min": 2, "ok": true, "gate": "ai-safety", "unblock": "Not needed -- check passes at current counts." }, { "key": "use_cases", "label": "Use cases", "count": 4, "min": 3, "ok": true, "gate": "buildability", "unblock": "Not needed -- check passes at current counts." }, { "key": "evidence_reg", "label": "Evidence register", "count": 8, "min": 5, "ok": true, "gate": "domain", "unblock": "Not needed -- check passes at current counts." }, { "key": "assumptions", "label": "Assumption register", "count": 7, "min": 4, "ok": true, "gate": "domain", "unblock": "Not needed -- check passes at current counts." }, { "key": "stress_boundary", "label": "Boundary stress tests", "count": 5, "min": 3, "ok": true, "gate": "boundary", "unblock": "Not needed -- check passes at current counts." }, { "key": "stress_agg", "label": "Aggregate stress tests", "count": 5, "min": 3, "ok": true, "gate": "invariant", "unblock": "Not needed -- check passes at current counts." }, { "key": "stress_agent", "label": "Agent stress tests", "count": 3, "min": 2, "ok": true, "gate": "ai-safety", "unblock": "Not needed -- check passes at current counts." }, { "key": "gates_pass", "label": "Hard gates passing", "count": 7, "min": 7, "ok": true, "gate": null, "unblock": "Not needed -- check passes at current counts." }, { "key": "rubric", "label": "Extended rubric pass", "count": 1, "min": 1, "ok": true, "gate": "buildability", "unblock": "Not needed -- check passes at current counts." }, { "key": "foundry", "label": "Foundry package", "count": 13, "min": 4, "ok": true, "gate": "buildability", "unblock": "Not needed -- check passes at current counts." } ], "failingGates": [ "[PLACEHOLDER] owner to complete" ] }, "microsite": { "category": "Home services / warranty recovery", "shortTitle": "AuthLift", "audience": "independent or small (2-25 tech) HVAC, plumbing, electrical, and appliance-repair contractors enrolled as network vendors for home warranty companies, completing 10+ work orders/month (owner or office/ops manager as decision-maker)", "problem": "Every home-warranty work order a contractor completes runs through the warranty company's contractor portal with a bare-minimum diagnosis form and no systematic evidence package, cost benchmark, or appeal path. The warranty company's default, lowest-cost authorization stands unless the contractor personally fights it -- and most contractors don't have the back-office time to fight every under-authorization, so they eat the loss, do a band-aid fix, or start declining warranty-channel work altogether.", "offer": "On AuthLift, contractors stop absorbing under-authorizations and start getting paid what the job is worth. Forward a work order number, photos, meter/pressure readings, and diagnosis notes; AuthLift's AI engine assembles a complete evidence package -- nameplate/serial data, code citations, itemized parts-and-labor cost benchmark -- and a trade-qualified reviewer releases the Authorization Boost Package for submission through the warranty company's contractor portal. When a work order is still under-authorized, scope-limited, or denied, AuthLift files the structured appeal and tracks it to resolution, with the contractor's consent captured before anything is filed in their name.", "faq": [ { "q": "Is AuthLift for the field crew or for the office/ops manager?", "a": "Both, because at 2-25 techs they're usually the same decision-maker: the contractor owner or office/ops manager who reconciles warranty-company payouts against job cost. If a recent work order came back authorized for less than the diagnosed repair actually requires, the workflow will match your reality immediately." }, { "q": "How is an Authorization Boost Package built to win on the first pass?", "a": "Every field in the evidence package carries a source citation from the photos, meter readings, or diagnosis notes you forwarded -- missing items ship as an explicit gap, never an invented reading. The completeness checklist (required fields, photo counts, documentation types per warranty company) runs through deterministic rules, not a language model. A trade-qualified reviewer releases every package before it is submitted." }, { "q": "What arrives at the end of a case?", "a": "A submitted, tracked Authorization Boost Package -- evidence package (photos, meter/pressure readings, nameplate/serial data, code citations, itemized parts-and-labor cost benchmark) plus, if the warranty company's response under-authorizes, scope-limits, or denies, a structured appeal filed with your consent -- followed to a paid resolution." }, { "q": "How does AuthLift pricing work?", "a": "Outcome-based, never hourly. The Authorization Boost Package runs a $25 flat intake fee per work order (covers baseline evidence-assembly cost regardless of outcome) plus a 28% contingency fee on the uplift secured above the warranty company's first offer. No recovery, no contingency fee -- you owe only the $25 intake fee if AuthLift doesn't secure more than the first offer. Auto-Submit runs $99-249/mo by volume once you have 3+ successful cases." }, { "q": "How do I get started on AuthLift?", "a": "Run the free Authorization Audit -- forward one recent underpaid or denied work order for a gap analysis delivered within 24 hours, no cost, no obligation -- or go straight to a paid Authorization Boost Package if you already have a work order in hand." }, { "q": "Do you certify repairs, inspect equipment, or act as an insurance adjuster on our behalf?", "a": "No -- and that boundary is the design. AuthLift does not perform, certify, or sign off on physical repairs, does not act as a licensed insurance adjuster, public adjuster, or attorney, and does not represent a homeowner/policyholder against their own warranty coverage. Our reviewer releases the evidence package's completeness and accuracy attestation; the contractor's own licensed tradesperson attests to the diagnosis, code citations, and recommended scope. The contractor's license backs every technical claim." }, { "q": "How long is case history retained?", "a": "Case evidence, submissions, and outcomes are retained per case, dated and versioned, for as long as the contractor account is active plus a standard retention buffer. Because a case can become the basis of a payment dispute, we offer a contractor-owned export option." }, { "q": "What if the warranty company won't respond to the appeal?", "a": "That's exactly what cycle-time tracking and reviewer escalation are built for. If the portal stalls past SLA, the reviewer escalates via phone or email and the case status stays visible. If the warranty company stays silent, the case ships at the tracked status, never marked resolved on a guess." }, { "q": "What if we work with multiple warranty companies?", "a": "The per-provider rule library is checklist-card based and expandable -- American Home Shield, Cinch, Choice Home Warranty, First American, Old Republic, 2-10 HBW, Landmark, and regional providers are all in scope. Every completeness checklist and cost benchmark is scored against the specific warranty company on the work order, so a case is never checked against the wrong provider's rules." } ], "process": [ { "title": "Intake: forward the work order", "body": "Forward the work order number, diagnostic photos, meter/pressure readings, unit nameplate/serial data, and your diagnosis notes via a simple form, email, or SMS. Each case gets a case ID on arrival, and the warranty company and unit are canonicalized against your account -- ambiguous matches go to a human, not a guess." }, { "title": "Extract and match against the completeness checklist", "body": "AI extracts nameplate, serial, and meter/pressure readings from photos, structures your diagnosis notes, and matches the case against the completeness checklist for the specific warranty company on the work order." }, { "title": "Draft the evidence package and cost benchmark", "body": "AI drafts the diagnosis narrative, code citations, and itemized parts-and-labor cost benchmark from regional cost data -- and, if the case needs one, an appeal argument -- all cited to your submitted evidence, never invented." }, { "title": "Human release gate", "body": "A trade-qualified reviewer verifies technical accuracy and cost benchmarks before anything is submitted. If the work order needs a supplemental-authorization request or appeal, the contractor confirms before it is filed in their name -- a required consent step, not a formality." }, { "title": "Submit and track", "body": "The Authorization Boost Package is submitted through the warranty company's contractor portal within SLA (same business day standard, 4 business hours for the MVP flow), and the case status -- submitted, authorized, under-authorized, appealed, resolved -- is tracked to a paid outcome." }, { "title": "Watch the outcome and the next work order", "body": "Every case outcome (authorized amount, denial reason if any, cycle time) feeds back into the cost-benchmark and denial-pattern libraries. Auto-Submit enrollees get every future work order submitted automatically without a per-case decision." } ], "northStarCta": { "label": "Start a case", "href": "/contact", "secondary_label": "See how a case is built", "secondary_href": "/how-it-works" }, "ubiquitousLanguage": { "audience": "independent or small (2-25 tech) HVAC, plumbing, electrical, and appliance-repair contractors enrolled as network vendors for home warranty companies, completing 10+ work orders/month", "domain": "home warranty (service contract) work order payment and scope authorization and appeal", "deliverable": "Authorization Boost Package + reviewer release (contractor consent required before any appeal)", "reviewer": "Trade-Qualified Reviewer (or certified claims specialist)", "record": "dated, versioned case record per work order", "unit_of_work": "case", "cta_primary": "Start a case", "cta_secondary": "See how a case is built", "regulator": "Warranty company", "regulator_full": "Home warranty (service contract) provider -- regulated as a home protection contract / service-contract provider by state agencies (e.g. California Department of Insurance, Texas TDLR), not as an insurer", "statute": "State service-contract statutes (CA Insurance Code Part 7 -- home protection contracts; Texas Occupations Code Ch. 1304)", "trigger_moment": "an authorization amount or scope decision the contractor believes under-covers the diagnosed repair, a scope-limiting temporary-fix decision, or a denial", "event_intake_started": "home_warranty_contractor_authorization_desk_intake_started", "event_conversation_requested": "home_warranty_contractor_authorization_desk_conversation_requested" }, "trust": { "standards": [ "Every evidence-package entry traces to a source citation from the photos, readings, or notes you forwarded -- missing items ship as explicit gaps, never invented readings", "The completeness checklist (required fields, photo counts, documentation types per warranty company) runs through versioned deterministic rules, never a language model; a trade-qualified reviewer signs every release before submission", "Case evidence and outcomes are retained per case, dated and versioned, with a contractor-owned export option" ], "response_time": "We reply within one business day -- a warranty company's appeal window does not wait for a sales rep.", "data_handling": "Your case documents and warranty-company portal credentials stay in per-contractor isolated storage and are never used to train models. AuthLift is not a law firm, insurance adjuster, or public adjuster and does not provide legal advice; all technical repair determinations remain those of the contractor's licensed personnel." }, "hook": "The next under-authorized work order lands on a tracked case, not a scramble -- AuthLift holds the evidence at rest. Contractors stop absorbing the loss and start submitting Authorization Boost Packages -- the case desk is where the evidence already lines up.", "sub_headline": "AuthLift stores every completeness-checklist decision -- evidence citation, cost benchmark, releaser -- in a dated case record you can point a warranty company to on demand. Every case maps each required field to a source at intake, deterministic rules score the completeness gaps, a trade-qualified reviewer releases the package, and the case stays reconstructable the day a dispute arrives.", "dream_outcome": "You answer the week: hand a warranty company a complete, evidence-cited case in hours instead of losing an afternoon on hold. The case record is the answer -- source-cited, versioned, and reproducible the day the payment question comes up.", "specific_pains": [ "A warranty company authorizes $640 less than the compressor replacement actually costs, and the portal gives you one text box to argue with -- nobody has time to build the case that wins it back.", "Ask for a fair authorization on a scope-limited work order and the office manager starts hunting for the diagnosis photo, the meter reading, and the parts invoice across three different phones and a truck glovebox.", "A general-purpose chatbot can produce a plausible-looking appeal letter; only a completeness-checklist-cited deterministic gate, with a trade-qualified reviewer release, produces a submission a warranty company won't bounce back for missing documentation.", "The warranty company's default authorization is the lowest-cost option unless someone personally fights it, and most contractors don't have the back-office time to fight every under-authorization on top of running the truck roll.", "A warranty company's portal reads a case as a package: photos, meter/pressure readings, nameplate/serial data, code citations, and cost benchmark. Miss any piece and the authorization defaults low." ], "cost_of_inaction": "An under-authorized work order that goes unchallenged is a permanent revenue leak, repeated every time a similar job comes through the warranty channel. A scope-limited band-aid fix instead of the correct repair risks a callback the contractor gets blamed for. Contractors who simply stop taking warranty-channel work over these issues lose a lead-generation channel they can't easily replace -- and the loss compounds every month it goes unaddressed.", "mechanism": { "name": "The AuthLift Authorization Boost engine", "steps": [ { "title": "Intake: forward the work order", "body": "Forward the work order number, diagnostic photos, meter/pressure readings, unit nameplate/serial data, and diagnosis notes. Each case gets a case ID on arrival, and the warranty company and unit are canonicalized -- ambiguous matches go to a human, not a guess." }, { "title": "Extract and match against the completeness checklist", "body": "AI extracts nameplate, serial, and meter/pressure readings from photos, structures the diagnosis notes, and matches the case against the completeness checklist for the specific warranty company." }, { "title": "Draft the evidence package and cost benchmark in deterministic rules", "body": "Required fields, photo counts, and documentation types all run through versioned deterministic gates, each citing its source, never a language model's judgment call alone." }, { "title": "Human release gate", "body": "A trade-qualified reviewer verifies technical accuracy and cost benchmarks before submission; if an appeal is needed, the contractor confirms the language before it's filed in their name." }, { "title": "Submit, track, watch the outcome", "body": "The Authorization Boost Package is submitted through the warranty company's contractor portal within SLA, and each denial reason or cycle-time data point feeds back into the checklist and cost-benchmark libraries -- plus automatic submission for Auto-Submit enrollees." } ] }, "offer_stack": [ { "item": "Authorization Boost Package per work order", "note": "evidence package (photos, meter/pressure readings, nameplate/serial data, code citations, itemized parts-and-labor cost benchmark), completeness checklist pass, and submission tracking" }, { "item": "Evidence package with source citations", "note": "the line-by-line record of every required field vs. what evidence exists -- a missing reading means the case is capped, never a guessed authorization estimate" }, { "item": "Human release on every case", "note": "trade-qualified reviewer sign-off on technical accuracy and cost benchmarks before every submission" }, { "item": "Structured appeal on under-authorization, scope-limit, or denial", "note": "the supplemental-authorization request AuthLift files with contractor consent, tracked to resolution" }, { "item": "Dated case record", "note": "the versioned record of every evidence item and outcome behind a case, available for contractor-owned export" }, { "item": "Auto-Submit subscription", "note": "$99-249/mo by volume once 3+ successful cases are on file -- every future work order submitted automatically without a per-case decision" } ], "guarantee": "No recovery, no contingency fee: if AuthLift doesn't secure more than the warranty company's first offer, the contractor owes only the $25 intake fee -- nothing else. Explicitly not guaranteed: a specific authorization outcome, warranty-company cooperation, or the accuracy of contractor-attested facts like diagnosis notes.", "urgency": "Release capacity is gated by the human chokepoint -- every case is signed by a trade-qualified reviewer before submission -- and the pilot cohort is capped at 20 total cases in month one. We stop taking new cases when the release desk is full, protecting the release discipline rather than filling a pipeline.", "objections": [ { "q": "\"Doesn't the warranty company already evaluate this fairly?\"", "a": "The warranty company's default decision is its lowest-cost option unless someone submits a complete, evidence-cited case that makes the fuller authorization the obvious call. Their incentive is to minimize payout, not to build your case for you." }, { "q": "\"Isn't this what our field-service software already does?\"", "a": "Field-service software (Housecall Pro, ServiceTitan-class tools) manages dispatch and invoicing, not warranty-specific evidence packages or appeals. AuthLift is a case desk, not a dashboard: we do the extraction, the cost benchmarking, and the submission -- you receive a tracked, resolved case." }, { "q": "\"Are we going to be liable for an AI-drafted claim?\"", "a": "No technical determination comes from a language model alone. AI extracts data and drafts the evidence package and appeal narrative from your submitted evidence; a trade-qualified reviewer verifies technical accuracy and cost benchmarks before every submission, and your own licensed tradesperson's diagnosis backs every technical claim." }, { "q": "\"Can you guarantee a bigger payout?\"", "a": "No -- and we won't sell that. The final authorized amount depends on the warranty company's coverage terms and discretion, neither of which we control. What we guarantee is the no-recovery-no-fee structure: you only pay the contingency if we secure more than the first offer." }, { "q": "\"Where does our warranty-company portal credential live?\"", "a": "In per-contractor isolated storage with least-privilege access, never used for model training. Submissions run under your own portal credentials and consent -- we never operate outside that boundary." }, { "q": "\"How is AuthLift priced?\"", "a": "Outcome-based, published tiers: $25 flat intake fee plus 28% contingency on uplift secured, never hourly, never charged if we don't beat the first offer. Anchor it against the revenue you're currently forfeiting by eating under-authorizations or declining warranty-channel work." } ], "who_this_is_not_for": [ "Homeowners or policyholders disputing their own warranty coverage -- that's consumer-side representation, a different buyer and a different legal posture; we'll point you to a consumer-side firm.", "Contractors looking for a guarantee of a specific authorization amount -- we decline that framing; outcomes depend on the warranty company's coverage terms and discretion, not paperwork alone.", "Contractors doing fewer than 10 warranty work orders a month, or shops with a full-time in-house claims specialist already extracting fair authorizations -- the case-desk format won't earn its keep at either end of that range." ], "proof_pillars": [ { "title": "Deterministic completeness rules, source-cited", "body": "Every completeness gap -- missing photo, missing meter reading, missing nameplate data -- runs through versioned rule tables against the specific warranty company's checklist, never a language model's judgment call. The record doesn't summarize the gap; it cites the missing field and the evidence pointer." }, { "title": "Human-released, every time", "body": "No case submits automatically. A trade-qualified reviewer verifies technical accuracy and cost benchmarks on every case, and the contractor confirms before any appeal is filed in their name -- a hand-off, never a guess." }, { "title": "Dated case record -- no rebuild", "body": "Every case carries the dated, versioned record of the evidence that produced it. Reconstruction for a payment dispute or a second look is a read operation, not a month of searching phones and gloveboxes." } ], "stakes_line": "The case record is the truth. Everything else -- the warranty company's first offer, the portal's one text box, the diagnosis note scrawled in the truck -- is the story that gets forgotten by the next work order.", "deliverable": "Authorization Boost Package + reviewer release (contractor consent required before any appeal)", "unit_of_work": "case", "lexicon": { "regulator": "Warranty company", "regulator_full": "Home warranty (service contract) provider -- regulated as a home protection contract / service-contract provider by state agencies (e.g. California Department of Insurance, Texas TDLR), not as an insurer", "statute": "State service-contract statutes (CA Insurance Code Part 7 -- home protection contracts; Texas Occupations Code Ch. 1304)", "statute_frame": "the intake-to-submission workflow where an unsubmitted or incomplete Authorization Boost Package is a self-inflicted underpayment risk.", "persona": "Contractor Owner/Operator", "persona_moment": "You're a contractor owner. A warranty company just authorized $640 less than the compressor replacement actually costs, and the portal gives you one text box to argue with. Someone needs to build the case that wins it back -- with every field tied to a source you can point to.", "trigger_moment": "an authorization amount or scope decision the contractor believes under-covers the diagnosed repair, a scope-limiting temporary-fix decision, or a denial", "enforcement_stakes": "revenue loss from an unchallenged under-authorization and the compounding cost of declining warranty-channel work over time (actual outcomes vary case-by-case and are never predictable or guaranteed)", "retention": "life of account + standard buffer", "cta_verb": "Start a case", "intake_checklist": [ "The work order number exactly as issued by the warranty company", "Diagnostic photos of the failure and the nameplate/serial data", "Meter or pressure readings supporting the diagnosis", "The contractor's own diagnosis notes and recommended scope", "The warranty company's first-offer authorization amount and scope, if already issued", "The internal contact and inbox we should copy on status updates", "Any prior Authorization Audit results or Authorization Boost Packages for this contractor, even partial" ], "trust_standards_specific": [ "Every evidence-package entry traces to a source citation from the photos, readings, or notes forwarded -- gaps ship explicit, never invented", "A trade-qualified reviewer signs every release; contractor consent is captured before any appeal is filed in their name", "Case evidence and outcomes are retained per case, dated and versioned, with a contractor-owned export option", "Completeness checklist requirements are mapped to your evidence line-by-line; missing required fields block submission until resolved or explicitly flagged", "AI drafting is bounded to extraction, cost benchmarking, and evidence-package/appeal-narrative drafting from structured input, disclosed, and gated on reviewer release before any case is submitted" ], "regulator_faqs": [ { "q": "Do you certify repairs or act as our insurance adjuster?", "a": "No -- AuthLift is not a law firm, insurance adjuster, or public adjuster and does not provide legal advice; all technical repair determinations remain those of the contractor's licensed personnel. The contractor's own licensed tradesperson attests to the diagnosis, code citations, and recommended scope; physical repair work always stays with the contractor's own licensed personnel." }, { "q": "How long is case history retained?", "a": "For the life of the contractor account plus a standard retention buffer, dated and versioned per case, with a contractor-owned export option given a case's potential role in a payment dispute." }, { "q": "What if the work order was never given a first-offer authorization?", "a": "That's still a standard intake -- AuthLift builds and submits the initial Authorization Boost Package rather than an appeal. An appeal only applies once a first offer exists to compare against." }, { "q": "What if we already started documenting the case ourselves?", "a": "Send what exists. We pick up mid-workflow, keep your documentation intact, register what's usable as evidence, and only chase the pieces the completeness checklist is still missing -- no rework, no re-scoring what's already sourced." } ] }, "proof_angle": { "id": "authorization-readiness", "headline": "The next under-authorized work order lands on a tracked case, not a scramble -- AuthLift holds the evidence at rest.", "lever": "AuthLift stores every completeness-checklist decision -- evidence citation, cost benchmark, releaser -- in a dated case record you can point a warranty company to on demand.", "outcome_verb": "recover", "outcome_frame": "recover the gap between a warranty company's first offer and what the diagnosed repair actually costs, in hours instead of a lost afternoon", "proof_promise": "The case record is the authorization-readiness answer -- source-cited, versioned, and reproducible the day a payment question comes up." }, "indexable": true }, "ddd": { "slug": "home-warranty-contractor-authorization-desk", "project_name": "AuthLift", "business_understanding": { "summary": "AuthLift -- On AuthLift, independent HVAC, plumbing, electrical, and appliance-repair contractors stop absorbing under-authorized home-warranty work orders. Work-order photos, meter/pressure readings, nameplate data, and diagnosis notes are extracted at intake, checked against a per-warranty-company completeness checklist in deterministic code, and every Authorization Boost Package releases with a trade-qualified reviewer's sign-off before submission through the warranty company's contractor portal.", "customer_profile": "independent or small (2-25 tech) HVAC, plumbing, electrical, and appliance-repair contracting businesses enrolled as network vendors for one or more home warranty companies (American Home Shield, Cinch, Choice Home Warranty, First American, Old Republic, 2-10 HBW, Landmark, and regional providers), completing 10+ warranty work orders/month", "customer_pain": "Contractors submit a bare-minimum diagnosis note through a generic portal form with no systematic evidence package, cost benchmark, or appeal path, so the warranty company's default (lowest-cost) authorization stands unless the contractor personally fights it. Negotiated-down pay rates, multi-week payment delays, forced band-aid repairs, mandated low-cost parts, and days-to-weeks approval waits are all documented in contractor-facing trade coverage -- severe enough that some licensed contractors opt out of the warranty channel entirely.", "paid_outcome": "A trade-qualified-reviewer-released Authorization Boost Package per work order: evidence package (photos, meter/pressure readings, nameplate/serial data, code citations, itemized parts-and-labor cost benchmark) submitted through the warranty company's contractor portal and tracked to a paid resolution -- plus a structured appeal when the response under-authorizes, scope-limits, or denies, and an optional Auto-Submit subscription that removes the per-case decision once a contractor has 3+ successful cases.", "value_creation": "AI compresses evidence extraction, per-warranty-company completeness matching, cost benchmarking, and evidence-package/appeal-narrative drafting; deterministic code owns every hard-fail gate (missing photos, missing readings, incomplete nameplate data, missing documentation type per warranty company); a trade-qualified reviewer releases every package for submission and the contractor confirms before any appeal is filed in their name; the platform binds them with an append-only case audit trail.", "why_ai_native": "The extract-draft-release-submit-track loop is only economical with a bounded AI layer feeding deterministic rules. A pure-manual claims-consulting service cannot hit the $25 + 28% pricing at the 4-business-hour MVP cycle time contractors need before the next work order; a pure-automated portal-filling tool cannot hold the completeness gate, escalate a contested cost benchmark, or absorb the judgment calls (under-authorization detection, appeal-language sign-off) that keep a case defensible.", "operational_risks": [ "Trade-qualified reviewer bottleneck during seasonal HVAC demand spikes (summer/winter)", "Warranty-company portal access rules changing to block third-party submitters", "OEM/warranty-company refusal to engage with a contractor-submitted appeal", "Overstated diagnosis certainty in a drafted evidence package", "Contingency-fee structure disputed by a warranty company as improper practice" ], "assumptions": [ "Independent HVAC contractors will pay a $25 flat intake fee plus 28% contingency on secured uplift over continuing to eat under-authorizations.", "A standard Authorization Boost Package can be assembled from contractor-supplied evidence within the 4-business-hour MVP cycle.", "The vertical tolerates AI-assisted extraction and drafting when trade-qualified-reviewer review is explicit and audit-traceable.", "Logical per-tenant isolation with row-level auth is acceptable for the pilot cohort -- single-tenant infrastructure is not required.", "The B2B contractor-vendor-representation framing keeps AuthLift outside public-adjuster and insurance-adjuster licensing regimes at MVP scope, pending the 50-state legal review." ], "validation_questions": [ "Which trade-qualified reviewer(s) will staff release on day one, and at what caseload before a second reviewer is needed?", "Which warranty companies are in scope for the per-provider rule library at launch beyond the pilot cohort's actual network enrollments?", "What is the actual willingness-to-pay once an Authorization Audit shows a real underpayment gap?", "Which existing systems (dispatch/field-service software, warranty-company portals) must intake integrate with on day one?", "Is there a state-by-state constraint on representing a contractor-vendor in an appeal that changes the licensing-boundary posture?" ] }, "domain_discovery": { "actors": [ { "actor": "Contractor Owner/Operator", "role": "independent HVAC/plumbing/electrical/appliance-repair contractor owner or office/ops manager who reconciles warranty-company payouts against job cost", "goals": [ "Get paid what a diagnosed repair actually costs on every warranty work order", "Avoid doing a scope-limited band-aid fix instead of the correct repair" ], "decisions": [ "Submit a case intake", "Confirm or request revisions on the draft evidence package", "Confirm before an appeal is filed in their name" ], "pain_points": [ "Evidence scattered across phone photos, meter readings, and hand-written diagnosis notes", "No independent proof the diagnosed repair scope is correct", "Discovering an under-authorization only after the warranty company's decision is final" ] }, { "actor": "Trade-Qualified Reviewer", "role": "Releases every Authorization Boost Package before submission; the everyday human chokepoint", "goals": [ "Release only packages whose technical claims and cost benchmarks are evidence-cited", "Keep cycle time inside the 4-business-hour MVP / same-business-day standard SLA" ], "decisions": [ "Release, request revision, or flag for escalation", "Confirm a cost-benchmark line is accurate before submission" ], "pain_points": [ "Incomplete photo or meter-reading evidence", "Ambiguous AI extraction on non-standard warranty-company portal formats", "Reviewer shortage during seasonal HVAC demand spikes" ] }, { "actor": "Contractor's Licensed Tradesperson", "role": "The contractor's own licensed technician who performs the physical repair and attests to the diagnosis, code citations, and recommended scope; AuthLift drafts, the tradesperson's license backs every technical claim", "goals": [ "Have the diagnosed repair scope correctly represented in the submission", "Never be put in a position of certifying a claim AuthLift invented" ], "decisions": [ "Attest to the diagnosis and code citations", "Confirm the recommended repair scope" ], "pain_points": [ "Diagnosis notes taken quickly in the field with limited detail", "Being asked to attest to a claim that overstates certainty" ] }, { "actor": "Warranty Company", "role": "American Home Shield, Cinch, Choice Home Warranty, First American, Old Republic, 2-10 HBW, Landmark, and regional providers; authorizes and pays work orders through its contractor portal", "goals": [ "Confirm the diagnosed repair and cost are within the coverage terms before authorizing payment" ], "decisions": [ "Authorize, under-authorize, scope-limit, or deny a work order based on the submitted evidence" ], "pain_points": [ "Bare-minimum submissions that force a manual back-and-forth", "Contractors who dispute every authorization regardless of merit" ] }, { "actor": "AI extraction/drafting layer", "role": "Extracts data from photos/readings, drafts evidence packages and appeal narratives, benchmarks parts/labor costs, tracks case status, and flags exception patterns; never invents dates, readings, or diagnoses", "goals": [ "Produce a fully cited evidence-package draft", "Escalate rather than guess on ambiguous readings or contested cost benchmarks" ], "decisions": [ "Draft vs escalate", "Which warranty-company completeness-checklist rules and cost-benchmark data to cite" ], "pain_points": [ "Heterogeneous photo quality and non-standard warranty-company portal formats", "Sparse meter/pressure-reading evidence" ] }, { "actor": "Platform admin", "role": "Runs the tenant, manages users/integrations (internal, not contractor-facing)", "goals": [ "Keep the system safe, observable, and rule-library current" ], "decisions": [ "Provision users", "Rotate secrets and manage feature flags" ], "pain_points": [ "Change management across tenants and warranty-company portal formats" ] } ], "glossary": [ { "term": "work order", "definition": "The warranty company's service dispatch ticket for one repair job.", "used_by": "All actors", "context": "Case Intake & Qualification", "example": "\"Forward the work order number so we can open the case.\"", "notes": "Never call it a \"job,\" \"ticket,\" or \"claim\" interchangeably -- always \"work order.\"" }, { "term": "evidence package", "definition": "The diagnostic file AuthLift assembles (photos, meter/pressure readings, nameplate/serial data, code citations, itemized parts-and-labor cost benchmark) to support a work order's authorization.", "used_by": "AI extraction/drafting layer, Trade-Qualified Reviewer, Contractor Owner/Operator", "context": "Evidence Assembly", "example": "\"The evidence package is missing the meter reading for the compressor.\"", "notes": "Every line cites evidence or is marked an explicit gap; never invented." }, { "term": "Authorization Boost Package", "definition": "The paid service/deliverable: assembly + submission of the evidence package for one work order, tracked to resolution.", "used_by": "All actors", "context": "Review & Compliance, Portal Submission & Tracking", "example": "\"Ship the Authorization Boost Package once the reviewer releases it.\"", "notes": "Capitalized -- this is the product name." }, { "term": "authorization", "definition": "The warranty company's approved dollar amount and repair scope for a work order.", "used_by": "All actors", "context": "Outcome & Uplift Tracking", "example": "\"The authorization came back $640 under the diagnosed repair cost.\"", "notes": "Never 'approval' alone -- always pair amount + scope." }, { "term": "under-authorization", "definition": "When the approved amount or scope is less than the diagnosed repair actually requires (includes scope-limiting to a temporary/band-aid fix).", "used_by": "All actors", "context": "Outcome & Uplift Tracking", "example": "\"This is an under-authorization -- the compressor swap was scoped down to a patch.\"", "notes": "Triggers the appeal decision." }, { "term": "appeal", "definition": "The structured supplemental-authorization request AuthLift files when a work order is under-authorized, scope-limited, or denied.", "used_by": "Trade-Qualified Reviewer, Contractor Owner/Operator", "context": "Appeal & Escalation Desk", "example": "\"File the appeal once the contractor confirms the language.\"", "notes": "Requires captured contractor consent before filing." }, { "term": "reviewer", "definition": "The trade-qualified human (or certified claims specialist) who verifies technical accuracy and cost benchmarks before submission.", "used_by": "All actors", "context": "Review & Compliance", "example": "\"The reviewer flagged the cost benchmark for a second check.\"", "notes": "Also 'Trade-Qualified Reviewer' -- the everyday human chokepoint." }, { "term": "contractor", "definition": "The buyer -- an independent HVAC, plumbing, electrical, or appliance-repair business.", "used_by": "All actors", "context": "Case Intake & Qualification", "example": "\"The contractor forwarded three work orders this week.\"", "notes": "Never 'customer' or 'client' in domain copy -- always 'contractor.'" }, { "term": "warranty company", "definition": "The home service contract provider that authorizes and pays work orders.", "used_by": "All actors", "context": "Warranty Company Rule Library & Retrieval", "example": "\"This case's warranty company is Choice Home Warranty.\"", "notes": "Never 'insurer' -- home warranties are service contracts, not insurance." }, { "term": "uplift", "definition": "The dollar increase between the warranty company's first offer and the final approved amount.", "used_by": "All actors", "context": "Outcome & Uplift Tracking", "example": "\"Uplift on this case was $640.\"", "notes": "The contingency fee is based on this figure." }, { "term": "case", "definition": "One work order moving through the AuthLift pipeline end to end, from intake to payout confirmation.", "used_by": "All actors", "context": "Case Intake & Qualification", "example": "\"Case #48213 is in reviewer release.\"", "notes": "The unit of work across the whole system." }, { "term": "Authorization Audit", "definition": "The free lead-magnet diagnostic on one recent underpaid/denied work order, delivered within 24 hours.", "used_by": "Contractor Owner/Operator, AI extraction/drafting layer", "context": "Case Intake & Qualification", "example": "\"Run the free Authorization Audit before committing to a paid case.\"", "notes": "Capitalized -- a named offer, not a released package." }, { "term": "Auto-Submit", "definition": "The monthly subscription upsell ($99-249/mo by volume) that submits every future work order automatically once a contractor has 3+ successful cases.", "used_by": "Contractor Owner/Operator, Trade-Qualified Reviewer", "context": "Auto-Submit & Recurring Programs", "example": "\"Enroll in Auto-Submit once the third successful case closes.\"", "notes": "Capitalized -- distinct from a one-time case purchase." }, { "term": "completeness checklist", "definition": "The deterministic per-warranty-company gate (required fields, photo counts, documentation types) a case must pass before a reviewer sees it.", "used_by": "AI extraction/drafting layer, Trade-Qualified Reviewer", "context": "Evidence Assembly", "example": "\"The completeness checklist flags one missing photo for this warranty company.\"", "notes": "Never invented; always evidence-pointer cited." }, { "term": "cycle time", "definition": "Business days from submission to resolution.", "used_by": "All actors", "context": "Outcome & Uplift Tracking", "example": "\"Cycle time on this case was 3 business days.\"", "notes": "Tracked per case and per warranty company." }, { "term": "portal", "definition": "The warranty company's contractor portal -- the online system where evidence packages and appeals are actually submitted.", "used_by": "Trade-Qualified Reviewer, AI extraction/drafting layer", "context": "Portal Submission & Tracking", "example": "\"Submission went through the Cinch contractor portal.\"", "notes": "Never call it a 'dashboard' -- it's the warranty company's own system." }, { "term": "owner action", "definition": "A fact only the contractor can supply, e.g. confirming the licensed tradesperson's diagnosis attestation.", "used_by": "Contractor Owner/Operator, Compliance & Licensing Governance", "context": "Compliance & Licensing Governance", "example": "\"Owner action open: confirm the licensed tradesperson attestation for this case.\"", "notes": "Caps the release at pending while open." } ], "decisions": [ { "decision": "Accept case intake", "who": "Case Intake & Qualification context (rule + operator override)", "inputs": [ "Contractor identity", "Work order number + warranty company", "Scope statement (ICP fit)" ], "rule": "Reject if the contractor is out of ICP (fewer than 10 warranty work orders/month, or no active warranty-company enrollment) or the work order number is missing", "output": "Case intake accepted event", "risk": "Accepting an out-of-scope engagement degrades reviewer trust and margin" }, { "decision": "Draft vs escalate", "who": "AI extraction/drafting layer", "inputs": [ "Evidence coverage", "Confidence score", "Cost-benchmark match certainty" ], "rule": "Escalate below confidence threshold, on ambiguous photo/reading extraction, or when the warranty company's completeness checklist cannot be matched", "output": "Draft-ready evidence package OR escalation event", "risk": "A silent low-confidence draft erodes reviewer trust" }, { "decision": "Release the Authorization Boost Package", "who": "Trade-Qualified Reviewer", "inputs": [ "Draft evidence package", "Full evidence citations", "Completeness-checklist evaluation results" ], "rule": "Release only if every evidence-package line cites a source or an explicit gap, AND every hard gap is either cleared or logged as an open owner action", "output": "Package released event", "risk": "Over-broad release erodes the audit trail and submission defensibility" }, { "decision": "File an appeal", "who": "Trade-Qualified Reviewer + Contractor Owner/Operator", "inputs": [ "Authorization outcome", "Under-authorization/scope-limit/denial determination", "Contractor consent" ], "rule": "File only after contractor consent is captured on the specific appeal language", "output": "Appeal filed event", "risk": "Filing without consent breaks the trust boundary with the contractor" }, { "decision": "Retract a submitted package", "who": "Legal + Trade-Qualified Reviewer", "inputs": [ "Newly discovered fact (e.g. inaccurate evidence)", "Impact assessment" ], "rule": "Retract if any submitted claim is materially wrong OR unsupported by evidence", "output": "Retraction event + contractor notification", "risk": "Delayed retraction compounds dispute exposure on the case record" } ], "events": [ { "event": "caseIntakeReceived", "meaning": "A work order is now committed to fulfillment", "trigger": "Contractor or auto-rule accepts the intake", "downstream": [ "Normalization + rule-library retrieval scheduled", "AI extraction scheduled" ] }, { "event": "evidenceIngested", "meaning": "Enough photo/reading/nameplate/diagnosis evidence exists to extract", "trigger": "Normalization passes the coverage rule", "downstream": [ "Extraction authorized" ] }, { "event": "evidencePackageDrafted", "meaning": "AI extraction produced a cited evidence-package draft for reviewer review", "trigger": "Extraction Agent finishes its run", "downstream": [ "Completeness-checklist evaluation" ] }, { "event": "completenessCheckPassed", "meaning": "Deterministic rules confirmed every required field/photo/documentation type is present", "trigger": "Rule engine completes evaluation with no open gaps", "downstream": [ "Reviewer queue" ] }, { "event": "completenessCheckFailed", "meaning": "Deterministic rules found at least one hard gap", "trigger": "Rule engine completes evaluation with open gaps", "downstream": [ "Owner action raised or contractor chase" ] }, { "event": "escalationRaised", "meaning": "AI or the reviewer could not complete safely", "trigger": "Confidence below threshold, ambiguous cost benchmark, or contested code citation", "downstream": [ "Reviewer escalation queue" ] }, { "event": "reviewerApproved", "meaning": "Trade-qualified reviewer took accountability for the package", "trigger": "Release signature captured", "downstream": [ "Submission authorized", "Audit-log snapshot" ] }, { "event": "packageSubmitted", "meaning": "Authorization Boost Package submitted through the warranty company's contractor portal", "trigger": "Portal-submission adapter confirms transmit", "downstream": [ "Tracking ID logged", "Contractor notification" ] }, { "event": "authorizationReceived", "meaning": "The warranty company returned an authorized amount and scope", "trigger": "Portal status change or contractor-reported outcome", "downstream": [ "Under-authorization check" ] }, { "event": "underAuthorizationDetected", "meaning": "The authorized amount or scope is less than the diagnosed repair requires", "trigger": "Authorization compared against the evidence-package cost benchmark", "downstream": [ "Appeal decision" ] }, { "event": "contractorConsentConfirmed", "meaning": "The contractor approved the specific appeal language", "trigger": "Contractor confirms via the intake channel", "downstream": [ "Appeal filing authorized" ] }, { "event": "appealFiled", "meaning": "The structured supplemental-authorization request was submitted", "trigger": "Reviewer submits after contractor consent", "downstream": [ "Cycle-time tracking resumed" ] }, { "event": "upliftConfirmed", "meaning": "A final approved amount higher than the first offer is on file", "trigger": "Warranty company issues a revised authorization", "downstream": [ "Billing event (contingency fee)" ] }, { "event": "caseResolved", "meaning": "The case reached a final authorization outcome and payout confirmation", "trigger": "Reviewer confirms resolution", "downstream": [ "Billing event", "Cost-benchmark/denial-pattern library update" ] }, { "event": "ownerActionResolved", "meaning": "A blocking contractor-supplied fact is now on file", "trigger": "Contractor updates the ledger", "downstream": [ "Release-decision recomputation" ] }, { "event": "autoSubmitEnrolled", "meaning": "The contractor enrolled in the Auto-Submit subscription after 3+ successful cases", "trigger": "Success-lead confirms eligibility and contractor opts in", "downstream": [ "Future work orders auto-open as cases" ] } ] }, "subdomains": [ { "name": "Authorization Boost Fulfillment (evidence-linked evidence-package + submission)", "type": "core", "description": "The end-to-end path from case intake to reviewer-released Authorization Boost Package, with every evidence-package line cited.", "reason": "This is what contractors pay for and what a warranty company's portal review tests against.", "business_value": "Direct revenue and authorization defensibility.", "recommendation": "build", "ai_involvement": "high", "human_involvement": "high", "risks": [ "Overstated or fabricated evidence-package lines", "Reviewer bottleneck during seasonal demand spikes", "Un-reconstructable case record" ], "validation_questions": [ "Can the reviewer release in <=4 business hours on the MVP flow?", "Can we reconstruct any past case's evidence trail on demand?" ] }, { "name": "Evidence Assembly (bounded AI extraction + drafting)", "type": "core", "description": "The bounded AI layer that extracts, classifies, drafts the evidence package and cost benchmark, cites evidence, and escalates -- never releases a package or files an appeal unassisted.", "reason": "The AI-native competitive edge lives here; misuse here creates every high-severity risk.", "business_value": "Cycle-time and margin advantage over manual claims consulting.", "recommendation": "build", "ai_involvement": "high", "human_involvement": "medium", "risks": [ "Prompt injection via forwarded photo/notes content", "Grounding drift on non-standard warranty-company portal formats", "Silent low-confidence output" ], "validation_questions": [ "What is the acceptance rate of AI-drafted evidence packages by reviewers?", "What percent of runs escalate correctly on ambiguous readings or contested cost benchmarks?" ] }, { "name": "Review & Compliance (reviewer release + retraction)", "type": "core", "description": "Trade-qualified reviewer release workflow, signature capture, retraction workflow, and audit-log snapshots.", "reason": "Release is the trust primitive of the whole business.", "business_value": "Defensibility; premium pricing over unmanaged self-submission.", "recommendation": "build", "ai_involvement": "medium", "human_involvement": "high", "risks": [ "Release-signature spoofing", "Repudiation of a release", "Delayed retraction" ], "validation_questions": [ "Is every release cryptographically bound to an authenticated session?", "Can we replay any past release on demand?" ] }, { "name": "Warranty Company Rule Library & Retrieval", "type": "supporting", "description": "Per-warranty-company completeness-checklist library, coverage/exclusion language, and regional parts/labor cost-benchmark data feeding the extraction layer.", "reason": "Poor or stale rule-library data directly causes false completeness failures and inaccurate cost benchmarks.", "business_value": "Drives extraction and release quality.", "recommendation": "build", "ai_involvement": "high", "human_involvement": "medium", "risks": [ "Stale warranty-company checklist after a portal-format change", "Cross-tenant retrieval leakage" ], "validation_questions": [ "Is every completeness-checklist card dated to its warranty-company source?" ] }, { "name": "Compliance & Licensing Governance", "type": "supporting", "description": "Owner-action ledger, release-decision policy, licensing-boundary enforcement (AI may extract/draft/benchmark/track; reviewers may verify and format; only the contractor's licensed tradesperson attests to diagnosis and scope; AuthLift never performs, certifies, or signs off on physical repairs, and never represents a homeowner/policyholder).", "reason": "Cross-cuts every context; owns 'can we publicly claim this case is submission-ready.'", "business_value": "Prevents category-level and licensing-boundary failure.", "recommendation": "build", "ai_involvement": "low", "human_involvement": "high", "risks": [ "Premature public claim of guaranteed-authorization outcomes", "Mis-selling as insurance adjusting or legal representation" ], "validation_questions": [ "Are all owner actions closed before a public release claim?" ] }, { "name": "Case Intake & Qualification", "type": "supporting", "description": "Free Authorization Audit lead capture through accepted engagement + scope statement.", "reason": "Feeds Fulfillment; not the differentiator, but if broken, nothing else runs.", "business_value": "Feeds pipeline via the Authorization Audit lead magnet.", "recommendation": "build", "ai_involvement": "medium", "human_involvement": "high", "risks": [ "Accepting an out-of-ICP engagement" ], "validation_questions": [ "Do we reject contractors doing fewer than 10 warranty work orders/month?" ] }, { "name": "Client Onboarding & Contractor Profile", "type": "supporting", "description": "Tenant provisioning, reviewer-of-record registration, warranty-company portal credential capture, engagement letter.", "reason": "One-time high-touch step per contractor.", "business_value": "Reduces time-to-first-case.", "recommendation": "build", "ai_involvement": "low", "human_involvement": "high", "risks": [ "No reviewer of record registered before intake opens" ], "validation_questions": [ "Is a trade-qualified reviewer named per tenant before go-live?" ] }, { "name": "Client Success & Retention", "type": "supporting", "description": "Delivery/status surface, revision loop, Auto-Submit renewal and upsell signal.", "reason": "Customer-visible surface; drives retention and Auto-Submit upsell.", "business_value": "Retention.", "recommendation": "build", "ai_involvement": "low", "human_involvement": "medium", "risks": [ "Silent submission failure ahead of an appeal-window deadline" ], "validation_questions": [ "Do we alert the contractor within 1h of any submission failure?" ] }, { "name": "Appeal & Escalation Desk", "type": "supporting", "description": "Structured appeal drafting and filing for under-authorized, scope-limited, or denied work orders, with mandatory contractor consent before filing.", "reason": "Monetizes the highest-friction part of the workflow (winning back the gap) without becoming unpaid advocacy.", "business_value": "Uplift revenue and win-rate KPI.", "recommendation": "build", "ai_involvement": "medium", "human_involvement": "medium", "risks": [ "Warranty company non-responsive to appeal", "Appeal desk scope-creeping into unpaid custom advocacy" ], "validation_questions": [ "Is the appeal win rate >=40% within 30 days when an appeal is filed?" ] }, { "name": "Auto-Submit & Recurring Programs", "type": "supporting", "description": "Auto-Submit subscription covering every future work order once a contractor has 3+ successful cases.", "reason": "Converts one-time cases into recurring revenue for high-volume contractors.", "business_value": "Recurring revenue ($99-249/mo).", "recommendation": "build", "ai_involvement": "low", "human_involvement": "medium", "risks": [ "Auto-Submit scope-creeping into unpaid custom work" ], "validation_questions": [ "Is every Auto-Submit work order still passing the completeness checklist before submission?" ] }, { "name": "Billing & Revenue", "type": "generic", "description": "Per-case intake fee, contingency-on-uplift, and Auto-Submit subscription invoicing, dunning, revenue reporting.", "reason": "Solved category; do not build.", "business_value": "Cash collection.", "recommendation": "buy", "ai_involvement": "low", "human_involvement": "low", "risks": [ "Tax jurisdictional errors" ], "validation_questions": [ "Is Stripe Tax sufficient for the pilot-state launch jurisdictions?" ] }, { "name": "Identity & Access", "type": "generic", "description": "SSO, MFA, RBAC, session management.", "reason": "Solved category.", "business_value": "Table stakes.", "recommendation": "integrate", "ai_involvement": "low", "human_involvement": "low", "risks": [ "Role escalation" ], "validation_questions": [ "Are roles stored in a dedicated table?" ] }, { "name": "Analytics & Reporting", "type": "supporting", "description": "Authorization-Audit-to-paid conversion, cycle time, uplift secured, escalation rate, gross margin, and Auto-Submit attach reporting.", "reason": "Drives every operational decision against the brief's KPI targets.", "business_value": "Feedback loop.", "recommendation": "build", "ai_involvement": "low", "human_involvement": "low", "risks": [ "Vanity metrics" ], "validation_questions": [ "Is Authorization-Audit-to-paid conversion >=25% wired as the north-star?" ] }, { "name": "External Integrations (Anti-Corruption Layer)", "type": "supporting", "description": "Adapters to warranty-company contractor portals, contractor dispatch/field-service platforms, and other tools with translation to internal domain terms.", "reason": "External schemas must never leak into the core.", "business_value": "Enables integration without corrupting the model.", "recommendation": "build", "ai_involvement": "low", "human_involvement": "medium", "risks": [ "Silent schema drift" ], "validation_questions": [ "Do all external calls pass through an ACL translator?" ] } ], "core_domain_analysis": { "primary_core": "Authorization Boost Fulfillment (evidence-linked evidence-package + submission)", "secondary_cores": [ "Evidence Assembly (bounded AI extraction + drafting)", "Review & Compliance (reviewer release + retraction)" ], "supporting_may_become_core": [ "Warranty Company Rule Library & Retrieval (as multi-provider coverage accumulates)", "Appeal & Escalation Desk (as appeal win-rate becomes a differentiator)" ], "generic_do_not_distract": [ "Billing & Revenue", "Identity & Access" ], "rationale": "The paid outcome (reviewer-released, evidence-linked Authorization Boost Package) lives in Fulfillment, but its defensibility depends on Evidence Assembly and Review & Compliance behaving correctly. Treat all three as core; do not dilute engineering time on generic subdomains." }, "bounded_contexts": [ { "name": "Authorization Boost Fulfillment", "purpose": "Turn accepted case intakes into reviewer-released Authorization Boost Packages.", "subdomain": "Authorization Boost Fulfillment (core)", "type": "core", "owned_language": [ "work order", "evidence package", "completeness checklist", "Authorization Boost Package", "case" ], "owns": [ "Case intake lifecycle", "Evidence-package state", "Evidence links", "Submission packet composition" ], "does_not_own": [ "Reviewer identity", "Billing", "Public release-claim decision" ], "primary_actors": [ "Contractor Owner/Operator", "AI extraction/drafting layer", "Trade-Qualified Reviewer" ], "entities": [ "CaseIntake", "EvidencePackage", "Authorization Boost Package", "Submission" ], "value_objects": [ "Confidence score", "Evidence citation", "Submission address" ], "aggregates": [ "CaseAggregate", "EvidencePackageAggregate", "CompletenessChecklistAggregate" ], "domain_services": [ "Evidence-package composer", "Submission adapter" ], "application_services": [ "OpenCaseIntake", "IngestEvidence", "StartExtractionRun", "RunCompletenessChecklist", "SubmitToPortal" ], "commands": [ "OpenCaseIntake", "IngestEvidence", "StartExtractionRun", "RunCompletenessChecklist", "SubmitToPortal" ], "domain_events": [ "CaseIntakeReceived", "EvidenceIngested", "EvidencePackageDrafted", "CompletenessCheckPassed", "PackageSubmitted" ], "policies": [ "Auto-request reviewer release when completeness check passes", "Auto-block submission until reviewer release is received" ], "specifications": [ "EvidenceCoverageSpec", "SubmittabilitySpec" ], "invariants": [ "An Authorization Boost Package cannot be submitted without a valid reviewer Release", "Every evidence-package line cites at least one evidence item or is marked an explicit gap" ], "ai_agents": [ "Extraction Agent" ], "human_roles": [ "Contractor Owner/Operator", "Trade-Qualified Reviewer" ], "data_owned": [ "CaseIntake", "EvidencePackage", "Authorization Boost Package", "Submission" ], "inputs": [ "Intake payload", "Ingested evidence", "Rule-library retrieval hits" ], "outputs": [ "Released Authorization Boost Package", "Submission confirmation" ], "external_integrations": [ "Warranty-company contractor portals", "Contractor dispatch / field-service platforms" ], "risks": [ "An un-cited evidence-package line slips into submission", "Submission adapter fails silently" ], "interfaces": [ "-> Review & Compliance (request release)", "-> Client Success & Retention (PackageSubmitted)", "<- Evidence Assembly (EvidencePackageDrafted)" ] }, { "name": "Evidence Assembly", "purpose": "Run bounded AI agents that extract, classify, draft, cite, and escalate.", "subdomain": "Evidence Assembly (bounded AI extraction + drafting) (core)", "type": "core", "owned_language": [ "prompt version", "confidence score", "escalation", "retrieval hit" ], "owns": [ "Prompt registry", "Extraction run log", "Confidence thresholds" ], "does_not_own": [ "Evidence sourcing", "Reviewer release", "Business release decisions" ], "primary_actors": [ "AI extraction/drafting layer", "Ops (prompt owner)" ], "entities": [ "ExtractionRun", "PromptVersion", "RetrievalHit" ], "value_objects": [ "Confidence score", "Token budget", "Model cost" ], "aggregates": [ "ExtractionRunAggregate" ], "domain_services": [ "Retrieval router", "Output validator", "Escalation router" ], "application_services": [ "StartAgentRun", "ValidateOutput", "PublishPromptVersion" ], "commands": [ "StartExtractionRun", "PublishPromptVersion", "SetConfidenceThreshold" ], "domain_events": [ "EvidencePackageDrafted", "EscalationRaised", "PromptVersionPublished" ], "policies": [ "Escalate on confidence < threshold, ambiguous reading extraction, or unmatched completeness checklist", "Never call the model with cross-tenant retrieval context", "Reject output failing the structured-output validator" ], "specifications": [ "GroundedOutputSpec", "TokenBudgetSpec" ], "invariants": [ "No extraction output leaves this context without passing OutputValidator", "Prompt versions are immutable once published" ], "ai_agents": [ "Extraction Agent", "Drafting Agent", "Denial-Pattern QA Agent" ], "human_roles": [ "Ops (prompt owner)" ], "data_owned": [ "Prompt registry", "Extraction run logs", "Confidence thresholds" ], "inputs": [ "Intake context", "Rule-library retrieval hits", "Prompt version" ], "outputs": [ "Evidence-package draft payload", "Escalation event", "Run trace" ], "external_integrations": [ "OpenAI / Anthropic API", "Warranty Company Rule Library retrieval index" ], "risks": [ "Prompt injection via forwarded photo/notes content", "Retrieval leakage across tenants", "Silent overstatement of diagnosis certainty" ], "interfaces": [ "-> Authorization Boost Fulfillment (EvidencePackageDrafted)", "-> Review & Compliance (EscalationRaised)", "<- Warranty Company Rule Library & Retrieval (RetrievalHit)" ] }, { "name": "Review & Compliance", "purpose": "Trade-qualified reviewer release workflow, signature capture, retraction workflow, audit-log snapshots.", "subdomain": "Review & Compliance (reviewer release + retraction) (core)", "type": "core", "owned_language": [ "release", "retraction", "reviewer session" ], "owns": [ "Release log", "Reviewer queue", "Retraction workflow" ], "does_not_own": [ "Authorization Boost Package content", "Public release-claim decision" ], "primary_actors": [ "Trade-Qualified Reviewer", "Legal reviewer" ], "entities": [ "Release", "PackageRetraction", "ReviewerSession" ], "value_objects": [ "Release manifest", "Retraction reason" ], "aggregates": [ "ReviewAggregate", "PackageRetractionAggregate" ], "domain_services": [ "Release service", "Retraction service" ], "application_services": [ "ReleasePackage", "RejectPackage", "RetractPackage" ], "commands": [ "ReleasePackage", "RetractPackage" ], "domain_events": [ "ReviewerApproved", "PackageReleaseRejected", "PackageRetracted" ], "policies": [ "Only the tenant's registered trade-qualified reviewer may release", "Retraction requires legal + reviewer co-signature" ], "specifications": [ "ReleaserAuthoritySpec", "RetractionPreconditionsSpec" ], "invariants": [ "A Release is bound to a live authenticated session, not a form field", "Released Authorization Boost Packages are immutable; corrections go through PackageRetraction" ], "ai_agents": [], "human_roles": [ "Trade-Qualified Reviewer", "Legal reviewer" ], "data_owned": [ "Releases", "Retractions", "Reviewer sessions" ], "inputs": [ "Evidence package drafted", "Escalation payload" ], "outputs": [ "Release event", "Retraction event" ], "external_integrations": [ "IdP (Okta / Google)" ], "risks": [ "Release-signature spoofing", "Repudiation of a release" ], "interfaces": [ "-> Authorization Boost Fulfillment (ReviewerApproved)", "-> Compliance & Licensing Governance (PackageRetracted)" ] }, { "name": "Warranty Company Rule Library & Retrieval", "purpose": "Own per-warranty-company completeness-checklist library, coverage/exclusion language, cost-benchmark data, and retrieval indices feeding extraction.", "subdomain": "Warranty Company Rule Library & Retrieval (supporting)", "type": "supporting", "owned_language": [ "warranty company", "completeness checklist", "cost benchmark" ], "owns": [ "Warranty-company rule sets", "Completeness-checklist cards", "Cost-benchmark data", "Retrieval indices" ], "does_not_own": [ "Prompt versions", "Model calls" ], "primary_actors": [ "Ops (prompt owner)" ], "entities": [ "WarrantyCompanyRuleSet", "ChecklistCard", "CostBenchmarkEntry", "IndexShard" ], "value_objects": [ "Provider citation", "SourceCitation" ], "aggregates": [ "WarrantyCompanyRuleSetAggregate" ], "domain_services": [ "Ingestion pipeline", "Reindex service" ], "application_services": [ "IngestRuleUpdate", "Reindex", "PurgeStaleRuleSet" ], "commands": [ "IngestRuleUpdate", "Reindex", "PurgeStaleRuleSet" ], "domain_events": [ "RuleUpdateIngested", "IndexRebuilt" ], "policies": [ "Retrieval indices partitioned per tenant and per warranty company", "Purge cascades to indices within SLA" ], "specifications": [ "TenantIsolationSpec", "ProviderScopeSpec" ], "invariants": [ "Retrieval is scoped to the completeness checklist adopted by the case's warranty company" ], "ai_agents": [], "human_roles": [ "Ops (prompt owner)" ], "data_owned": [ "Warranty-company rule sets", "Indices" ], "inputs": [ "Warranty-company published portal/coverage updates", "Regional cost-benchmark source data" ], "outputs": [ "Retrieval hits with citations" ], "external_integrations": [ "Blob storage", "Search API" ], "risks": [ "Cross-tenant retrieval leak", "Stale warranty-company rule set" ], "interfaces": [ "-> Evidence Assembly" ] }, { "name": "Compliance & Licensing Governance", "purpose": "Own the release-readiness decision, owner-action ledger, and licensing-boundary enforcement.", "subdomain": "Compliance & Licensing Governance (supporting)", "type": "supporting", "owned_language": [ "owner action", "release decision", "licensing boundary" ], "owns": [ "Owner-action ledger", "Release-decision policy", "Licensing-boundary attestations" ], "does_not_own": [ "Authorization Boost Package content", "Reviewer identity" ], "primary_actors": [ "Business owner / founder", "Legal reviewer", "Trade-Qualified Reviewer" ], "entities": [ "OwnerAction", "ReleaseDecision", "DSARRequest" ], "value_objects": [ "Blocker reason", "Jurisdiction" ], "aggregates": [ "OwnerActionLedgerAggregate" ], "domain_services": [ "Release-decision engine", "DSAR fulfillment service" ], "application_services": [ "ResolveOwnerAction", "RecomputeReleaseDecision", "ProcessDSAR" ], "commands": [ "ResolveOwnerAction", "RaiseOwnerAction", "ProcessDSAR" ], "domain_events": [ "OwnerActionResolved", "ReleaseDecisionChanged", "DSARFulfilled" ], "policies": [ "Block a public release-readiness claim while any owner action is open", "DSAR SLA 30 days", "AI may extract/benchmark/draft; only the contractor's licensed tradesperson may attest to diagnosis and scope; AuthLift never performs, certifies, or signs off on the physical repair, and never represents a homeowner/policyholder" ], "specifications": [ "ReleaseReadinessSpec", "DSARSpec" ], "invariants": [ "Release cannot flip to 'ready' with open blocking owner actions" ], "ai_agents": [], "human_roles": [ "Business owner / founder", "Legal reviewer" ], "data_owned": [ "Owner-action ledger", "Release decisions", "DSAR queue" ], "inputs": [ "Contractor input", "Legal review outcome" ], "outputs": [ "Release-decision event", "DSAR confirmation" ], "external_integrations": [ "Email inbox" ], "risks": [ "Public release-readiness claim while a blocker is open", "Mis-selling as insurance adjusting or legal representation" ], "interfaces": [ "<- Authorization Boost Fulfillment", "<- Review & Compliance (PackageRetracted)" ] }, { "name": "Case Intake & Qualification", "purpose": "Lead (Authorization Audit) -> qualified engagement -> accepted case intake.", "subdomain": "Case Intake & Qualification (supporting)", "type": "supporting", "owned_language": [ "lead", "engagement", "Authorization Audit" ], "owns": [ "Lead pipeline", "Engagement letter", "Authorization Audit requests" ], "does_not_own": [ "Fulfillment", "Billing" ], "primary_actors": [ "Business owner / founder", "Contractor Owner/Operator" ], "entities": [ "Lead", "Engagement" ], "value_objects": [ "Scope statement", "Pricing offer" ], "aggregates": [ "EngagementAggregate" ], "domain_services": [ "Scope-fit evaluator" ], "application_services": [ "QualifyLead", "AcceptEngagement" ], "commands": [ "QualifyLead", "AcceptEngagement" ], "domain_events": [ "EngagementAccepted" ], "policies": [ "Reject out-of-ICP engagement (fewer than 10 warranty work orders/month, no active enrollment)", "Engagement letter required before intake" ], "specifications": [ "ScopeFitSpec" ], "invariants": [ "Cannot open a case intake without an accepted engagement" ], "ai_agents": [], "human_roles": [ "Business owner / founder" ], "data_owned": [ "Leads", "Engagements" ], "inputs": [ "Authorization Audit upload", "Discovery notes" ], "outputs": [ "Accepted engagement event" ], "external_integrations": [ "CRM", "Email inbox" ], "risks": [ "Accepting an out-of-scope engagement" ], "interfaces": [ "-> Client Onboarding & Contractor Profile", "-> Authorization Boost Fulfillment (intake enablement)" ] }, { "name": "Client Onboarding & Contractor Profile", "purpose": "Provision the tenant, capture the reviewer-of-record, capture warranty-company portal credentials.", "subdomain": "Client Onboarding & Contractor Profile (supporting)", "type": "supporting", "owned_language": [ "tenant", "reviewer of record", "portal credential" ], "owns": [ "Tenant provisioning", "Reviewer-of-record record", "Portal credential storage" ], "does_not_own": [ "Release capture", "Submission" ], "primary_actors": [ "Onboarding lead", "Contractor Owner/Operator" ], "entities": [ "Tenant", "ReviewerOfRecord", "PortalCredential" ], "value_objects": [ "Contact matrix", "Warranty-company enrollment set" ], "aggregates": [ "ContractorAccountAggregate" ], "domain_services": [ "Tenant provisioner" ], "application_services": [ "ProvisionTenant", "RegisterReviewerOfRecord", "StorePortalCredential" ], "commands": [ "ProvisionTenant", "RegisterReviewerOfRecord", "StorePortalCredential" ], "domain_events": [ "TenantProvisioned", "ReviewerOfRecordRegistered" ], "policies": [ "No intake opens until a trade-qualified reviewer of record is registered per tenant" ], "specifications": [ "ReviewerCredentialSpec" ], "invariants": [ "Every tenant has at least one named trade-qualified reviewer of record on file" ], "ai_agents": [], "human_roles": [ "Onboarding lead" ], "data_owned": [ "Tenants", "Reviewer-of-record records", "Portal credentials" ], "inputs": [ "Engagement", "Contractor-supplied portal access" ], "outputs": [ "Provisioned tenant" ], "external_integrations": [ "IdP", "Warranty-company contractor portals" ], "risks": [ "No reviewer of record before go-live" ], "interfaces": [ "-> Authorization Boost Fulfillment" ] }, { "name": "Client Success & Retention", "purpose": "Deliver submitted packages, own the contractor-visible status surface, drive Auto-Submit renewal.", "subdomain": "Client Success & Retention (supporting)", "type": "supporting", "owned_language": [ "submission status", "revision request", "renewal signal" ], "owns": [ "Contractor status portal", "Submission log", "Revision workflow" ], "does_not_own": [ "Released content", "Billing" ], "primary_actors": [ "Contractor Owner/Operator", "Success lead" ], "entities": [ "SubmissionReceipt", "RevisionRequest" ], "value_objects": [ "Delivery method", "NPS signal" ], "aggregates": [ "DeliveryAggregate" ], "domain_services": [ "Submission adapter" ], "application_services": [ "ConfirmSubmission", "RecordRevisionRequest" ], "commands": [ "ConfirmSubmission", "RecordRevisionRequest" ], "domain_events": [ "SubmissionConfirmed", "RevisionRequested" ], "policies": [ "Alert contractor within 1h of any submission failure" ], "specifications": [ "SubmissionAcknowledgmentSpec" ], "invariants": [ "Every SubmissionConfirmed has a linked Release" ], "ai_agents": [ "Success Copilot (assist only)" ], "human_roles": [ "Success lead" ], "data_owned": [ "Submissions", "Revision requests" ], "inputs": [ "Released Authorization Boost Package", "Contractor feedback" ], "outputs": [ "Submission confirmation", "Revision request" ], "external_integrations": [ "Email", "Contractor status portal" ], "risks": [ "Silent submission failure ahead of an appeal-window deadline" ], "interfaces": [ "<- Authorization Boost Fulfillment", "-> Auto-Submit & Recurring Programs", "-> Billing & Revenue" ] }, { "name": "Appeal & Escalation Desk", "purpose": "Manage the paid structured-appeal workflow for under-authorized, scope-limited, or denied work orders.", "subdomain": "Appeal & Escalation Desk (supporting)", "type": "supporting", "owned_language": [ "appeal", "under-authorization", "escalation" ], "owns": [ "Appeal cases", "Appeal-narrative templates", "Cycle-time log" ], "does_not_own": [ "Evidence-package release", "Billing" ], "primary_actors": [ "Trade-Qualified Reviewer", "Contractor Owner/Operator" ], "entities": [ "Appeal", "AppealNarrative" ], "value_objects": [ "Appeal cadence", "Uplift citation" ], "aggregates": [ "AppealAggregate" ], "domain_services": [ "Appeal-narrative drafter", "Outcome validator" ], "application_services": [ "DraftAppeal", "ConfirmContractorConsent", "FileAppeal" ], "commands": [ "DraftAppeal", "ConfirmContractorConsent", "FileAppeal" ], "domain_events": [ "ContractorConsentConfirmed", "AppealFiled", "UnderAuthorizationDetected" ], "policies": [ "Open an appeal only after an under-authorization, scope-limit, or denial is detected", "An appeal cannot be filed without contractor consent" ], "specifications": [ "ConsentCapturedSpec" ], "invariants": [ "An appeal cannot be filed without captured contractor consent on the specific language" ], "ai_agents": [ "Drafting Agent" ], "human_roles": [ "Trade-Qualified Reviewer" ], "data_owned": [ "Appeals", "Appeal narratives" ], "inputs": [ "Authorization outcome", "Contractor consent" ], "outputs": [ "Filed appeal", "Uplift confirmation" ], "external_integrations": [ "Warranty-company contractor portals" ], "risks": [ "Warranty company non-responsive to the appeal", "Appeal desk scope-creeping into unpaid custom advocacy" ], "interfaces": [ "<- Authorization Boost Fulfillment (AuthorizationReceived)", "-> Outcome & Uplift Tracking (UpliftConfirmed)" ] }, { "name": "Auto-Submit & Recurring Programs", "purpose": "Own the Auto-Submit subscription: automatic per-work-order submission once a contractor has 3+ successful cases.", "subdomain": "Auto-Submit & Recurring Programs (supporting)", "type": "supporting", "owned_language": [ "Auto-Submit", "enrollment" ], "owns": [ "Auto-Submit enrollment", "Eligibility rule", "Renewal schedule" ], "does_not_own": [ "Individual case release", "Billing" ], "primary_actors": [ "Success lead", "Contractor Owner/Operator" ], "entities": [ "AutoSubmitSubscription", "EligibilityCheck" ], "value_objects": [ "Volume tier", "Cadence" ], "aggregates": [ "AutoSubmitSubscriptionAggregate" ], "domain_services": [ "Eligibility evaluator" ], "application_services": [ "EnrollAutoSubmit", "EvaluateEligibility" ], "commands": [ "EnrollAutoSubmit", "EvaluateEligibility" ], "domain_events": [ "AutoSubmitEnrolled", "EligibilityConfirmed" ], "policies": [ "Auto-Submit eligibility requires 3+ successful Authorization Boost Package cases", "Every Auto-Submit case still passes the completeness checklist before submission" ], "specifications": [ "EligibilitySpec" ], "invariants": [ "No contractor is enrolled in Auto-Submit without 3+ successful prior cases on file" ], "ai_agents": [], "human_roles": [ "Success lead" ], "data_owned": [ "Auto-Submit subscriptions", "Eligibility checks" ], "inputs": [ "Enrollment request", "Prior case outcomes" ], "outputs": [ "Enrollment confirmation", "New case intake batch" ], "external_integrations": [ "Contractor status portal" ], "risks": [ "Auto-Submit scope-creeping into unpaid custom work" ], "interfaces": [ "-> Authorization Boost Fulfillment (new intake batch)", "<- Client Success & Retention" ] }, { "name": "Billing & Revenue", "purpose": "Invoicing, subscription management, dunning, revenue reporting across all pricing tiers.", "subdomain": "Billing & Revenue (generic)", "type": "generic", "owned_language": [ "invoice", "subscription", "usage record" ], "owns": [ "Invoices", "Subscriptions", "Usage records" ], "does_not_own": [ "Fulfillment", "Release" ], "primary_actors": [ "Finance", "Contractor admin" ], "entities": [ "Subscription", "Invoice", "UsageRecord" ], "value_objects": [ "Line item", "Tax jurisdiction" ], "aggregates": [ "SubscriptionAggregate" ], "domain_services": [ "Billing adapter" ], "application_services": [ "ChargeCase", "ChargeSubscription", "RecordUsage" ], "commands": [ "ChargeCase", "ChargeSubscription", "RecordUsage" ], "domain_events": [ "InvoicePaid", "SubscriptionCanceled" ], "policies": [ "Charge the contingency fee only after UpliftConfirmed", "Charge the $25 intake fee on CaseIntakeReceived regardless of outcome" ], "specifications": [ "ChargeabilitySpec" ], "invariants": [ "No contingency charge without a confirmed uplift" ], "ai_agents": [], "human_roles": [ "Finance" ], "data_owned": [ "Subscriptions", "Invoices" ], "inputs": [ "Case resolution events" ], "outputs": [ "Invoice records" ], "external_integrations": [ "Stripe" ], "risks": [ "Tax jurisdictional errors" ], "interfaces": [ "<- Client Success & Retention" ] }, { "name": "Identity & Access", "purpose": "SSO, MFA, RBAC, session management.", "subdomain": "Identity & Access (generic)", "type": "generic", "owned_language": [ "user", "role", "session" ], "owns": [ "Users", "Roles table", "Sessions" ], "does_not_own": [ "Business capability decisions" ], "primary_actors": [ "Platform admin", "User" ], "entities": [ "User", "RoleAssignment", "Session" ], "value_objects": [ "Role", "Claim" ], "aggregates": [ "UserAggregate" ], "domain_services": [ "Auth service" ], "application_services": [ "SignIn", "AssignRole" ], "commands": [ "SignIn", "AssignRole" ], "domain_events": [ "UserSignedIn", "RoleAssigned" ], "policies": [ "Roles in a dedicated table, checked server-side" ], "specifications": [ "RoleAuthoritySpec" ], "invariants": [ "No role check runs client-only" ], "ai_agents": [], "human_roles": [ "Platform admin" ], "data_owned": [ "Users", "Roles", "Sessions" ], "inputs": [ "Auth events" ], "outputs": [ "Sessions" ], "external_integrations": [ "IdP (Google / Okta)" ], "risks": [ "Role escalation" ], "interfaces": [ "-> every other context" ] }, { "name": "Analytics & Reporting", "purpose": "Operational + business metrics, outcome reports against the brief's KPI targets.", "subdomain": "Analytics & Reporting (supporting)", "type": "supporting", "owned_language": [ "metric", "dashboard", "outcome report" ], "owns": [ "Metric definitions", "Dashboards" ], "does_not_own": [ "Raw write models" ], "primary_actors": [ "Ops lead", "Business owner / founder" ], "entities": [ "MetricDefinition", "Dashboard" ], "value_objects": [ "Window", "Target" ], "aggregates": [ "MetricDefinitionAggregate" ], "domain_services": [ "Rollup service" ], "application_services": [ "PublishMetric", "PublishDashboard" ], "commands": [ "PublishMetric", "PublishDashboard" ], "domain_events": [ "DashboardPublished" ], "policies": [ "North-star (average uplift per case) must be wired before Phase 2 launch" ], "specifications": [ "MetricDefinedSpec" ], "invariants": [ "Metrics have a definition, a target, and an owner" ], "ai_agents": [], "human_roles": [ "Ops lead" ], "data_owned": [ "Metric definitions", "Read-model rollups" ], "inputs": [ "Domain events (as read-only consumer)" ], "outputs": [ "Dashboards", "Outcome reports" ], "external_integrations": [ "BI tool" ], "risks": [ "Vanity metrics dominating" ], "interfaces": [ "<- every context (read-only)" ] } ], "context_map": [ { "upstream": "Case Intake & Qualification", "downstream": "Authorization Boost Fulfillment", "pattern": "customer-supplier", "business_reason": "Fulfillment cannot start without an accepted engagement.", "data_exchanged": [ "Engagement", "Scope statement" ], "events_exchanged": [ "EngagementAccepted" ], "contract_type": "Published language (Engagement record)", "failure_risks": [ "Silent scope mismatch" ], "acl_notes": "Fulfillment consumes only fields it needs; no direct DB coupling.", "ownership_boundary": "Case Intake owns engagement lifecycle." }, { "upstream": "Authorization Boost Fulfillment", "downstream": "Review & Compliance", "pattern": "customer-supplier", "business_reason": "Release is a hard gate on submission.", "data_exchanged": [ "EvidencePackage", "Evidence trail" ], "events_exchanged": [ "EvidencePackageDrafted", "ReviewerApproved" ], "contract_type": "Published language", "failure_risks": [ "Reviewer bottleneck" ], "acl_notes": "Review & Compliance never mutates evidence-package content; only appends a release.", "ownership_boundary": "Review & Compliance owns the release log." }, { "upstream": "Evidence Assembly", "downstream": "Authorization Boost Fulfillment", "pattern": "customer-supplier", "business_reason": "The evidence-package draft is produced by AI; Fulfillment consumes it.", "data_exchanged": [ "Evidence-package draft payload", "Confidence score" ], "events_exchanged": [ "EvidencePackageDrafted", "EscalationRaised" ], "contract_type": "Published language (validated schema)", "failure_risks": [ "A draft failing OutputValidator reaches Fulfillment" ], "acl_notes": "OutputValidator sits inside Evidence Assembly.", "ownership_boundary": "Evidence Assembly owns the run log; Fulfillment owns evidence-package state." }, { "upstream": "Warranty Company Rule Library & Retrieval", "downstream": "Evidence Assembly", "pattern": "open-host-service", "business_reason": "Rule-library retrieval is a stable interface used by all agents.", "data_exchanged": [ "Retrieval hits", "Provider citations" ], "events_exchanged": [ "RuleUpdateIngested", "IndexRebuilt" ], "contract_type": "Open-host published API", "failure_risks": [ "Cross-tenant leak", "Stale warranty-company rule set" ], "acl_notes": "Every call carries tenant + warranty-company claim.", "ownership_boundary": "Warranty Company Rule Library owns indices." }, { "upstream": "Client Onboarding & Contractor Profile", "downstream": "Authorization Boost Fulfillment", "pattern": "customer-supplier", "business_reason": "No intake without a provisioned tenant + reviewer of record.", "data_exchanged": [ "Tenant profile", "Reviewer-of-record identity" ], "events_exchanged": [ "TenantProvisioned", "ReviewerOfRecordRegistered" ], "contract_type": "Published language", "failure_risks": [ "No reviewer of record on file" ], "acl_notes": "Fulfillment consumes reviewer identity by id only.", "ownership_boundary": "Client Onboarding owns tenant lifecycle." }, { "upstream": "Authorization Boost Fulfillment", "downstream": "Client Success & Retention", "pattern": "customer-supplier", "business_reason": "Submission confirmation feeds the contractor-facing status surface.", "data_exchanged": [ "Submission", "Case status" ], "events_exchanged": [ "PackageSubmitted", "SubmissionConfirmed" ], "contract_type": "Published language", "failure_risks": [ "Silent submission failure" ], "acl_notes": "Client Success renders status; never mutates case state directly.", "ownership_boundary": "Client Success owns the contractor-facing status surface." }, { "upstream": "Authorization Boost Fulfillment", "downstream": "Appeal & Escalation Desk", "pattern": "customer-supplier", "business_reason": "An under-authorization detected on a submitted case triggers the appeal workflow.", "data_exchanged": [ "AuthorizationReceived", "Under-authorization determination" ], "events_exchanged": [ "AuthorizationReceived", "UnderAuthorizationDetected" ], "contract_type": "Published language", "failure_risks": [ "Missed under-authorization detection" ], "acl_notes": "Appeal Desk consumes only the authorization outcome, not raw evidence internals.", "ownership_boundary": "Appeal & Escalation Desk owns the appeal lifecycle." }, { "upstream": "Appeal & Escalation Desk", "downstream": "Outcome & Uplift Tracking", "pattern": "customer-supplier", "business_reason": "A resolved appeal produces the uplift figure billing depends on.", "data_exchanged": [ "AppealFiled", "Final authorized amount" ], "events_exchanged": [ "AppealFiled", "UpliftConfirmed" ], "contract_type": "Published language", "failure_risks": [ "Uplift miscalculated against the wrong first offer" ], "acl_notes": "Outcome & Uplift Tracking is the single source of truth for uplift math.", "ownership_boundary": "Outcome & Uplift Tracking owns the uplift figure." }, { "upstream": "Outcome & Uplift Tracking", "downstream": "Billing & Revenue", "pattern": "customer-supplier", "business_reason": "The contingency fee is only chargeable once uplift is confirmed.", "data_exchanged": [ "UpliftConfirmed" ], "events_exchanged": [ "UpliftConfirmed" ], "contract_type": "Published language", "failure_risks": [ "Premature contingency charge" ], "acl_notes": "Billing never computes uplift itself.", "ownership_boundary": "Billing owns invoices; Outcome & Uplift Tracking owns the uplift figure." }, { "upstream": "Client Success & Retention", "downstream": "Auto-Submit & Recurring Programs", "pattern": "customer-supplier", "business_reason": "A contractor's success record determines Auto-Submit eligibility.", "data_exchanged": [ "Case outcome history" ], "events_exchanged": [ "CaseResolved" ], "contract_type": "Published language", "failure_risks": [ "Eligibility computed on stale data" ], "acl_notes": "Auto-Submit recomputes eligibility on each CaseResolved.", "ownership_boundary": "Auto-Submit owns the enrollment decision." }, { "upstream": "Review & Compliance", "downstream": "Compliance & Licensing Governance", "pattern": "customer-supplier", "business_reason": "A retraction changes the public release-readiness posture.", "data_exchanged": [ "Retraction reason" ], "events_exchanged": [ "PackageRetracted" ], "contract_type": "Published language", "failure_risks": [ "Delayed release-decision recompute" ], "acl_notes": "Compliance & Licensing Governance recomputes release-readiness on every retraction.", "ownership_boundary": "Compliance & Licensing Governance owns the public release-claim decision." }, { "upstream": "Identity & Access", "downstream": "every context", "pattern": "open-host-service", "business_reason": "Every workflow needs authenticated, role-checked access.", "data_exchanged": [ "Session", "Role claim" ], "events_exchanged": [ "UserSignedIn", "RoleAssigned" ], "contract_type": "Open-host published API", "failure_risks": [ "Role escalation" ], "acl_notes": "Every context checks roles server-side, never trusting a client claim alone.", "ownership_boundary": "Identity & Access owns users, roles, sessions." } ], "aggregates": [ { "name": "EngagementAggregate", "root": "Engagement", "context": "Case Intake & Qualification", "purpose": "Guard lead qualification and accepted-engagement state.", "entities": [ "Lead", "Engagement" ], "value_objects": [ "ScopeStatement", "PricingOffer" ], "invariants": [ "Cannot open a case intake without an accepted engagement" ], "commands": [ "QualifyLead", "AcceptEngagement" ], "events": [ "EngagementAccepted" ], "repository": "EngagementRepository", "transaction_boundary": "One engagement per transaction" }, { "name": "ContractorAccountAggregate", "root": "ContractorAccount", "context": "Client Onboarding & Contractor Profile", "purpose": "Guard tenant provisioning, reviewer-of-record registration, and portal-credential custody.", "entities": [ "Tenant", "ReviewerOfRecord", "PortalCredential" ], "value_objects": [ "ContactMatrix", "WarrantyCompanyEnrollmentSet" ], "invariants": [ "Every tenant has at least one named trade-qualified reviewer of record on file" ], "commands": [ "ProvisionTenant", "RegisterReviewerOfRecord", "StorePortalCredential" ], "events": [ "TenantProvisioned", "ReviewerOfRecordRegistered" ], "repository": "ContractorAccountRepository", "transaction_boundary": "One tenant per transaction" }, { "name": "CaseAggregate", "root": "Case", "context": "Authorization Boost Fulfillment", "purpose": "Guard the case lifecycle from intake through resolution.", "entities": [ "CaseIntake", "Submission" ], "value_objects": [ "WorkOrderNumber", "WarrantyCompanyRef" ], "invariants": [ "A case cannot advance to submission without a passed completeness checklist" ], "commands": [ "OpenCaseIntake", "IngestEvidence", "SubmitToPortal" ], "events": [ "CaseIntakeReceived", "EvidenceIngested", "PackageSubmitted" ], "repository": "CaseRepository", "transaction_boundary": "One case per transaction" }, { "name": "EvidencePackageAggregate", "root": "EvidencePackage", "context": "Authorization Boost Fulfillment", "purpose": "Guard evidence-package state and citation integrity.", "entities": [ "EvidenceLine", "CostBenchmarkLine" ], "value_objects": [ "EvidenceCitation", "ConfidenceScore" ], "invariants": [ "Every evidence-package line cites at least one evidence item or is marked an explicit gap" ], "commands": [ "DraftEvidencePackage" ], "events": [ "EvidencePackageDrafted" ], "repository": "EvidencePackageRepository", "transaction_boundary": "One evidence package per transaction" }, { "name": "CompletenessChecklistAggregate", "root": "CompletenessChecklist", "context": "Authorization Boost Fulfillment", "purpose": "Guard the deterministic per-warranty-company completeness gate.", "entities": [ "ChecklistItem" ], "value_objects": [ "HardGapReason" ], "invariants": [ "A case cannot pass the completeness checklist with an unresolved hard gap" ], "commands": [ "RunCompletenessChecklist" ], "events": [ "CompletenessCheckPassed", "CompletenessCheckFailed" ], "repository": "CompletenessChecklistRepository", "transaction_boundary": "One checklist run per transaction" }, { "name": "ExtractionRunAggregate", "root": "ExtractionRun", "context": "Evidence Assembly", "purpose": "Guard a single bounded AI extraction/drafting run and its audit trail.", "entities": [ "PromptVersion", "RetrievalHit" ], "value_objects": [ "TokenBudget", "ModelCost" ], "invariants": [ "No extraction output leaves this context without passing OutputValidator" ], "commands": [ "StartExtractionRun", "PublishPromptVersion" ], "events": [ "EvidencePackageDrafted", "EscalationRaised" ], "repository": "ExtractionRunRepository", "transaction_boundary": "One run per transaction" }, { "name": "WarrantyCompanyRuleSetAggregate", "root": "WarrantyCompanyRuleSet", "context": "Warranty Company Rule Library & Retrieval", "purpose": "Guard per-warranty-company completeness-checklist and cost-benchmark data integrity.", "entities": [ "ChecklistCard", "CostBenchmarkEntry" ], "value_objects": [ "ProviderCitation" ], "invariants": [ "Retrieval is scoped to the completeness checklist adopted by the case's warranty company" ], "commands": [ "IngestRuleUpdate", "Reindex" ], "events": [ "RuleUpdateIngested", "IndexRebuilt" ], "repository": "WarrantyCompanyRuleSetRepository", "transaction_boundary": "One rule set per transaction" }, { "name": "ReviewAggregate", "root": "Review", "context": "Review & Compliance", "purpose": "Guard the reviewer release lifecycle and signature integrity.", "entities": [ "ReviewerSession" ], "value_objects": [ "ReleaseManifest" ], "invariants": [ "A Release is bound to a live authenticated session, not a form field" ], "commands": [ "ReleasePackage", "RejectPackage" ], "events": [ "ReviewerApproved", "PackageReleaseRejected" ], "repository": "ReviewRepository", "transaction_boundary": "One release per transaction" }, { "name": "PackageRetractionAggregate", "root": "PackageRetraction", "context": "Review & Compliance", "purpose": "Guard the retraction workflow for a previously released package.", "entities": [ "RetractionRecord" ], "value_objects": [ "RetractionReason" ], "invariants": [ "Released Authorization Boost Packages are immutable; corrections go through PackageRetraction" ], "commands": [ "RetractPackage" ], "events": [ "PackageRetracted" ], "repository": "PackageRetractionRepository", "transaction_boundary": "One retraction per transaction" }, { "name": "AppealAggregate", "root": "Appeal", "context": "Appeal & Escalation Desk", "purpose": "Guard the structured-appeal lifecycle and consent capture.", "entities": [ "AppealNarrative" ], "value_objects": [ "UpliftCitation" ], "invariants": [ "An appeal cannot be filed without captured contractor consent on the specific language" ], "commands": [ "DraftAppeal", "ConfirmContractorConsent", "FileAppeal" ], "events": [ "ContractorConsentConfirmed", "AppealFiled" ], "repository": "AppealRepository", "transaction_boundary": "One appeal per transaction" }, { "name": "OwnerActionLedgerAggregate", "root": "OwnerActionLedger", "context": "Compliance & Licensing Governance", "purpose": "Guard the contractor-action ledger and the public release-readiness decision.", "entities": [ "OwnerAction", "ReleaseDecision" ], "value_objects": [ "BlockerReason" ], "invariants": [ "Release cannot flip to 'ready' with open blocking owner actions" ], "commands": [ "ResolveOwnerAction", "RaiseOwnerAction" ], "events": [ "OwnerActionResolved", "ReleaseDecisionChanged" ], "repository": "OwnerActionLedgerRepository", "transaction_boundary": "One ledger per tenant per transaction" }, { "name": "AutoSubmitSubscriptionAggregate", "root": "AutoSubmitSubscription", "context": "Auto-Submit & Recurring Programs", "purpose": "Guard Auto-Submit eligibility and enrollment state.", "entities": [ "EligibilityCheck" ], "value_objects": [ "VolumeTier" ], "invariants": [ "No contractor is enrolled in Auto-Submit without 3+ successful prior cases on file" ], "commands": [ "EnrollAutoSubmit", "EvaluateEligibility" ], "events": [ "AutoSubmitEnrolled", "EligibilityConfirmed" ], "repository": "AutoSubmitSubscriptionRepository", "transaction_boundary": "One subscription per transaction" } ], "event_storm": [ { "seq": 1, "command": "QualifyLead", "event": "LeadQualified", "actor": "Business owner / founder", "context": "Case Intake & Qualification", "aggregate": "EngagementAggregate", "policy": "Reject out-of-ICP", "downstream": "Engagement offer", "risk": "Out-of-scope acceptance" }, { "seq": 2, "command": "AcceptEngagement", "event": "EngagementAccepted", "actor": "Contractor Owner/Operator", "context": "Case Intake & Qualification", "aggregate": "EngagementAggregate", "policy": "Engagement letter required before intake", "downstream": "Client Onboarding & Contractor Profile", "risk": "Scope mismatch" }, { "seq": 3, "command": "ProvisionTenant", "event": "TenantProvisioned", "actor": "Onboarding lead", "context": "Client Onboarding & Contractor Profile", "aggregate": "ContractorAccountAggregate", "policy": "No intake without a reviewer of record", "downstream": "Authorization Boost Fulfillment enablement", "risk": "No reviewer of record before go-live" }, { "seq": 4, "command": "OpenCaseIntake", "event": "CaseIntakeReceived", "actor": "Contractor Owner/Operator", "context": "Authorization Boost Fulfillment", "aggregate": "CaseAggregate", "policy": "Reject duplicate open intake for the same work order", "downstream": "Normalization + rule-library retrieval", "risk": "Duplicate intake" }, { "seq": 5, "command": "IngestEvidence", "event": "EvidenceIngested", "actor": "AI extraction/drafting layer", "context": "Authorization Boost Fulfillment", "aggregate": "CaseAggregate", "policy": "Evidence coverage rule must pass before extraction starts", "downstream": "Extraction authorized", "risk": "Sparse evidence coverage" }, { "seq": 6, "command": "StartExtractionRun", "event": "EvidencePackageDrafted", "actor": "AI extraction/drafting layer", "context": "Evidence Assembly", "aggregate": "ExtractionRunAggregate", "policy": "Escalate below confidence threshold or on unmatched checklist", "downstream": "Completeness checklist evaluation", "risk": "Hallucinated citation" }, { "seq": 7, "command": "RunCompletenessChecklist", "event": "CompletenessCheckPassed", "actor": "AI extraction/drafting layer", "context": "Authorization Boost Fulfillment", "aggregate": "CompletenessChecklistAggregate", "policy": "Every required field/photo/documentation type present", "downstream": "Reviewer queue", "risk": "False completeness pass" }, { "seq": 8, "command": "n/a (system)", "event": "EscalationRaised", "actor": "AI extraction/drafting layer", "context": "Evidence Assembly", "aggregate": "ExtractionRunAggregate", "policy": "Escalate on ambiguous cost benchmark or contested code citation", "downstream": "Trade-Qualified Reviewer escalation queue", "risk": "Under- or over-escalation" }, { "seq": 9, "command": "ReleasePackage", "event": "ReviewerApproved", "actor": "Trade-Qualified Reviewer", "context": "Review & Compliance", "aggregate": "ReviewAggregate", "policy": "Only the tenant's registered reviewer may release", "downstream": "Submission authorized", "risk": "Release-signature spoofing" }, { "seq": 10, "command": "SubmitToPortal", "event": "PackageSubmitted", "actor": "AI extraction/drafting layer", "context": "Authorization Boost Fulfillment", "aggregate": "CaseAggregate", "policy": "Cannot submit without a valid Release", "downstream": "Portal tracking + Client Success", "risk": "Submission adapter failure" }, { "seq": 11, "command": "n/a (portal callback)", "event": "AuthorizationReceived", "actor": "Warranty Company", "context": "Authorization Boost Fulfillment", "aggregate": "CaseAggregate", "policy": "Compare authorization against cost-benchmark line", "downstream": "Under-authorization check", "risk": "Authorization outcome missed / not captured" }, { "seq": 12, "command": "n/a (system)", "event": "UnderAuthorizationDetected", "actor": "AI extraction/drafting layer", "context": "Appeal & Escalation Desk", "aggregate": "AppealAggregate", "policy": "Flag when authorized amount or scope is below the diagnosed cost benchmark", "downstream": "Appeal decision", "risk": "Missed under-authorization" }, { "seq": 13, "command": "ConfirmContractorConsent", "event": "ContractorConsentConfirmed", "actor": "Contractor Owner/Operator", "context": "Appeal & Escalation Desk", "aggregate": "AppealAggregate", "policy": "Appeal cannot be filed without consent", "downstream": "Appeal filing authorized", "risk": "Filing without consent" }, { "seq": 14, "command": "FileAppeal", "event": "AppealFiled", "actor": "Trade-Qualified Reviewer", "context": "Appeal & Escalation Desk", "aggregate": "AppealAggregate", "policy": "Reviewer submits only after consent is captured", "downstream": "Cycle-time tracking resumed", "risk": "Warranty company non-responsive" }, { "seq": 15, "command": "n/a (portal callback)", "event": "UpliftConfirmed", "actor": "Warranty Company", "context": "Appeal & Escalation Desk", "aggregate": "AppealAggregate", "policy": "Uplift computed against the original first offer only", "downstream": "Billing (contingency fee)", "risk": "Uplift miscalculated" } ], "commands": [ { "name": "OpenCaseIntake", "issued_by": "Contractor Owner/Operator", "preconditions": [ "Engagement accepted", "Tenant provisioned" ], "aggregate": "CaseAggregate", "success_event": "CaseIntakeReceived", "failure_event": "IntakeRejected", "authorization": "Tenant member with Operator role", "validation": "Work order number + warranty company present; no duplicate open intake for the same work order", "audit": "Command + payload hash logged with tenant + user" }, { "name": "IngestEvidence", "issued_by": "Contractor Owner/Operator", "preconditions": [ "Case intake open" ], "aggregate": "CaseAggregate", "success_event": "EvidenceIngested", "failure_event": "EvidenceRejected", "authorization": "Tenant member with Operator role", "validation": "At least one photo or reading present; file types allow-listed", "audit": "Command + payload hash logged with tenant + user" }, { "name": "StartExtractionRun", "issued_by": "AI extraction/drafting layer", "preconditions": [ "EvidenceIngested" ], "aggregate": "ExtractionRunAggregate", "success_event": "EvidencePackageDrafted", "failure_event": "ExtractionRunFailed", "authorization": "System (Evidence Assembly service account)", "validation": "Prompt version published; tenant-scoped retrieval context only", "audit": "Prompt version + retrieval hit ids + cost logged" }, { "name": "RunCompletenessChecklist", "issued_by": "AI extraction/drafting layer", "preconditions": [ "EvidencePackageDrafted" ], "aggregate": "CompletenessChecklistAggregate", "success_event": "CompletenessCheckPassed", "failure_event": "CompletenessCheckFailed", "authorization": "System (rule engine)", "validation": "Every required field for the case's warranty company evaluated", "audit": "Rule version + evaluation result logged" }, { "name": "ReleasePackage", "issued_by": "Trade-Qualified Reviewer", "preconditions": [ "CompletenessCheckPassed" ], "aggregate": "ReviewAggregate", "success_event": "ReviewerApproved", "failure_event": "PackageReleaseRejected", "authorization": "Tenant's registered trade-qualified reviewer only", "validation": "Every evidence-package line cites a source or explicit gap", "audit": "Release bound to authenticated session + timestamp" }, { "name": "SubmitToPortal", "issued_by": "AI extraction/drafting layer", "preconditions": [ "ReviewerApproved" ], "aggregate": "CaseAggregate", "success_event": "PackageSubmitted", "failure_event": "SubmissionFailed", "authorization": "System (submission adapter, contractor's own portal credentials)", "validation": "Valid Release reference present", "audit": "Submission payload hash + tracking id logged" }, { "name": "ConfirmContractorConsent", "issued_by": "Contractor Owner/Operator", "preconditions": [ "UnderAuthorizationDetected" ], "aggregate": "AppealAggregate", "success_event": "ContractorConsentConfirmed", "failure_event": "ConsentDeclined", "authorization": "Tenant member with Operator role", "validation": "Consent tied to the specific appeal-language version", "audit": "Consent event logged with contractor identity + timestamp" }, { "name": "FileAppeal", "issued_by": "Trade-Qualified Reviewer", "preconditions": [ "ContractorConsentConfirmed" ], "aggregate": "AppealAggregate", "success_event": "AppealFiled", "failure_event": "AppealFilingFailed", "authorization": "Tenant's registered trade-qualified reviewer only", "validation": "Consent present and not expired", "audit": "Filing payload hash + tracking id logged" }, { "name": "ResolveCase", "issued_by": "Trade-Qualified Reviewer", "preconditions": [ "AuthorizationReceived or UpliftConfirmed" ], "aggregate": "CaseAggregate", "success_event": "CaseResolved", "failure_event": "CaseResolutionRejected", "authorization": "Tenant's registered trade-qualified reviewer only", "validation": "Final authorization amount and scope on file", "audit": "Resolution event logged with actor + timestamp" }, { "name": "EnrollAutoSubmit", "issued_by": "Contractor Owner/Operator", "preconditions": [ "3+ CaseResolved with successful outcome" ], "aggregate": "AutoSubmitSubscriptionAggregate", "success_event": "AutoSubmitEnrolled", "failure_event": "EnrollmentRejected", "authorization": "Tenant member with Operator role", "validation": "Eligibility check passes", "audit": "Enrollment event logged with contractor identity" }, { "name": "ResolveOwnerAction", "issued_by": "Contractor Owner/Operator", "preconditions": [ "OwnerAction open" ], "aggregate": "OwnerActionLedgerAggregate", "success_event": "OwnerActionResolved", "failure_event": "OwnerActionRejected", "authorization": "Tenant member with Operator role", "validation": "Supplied fact matches the required schema for the blocker", "audit": "Ledger entry logged with contractor identity + timestamp" }, { "name": "RetractPackage", "issued_by": "Legal reviewer", "preconditions": [ "PackageSubmitted", "Material finding confirmed" ], "aggregate": "PackageRetractionAggregate", "success_event": "PackageRetracted", "failure_event": "RetractionRejected", "authorization": "Legal reviewer + Trade-Qualified Reviewer co-signature", "validation": "Retraction reason documented", "audit": "Retraction event logged; contractor notification triggered" } ], "policies": [ { "name": "Auto-request reviewer release on completeness check pass", "trigger": "CompletenessCheckPassed", "condition": "Evidence coverage spec passes", "action": "Enqueue ReleasePackage", "context": "Authorization Boost Fulfillment", "ai_involvement": "none", "human_approval": false }, { "name": "Escalate on low confidence or unmatched checklist", "trigger": "StartExtractionRun completes", "condition": "Confidence score below threshold OR completeness checklist cannot be matched to a known warranty company", "action": "Raise EscalationRaised to Trade-Qualified Reviewer", "context": "Evidence Assembly", "ai_involvement": "primary", "human_approval": true }, { "name": "Block submission on open compliance blocker", "trigger": "SubmitToPortal requested", "condition": "An open owner action exists on the case", "action": "Reject with DeliveryBlocked", "context": "Compliance & Licensing Governance", "ai_involvement": "none", "human_approval": false }, { "name": "Detect under-authorization on authorization receipt", "trigger": "AuthorizationReceived", "condition": "Authorized amount or scope below the cost-benchmark line", "action": "Raise UnderAuthorizationDetected", "context": "Appeal & Escalation Desk", "ai_involvement": "primary", "human_approval": false }, { "name": "Require consent before appeal filing", "trigger": "UnderAuthorizationDetected", "condition": "Contractor has not yet confirmed the appeal language", "action": "Hold FileAppeal until ContractorConsentConfirmed", "context": "Appeal & Escalation Desk", "ai_involvement": "none", "human_approval": true }, { "name": "Charge contingency fee only after uplift confirmation", "trigger": "UpliftConfirmed", "condition": "Final authorized amount exceeds the original first offer", "action": "Enqueue ChargeCase (contingency line)", "context": "Billing & Revenue", "ai_involvement": "none", "human_approval": false }, { "name": "Enroll Auto-Submit only on proven success", "trigger": "CaseResolved", "condition": "Contractor has 3+ successful cases and requests enrollment", "action": "Enqueue EnrollAutoSubmit", "context": "Auto-Submit & Recurring Programs", "ai_involvement": "none", "human_approval": true }, { "name": "Retract on material finding", "trigger": "New fact contradicts a submitted claim", "condition": "Legal + reviewer confirm the finding is material", "action": "Enqueue RetractPackage", "context": "Review & Compliance", "ai_involvement": "none", "human_approval": true }, { "name": "Alert on submission failure", "trigger": "SubmissionFailed", "condition": "Submission adapter returns an error", "action": "Alert contractor within 1h; open Success ticket", "context": "Client Success & Retention", "ai_involvement": "none", "human_approval": false }, { "name": "Never call the model with cross-tenant retrieval context", "trigger": "StartExtractionRun", "condition": "Always", "action": "Scope retrieval router to the requesting tenant only", "context": "Evidence Assembly", "ai_involvement": "primary", "human_approval": false }, { "name": "Cap pilot cohort at 20 total cases in month one", "trigger": "OpenCaseIntake", "condition": "Pilot case count would exceed 20 in the current pilot window", "action": "Reject new intake; queue for next window", "context": "Case Intake & Qualification", "ai_involvement": "none", "human_approval": true }, { "name": "Reject out-of-ICP engagement", "trigger": "QualifyLead", "condition": "Contractor completes fewer than 10 warranty work orders/month or has no active warranty-company enrollment", "action": "Decline engagement", "context": "Case Intake & Qualification", "ai_involvement": "none", "human_approval": true } ], "invariants": [ { "invariant": "An Authorization Boost Package cannot be submitted without a valid reviewer Release.", "context": "Authorization Boost Fulfillment <-> Review & Compliance", "aggregate": "CaseAggregate", "why": "Submission defensibility; brand-risk", "enforcement": "Aggregate command handler rejects submission without a release reference" }, { "invariant": "Every evidence-package line cites at least one evidence item or is marked an explicit gap.", "context": "Authorization Boost Fulfillment", "aggregate": "EvidencePackageAggregate", "why": "Prevents fabricated readings or citations in a submitted package", "enforcement": "OutputValidator rejects uncited claims before EvidencePackageDrafted fires" }, { "invariant": "A Release is bound to a live authenticated session, not a form field.", "context": "Review & Compliance", "aggregate": "ReviewAggregate", "why": "Prevents release-signature spoofing", "enforcement": "Release handler reads the session claim server-side, never a client-supplied field" }, { "invariant": "Released Authorization Boost Packages are immutable; corrections go through PackageRetraction.", "context": "Review & Compliance", "aggregate": "ReviewAggregate", "why": "Preserves audit-trail integrity", "enforcement": "Write path blocks in-place edits on a released package" }, { "invariant": "No extraction output leaves Evidence Assembly without an OutputValidator pass.", "context": "Evidence Assembly", "aggregate": "ExtractionRunAggregate", "why": "Prevents hallucinated citations reaching a reviewer", "enforcement": "ExtractionRun handler blocks EvidencePackageDrafted on a validator failure" }, { "invariant": "Retrieval is scoped to the completeness checklist adopted by the case's warranty company.", "context": "Warranty Company Rule Library & Retrieval", "aggregate": "WarrantyCompanyRuleSetAggregate", "why": "Prevents a false completeness pass or fail from the wrong provider's rules", "enforcement": "Retrieval router requires a warranty-company claim on every call" }, { "invariant": "Release cannot flip to 'ready' with open blocking owner actions.", "context": "Compliance & Licensing Governance", "aggregate": "OwnerActionLedgerAggregate", "why": "Prevents a premature public claim of submission-readiness", "enforcement": "ReleaseReadinessSpec checked before any public release-decision change" }, { "invariant": "Every tenant has at least one named trade-qualified reviewer of record on file before intake opens.", "context": "Client Onboarding & Contractor Profile", "aggregate": "ContractorAccountAggregate", "why": "No case can pass the human chokepoint without a named reviewer", "enforcement": "OpenCaseIntake handler checks for a registered reviewer of record" }, { "invariant": "An appeal cannot be filed without captured contractor consent on the specific language.", "context": "Appeal & Escalation Desk", "aggregate": "AppealAggregate", "why": "Preserves the contractor-consent human chokepoint", "enforcement": "FileAppeal handler requires a matching ContractorConsentConfirmed event" }, { "invariant": "Roles are stored in a dedicated table and checked server-side.", "context": "Identity & Access", "aggregate": "UserAggregate", "why": "Prevents privilege escalation via a client-only role check", "enforcement": "Every authorization check reads the roles table server-side" } ], "ai_agents": [ { "name": "Extraction Agent", "context": "Evidence Assembly", "responsibility": "Extract structured data from heterogeneous work-order photos, meter/pressure readings, nameplate/serial data, and contractor diagnosis notes; build the cited evidence package.", "inputs": [ "Ingested evidence (tenant-scoped)", "Warranty-company rule-set retrieval hits", "Prompt version" ], "outputs": [ "Structured evidence-package draft", "Confidence score", "Citations" ], "tools": [ "Retrieval API", "Structured-output validator", "Cost meter" ], "forbidden_actions": [ "Call external tools not in its allowlist", "Access another tenant's retrieval index", "Emit output that skips the OutputValidator", "Attest to a diagnosis, code citation, or recommended scope", "Invent readings, dates, or diagnoses not present in source evidence" ], "memory_scope": "Per-run only; no cross-run memory; prompt-injection scrubber on all contractor and warranty-company inputs.", "retrieval_sources": [ "Tenant-scoped evidence index", "Warranty-company completeness-checklist library (read-only cache)" ], "validations": [ "Structured-output schema", "Citation-coverage rule", "PII-scrub rule on prompt inputs" ], "confidence_scoring": "Model-reported logprobs + citation-coverage combined into a bounded [0..1] score.", "escalation_triggers": [ "Score < threshold", "No matching completeness checklist found for the warranty company", "Contested cost-benchmark line", "Missing citation on any claim" ], "human_approval": true, "failure_modes": [ "Prompt injection via forwarded photo/notes content", "Hallucinated citation", "Retrieval-tenant leak" ], "audit_logs": [ "Prompt version", "Retrieval hits (ids only)", "Cost + latency", "Validator verdict" ], "metrics": [ "Draft acceptance rate", "Escalation rate", "Cost per case", "p95 latency" ], "versioning": "Prompt versions immutable once published; published via the prompt registry; rollout via feature flag." }, { "name": "Drafting Agent", "context": "Evidence Assembly", "responsibility": "Compose the itemized parts-and-labor cost benchmark and, when a case is under-authorized, scope-limited, or denied, draft the structured appeal narrative -- always cited to the evidence package and the case's cost-benchmark library.", "inputs": [ "Extraction Agent output", "Regional cost-benchmark data", "Denial-pattern library" ], "outputs": [ "Cost-benchmark composition", "Draft appeal narrative" ], "tools": [ "Cost-benchmark retrieval API", "Structured-output validator" ], "forbidden_actions": [ "File an appeal without contractor consent", "Invent a cost-benchmark figure not sourced from the regional library", "Overstate diagnosis certainty beyond the contractor's notes/photos" ], "memory_scope": "Per-case only; no cross-tenant memory.", "retrieval_sources": [ "Regional cost-benchmark library", "Per-warranty-company denial-pattern library" ], "validations": [ "Structured-output schema", "Citation-coverage rule" ], "confidence_scoring": "Model-reported logprobs + citation-coverage combined into a bounded [0..1] score.", "escalation_triggers": [ "Score < threshold", "Contested cost-benchmark line", "No denial-pattern match for the warranty company's stated reason" ], "human_approval": true, "failure_modes": [ "Overstated diagnosis certainty", "Cost-benchmark drift on a non-standard part" ], "audit_logs": [ "Prompt version", "Cost-benchmark source ids", "Validator verdict" ], "metrics": [ "Appeal win rate", "Cost-benchmark acceptance rate", "Escalation rate" ], "versioning": "Prompt versions immutable once published; rollout via feature flag paired with an eval run." }, { "name": "Denial-Pattern QA Agent", "context": "Evidence Assembly", "responsibility": "Second-pass check of a drafted evidence package or appeal against the warranty company's specific denial-reason history to pre-empt common rejection triggers before reviewer release.", "inputs": [ "Drafted evidence package or appeal narrative", "Per-warranty-company denial-pattern library" ], "outputs": [ "Pre-empt flag list", "QA verdict" ], "tools": [ "Denial-pattern retrieval API", "Structured-output validator" ], "forbidden_actions": [ "Auto-release a package", "Alter evidence-package content directly (flags only, does not edit)" ], "memory_scope": "Per-run only.", "retrieval_sources": [ "Per-warranty-company denial-pattern library" ], "validations": [ "Structured-output schema", "Flag-to-clause linkage check" ], "confidence_scoring": "Rule-weighted match score against known denial-reason patterns.", "escalation_triggers": [ "High-confidence match to a known rejection trigger", "No denial-pattern library entry for the warranty company" ], "human_approval": true, "failure_modes": [ "Overfitting to a stale denial-pattern library", "False-positive pre-empt flag" ], "audit_logs": [ "Denial-pattern library version", "Flag list", "QA verdict" ], "metrics": [ "First-pass authorization win rate", "Pre-empt flag precision" ], "versioning": "Denial-pattern library versioned per warranty company; QA agent prompt versioned separately." } ], "use_cases": [ { "name": "Deliver a reviewer-released Authorization Boost Package", "actor": "Contractor Owner/Operator + Trade-Qualified Reviewer", "context": "Authorization Boost Fulfillment + Review & Compliance + Evidence Assembly", "goal": "Produce and submit a released Authorization Boost Package for one work order", "preconditions": [ "Tenant provisioned", "Trade-qualified reviewer of record registered", "Engagement accepted" ], "main_flow": [ "Contractor opens a case intake", "Evidence ingested (photos, meter/pressure readings, nameplate/serial data, diagnosis notes)", "Extraction Agent drafts the evidence package with citations", "Deterministic rules evaluate the completeness checklist", "Trade-Qualified Reviewer releases the package (or escalates)", "Submission adapter submits the package through the warranty company's contractor portal", "Success lead confirms submission" ], "alternative_flows": [ "Confidence below threshold or unmatched completeness checklist -> EscalationRaised -> reviewer resolves", "Blocking owner action open -> submission blocked -> surfaced to contractor", "Submission failure -> alert contractor within 1h" ], "business_rules": [ "Every evidence-package line cites evidence or is an explicit gap", "Only the tenant's registered reviewer may release" ], "ai_role": "Extract + draft the evidence package + score confidence", "human_role": "Release; escalate; retract", "commands": [ "OpenCaseIntake", "IngestEvidence", "StartExtractionRun", "RunCompletenessChecklist", "ReleasePackage", "SubmitToPortal" ], "events": [ "CaseIntakeReceived", "EvidenceIngested", "EvidencePackageDrafted", "CompletenessCheckPassed", "ReviewerApproved", "PackageSubmitted" ], "aggregates": [ "CaseAggregate", "EvidencePackageAggregate", "ExtractionRunAggregate", "ReviewAggregate", "CompletenessChecklistAggregate" ], "success": "Authorization Boost Package submitted + release attached + audit trail complete", "failure_handling": "EscalationRaised -> reviewer queue; SubmissionFailed -> contractor alert + Success ticket", "audit": "Full command -> event chain with actor + timestamp per step" }, { "name": "File a supplemental appeal after an under-authorized work order", "actor": "Trade-Qualified Reviewer + Contractor Owner/Operator", "context": "Appeal & Escalation Desk + Authorization Boost Fulfillment", "goal": "Detect an under-authorization, draft the appeal, capture contractor consent, and file", "preconditions": [ "Case submitted and AuthorizationReceived", "Cost-benchmark line on file for comparison" ], "main_flow": [ "Authorization received from the warranty company", "System compares authorized amount/scope against the cost-benchmark line", "UnderAuthorizationDetected raised", "Drafting Agent drafts the appeal narrative", "Contractor reviews and confirms the appeal language", "Trade-Qualified Reviewer files the appeal" ], "alternative_flows": [ "Contractor declines consent -> appeal not filed -> case marked resolved at the original authorization", "Warranty company non-responsive past SLA -> reviewer escalates via phone/email" ], "business_rules": [ "An appeal cannot be filed without captured contractor consent", "Uplift always computed against the original first offer" ], "ai_role": "Detect the under-authorization; draft the appeal narrative", "human_role": "Confirm consent (contractor); file the appeal (reviewer)", "commands": [ "ConfirmContractorConsent", "FileAppeal" ], "events": [ "UnderAuthorizationDetected", "ContractorConsentConfirmed", "AppealFiled", "UpliftConfirmed" ], "aggregates": [ "AppealAggregate", "CaseAggregate" ], "success": "Appeal filed with consent on file; uplift confirmed on resolution", "failure_handling": "Consent declined -> case resolved at original authorization; non-responsive warranty company -> reviewer escalation", "audit": "Consent event + filing event logged with actor + timestamp" }, { "name": "Escalate a contested cost-benchmark line", "actor": "AI extraction/drafting layer + Trade-Qualified Reviewer", "context": "Evidence Assembly + Review & Compliance", "goal": "Resolve a cost-benchmark line the Drafting Agent cannot confidently source", "preconditions": [ "EvidencePackageDrafted with a flagged cost-benchmark line" ], "main_flow": [ "Drafting Agent flags a cost-benchmark line below the confidence threshold", "EscalationRaised routes to the reviewer queue", "Trade-Qualified Reviewer manually verifies the cost benchmark against the regional library", "Reviewer corrects or confirms the line and proceeds to release" ], "alternative_flows": [ "No regional cost-benchmark data available -> reviewer sources externally and the correction feeds back into the library" ], "business_rules": [ "No cost-benchmark line ships without either an AI citation or an explicit reviewer correction" ], "ai_role": "Flag the contested line; never silently guess", "human_role": "Verify and correct the cost benchmark", "commands": [ "StartExtractionRun", "ReleasePackage" ], "events": [ "EscalationRaised", "ReviewerApproved" ], "aggregates": [ "ExtractionRunAggregate", "ReviewAggregate" ], "success": "Cost-benchmark line resolved and package released", "failure_handling": "Persistent low-confidence pattern flagged to Ops for a rule-library update", "audit": "Escalation + resolution logged with actor + timestamp" }, { "name": "Enroll a contractor in Auto-Submit", "actor": "Contractor Owner/Operator + Success lead", "context": "Auto-Submit & Recurring Programs + Client Success & Retention", "goal": "Convert a proven contractor to automatic per-work-order submission", "preconditions": [ "3+ CaseResolved with successful outcomes on file" ], "main_flow": [ "Contractor requests Auto-Submit enrollment", "Eligibility evaluator checks the 3+ successful-case rule", "Success lead confirms the volume tier and price", "Contractor enrolled; future work orders auto-open as cases" ], "alternative_flows": [ "Eligibility check fails -> enrollment declined with the specific gap explained" ], "business_rules": [ "No enrollment without 3+ successful prior cases", "Every Auto-Submit case still passes the completeness checklist before submission" ], "ai_role": "None -- eligibility is a deterministic rule", "human_role": "Success lead confirms tier and price; contractor opts in", "commands": [ "EvaluateEligibility", "EnrollAutoSubmit" ], "events": [ "EligibilityConfirmed", "AutoSubmitEnrolled" ], "aggregates": [ "AutoSubmitSubscriptionAggregate" ], "success": "Contractor enrolled; billing subscription active", "failure_handling": "Eligibility failure explained with a path to reach 3 successful cases", "audit": "Enrollment event logged with contractor identity" } ], "human_roles": [ { "role": "Trade-Qualified Reviewer", "responsibilities": [ "Release submission-ready Authorization Boost Packages", "Verify cost-benchmark accuracy", "File appeals after contractor consent is captured" ], "contexts": [ "Review & Compliance", "Authorization Boost Fulfillment", "Appeal & Escalation Desk" ], "decisions_owned": [ "Release", "Escalation resolution", "Appeal filing" ], "ai_support": [ "Cited evidence-package drafts", "Confidence-ranked completeness gaps", "Denial-pattern pre-empt flags" ], "approval_authority": "Package release; appeal filing", "escalation_authority": "Escalate a contested claim to Legal reviewer or Business owner", "quality_metrics": [ "Cycle time to release", "Release-to-retraction ratio", "Appeal win rate" ], "workload_risks": [ "Reviewer shortage / early demand trap during seasonal HVAC spikes" ] }, { "role": "Contractor Owner/Operator", "responsibilities": [ "Forward accurate work-order evidence at intake", "Confirm or request revisions on a draft evidence package", "Confirm before any appeal is filed in their name" ], "contexts": [ "Case Intake & Qualification", "Authorization Boost Fulfillment", "Appeal & Escalation Desk" ], "decisions_owned": [ "Case intake submission", "Appeal consent" ], "ai_support": [ "Guided intake checklist", "Status tracking on open cases" ], "approval_authority": "Contractor consent on appeal language", "escalation_authority": "Escalate a service concern to Success lead", "quality_metrics": [ "Second-case conversion", "Auto-Submit attach" ], "workload_risks": [ "Evidence submitted too sparse to meet the completeness checklist on the first pass" ] }, { "role": "Business Owner / Founder", "responsibilities": [ "Own pilot recruitment and pricing decisions", "Own the public release-readiness claim", "Own kill/pivot decisions" ], "contexts": [ "Case Intake & Qualification", "Compliance & Licensing Governance" ], "decisions_owned": [ "Pilot cohort acceptance", "Public release-readiness claim" ], "ai_support": [ "Pipeline and conversion dashboards" ], "approval_authority": "Public release-readiness claim; pricing changes", "escalation_authority": "Escalate a licensing-boundary question to external counsel", "quality_metrics": [ "Pilot signups", "Kill-criteria adherence" ], "workload_risks": [ "Founder-led fulfillment bottleneck before Phase 1 hardens" ] }, { "role": "Legal Reviewer", "responsibilities": [ "Review engagement and disclaimer language", "Co-sign retractions", "Own the 50-state licensing-boundary review" ], "contexts": [ "Compliance & Licensing Governance", "Review & Compliance" ], "decisions_owned": [ "Retraction co-signature", "Licensing-boundary sign-off" ], "ai_support": [ "None -- legal review is fully human" ], "approval_authority": "Retraction; licensing-boundary expansion decisions", "escalation_authority": "Escalate to outside counsel", "quality_metrics": [ "Retraction count (target: 0)", "Licensing-boundary review completion" ], "workload_risks": [ "Legal review becomes a bottleneck before consumer-facing expansion" ] }, { "role": "Ops (rule-library / prompt owner)", "responsibilities": [ "Maintain the per-warranty-company completeness-checklist and cost-benchmark libraries", "Own prompt versioning and rollout", "Manage feature flags and secrets" ], "contexts": [ "Warranty Company Rule Library & Retrieval", "Evidence Assembly", "Identity & Access" ], "decisions_owned": [ "Prompt version rollout", "Rule-library update ingestion" ], "ai_support": [ "Eval Agent regression reports (planned as the AI-quality workbench matures)" ], "approval_authority": "Prompt version publish", "escalation_authority": "Escalate a model-cost or rule-library staleness issue to Engineering Lead", "quality_metrics": [ "Draft acceptance rate", "Rule-library freshness" ], "workload_risks": [ "Rule-library drift as warranty-company portals change format" ] }, { "role": "Success Lead", "responsibilities": [ "Confirm submission delivery", "Manage the contractor-facing status surface", "Drive Auto-Submit enrollment" ], "contexts": [ "Client Success & Retention", "Auto-Submit & Recurring Programs" ], "decisions_owned": [ "Submission confirmation", "Auto-Submit tier confirmation" ], "ai_support": [ "Success Copilot (assist only) drafts status updates" ], "approval_authority": "None -- confirms, does not release", "escalation_authority": "Escalate a silent submission failure to Business owner", "quality_metrics": [ "Second-case conversion rate", "Auto-Submit attach rate" ], "workload_risks": [ "Silent submission failure ahead of an appeal-window deadline" ] } ], "data_objects": [ { "name": "CaseIntake", "meaning": "Unit of intake work per work order brought in by the contractor", "owner_context": "Authorization Boost Fulfillment", "writers": [ "Authorization Boost Fulfillment" ], "readers": [ "Review & Compliance", "Analytics & Reporting" ], "source_of_truth": "Authorization Boost Fulfillment DB", "retention": "Life of account + 2 years", "privacy": "confidential", "audit": true }, { "name": "EvidencePackage", "meaning": "The cited diagnostic file (photos, readings, nameplate data, code citations, cost benchmark) assembled for one work order", "owner_context": "Authorization Boost Fulfillment", "writers": [ "Evidence Assembly" ], "readers": [ "Review & Compliance", "Warranty Company (via submission)" ], "source_of_truth": "Authorization Boost Fulfillment DB", "retention": "Life of account + 2 years", "privacy": "confidential", "audit": true }, { "name": "CompletenessChecklist", "meaning": "The deterministic per-warranty-company gate evaluation result for a case", "owner_context": "Authorization Boost Fulfillment", "writers": [ "Authorization Boost Fulfillment" ], "readers": [ "Review & Compliance" ], "source_of_truth": "Authorization Boost Fulfillment DB", "retention": "Life of account + 2 years", "privacy": "internal", "audit": true }, { "name": "Release", "meaning": "The reviewer's signed attestation that a package is complete and its citations are sourced", "owner_context": "Review & Compliance", "writers": [ "Review & Compliance" ], "readers": [ "Authorization Boost Fulfillment", "Compliance & Licensing Governance" ], "source_of_truth": "Review & Compliance DB", "retention": "Life of account + 2 years", "privacy": "confidential", "audit": true }, { "name": "Appeal", "meaning": "The structured supplemental-authorization request filed for an under-authorized, scope-limited, or denied work order", "owner_context": "Appeal & Escalation Desk", "writers": [ "Appeal & Escalation Desk" ], "readers": [ "Authorization Boost Fulfillment", "Analytics & Reporting" ], "source_of_truth": "Appeal & Escalation Desk DB", "retention": "Life of account + 2 years", "privacy": "confidential", "audit": true }, { "name": "AuthorizationOutcome", "meaning": "The warranty company's returned authorized amount and scope for a work order, and the resulting uplift if any", "owner_context": "Appeal & Escalation Desk", "writers": [ "Appeal & Escalation Desk" ], "readers": [ "Billing & Revenue", "Analytics & Reporting" ], "source_of_truth": "Appeal & Escalation Desk DB", "retention": "Life of account + 2 years", "privacy": "confidential", "audit": true }, { "name": "WarrantyCompanyRuleSet", "meaning": "Per-warranty-company completeness-checklist cards, coverage/exclusion language, and cost-benchmark data", "owner_context": "Warranty Company Rule Library & Retrieval", "writers": [ "Warranty Company Rule Library & Retrieval" ], "readers": [ "Evidence Assembly" ], "source_of_truth": "Warranty Company Rule Library & Retrieval DB", "retention": "Current + 3 prior versions", "privacy": "internal", "audit": true }, { "name": "ContractorAccount", "meaning": "Tenant profile, reviewer-of-record registration, and warranty-company portal credential custody", "owner_context": "Client Onboarding & Contractor Profile", "writers": [ "Client Onboarding & Contractor Profile" ], "readers": [ "Authorization Boost Fulfillment", "Identity & Access" ], "source_of_truth": "Client Onboarding & Contractor Profile DB", "retention": "Life of account + 2 years", "privacy": "confidential", "audit": true }, { "name": "OwnerActionLedger", "meaning": "Open contractor-supplied blockers gating the public release-readiness claim", "owner_context": "Compliance & Licensing Governance", "writers": [ "Compliance & Licensing Governance" ], "readers": [ "Authorization Boost Fulfillment" ], "source_of_truth": "Compliance & Licensing Governance DB", "retention": "Life of account + 2 years", "privacy": "internal", "audit": true }, { "name": "AutoSubmitSubscription", "meaning": "Enrollment and volume-tier state for a contractor's recurring Auto-Submit subscription", "owner_context": "Auto-Submit & Recurring Programs", "writers": [ "Auto-Submit & Recurring Programs" ], "readers": [ "Billing & Revenue", "Analytics & Reporting" ], "source_of_truth": "Auto-Submit & Recurring Programs DB", "retention": "Life of account + 2 years", "privacy": "confidential", "audit": true } ], "external_integrations": [ { "system": "Warranty-company contractor portals (American Home Shield, Cinch, Choice Home Warranty, First American, Old Republic, 2-10 HBW, Landmark, and regional providers)", "risk": "Portal-format drift; access-rule changes blocking third-party submitters; rate limits", "internal_model": "portal-submission record", "acl_strategy": "Adapter in External Integrations translates each provider's portal schema -> internal domain term; upstream schema never leaks past the adapter.", "owner_context": "External Integrations", "data_in": [ "Authorization status", "Denial reason" ], "data_out": [ "Evidence package", "Appeal narrative" ], "trigger": "api", "failure_strategy": "Exponential backoff with jitter; circuit breaker on repeated failure; dead-letter with owner-visible alert.", "audit_need": "Every call logged with tenant, request id, cost, and payload hash (no credentials in logs)." }, { "system": "Contractor dispatch / field-service platforms (Housecall Pro, ServiceTitan-class, Jobber-class tools)", "risk": "Schema drift; silent field rename; rate limits", "internal_model": "work-order reference record", "acl_strategy": "Adapter translates external schema -> internal CaseIntake fields; upstream schema never leaks past the adapter.", "owner_context": "External Integrations", "data_in": [ "Work order number", "Contractor account reference" ], "data_out": [ "Case status" ], "trigger": "api", "failure_strategy": "Exponential backoff with jitter; circuit breaker on repeated failure.", "audit_need": "Every call logged with tenant, request id, cost, and payload hash." }, { "system": "OpenAI / Anthropic API", "risk": "Model latency spikes; cost overrun; provider outage", "internal_model": "extraction/drafting run", "acl_strategy": "Provider-agnostic prompt interface; model swap does not change internal domain events.", "owner_context": "Evidence Assembly", "data_in": [ "Prompt payload (PII-scrubbed)" ], "data_out": [ "Structured extraction/drafting output" ], "trigger": "api", "failure_strategy": "Retry once, then EscalationRaised.", "audit_need": "Every call logged with tenant, prompt version, cost, latency." }, { "system": "Stripe", "risk": "Tax jurisdictional errors; webhook delivery failure", "internal_model": "invoice / subscription record", "acl_strategy": "Billing & Revenue adapter translates Stripe events -> internal InvoicePaid/SubscriptionCanceled.", "owner_context": "Billing & Revenue", "data_in": [ "Payment confirmation" ], "data_out": [ "Charge request" ], "trigger": "webhook", "failure_strategy": "Webhook signature verification; replay-safe idempotency keys.", "audit_need": "Every charge logged with case reference and uplift basis." }, { "system": "IdP (Google / Okta)", "risk": "Session hijack; misconfigured SSO", "internal_model": "authenticated session", "acl_strategy": "Standard OIDC adapter; no custom session logic outside the Identity & Access context.", "owner_context": "Identity & Access", "data_in": [ "Auth assertion" ], "data_out": [ "Session token" ], "trigger": "api", "failure_strategy": "Fail closed; force re-authentication.", "audit_need": "Every sign-in logged with actor + IP + timestamp." }, { "system": "Email / SMS intake channel", "risk": "Spoofed sender; malformed attachment", "internal_model": "case-intake evidence submission", "acl_strategy": "Intake adapter validates sender against the contractor's registered contact matrix before creating a CaseIntake.", "owner_context": "External Integrations", "data_in": [ "Forwarded work order + photos + notes" ], "data_out": [ "Intake acknowledgment" ], "trigger": "email/sms webhook", "failure_strategy": "Quarantine unmatched senders for manual review.", "audit_need": "Every inbound message logged with sender + attachment hashes." } ], "adrs": [ { "id": "ADR-001", "decision": "Architecture style", "status": "accepted", "context": "Single team, single regulated-adjacent vertical (home-warranty contractor authorization/appeal) per blueprint, evidence-linked workflow.", "options": [ "Modular monolith", "Microservices", "Serverless workflow", "No-code first" ], "chosen": "Modular monolith with event-driven internals", "business_reason": "Ship a defensible vertical slice with one team; avoid distributed-systems cost until scale forces it.", "technical_reason": "Deterministic transactions across aggregates; simpler ops; one deployable.", "tradeoffs": [ "May feel unsophisticated to enterprise reviewers", "Refactor cost if we later split" ], "risks": [ "Module boundaries erode without discipline" ], "revisit_trigger": "Any single module needs independent scaling or a team boundary." }, { "id": "ADR-002", "decision": "Portal submission strategy", "status": "accepted", "context": "Warranty companies do not publish a stable third-party submission API; submissions happen through each provider's own contractor portal.", "options": [ "Contractor-submitted packages only", "AuthLift submits directly under contractor credentials", "Browser-automation adapter per provider" ], "chosen": "AuthLift submits directly under contractor credentials once trust is established, starting with contractor-submitted packages in the pilot cohort", "business_reason": "Preserves the contractor relationship with the warranty company and avoids third-party-blocking risk in week one.", "technical_reason": "Per-provider adapters isolate portal-format drift behind the External Integrations ACL.", "tradeoffs": [ "Slower time-to-value in week one", "Manual submission step adds reviewer overhead early" ], "risks": [ "A provider changes access rules to block third-party submitters" ], "revisit_trigger": "Any provider formally blocks or explicitly permits third-party submission." }, { "id": "ADR-003", "decision": "Tenant isolation model", "status": "accepted", "context": "Pilot cohort is 5-10 contractors; enterprise contractor-group buyers may later require stricter isolation.", "options": [ "Logical per-tenant isolation with row-level auth", "Single-tenant infrastructure per contractor", "Hybrid (logical default, single-tenant opt-in)" ], "chosen": "Logical per-tenant isolation with row-level auth for the pilot cohort", "business_reason": "Keeps hosting cost low while the pilot validates demand.", "technical_reason": "Row-level auth + per-tenant retrieval indices sufficiently isolate case evidence and portal credentials at pilot scale.", "tradeoffs": [ "May not satisfy a future enterprise single-tenant requirement without rework" ], "risks": [ "A pilot contractor or diligence request demands single-tenant hosting" ], "revisit_trigger": "Any prospect with a hard single-tenant clause." }, { "id": "ADR-004", "decision": "AI orchestration boundary", "status": "accepted", "context": "Extraction, drafting, and QA all touch case evidence that ultimately backs a paid submission to a warranty company.", "options": [ "Single general-purpose agent for the whole pipeline", "Bounded, single-responsibility agents with a human release gate", "No AI -- fully manual claims consulting" ], "chosen": "Bounded, single-responsibility agents (Extraction, Drafting, Denial-Pattern QA) with a mandatory reviewer release gate", "business_reason": "Keeps the human chokepoint enforceable and the cost structure economical at $25 + 28% pricing.", "technical_reason": "Narrow agent responsibilities make forbidden-action enforcement and evaluation tractable.", "tradeoffs": [ "More orchestration code than a single agent" ], "risks": [ "Agent boundary erosion over time without discipline" ], "revisit_trigger": "Any agent responsibility grows past its stated scope." }, { "id": "ADR-005", "decision": "Pricing and billing trigger", "status": "accepted", "context": "Outcome-based pricing ($25 flat intake + 28% contingency on uplift) must never charge a contingency fee without a confirmed uplift.", "options": [ "Charge on submission", "Charge on authorization receipt", "Charge only on UpliftConfirmed for the contingency line; charge the intake fee on CaseIntakeReceived" ], "chosen": "Charge only on UpliftConfirmed for the contingency line; charge the intake fee on CaseIntakeReceived", "business_reason": "Matches the brief's no-recovery-no-fee guarantee exactly.", "technical_reason": "Billing & Revenue never computes uplift itself; it only consumes the UpliftConfirmed event.", "tradeoffs": [ "Revenue recognition lags case resolution" ], "risks": [ "Uplift miscalculated against the wrong first offer" ], "revisit_trigger": "Any dispute over the uplift basis for a contingency charge." }, { "id": "ADR-006", "decision": "Appeal consent mechanism", "status": "accepted", "context": "An appeal is filed in the contractor's name and must never be filed without their explicit confirmation.", "options": [ "Implied consent on engagement signup", "Explicit per-appeal consent capture", "Reviewer-only sign-off, no contractor step" ], "chosen": "Explicit per-appeal consent capture tied to the specific appeal-language version", "business_reason": "Preserves contractor trust and the human-chokepoint discipline stated in the brief.", "technical_reason": "ConfirmContractorConsent is a required precondition on the FileAppeal command.", "tradeoffs": [ "Adds a step to the appeal cycle time" ], "risks": [ "Consent captured on a stale version of the appeal language" ], "revisit_trigger": "Any appeal-language edit after consent is captured." }, { "id": "ADR-007", "decision": "Data retention for case evidence", "status": "accepted", "context": "Case evidence can become the basis of a payment dispute well after resolution.", "options": [ "Delete on case close", "Retain for life of account only", "Retain for life of account + 2 years" ], "chosen": "Retain for life of account + 2 years, dated and versioned per case", "business_reason": "Balances dispute-defense value against storage cost and privacy minimization.", "technical_reason": "Retention policy enforced at the data-object level with a scheduled purge job.", "tradeoffs": [ "Storage cost grows with case volume" ], "risks": [ "Retention window insufficient for a delayed dispute" ], "revisit_trigger": "Any contractor or warranty-company dispute surfacing after the retention window." }, { "id": "ADR-008", "decision": "Deployment topology", "status": "accepted", "context": "Pilot cohort of 5-10 contractors with seasonal HVAC demand spikes; no stated multi-region requirement.", "options": [ "Single region + multi-AZ", "Multi-region active-active", "Single region, single-AZ" ], "chosen": "Single production region + multi-AZ managed database", "business_reason": "Boring, low-ops-burden topology appropriate for pilot scale.", "technical_reason": "Multi-AZ absorbs an availability-zone failure without the complexity of multi-region.", "tradeoffs": [ "A full-region outage takes production down" ], "risks": [ "Regional outage during a rush-case cycle" ], "revisit_trigger": "Sustained multi-region demand or an enterprise DR requirement." } ], "critical_path": [ "CaseIntakeReceived -> EvidenceIngested -> EvidencePackageDrafted -> CompletenessCheckPassed -> ReviewerApproved -> PackageSubmitted -> AuthorizationReceived -> CaseResolved" ], "data_duplication_notes": [ "Trade-Qualified Reviewer of record is stored in Client Onboarding, referenced by Review & Compliance -- Review & Compliance does not own it", "OwnerActionLedger duplicates minimal facts into read models for Authorization Boost Fulfillment consumption" ], "escalation_flows": [ "AI extraction/drafting layer escalates to Trade-Qualified Reviewer", "Trade-Qualified Reviewer escalates a contested cost-benchmark line or a licensing-boundary question to Legal reviewer", "Success lead escalates a silent submission failure to Business owner / founder", "Business owner escalates a warranty-company channel inquiry to external counsel" ], "escalation_matrix": [ "AI extraction/drafting layer -> Trade-Qualified Reviewer -> Legal reviewer -> Business owner -> External counsel", "Success lead -> Business owner -> External counsel (warranty-company channel inquiries)" ], "exception_flows": [ "EvidencePackageDrafted with a contested cost-benchmark line or unmatched completeness checklist -> EscalationRaised -> Trade-Qualified Reviewer resolves -> ReviewerApproved", "SubmitToPortal blocked by an open owner action -> DeliveryBlocked -> contractor resolves -> retry", "SubmissionFailed at the adapter -> contractor alert within 1h -> Success ticket -> retry with backoff", "AuthorizationReceived flags an under-authorization with no contractor response -> case held pending consent -> reminder cadence -> resolved at original authorization if consent never granted" ], "manual_override_flows": [ "Trade-Qualified Reviewer may override an AI-classified completeness gap and re-route to Legal reviewer", "Business owner may force-block a submission via the Compliance & Licensing Governance ledger", "Ops may pull a prompt version at any time (feature flag)" ], "manual_override_rules": [ "Any manual override captured as an explicit override event with actor + reason", "No override may bypass the reviewer-release or contractor-consent invariants" ], "prompt_chain_map": [ "Intake -> Extraction Agent (extract + cite evidence package) -> OutputValidator -> Drafting Agent (cost benchmark + appeal narrative) -> Denial-Pattern QA Agent -> Trade-Qualified Reviewer (release or escalate)", "Retraction analysis -> manual review only (no AI agent in the retraction path) -> Legal reviewer + Trade-Qualified Reviewer co-sign" ], "prompt_versioning": "Prompt versions immutable once published; rolled out via feature flag; every rollout paired with an acceptance-rate spot check against a golden dataset of past released packages.", "rag_map": [ "Per-tenant evidence index -> retrieval router -> tenant-scoped hits -> Extraction Agent", "Warranty-company completeness-checklist + cost-benchmark library (per provider, read-only cache) -> shared retrieval -> Extraction Agent and Drafting Agent (cited)" ], "read_models": [ "Contractor dashboard read model (per tenant): open cases, in-extraction, in-review, submitted this month", "Reviewer queue read model: evidence packages awaiting release with confidence + escalation reason", "Compliance ledger read model: open owner actions + release-decision", "Case-history scorecard read model: authorization outcomes across all of a contractor's warranty-company relationships", "Analytics rollup read model: metric definitions rolled up daily" ], "reporting_models": [ "Outcome report per contractor: cases submitted, cycle time, escalation rate, average uplift secured", "Ops report: AI cost per case, escalation rate, reviewer load" ], "retry_flows": [ "External API failure -> exponential backoff with jitter, then dead-letter with owner-visible alert", "Model timeout -> retry once, then EscalationRaised", "Submission adapter failure -> retry with backoff, then contractor alert" ], "separation_of_duties": [ "Extraction Agent cannot release a package; Trade-Qualified Reviewer cannot attest to a diagnosis without the contractor's licensed tradesperson's input; Legal reviewer cannot silently retract a package" ], "ai_audit_plan": [ "Every ExtractionRun logged with prompt version, retrieval hit ids, cost, latency, validator verdict", "13-month rolling retention on run logs", "PII and portal credentials scrubbed from log payloads" ], "ai_evaluation": [ "Golden dataset of past reviewer-released Authorization Boost Packages per warranty company", "Regression thresholds on release-acceptance rate + citation coverage", "Every prompt release requires a passing acceptance-rate spot check before rollout" ], "final_recommendations": [ "Ship a modular-monolith, evidence-linked, release-gated vertical slice for the Authorization Boost Package MVP. Preserve the invariant that no package leaves the system without a signed human release from a trade-qualified reviewer, and no appeal is filed without captured contractor consent. Do not launch commercially until owner-action facts close and at least one reviewer-released case has been delivered and paid.", "Do NOT default to microservices. Extract a module only when a specific pressure demands it.", "Do NOT allow AI to attest to a diagnosis, code citation, or recommended repair scope -- that responsibility stays with the contractor's own licensed tradesperson.", "Do NOT launch consumer-facing (policyholder-representation) scope until the 50-state licensing-boundary review is complete." ], "hallucination_controls": [ "Retrieval-first (no free-form generation of readings, dates, or diagnoses without citation)", "Structured-output validator enforces citation-per-claim", "Confidence-scored escalation to Trade-Qualified Reviewer", "Reviewer release gate on every outbound Authorization Boost Package" ], "human_in_the_loop_plan": [ "Trade-Qualified Reviewer release on every Authorization Boost Package before submission", "Contractor consent captured before any appeal is filed in their name", "Legal + Trade-Qualified Reviewer co-sign on retractions", "Business owner approval on public release-readiness claims for the microsite", "Ops sign-off on prompt-version rollout" ], "human_review_checkpoints": [ "AI evidence-package draft -> Trade-Qualified Reviewer approval", "Under-authorization detected -> contractor consent before appeal filing", "Public release-readiness claim -> business owner acceptance", "Retraction -> legal + reviewer co-sign", "Prompt rollout -> ops + acceptance-rate spot check" ], "data_quality_risks": [ "Silent schema drift from warranty-company portal or dispatch-software integrations", "Stale warranty-company rule set after a portal-format change", "Missing appeal cross-links after a manual pilot-era case import" ], "data_retention": [ "Cases + evidence packages + releases + appeals: life of account + 2 years", "ExtractionRun logs: 13 months rolling", "Users + sessions: life of account + 2 years" ], "quality_control_workflow": [ "Weekly reviewer calibration meeting", "Monthly acceptance-rate regression report", "Quarterly retraction-rate review with business owner + legal" ], "architecture": { "style": "modular-monolith-event-driven", "why": "Single team + single vertical (home-warranty contractor authorization/appeal) per blueprint + strong consistency requirements around release / submission / release-decision favor a monolith. Event-driven internals give an audit-friendly append-only log without the operational cost of microservices.", "rejected_alternatives": [ "Microservices -- no independent scaling or team boundary justifies distributed cost yet.", "Serverless-workflow-only -- reviewer release and audit invariants are easier to keep correct in a monolith.", "No-code / low-code -- cannot enforce OutputValidator, prompt versioning, or per-tenant retrieval isolation with fidelity." ], "backend_modules": [ "Authorization Boost Fulfillment", "Evidence Assembly", "Review & Compliance", "Compliance & Licensing Governance", "Warranty Company Rule Library & Retrieval", "Case Intake & Qualification", "Client Onboarding & Contractor Profile", "Client Success & Retention", "Appeal & Escalation Desk", "Auto-Submit & Recurring Programs", "Analytics & Reporting" ], "frontend_modules": [ "Contractor dashboard", "Reviewer console", "Legal escalation console", "Contractor status portal", "Business owner console", "Ops (prompt + rule library) console" ], "api_boundaries": [ "/intake/*", "/cases/*", "/reviewer/*", "/compliance/*", "/knowledge/*", "/appeals/*", "/auto-submit/*", "/admin/*" ], "database_strategy": "One managed Postgres; schema-per-context; cross-context reads via published projections; RLS on protected tables.", "event_bus": "In-process event dispatcher backed by an outbox table (transactional publish); upgrade path to a real broker if throughput demands.", "queue": "Background job queue (managed) for extraction runs, submission adapters, and reindex jobs.", "workflow_engine": "None initially -- orchestrate via domain events + policies; add a workflow engine if orchestrations exceed 5 sequential steps.", "ai_orchestration": "Evidence Assembly context owns bounded agents; OutputValidator + prompt registry + tenant-scoped retrieval; retries with backoff.", "rag_layer": "Per-tenant partitioned evidence indices plus a shared warranty-company completeness-checklist and cost-benchmark index in a managed vector DB; ingestion pipeline in the Warranty Company Rule Library & Retrieval context.", "file_storage": "Managed blob storage with per-tenant prefixes + signed URLs; photos and readings hashed on write.", "authn_authz": "IdP (Google / Okta) for authn; RBAC via a dedicated roles table with server-side checks + RLS.", "admin_dashboard": "Ops-facing admin for tenants, users, feature flags, prompt versions, and the warranty-company rule library.", "client_portal": "Contractor-facing portal: submit intake, see completeness-checklist status, receive submitted packages and appeal outcomes.", "operator_dashboard": "Internal: intake queue, reviewer queue, escalation queue, submission health, appeal-case queue.", "observability": "Structured logs, RED metrics per workflow, model-call spans, and a weekly SLO review; see architecture.observability for details.", "deployment": "Single production region + multi-AZ managed database; preview environments per PR.", "audit_logging": "Append-only audit log for all case state transitions; hash-chained snapshots on submitted and released packages." }, "security_governance": { "controls": [ { "risk": "Prompt injection via forwarded photo/notes content", "context": "Evidence Assembly", "impact": "high", "control": "Input scrubber + OutputValidator + tenant-scoped retrieval", "audit": "ExtractionRun trace" }, { "risk": "Cross-tenant retrieval leak", "context": "Warranty Company Rule Library & Retrieval", "impact": "severe", "control": "Per-tenant index partitions + TenantIsolationSpec enforced at router", "audit": "Retrieval call log" }, { "risk": "Release-signature spoofing", "context": "Review & Compliance", "impact": "severe", "control": "Release bound to authenticated session; server-side validation", "audit": "Release manifest" }, { "risk": "Premature public claim of submission-readiness or guaranteed authorization", "context": "Compliance & Licensing Governance", "impact": "high", "control": "ReleaseReadinessSpec on OwnerActionLedger", "audit": "Release-decision log" }, { "risk": "Privilege escalation", "context": "Identity & Access", "impact": "high", "control": "Roles in dedicated table + server-side checks + RLS", "audit": "Role assignment log" }, { "risk": "Silent submission failure ahead of an appeal-window deadline", "context": "Client Success & Retention", "impact": "medium", "control": "Adapter receipt required; alert contractor within 1h on failure", "audit": "Submission receipt archive" } ], "ai_governance": [ "Every prompt version has a named owner + acceptance-rate spot check + rollout flag", "AI outputs marked as drafts until reviewer release", "Model + prompt inventory maintained in the Ops console" ], "prompt_injection_defense": [ "Strip / neutralize instruction-like patterns in contractor and warranty-company inputs before prompt assembly", "Never concatenate raw contractor/warranty-company input into a system prompt", "OutputValidator rejects outputs that reference forbidden actions" ], "sensitive_data_handling": [ "Portal credentials and PII scrubbed from logs", "Regulated data classes never sent to external model providers unless a DPA covers it", "Per-tenant blob storage prefixes + signed URLs" ], "access_control_matrix": [ { "role": "Contractor Owner/Operator", "context": "Authorization Boost Fulfillment", "capabilities": [ "OpenCaseIntake", "IngestEvidence", "View own cases", "ConfirmContractorConsent" ] }, { "role": "Trade-Qualified Reviewer", "context": "Review & Compliance", "capabilities": [ "ReleasePackage", "RejectPackage", "FileAppeal" ] }, { "role": "Legal Reviewer", "context": "Compliance & Licensing Governance", "capabilities": [ "RetractPackage (co-sign)", "ProcessDSAR" ] }, { "role": "Ops (rule-library / prompt owner)", "context": "Warranty Company Rule Library & Retrieval", "capabilities": [ "IngestRuleUpdate", "Reindex", "PublishPromptVersion" ] }, { "role": "Platform admin", "context": "Identity & Access", "capabilities": [ "AssignRole", "Provision users", "Rotate secrets" ] } ], "audit_log_requirements": [ "Every command logged with tenant, actor, payload hash, timestamp", "Every release and retraction logged with server-side session identity", "Every model call logged with prompt version, cost, latency, validator verdict" ] }, "observability": { "metrics": [ { "metric": "Submitted Authorization Boost Packages / week / tenant", "type": "business", "context": "Authorization Boost Fulfillment", "why": "North star: repeatable value delivery", "target": ">= contracted cadence", "alert_threshold": "< 80% of contracted cadence" }, { "metric": "Authorization-Audit-to-paid conversion", "type": "business", "context": "Case Intake & Qualification", "why": "Validates the Authorization Audit lead magnet", "target": ">= 25%", "alert_threshold": "< 15% monthly" }, { "metric": "AI evidence-package draft acceptance rate", "type": "ai-quality", "context": "Evidence Assembly", "why": "Signals grounding + prompt fit", "target": ">= 70% by Phase 2", "alert_threshold": "< 50% weekly" }, { "metric": "Escalation-to-reviewer rate", "type": "ai-quality", "context": "Evidence Assembly", "why": "Guardrails firing correctly, not over- or under-escalating", "target": "<= 20% of cases", "alert_threshold": "> 35% weekly" }, { "metric": "Cycle time to release (p50 + p95)", "type": "operational", "context": "Review & Compliance", "why": "Reviewer throughput vs the 4-business-hour MVP / same-business-day standard", "target": "p95 <= 4 business hours MVP, <= 1 business day standard", "alert_threshold": "> 1 business day" }, { "metric": "Appeal win rate within 30 days", "type": "business", "context": "Appeal & Escalation Desk", "why": "Uplift value delivered", "target": ">= 40% when an appeal is filed", "alert_threshold": "< 20% monthly" }, { "metric": "Submission failure rate", "type": "reliability", "context": "Client Success & Retention", "why": "Contractor-facing reliability ahead of appeal-window deadlines", "target": "< 0.5%", "alert_threshold": "> 1% daily" }, { "metric": "Owner-action open count", "type": "business", "context": "Compliance & Licensing Governance", "why": "Release-readiness for public claims", "target": "0 for launched blueprints", "alert_threshold": "any blocker aging > 30 days" }, { "metric": "Model cost per case", "type": "financial", "context": "Evidence Assembly", "why": "Margin control against the >=55% gross-margin target", "target": "<= target per pricing tier", "alert_threshold": "> 20% over target weekly" } ], "dashboards": [ "Reviewer queue health", "Contractor pipeline (audit -> paid -> second case -> Auto-Submit)", "Warranty-company rule-library freshness", "Model cost + latency" ], "audit_reports": [ "Weekly release + retraction report", "Monthly acceptance-rate regression report" ], "business_events": [ "CaseIntakeReceived", "ReviewerApproved", "PackageSubmitted", "AppealFiled", "UpliftConfirmed", "CaseResolved" ], "ai_evaluation_reports": [ "Monthly Extraction/Drafting Agent acceptance-rate report against the golden dataset" ], "client_outcome_reports": [ "Per-contractor outcome report: cases submitted, cycle time, escalation rate, average uplift secured" ], "quality_review_reports": [ "Quarterly retraction-rate review with business owner + legal" ] }, "testing_strategy": { "tests": [ { "type": "Domain unit", "validates": "Aggregate invariants", "context": "all core contexts", "example": "CaseAggregate rejects submission without a release" }, { "type": "Aggregate invariant", "validates": "Consistency boundaries", "context": "Authorization Boost Fulfillment / Review & Compliance", "example": "Released package is immutable" }, { "type": "Policy", "validates": "Reactive rules", "context": "Evidence Assembly", "example": "Escalates below confidence threshold or on unmatched completeness checklist" }, { "type": "Specification", "validates": "Reusable rules", "context": "Compliance & Licensing Governance", "example": "ReleaseReadinessSpec blocks 'ready' with open owner actions" }, { "type": "Application use-case", "validates": "End-to-end command flow", "context": "Fulfillment + Review & Compliance", "example": "Submit a released Authorization Boost Package happy path" }, { "type": "Integration", "validates": "Adapter behavior", "context": "External Integrations", "example": "Warranty-company portal adapter translates correctly" }, { "type": "Contract", "validates": "Published-language event schemas", "context": "cross-context", "example": "EvidencePackageDrafted payload matches consumer expectations" }, { "type": "AI prompt eval", "validates": "Prompt quality vs golden dataset", "context": "Evidence Assembly", "example": "Extraction Agent accepts >= 40% in shadow mode" }, { "type": "RAG retrieval", "validates": "Tenant isolation + warranty-company coverage", "context": "Warranty Company Rule Library & Retrieval", "example": "Cross-tenant lookup returns zero rows" }, { "type": "Golden dataset", "validates": "AI regression", "context": "Evidence Assembly", "example": "No regression on past released packages" }, { "type": "Human review simulation", "validates": "Escalation UX", "context": "Review & Compliance", "example": "Reviewer can complete a release in <= 5 clicks" }, { "type": "End-to-end", "validates": "Critical path", "context": "all", "example": "Intake -> release -> submission in staging" }, { "type": "Security", "validates": "Auth + RLS + injection defense", "context": "Identity & Access + Evidence Assembly", "example": "Cross-tenant credential access attempt returns 403" } ], "ai_eval_dataset": [ "[PLACEHOLDER] owner to complete" ], "contract_testing_plan": "SemVer on every published-language event schema; consumer contract tests run in CI before merge.", "critical_domain_rules": [ "No submission without a valid Release", "No appeal without contractor consent", "No contingency charge without UpliftConfirmed" ], "manual_qa_checklist": [ "Reviewer release UX walkthrough", "Completeness-checklist accuracy spot check per warranty company", "Retraction-flow dry run" ], "regression_plan": "Golden-dataset regression run on every prompt-version rollout; block rollout on acceptance-rate drop." }, "module_structure": { "tree": "/src\n /contexts\n /case-intake-qualification\n /domain\n /application\n /infrastructure\n /interfaces\n /client-onboarding-contractor-profile\n /domain\n /application\n /infrastructure\n /interfaces\n /authorization-boost-fulfillment\n /domain\n /application\n /infrastructure\n /interfaces\n /evidence-assembly\n /domain\n /application\n /infrastructure\n /interfaces\n /review-compliance\n /domain\n /application\n /infrastructure\n /interfaces\n /warranty-company-rule-library\n /domain\n /application\n /infrastructure\n /interfaces\n /compliance-licensing-governance\n /domain\n /application\n /infrastructure\n /interfaces\n /appeal-escalation-desk\n /domain\n /application\n /infrastructure\n /interfaces\n /auto-submit-recurring-programs\n /domain\n /application\n /infrastructure\n /interfaces\n /client-success-retention\n /domain\n /application\n /infrastructure\n /interfaces\n /analytics\n /domain\n /application\n /infrastructure\n /interfaces\n /shared\n /kernel # tiny -- Ids, Money, Tenant, Actor\n /events # published-language event contracts\n /auth # session + role primitives\n /observability # logging, metrics, tracing\n /config", "modules": [ { "name": "authorization-boost-fulfillment", "purpose": "CaseIntake -> EvidencePackage -> Authorization Boost Package lifecycle", "owned_domain": [ "CaseIntake", "EvidencePackage", "Authorization Boost Package", "Submission" ], "application_services": [ "OpenCaseIntake", "IngestEvidence", "RunCompletenessChecklist", "SubmitToPortal" ], "infra_adapters": [ "Submission adapter", "Outbox publisher" ], "public_interfaces": [ "/intake/*", "/cases/*" ], "forbidden_deps": [ "billing infra", "identity provider internals" ] }, { "name": "evidence-assembly", "purpose": "Bounded AI extraction + drafting agents", "owned_domain": [ "ExtractionRun", "PromptVersion" ], "application_services": [ "StartExtractionRun", "PublishPromptVersion" ], "infra_adapters": [ "OpenAI/Anthropic client", "Retrieval router" ], "public_interfaces": [ "/knowledge/extract" ], "forbidden_deps": [ "billing infra", "direct DB access to other modules" ] }, { "name": "review-compliance", "purpose": "Reviewer release, retraction, audit-log snapshots", "owned_domain": [ "Release", "PackageRetraction", "ReviewerSession" ], "application_services": [ "ReleasePackage", "RejectPackage", "RetractPackage" ], "infra_adapters": [ "Session validator" ], "public_interfaces": [ "/reviewer/*" ], "forbidden_deps": [ "billing infra" ] }, { "name": "appeal-escalation-desk", "purpose": "Appeal drafting, consent capture, filing", "owned_domain": [ "Appeal", "AppealNarrative" ], "application_services": [ "DraftAppeal", "ConfirmContractorConsent", "FileAppeal" ], "infra_adapters": [ "Warranty-company portal adapter" ], "public_interfaces": [ "/appeals/*" ], "forbidden_deps": [ "billing infra" ] }, { "name": "compliance-licensing-governance", "purpose": "Owner-action ledger, release-decision policy", "owned_domain": [ "OwnerAction", "ReleaseDecision" ], "application_services": [ "ResolveOwnerAction", "RecomputeReleaseDecision" ], "infra_adapters": [ "Email inbox adapter" ], "public_interfaces": [ "/compliance/*" ], "forbidden_deps": [ "direct DB access to other modules" ] } ], "dependency_rules": [ "Contexts depend only on published events/interfaces of other contexts, never on internal tables.", "The shared kernel stays tiny (Ids, Money, Tenant, Actor); no domain concept may live there.", "Evidence Assembly may not call Billing & Revenue directly." ] }, "self_audit": { "scores": [ { "category": "Domain accuracy", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilot cases land real data." }, { "category": "Ubiquitous language quality", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilot cases land real data." }, { "category": "Subdomain classification quality", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilot cases land real data." }, { "category": "Bounded context clarity", "score": 9, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilot cases land real data." }, { "category": "Core domain focus", "score": 9, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilot cases land real data." }, { "category": "Context map quality", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilot cases land real data." }, { "category": "Aggregate design quality", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilot cases land real data." }, { "category": "Invariant quality", "score": 9, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilot cases land real data." }, { "category": "AI-agent responsibility design", "score": 9, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilot cases land real data." }, { "category": "Human review safety", "score": 9, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilot cases land real data." }, { "category": "Data ownership clarity", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilot cases land real data." }, { "category": "Integration protection", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilot cases land real data." } ], "weakest_parts": [ "Licensing-boundary posture is Inferred, not confirmed state-by-state, pending the 50-state legal review.", "Portal-submission strategy depends on warranty companies tolerating contractor-consented third-party submission." ], "biggest_assumptions": [ "A trade-qualified reviewer can be sourced and retained for launch.", "Warranty companies will not uniformly block third-party portal submission." ], "highest_risk_decisions": [ "Filing an appeal on the contractor's behalf without triggering public-adjuster licensing exposure.", "Charging a contingency fee tied to a warranty company's payment decision." ], "needs_domain_expert": [ "Per-warranty-company denial-pattern accuracy review by a trade-licensed reviewer." ], "needs_legal": [ "50-state public-adjuster and insurance-adjuster licensing-boundary review before any consumer-facing expansion." ], "needs_prototype": [ "Warranty-company portal adapter reliability across at least 3 providers." ], "validate_before_prod": [ "Reviewer release cycle time under real case load.", "Completeness-checklist accuracy against at least 20 real warranty-company submissions." ] }, "mvp_roadmap": [ { "phase": "Phase 0 -- Manual workflow with instrumented capture", "goal": "Deliver one Authorization Boost Package end-to-end manually, capture every step as a domain event.", "features": [ "Manual intake form", "Evidence upload", "Human-drafted evidence package", "Reviewer release via signed form" ], "contexts": [ "Case Intake & Qualification", "Authorization Boost Fulfillment", "Review & Compliance" ], "ai_needs": [ "[PLACEHOLDER] owner to complete" ], "human_workflows": [ "Reviewer release" ], "data_needs": [ "CaseIntake", "EvidencePackage", "Authorization Boost Package" ], "integrations": [ "Email" ], "risks": [ "Un-audited manual step" ], "exit_criteria": [ "1 real Authorization Boost Package delivered + reviewer-released" ] }, { "phase": "Phase 1 -- AI-assisted extraction with human release", "goal": "Introduce the Extraction Agent for evidence extraction while keeping the reviewer as the mandatory release gate.", "features": [ "AI evidence extraction", "Completeness checklist automation", "Reviewer console" ], "contexts": [ "Evidence Assembly", "Authorization Boost Fulfillment", "Review & Compliance" ], "ai_needs": [ "Extraction Agent", "OutputValidator" ], "human_workflows": [ "Reviewer release", "Escalation resolution" ], "data_needs": [ "ExtractionRun", "CompletenessChecklist" ], "integrations": [ "OpenAI / Anthropic API" ], "risks": [ "Low AI draft acceptance on non-standard photo formats" ], "exit_criteria": [ "p95 workflow latency published", "Draft acceptance rate baseline captured" ] }, { "phase": "Phase 2 -- Pilot cohort with appeal desk", "goal": "Run the 5-10 contractor pilot cohort, capped at 20 total cases, including the appeal workflow.", "features": [ "Appeal drafting + consent capture", "Cost-benchmark library", "Denial-pattern QA" ], "contexts": [ "Appeal & Escalation Desk", "Warranty Company Rule Library & Retrieval" ], "ai_needs": [ "Drafting Agent", "Denial-Pattern QA Agent" ], "human_workflows": [ "Contractor consent", "Appeal filing" ], "data_needs": [ "Appeal", "AuthorizationOutcome", "WarrantyCompanyRuleSet" ], "integrations": [ "Warranty-company contractor portals (pilot providers)" ], "risks": [ "Reviewer shortage during a seasonal demand spike" ], "exit_criteria": [ ">=5 contractors converted to a second paid case", "Authorization-Audit-to-paid conversion signal captured" ] }, { "phase": "Phase 3 -- Commercial launch with Auto-Submit", "goal": "Public commercial launch and the Auto-Submit recurring subscription.", "features": [ "Auto-Submit enrollment", "Contractor status portal", "Analytics dashboards" ], "contexts": [ "Auto-Submit & Recurring Programs", "Client Success & Retention", "Analytics & Reporting" ], "ai_needs": [ "Success Copilot (assist only)" ], "human_workflows": [ "Auto-Submit tier confirmation" ], "data_needs": [ "AutoSubmitSubscription" ], "integrations": [ "Stripe" ], "risks": [ "Auto-Submit scope-creeping into unpaid custom work" ], "exit_criteria": [ "Zero blocking owner actions for launched blueprint", "Publicly indexable microsite with WebPage+FAQPage schema only" ] } ], "risk_register": [ { "risk": "A warranty company changes portal access rules to block third-party submitters", "likelihood": "medium", "impact": "high", "signal": "See ProductBlueprintDNA / risk register for tuned early-warning signals", "mitigation": "Always submit under the contractor's own credentials/consent; maintain relationships across multiple providers so no single policy change is fatal", "owner": "ops", "context": "Warranty Company Rule Library & Retrieval" }, { "risk": "AI misextracts diagnostic data, leading to an inaccurate evidence package", "likelihood": "medium", "impact": "high", "signal": "See ProductBlueprintDNA / risk register for tuned early-warning signals", "mitigation": "Mandatory trade-qualified reviewer review before every submission; red-team accuracy checks", "owner": "engineering", "context": "Evidence Assembly" }, { "risk": "Public-adjuster licensing exposure if scope creeps to consumer-side representation", "likelihood": "low", "impact": "severe", "signal": "See ProductBlueprintDNA / risk register for tuned early-warning signals", "mitigation": "Strict B2B-only scope at launch; explicit disclaimers; 50-state legal review before any consumer-facing expansion", "owner": "legal", "context": "Compliance & Licensing Governance" }, { "risk": "Contractor distrust of a third party submitting on their behalf to a partner they depend on", "likelihood": "medium", "impact": "medium", "signal": "See ProductBlueprintDNA / risk register for tuned early-warning signals", "mitigation": "Contractor reviews and confirms every package before submission in early cohorts; transparent case tracking", "owner": "ops", "context": "Client Success & Retention" }, { "risk": "Reviewer shortage during a seasonal HVAC demand spike (early demand trap)", "likelihood": "high", "impact": "high", "signal": "See ProductBlueprintDNA / risk register for tuned early-warning signals", "mitigation": "Hard pilot cap at 20 cases in month one; build-before-scale gates; SOC 2 Type I year one", "owner": "ops", "context": "Review & Compliance" }, { "risk": "Single-region outage takes production down during a rush-case cycle", "likelihood": "low", "impact": "high", "signal": "See ProductBlueprintDNA / risk register for tuned early-warning signals", "mitigation": "Multi-AZ managed database; nightly cross-region backup", "owner": "engineering", "context": "Authorization Boost Fulfillment" } ], "scaling_roadmap": [ { "stage": "<= 10 tenants", "trigger": "Pilot cohort (20-case cap)", "architecture_change": "Single-region modular monolith + managed DB", "operational_change": "Founder-led ops; weekly working session", "risk": "Single-reviewer queue" }, { "stage": "10-50 tenants", "trigger": "Phase 2/3 commercial launch", "architecture_change": "Add a second reviewer seat; harden the per-warranty-company rule library", "operational_change": "Dedicated Ops role for prompt/rule-library maintenance", "risk": "Rule-library drift across more providers" }, { "stage": "50-200 tenants", "trigger": "Auto-Submit attach rate exceeds 60% of active contractors", "architecture_change": "Extract Evidence Assembly into an independently scaled worker pool", "operational_change": "Add a second reviewer shift to cover extended SLA hours", "risk": "Extraction throughput becomes the bottleneck" }, { "stage": "200+ tenants", "trigger": "Multi-state consumer-facing expansion approved by legal", "architecture_change": "Evaluate multi-region deployment; consider a real event broker", "operational_change": "Dedicated compliance function beyond the founder/legal-reviewer pair", "risk": "Licensing-boundary complexity across expanded scope" } ], "extensions": { "service_business_reality_check": { "is_service_business": true, "paid_outcome_clear": true, "workflow_present": true, "ai_native_fit_score": 8, "red_flags": [ "[PLACEHOLDER] owner to complete" ] }, "ai_native_fit": { "score": 8, "why": "Evidence-linked extraction + confidence-scored escalation is only economical with bounded AI orchestration. Pure-manual claims consulting is uneconomic at $25 + 28% pricing; a pure-automated portal-filling tool is undefensible without a human release gate.", "disqualifiers": [ "Liability-adjacent vertical: cannot ship without a named trade-qualified reviewer release" ] }, "domain_evidence_register": [ { "claim": "AuthLift's paid outcome is a reviewer-released Authorization Boost Package", "evidence_type": "primary", "source": "Business Understanding + subdomain 'Authorization Boost Fulfillment'", "strength": "strong", "gaps": "Confirm with 3 pilot-contractor interviews" }, { "claim": "Reviewer release is commercially required for submission defensibility", "evidence_type": "primary", "source": "BRIEF.md §6 human chokepoints", "strength": "strong", "gaps": "Vertical-specific attestation-standard citation" }, { "claim": "AI extraction materially reduces cycle time vs. pure-manual claims review", "evidence_type": "assumed", "source": "Category benchmark (adjacent recovery-desk businesses)", "strength": "medium", "gaps": "Measure on internal golden dataset" }, { "claim": "Contractor will supply structured intake (photos, readings, notes) within the 4-business-hour MVP SLA", "evidence_type": "assumed", "source": "Prospect conversations (unverified)", "strength": "weak", "gaps": "Run 5 intake dry-runs with pilot contractors" }, { "claim": "Per-tenant retrieval isolation prevents cross-tenant leakage of case evidence or portal credentials", "evidence_type": "primary", "source": "Architecture (Warranty Company Rule Library & Retrieval context)", "strength": "strong", "gaps": "Add automated cross-tenant lookup test" }, { "claim": "Owner-action ledger blocks a premature release-readiness claim", "evidence_type": "primary", "source": "Compliance & Licensing Governance context invariants", "strength": "strong", "gaps": "None" }, { "claim": "Model + prompt versioning enables reproducible evidence-package outputs", "evidence_type": "primary", "source": "Evidence Assembly context", "strength": "strong", "gaps": "Acceptance-rate regression thresholds not yet baselined" }, { "claim": "28% contingency-on-uplift supports the pricing hypothesis", "evidence_type": "assumed", "source": "Pricing hypothesis anchored to adjacent recovery-desk pricing (not home-warranty-specific)", "strength": "medium", "gaps": "Test with 5 pricing conversations" } ], "assumption_register": [ { "assumption": "Independent HVAC contractors will pay a $25 flat intake fee plus 28% contingency on secured uplift over continuing to eat under-authorizations.", "impact_if_wrong": "high", "how_to_validate": "Pilot-contractor interview + measurement", "blocking": true }, { "assumption": "A standard Authorization Boost Package can be assembled from contractor-supplied evidence within the 4-business-hour MVP cycle.", "impact_if_wrong": "high", "how_to_validate": "Pilot-contractor interview + measurement", "blocking": true }, { "assumption": "The vertical tolerates AI-assisted extraction and drafting when trade-qualified-reviewer review is explicit and audit-traceable.", "impact_if_wrong": "high", "how_to_validate": "Pilot-contractor interview + measurement", "blocking": false }, { "assumption": "Logical per-tenant isolation with row-level auth is acceptable for the first cohort -- single-tenant infrastructure is not required.", "impact_if_wrong": "medium", "how_to_validate": "Instrument metric + review after Phase 1", "blocking": false }, { "assumption": "Warranty companies will not uniformly block third-party portal submission during the pilot.", "impact_if_wrong": "high", "how_to_validate": "Instrument metric + review after Phase 1", "blocking": false }, { "assumption": "A trade-qualified reviewer (or certified claims specialist) can be sourced and retained for this vertical.", "impact_if_wrong": "severe", "how_to_validate": "Recruit + confirm engagement before commercial launch", "blocking": true }, { "assumption": "The B2B contractor-vendor-representation framing keeps AuthLift outside public-adjuster licensing regimes at MVP scope.", "impact_if_wrong": "severe", "how_to_validate": "Complete the 50-state legal review before any consumer-facing expansion", "blocking": true } ], "language_conflict_map": [ { "term": "Engagement", "meaning_a": "A signed billing contract", "context_a": "Billing & Revenue", "meaning_b": "An accepted unit of intake work", "context_b": "Case Intake & Qualification", "resolution": "Billing owns 'Subscription'; Case Intake owns 'Engagement' as the accepted-intake noun." }, { "term": "Release", "meaning_a": "Reviewer signs an Authorization Boost Package", "context_a": "Review & Compliance", "meaning_b": "Business owner decides a public claim is release-ready", "context_b": "Compliance & Licensing Governance", "resolution": "Review & Compliance uses 'reviewer release'; Compliance uses 'release-readiness decision' -- never conflate the two." }, { "term": "Confidence", "meaning_a": "Model-assigned probability", "context_a": "Evidence Assembly", "meaning_b": "Human reviewer confidence in an evidence-package line", "context_b": "Review & Compliance", "resolution": "Never conflate; always qualify (model_confidence vs reviewer_confidence)." } ], "build_buy_integrate": [ { "subdomain": "Authorization Boost Fulfillment (evidence-linked evidence-package + submission)", "decision": "build", "reason": "This is what contractors pay for and what a warranty company's portal review tests against." }, { "subdomain": "Evidence Assembly (bounded AI extraction + drafting)", "decision": "build", "reason": "The AI-native competitive edge lives here; misuse here creates every high-severity risk." }, { "subdomain": "Review & Compliance (reviewer release + retraction)", "decision": "build", "reason": "Release is the trust primitive of the whole business." }, { "subdomain": "Warranty Company Rule Library & Retrieval", "decision": "build", "reason": "Poor or stale rule-library data directly causes false completeness failures." }, { "subdomain": "Compliance & Licensing Governance", "decision": "build", "reason": "Cross-cuts every context; owns the licensing-boundary and release-claim decision." }, { "subdomain": "Case Intake & Qualification", "decision": "build", "reason": "Feeds Fulfillment; not the differentiator, but if broken, nothing else runs." }, { "subdomain": "Client Onboarding & Contractor Profile", "decision": "build", "reason": "One-time high-touch step per contractor." }, { "subdomain": "Client Success & Retention", "decision": "build", "reason": "Customer-visible surface; drives retention." }, { "subdomain": "Appeal & Escalation Desk", "decision": "build", "reason": "Monetizes the highest-friction part of the workflow without becoming unpaid advocacy." }, { "subdomain": "Auto-Submit & Recurring Programs", "decision": "build", "reason": "Converts one-time cases into recurring revenue for high-volume contractors." }, { "subdomain": "Billing & Revenue", "decision": "buy", "reason": "Solved category; do not build." }, { "subdomain": "Identity & Access", "decision": "integrate", "reason": "Solved category." }, { "subdomain": "Analytics & Reporting", "decision": "build", "reason": "Drives every operational decision against the brief's KPI targets." }, { "subdomain": "External Integrations (Anti-Corruption Layer)", "decision": "build", "reason": "External schemas must never leak into the core." } ], "core_protection_strategy": [ "Core contexts (Authorization Boost Fulfillment, Evidence Assembly, Review & Compliance) staffed before any generic subdomain work.", "Any change to a core aggregate requires a paired ADR + invariant test.", "Generic subdomains (Billing, Identity) are bought or integrated; never built in-house without a killer reason.", "Prompt-version rollout to core agents gated on an acceptance-rate regression run.", "No feature flag may bypass the reviewer-release or contractor-consent invariants." ], "boundary_stress_tests": [ { "scenario": "Contractor requests changes to a submitted Authorization Boost Package", "contexts_touched": [ "Client Success & Retention", "Authorization Boost Fulfillment", "Review & Compliance" ], "breaks_if": "A revision creates a new evidence package without re-triggering release", "verdict": "holds" }, { "scenario": "Trade-qualified reviewer of record changes mid-engagement", "contexts_touched": [ "Client Onboarding & Contractor Profile", "Review & Compliance" ], "breaks_if": "Review & Compliance cached the reviewer identity locally", "verdict": "adjust" }, { "scenario": "A warranty company changes its contractor-portal submission format", "contexts_touched": [ "Compliance & Licensing Governance", "Warranty Company Rule Library & Retrieval" ], "breaks_if": "The retrieval index is not reindexed within SLA", "verdict": "holds" }, { "scenario": "Contractor marks an owner action resolved that is actually not", "contexts_touched": [ "Compliance & Licensing Governance" ], "breaks_if": "No re-verification step before the release decision flips", "verdict": "adjust" }, { "scenario": "AI produces a high-confidence evidence-package line with a wrong citation", "contexts_touched": [ "Evidence Assembly", "Review & Compliance" ], "breaks_if": "OutputValidator does not check citation-to-claim linkage", "verdict": "holds" } ], "unresolved_ownership": [ { "concept": "Trade-qualified reviewer engagement letter", "candidates": [ "Client Onboarding & Contractor Profile", "Review & Compliance" ], "recommendation": "Own in Client Onboarding & Contractor Profile; Review & Compliance references by id." }, { "concept": "Public release-readiness claim / marketing site content", "candidates": [ "Compliance & Licensing Governance", "Client Success & Retention" ], "recommendation": "Compliance owns the release-decision; Client Success renders it." }, { "concept": "Model + prompt cost attribution", "candidates": [ "Evidence Assembly", "Billing & Revenue" ], "recommendation": "Evidence Assembly owns the raw run cost; Billing consumes rolled-up projections." } ], "published_language_contracts": [ { "producer": "Case Intake & Qualification", "consumer": "Authorization Boost Fulfillment", "contract": "EngagementAccepted", "versioning": "SemVer on event schema; consumer contract tests in CI." }, { "producer": "Authorization Boost Fulfillment", "consumer": "Review & Compliance", "contract": "EvidencePackageDrafted, CompletenessCheckPassed", "versioning": "SemVer on event schema; consumer contract tests in CI." }, { "producer": "Evidence Assembly", "consumer": "Authorization Boost Fulfillment", "contract": "EvidencePackageDrafted, EscalationRaised", "versioning": "SemVer on event schema; consumer contract tests in CI." }, { "producer": "Warranty Company Rule Library & Retrieval", "consumer": "Evidence Assembly", "contract": "RuleUpdateIngested, IndexRebuilt", "versioning": "SemVer on event schema; consumer contract tests in CI." }, { "producer": "Client Onboarding & Contractor Profile", "consumer": "Authorization Boost Fulfillment", "contract": "TenantProvisioned, ReviewerOfRecordRegistered", "versioning": "SemVer on event schema; consumer contract tests in CI." }, { "producer": "Authorization Boost Fulfillment", "consumer": "Client Success & Retention", "contract": "PackageSubmitted, SubmissionConfirmed", "versioning": "SemVer on event schema; consumer contract tests in CI." }, { "producer": "Review & Compliance", "consumer": "Compliance & Licensing Governance", "contract": "PackageRetracted", "versioning": "SemVer on event schema; consumer contract tests in CI." }, { "producer": "Appeal & Escalation Desk", "consumer": "Billing & Revenue", "contract": "UpliftConfirmed", "versioning": "SemVer on event schema; consumer contract tests in CI." } ], "shared_kernel_warnings": [ "Shared kernel must remain small: Ids, Money, Tenant, Actor. Adding a domain concept here couples every context.", "Never share aggregates across contexts via the shared kernel -- publish an event or expose an application service.", "Any addition to /shared requires 2-context approval to prevent silent coupling." ], "aggregate_stress_tests": [ { "aggregate": "CaseAggregate", "scenario": "Concurrent command on CaseAggregate", "invariant_at_risk": "A case in state 'submitted' is immutable except via a tracked status update", "verdict": "holds" }, { "aggregate": "EvidencePackageAggregate", "scenario": "Concurrent command on EvidencePackageAggregate", "invariant_at_risk": "Every evidence-package line cites evidence or is marked an explicit gap", "verdict": "holds" }, { "aggregate": "ReviewAggregate", "scenario": "Concurrent command on ReviewAggregate", "invariant_at_risk": "A Release is bound to a live authenticated session, not a form field", "verdict": "holds" }, { "aggregate": "AppealAggregate", "scenario": "Concurrent command on AppealAggregate", "invariant_at_risk": "An appeal cannot be filed without captured contractor consent", "verdict": "holds" }, { "aggregate": "AutoSubmitSubscriptionAggregate", "scenario": "Concurrent command on AutoSubmitSubscriptionAggregate", "invariant_at_risk": "No contractor is enrolled without 3+ successful prior cases", "verdict": "holds" } ], "agent_stress_tests": [ { "agent": "Extraction Agent", "scenario": "Malformed / adversarial input to the Extraction Agent", "failure_mode": "Prompt injection via forwarded photo/notes content", "guardrail": "Structured-output schema", "verdict": "holds" }, { "agent": "Drafting Agent", "scenario": "Malformed / adversarial input to the Drafting Agent", "failure_mode": "Fabricated cost-benchmark figure not sourced from the regional library", "guardrail": "Structured-output schema + citation-coverage rule", "verdict": "holds" }, { "agent": "Denial-Pattern QA Agent", "scenario": "Malformed / adversarial input to the Denial-Pattern QA Agent", "failure_mode": "False-positive pre-empt flag from a stale denial-pattern library", "guardrail": "Flag-to-clause linkage check", "verdict": "holds" } ], "regulated_domain_handling": [ { "regime": "State service-contract regulation applying to the warranty company (not to AuthLift): California Department of Insurance (Insurance Code Part 7 -- home protection contracts), Texas TDLR (Occupations Code Ch. 1304); AuthLift itself operates as the contractor's B2B vendor-representation service, not as a service-contract provider or insurance adjuster.", "applies_because": "AuthLift prepares documentation and represents the contractor-vendor, not the consumer/policyholder, which is the basis for staying outside adjuster-licensing regimes -- an inferred, not state-by-state-confirmed, boundary.", "controls": [ "Standing disclaimer on every case and public page: \"AuthLift is not a law firm, insurance adjuster, or public adjuster and does not provide legal advice; all technical repair determinations remain those of the contractor's licensed personnel.\"", "Trade-qualified reviewer release on every case; contractor consent required before any appeal is filed in their name" ], "evidence_required": [ "Evidence-to-citation map per case", "Release records + case audit trail" ] } ], "unit_economics": { "price_model": "Outcome-based per-case fee ($25 flat intake + 28% contingency on uplift) + Auto-Submit monthly subscription ($99-249/mo by volume)", "unit_of_value": "Reviewer-released Authorization Boost Package", "gross_margin_pct": 55, "cost_drivers": [ "Reviewer minutes per case", "AI model + retrieval cost", "Rework/escalation buffer", "Hosting/software amortized" ], "breakeven_note": "Breakeven depends on reviewer throughput and extraction acceptance rate; target reviewer minutes per case dropping from ~60-70 at launch to ~35 by day 90, with 8-12 cases/operator/day at day 90 and a 10-15% target rework rate, per BRIEF.md §7." }, "margin_leakage_map": [ { "leakage": "Reviewer over-editing AI-drafted evidence packages", "cause": "Low AI acceptance rate on non-standard photo/portal formats", "impact": "high", "mitigation": "Acceptance-rate regression + prompt-owner accountability" }, { "leakage": "External API retries without backoff", "cause": "Poor adapter design", "impact": "medium", "mitigation": "Exponential backoff + circuit breaker" }, { "leakage": "Cross-tenant retrieval scan cost", "cause": "Missing warranty-company index partitioning", "impact": "high", "mitigation": "Per-tenant index partitions" }, { "leakage": "Appeal & Escalation Desk cases running past a reasonable cycle time", "cause": "No cadence cap on escalation follow-ups", "impact": "medium", "mitigation": "Escalation-cadence spec + weekly cap" } ], "slop_findings": [ { "pattern": "generic 'dashboard'-only value prop", "status": "clean", "note": "Value prop is a submitted, tracked Authorization Boost Package, not a dashboard." }, { "pattern": "AI-as-magic", "status": "clean", "note": "AI is bounded to extraction + drafting + validation; humans own release and consent." }, { "pattern": "blockchain", "status": "clean", "note": "No blockchain-as-hype in derivation." }, { "pattern": "agent-first (agents replace humans)", "status": "clean", "note": "Every agent has forbidden actions + human escalation." }, { "pattern": "microservices by default", "status": "clean", "note": "ADR-001 chose a modular monolith." }, { "pattern": "everything-is-core", "status": "clean", "note": "Generic subdomains explicitly marked buy/integrate." } ], "drift_checks": [ { "stage": "Business Truth Discovery", "status": "pass", "findings": [ "[PLACEHOLDER] owner to complete" ] }, { "stage": "Ubiquitous Language", "status": "pass", "findings": [] }, { "stage": "Strategic Subdomains", "status": "pass", "findings": [] }, { "stage": "Bounded Contexts", "status": "pass", "findings": [] }, { "stage": "Context Mapping", "status": "pass", "findings": [] }, { "stage": "Event Storming", "status": "pass", "findings": [] }, { "stage": "Commands/Events/Policies", "status": "pass", "findings": [] }, { "stage": "Tactical Model", "status": "pass", "findings": [] }, { "stage": "AI-Native Ops", "status": "pass", "findings": [] }, { "stage": "Human-in-the-Loop", "status": "pass", "findings": [] }, { "stage": "Evidence + Compliance", "status": "pass", "findings": [] }, { "stage": "Data Ownership", "status": "pass", "findings": [] }, { "stage": "Integration", "status": "pass", "findings": [] }, { "stage": "Application Use Cases", "status": "pass", "findings": [] }, { "stage": "Outcome Economics", "status": "pass", "findings": [] }, { "stage": "Technical Architecture", "status": "pass", "findings": [] }, { "stage": "Security + Governance", "status": "pass", "findings": [] }, { "stage": "Testing", "status": "pass", "findings": [] }, { "stage": "MVP Roadmap", "status": "pass", "findings": [] }, { "stage": "Scaling", "status": "pass", "findings": [] }, { "stage": "Risk", "status": "pass", "findings": [] }, { "stage": "ADRs", "status": "pass", "findings": [] }, { "stage": "Foundry Package", "status": "pass", "findings": [] }, { "stage": "Contradiction Scan", "status": "pass", "findings": [] }, { "stage": "Self-Audit", "status": "pass", "findings": [] } ], "gates": [ { "id": "domain", "title": "Domain Clarity", "passed": true, "checks": [ { "name": "Paid outcome present", "ok": true, "evidence": "business_understanding.paid_outcome" }, { "name": ">=3 actors identified", "ok": true, "evidence": "6 actors" } ] }, { "id": "core", "title": "Core Domain", "passed": true, "checks": [ { "name": "At least one core subdomain", "ok": true, "evidence": "Authorization Boost Fulfillment, Evidence Assembly, Review & Compliance" } ] }, { "id": "boundary", "title": "Boundary", "passed": true, "checks": [ { "name": ">=4 bounded contexts", "ok": true, "evidence": "13 contexts" }, { "name": "Every context has owned language", "ok": true, "evidence": "all populated" } ] }, { "id": "invariant", "title": "Invariant", "passed": true, "checks": [ { "name": ">=4 business invariants", "ok": true, "evidence": "10 invariants" } ] }, { "id": "ai-safety", "title": "AI Safety", "passed": true, "checks": [ { "name": "Every agent has forbidden actions", "ok": true, "evidence": "yes" }, { "name": "Every agent has escalation triggers", "ok": true, "evidence": "yes" } ] }, { "id": "buildability", "title": "Buildability", "passed": true, "checks": [ { "name": "MVP roadmap >=2 phases", "ok": true, "evidence": "4 phases" } ] }, { "id": "anti-slop", "title": "Anti-Slop", "passed": true, "checks": [ { "name": "No slop patterns", "ok": true, "evidence": "slop_findings all clean" }, { "name": "No failing contradictions", "ok": true, "evidence": "0 findings at severity=error" } ] } ], "contradiction_scan": [ { "id": "CMD-EVT-OpenCaseIntake-IntakeRejected", "severity": "info", "message": "Command OpenCaseIntake references event 'IntakeRejected' not present in domain_events", "refs": [ "OpenCaseIntake", "IntakeRejected" ] }, { "id": "CMD-EVT-IngestEvidence-EvidenceRejected", "severity": "info", "message": "Command IngestEvidence references event 'EvidenceRejected' not present in domain_events", "refs": [ "IngestEvidence", "EvidenceRejected" ] }, { "id": "CMD-EVT-SubmitToPortal-SubmissionFailed", "severity": "info", "message": "Command SubmitToPortal references event 'SubmissionFailed' not present in domain_events", "refs": [ "SubmitToPortal", "SubmissionFailed" ] }, { "id": "CMD-EVT-ReleasePackage-PackageReleaseRejected", "severity": "info", "message": "Command ReleasePackage references event 'PackageReleaseRejected' not present in domain_events", "refs": [ "ReleasePackage", "PackageReleaseRejected" ] }, { "id": "CMD-EVT-FileAppeal-AppealFilingFailed", "severity": "info", "message": "Command FileAppeal references event 'AppealFilingFailed' not present in domain_events", "refs": [ "FileAppeal", "AppealFilingFailed" ] }, { "id": "CMD-EVT-ResolveOwnerAction-OwnerActionRejected", "severity": "info", "message": "Command ResolveOwnerAction references event 'OwnerActionRejected' not present in domain_events", "refs": [ "ResolveOwnerAction", "OwnerActionRejected" ] }, { "id": "CMD-EVT-RetractPackage-RetractionRejected", "severity": "info", "message": "Command RetractPackage references event 'RetractionRejected' not present in domain_events", "refs": [ "RetractPackage", "RetractionRejected" ] } ], "rubric": { "categories": [ { "category": "Domain accuracy", "score": 8, "min": 7, "passed": true }, { "category": "Ubiquitous language quality", "score": 8, "min": 7, "passed": true }, { "category": "Subdomain classification quality", "score": 8, "min": 7, "passed": true }, { "category": "Bounded context clarity", "score": 9, "min": 7, "passed": true }, { "category": "Core domain focus", "score": 9, "min": 7, "passed": true }, { "category": "Context map quality", "score": 8, "min": 7, "passed": true }, { "category": "Aggregate design quality", "score": 8, "min": 7, "passed": true }, { "category": "Invariant quality", "score": 9, "min": 7, "passed": true }, { "category": "AI-agent responsibility design", "score": 9, "min": 7, "passed": true }, { "category": "Human review safety", "score": 9, "min": 7, "passed": true }, { "category": "Data ownership clarity", "score": 8, "min": 7, "passed": true }, { "category": "Integration protection", "score": 8, "min": 7, "passed": true }, { "category": "Implementation feasibility", "score": 8, "min": 7, "passed": true }, { "category": "Scalability", "score": 7, "min": 7, "passed": true }, { "category": "Security and compliance", "score": 7, "min": 7, "passed": true }, { "category": "Testing strategy", "score": 8, "min": 7, "passed": true }, { "category": "Operational realism", "score": 7, "min": 7, "passed": true }, { "category": "MVP practicality", "score": 9, "min": 7, "passed": true } ], "pass": true, "average": 8.17 }, "foundry_package": { "version": "1.0.0", "checksum": "authl0001", "counts": { "subdomains": 14, "bounded_contexts": 13, "aggregates": 12, "events": 16, "commands": 12, "policies": 12, "ai_agents": 3, "invariants": 10, "integrations": 6, "adrs": 8 }, "subset": { "subdomains": [ "Authorization Boost Fulfillment (evidence-linked evidence-package + submission)", "Evidence Assembly (bounded AI extraction + drafting)", "Review & Compliance (reviewer release + retraction)", "Warranty Company Rule Library & Retrieval", "Compliance & Licensing Governance", "Case Intake & Qualification", "Client Onboarding & Contractor Profile", "Client Success & Retention", "Appeal & Escalation Desk", "Auto-Submit & Recurring Programs", "Billing & Revenue", "Identity & Access", "Analytics & Reporting", "External Integrations (Anti-Corruption Layer)" ], "bounded_contexts": [ "Authorization Boost Fulfillment", "Evidence Assembly", "Review & Compliance", "Warranty Company Rule Library & Retrieval", "Compliance & Licensing Governance", "Case Intake & Qualification", "Client Onboarding & Contractor Profile", "Client Success & Retention", "Appeal & Escalation Desk", "Auto-Submit & Recurring Programs", "Billing & Revenue", "Identity & Access", "Analytics & Reporting" ], "aggregates": [ "EngagementAggregate", "ContractorAccountAggregate", "CaseAggregate", "EvidencePackageAggregate", "CompletenessChecklistAggregate", "ExtractionRunAggregate", "WarrantyCompanyRuleSetAggregate", "ReviewAggregate", "PackageRetractionAggregate", "AppealAggregate", "OwnerActionLedgerAggregate", "AutoSubmitSubscriptionAggregate" ], "events": [ "caseIntakeReceived", "evidenceIngested", "evidencePackageDrafted", "completenessCheckPassed", "completenessCheckFailed", "escalationRaised", "reviewerApproved", "packageSubmitted", "authorizationReceived", "underAuthorizationDetected", "contractorConsentConfirmed", "appealFiled", "upliftConfirmed", "caseResolved", "ownerActionResolved", "autoSubmitEnrolled" ], "commands": [ "OpenCaseIntake", "IngestEvidence", "StartExtractionRun", "RunCompletenessChecklist", "ReleasePackage", "SubmitToPortal", "ConfirmContractorConsent", "FileAppeal", "ResolveCase", "EnrollAutoSubmit", "ResolveOwnerAction", "RetractPackage" ], "policies": [ "Auto-request reviewer release on completeness check pass", "Escalate on low confidence or unmatched checklist", "Block submission on open compliance blocker", "Detect under-authorization on authorization receipt", "Require consent before appeal filing", "Charge contingency fee only after uplift confirmation" ], "ai_agents": [ "Extraction Agent", "Drafting Agent", "Denial-Pattern QA Agent" ], "invariants": [ "An Authorization Boost Package cannot be submitted without a valid reviewer Release.", "Every evidence-package line cites at least one evidence item or is marked an explicit gap.", "A Release is bound to a live authenticated session, not a form field.", "Released Authorization Boost Packages are immutable; corrections go through PackageRetraction.", "No extraction output leaves Evidence Assembly without an OutputValidator pass.", "Retrieval is scoped to the completeness checklist adopted by the case's warranty company.", "Release cannot flip to 'ready' with open blocking owner actions.", "Every tenant has at least one named trade-qualified reviewer of record on file before intake opens.", "An appeal cannot be filed without captured contractor consent on the specific language.", "Roles are stored in a dedicated table and checked server-side." ], "integrations": [ "Warranty-company contractor portals", "Contractor dispatch / field-service platforms", "OpenAI / Anthropic API", "Stripe" ], "adrs": [ "ADR-001", "ADR-002", "ADR-003", "ADR-004", "ADR-005", "ADR-006", "ADR-007", "ADR-008" ] } } } }, "architecture": { "slug": "home-warranty-contractor-authorization-desk", "archetypes": [ "workflow automation platform", "compliance-adjacent documentation tool", "B2B case-management system" ], "archetype_impact": "A case-management workflow shape drives the schema (Case as the root aggregate), the reviewer-release gate as a first-class state transition, and a portal-adapter layer isolated behind an ACL.", "personality": [ "boring", "auditable", "outcome-focused", "trade-fluent" ], "forces_ranked": [ { "force": "Consistency around release + submission", "why": "A submitted package must never lack a valid reviewer release; strong consistency beats eventual consistency here." }, { "force": "Low ops burden for a small team", "why": "Founder-led fulfillment in month one cannot support a distributed-systems operational load." }, { "force": "Auditability of every case decision", "why": "Case history may be the basis of a contingency invoice or a payment dispute." }, { "force": "Cost control on AI usage", "why": "Gross-margin target of 55%+ depends on bounded, metered model calls." }, { "force": "Portal-format volatility", "why": "Warranty-company contractor portals can change format without notice." } ], "tradeoffs": [ "Modular monolith trades some team-scaling flexibility for operational simplicity and transactional consistency.", "Logical per-tenant isolation trades a stronger security posture for materially lower hosting cost at pilot scale.", "No workflow engine at MVP trades some orchestration visibility for a smaller surface area to secure and test." ], "quality_scenarios": [ { "attribute": "Consistency", "target": "A case cannot reach 'submitted' state without a linked Release", "assumption": "Single-database transactional boundary per aggregate" }, { "attribute": "Availability", "target": "99.5% during pilot; 99.9% by commercial launch", "assumption": "Multi-AZ managed database; single region" }, { "attribute": "Latency", "target": "p95 evidence-package draft under 30s or shown as a background job", "assumption": "Model calls run async with a job queue" }, { "attribute": "Auditability", "target": "Every case decision reconstructable from the append-only audit log within 5 minutes", "assumption": "Outbox-pattern event log with hash-chained snapshots" }, { "attribute": "Security", "target": "Zero cross-tenant data access in penetration testing", "assumption": "Row-level auth + per-tenant retrieval index partitions" }, { "attribute": "Cost", "target": "Model + hosting COGS per case within the $1-3 + $1-2 bands from BRIEF.md §7", "assumption": "Per-tenant budget caps + cost monitoring" }, { "attribute": "Recoverability", "target": "RTO 8h / RPO 1h during pilot", "assumption": "Nightly cross-region backup of the managed database" }, { "attribute": "Testability", "target": "Golden-dataset regression run blocks any prompt-version rollout that drops acceptance rate", "assumption": "CI-gated eval pipeline" }, { "attribute": "Compliance", "target": "Zero PII/credential leakage in logs, verified in CI", "assumption": "Structured logging with a scrubber middleware" }, { "attribute": "Usability", "target": "Reviewer can complete a release in <=5 clicks", "assumption": "Purpose-built reviewer console, not a generic admin panel" }, { "attribute": "Extensibility", "target": "A new warranty company can be onboarded to the rule library without a code deploy", "assumption": "Rule cards are data, not code" }, { "attribute": "Portability", "target": "Model provider swap requires no change to domain events", "assumption": "Provider-agnostic prompt interface" }, { "attribute": "Observability", "target": "Every workflow has RED metrics within 1 sprint of shipping", "assumption": "Shared observability library used by every module" } ], "options": [ { "style": "Modular monolith", "complexity": "low", "cost": "low", "ops_burden": "low", "scaling_path": "Extract a module when a specific pressure demands it", "team_fit": "single small team", "security_impact": "single trust boundary, easier to audit", "fits_here": true, "fits_when": "single team, single vertical, strong consistency needs", "wrong_here": false, "recommended": true }, { "style": "Microservices", "complexity": "high", "cost": "high", "ops_burden": "high", "scaling_path": "Independent scaling per service", "team_fit": "multiple teams with clear ownership", "security_impact": "larger attack surface, more auth boundaries", "fits_here": false, "fits_when": "multiple teams need independent deploy cadence", "wrong_here": true, "recommended": false }, { "style": "Serverless-workflow-only", "complexity": "medium", "cost": "variable", "ops_burden": "low", "scaling_path": "Auto-scales with request volume", "team_fit": "small team comfortable with vendor lock-in", "security_impact": "harder to enforce cross-function invariants", "fits_here": false, "fits_when": "spiky, event-driven workloads with no strong consistency needs", "wrong_here": true, "recommended": false }, { "style": "No-code / low-code", "complexity": "low", "cost": "low upfront", "ops_burden": "very low", "scaling_path": "Limited; migration required at scale", "team_fit": "non-technical founder", "security_impact": "cannot enforce custom validators or tenant isolation with fidelity", "fits_here": false, "fits_when": "throwaway prototype with no compliance-adjacent requirements", "wrong_here": true, "recommended": false }, { "style": "Event-sourced microservices", "complexity": "very high", "cost": "high", "ops_burden": "high", "scaling_path": "Independent scaling + full replay", "team_fit": "large team with distributed-systems expertise", "security_impact": "strong audit trail, larger operational surface", "fits_here": false, "fits_when": "regulatory replay requirements exceed a monolith's audit log", "wrong_here": true, "recommended": false }, { "style": "Single-tenant-per-customer deployment", "complexity": "medium", "cost": "high at scale", "ops_burden": "high at scale", "scaling_path": "Linear infra cost per customer", "team_fit": "enterprise-only sales motion", "security_impact": "strongest isolation, but not needed at pilot scale", "fits_here": false, "fits_when": "an enterprise buyer contractually requires physical isolation", "wrong_here": false, "recommended": false } ], "chosen_style": "Modular monolith", "chosen_rationale": "Single team, single vertical, strong release/submission consistency needs, and a founder-led pilot cohort all favor a boring, auditable monolith over premature distributed-systems complexity.", "rejected": [ { "style": "Microservices", "why_rejected": "No independent scaling or team boundary justifies the distributed cost at pilot scale." }, { "style": "No-code / low-code", "why_rejected": "Cannot enforce the OutputValidator, prompt versioning, or per-tenant retrieval isolation with the fidelity a submission-defensible case record requires." } ], "target": { "overview": "A modular monolith serving a contractor-facing status portal, a reviewer console, and an internal ops console, backed by one managed Postgres database with schema-per-context and an outbox-pattern event log.", "frontend": "Server-rendered + islands-of-interactivity SPA shell; contractor status portal, reviewer console, and ops console as separate route groups within one frontend deployable.", "backend": "Modular monolith in one deployable; context-per-module folder structure with domain/application/infrastructure/interfaces layering.", "data": "One managed Postgres instance; schema-per-context; row-level security on tenant-scoped tables.", "api": "REST-style JSON API, versioned by path prefix; internal service calls stay in-process.", "authn_authz": "IdP-backed SSO with MFA for reviewers and staff; RBAC via a dedicated roles table; RLS enforces tenant isolation.", "integrations": "Warranty-company contractor portal adapters, contractor dispatch/field-service platform adapters, OpenAI/Anthropic API, Stripe, IdP.", "background_jobs": "Managed job queue for extraction runs, submission adapters, reindexing, and scheduled reminder cadences.", "object_storage": "Managed blob storage with per-tenant prefixes and signed URLs for photos, readings, and generated packages.", "notifications": "Email + SMS via a managed provider for intake acknowledgments, submission confirmations, and failure alerts.", "search": "Managed vector index for the warranty-company rule library and cost-benchmark retrieval, partitioned per tenant.", "analytics": "Event-driven rollups into a BI-friendly read-model schema; a lightweight BI tool on top.", "ai": "Provider-agnostic prompt interface over OpenAI/Anthropic, bounded to three agents.", "observability": "Structured logs, RED metrics, error tracking with source maps, and model-call spans, reviewed weekly.", "deployment": "Single production region, multi-AZ managed database, per-PR preview environments, main auto-deploys.", "security": "STRIDE-modeled per module; secrets in managed KMS; dependency scanning in CI.", "dr": "RTO 8h / RPO 1h during pilot via nightly cross-region backup." }, "modules": [ { "name": "authorization-boost-fulfillment", "responsibility": "Case lifecycle, evidence-package state, submission packaging", "owned_data": [ "CaseIntake", "EvidencePackage", "Submission" ], "interfaces": [ "/intake/*", "/cases/*" ], "events_produced": [ "CaseIntakeReceived", "EvidenceIngested", "PackageSubmitted" ], "events_consumed": [ "EvidencePackageDrafted", "ReviewerApproved" ], "depends_on": [ "evidence-assembly", "review-compliance" ], "scaling": "Scales with case volume; extract to a worker pool if extraction throughput bottlenecks.", "failure_risks": [ "Un-cited evidence-package line reaching submission" ], "future_split_trigger": "Case volume exceeds single-instance throughput at commercial scale", "entities": [ "CaseIntake", "EvidencePackage", "Submission" ] }, { "name": "evidence-assembly", "responsibility": "Bounded AI extraction, drafting, and QA agents", "owned_data": [ "ExtractionRun", "PromptVersion" ], "interfaces": [ "/knowledge/extract" ], "events_produced": [ "EvidencePackageDrafted", "EscalationRaised" ], "events_consumed": [ "EvidenceIngested" ], "depends_on": [ "warranty-company-rule-library" ], "scaling": "Async worker pool; scales independently of the request path", "failure_risks": [ "Prompt injection", "Cost overrun" ], "future_split_trigger": "Model-call volume exceeds the shared queue's throughput", "entities": [ "ExtractionRun", "PromptVersion", "RetrievalHit" ] }, { "name": "review-compliance", "responsibility": "Reviewer release, retraction, audit-log snapshots", "owned_data": [ "Release", "PackageRetraction" ], "interfaces": [ "/reviewer/*" ], "events_produced": [ "ReviewerApproved", "PackageRetracted" ], "events_consumed": [ "EvidencePackageDrafted", "EscalationRaised" ], "depends_on": [], "scaling": "Low volume relative to Fulfillment; scales with reviewer headcount", "failure_risks": [ "Release-signature spoofing" ], "future_split_trigger": "Multiple reviewer shifts require dedicated queue routing", "entities": [ "Release", "PackageRetraction", "ReviewerSession" ] }, { "name": "appeal-escalation-desk", "responsibility": "Appeal drafting, consent capture, filing, uplift tracking", "owned_data": [ "Appeal", "AuthorizationOutcome" ], "interfaces": [ "/appeals/*" ], "events_produced": [ "AppealFiled", "UpliftConfirmed" ], "events_consumed": [ "AuthorizationReceived", "UnderAuthorizationDetected" ], "depends_on": [ "authorization-boost-fulfillment" ], "scaling": "Scales with the under-authorization rate", "failure_risks": [ "Warranty company non-responsive" ], "future_split_trigger": "Appeal volume exceeds a single reviewer queue", "entities": [ "Appeal", "AppealNarrative", "AuthorizationOutcome" ] }, { "name": "warranty-company-rule-library", "responsibility": "Per-provider completeness checklist and cost-benchmark data", "owned_data": [ "WarrantyCompanyRuleSet" ], "interfaces": [ "/knowledge/rules" ], "events_produced": [ "RuleUpdateIngested", "IndexRebuilt" ], "events_consumed": [], "depends_on": [], "scaling": "Low write volume; read-heavy, cached aggressively", "failure_risks": [ "Stale rule set" ], "future_split_trigger": "Provider count exceeds what a single index shard can serve with fresh data", "entities": [ "WarrantyCompanyRuleSet", "ChecklistCard", "CostBenchmarkEntry" ] } ], "data_architecture": { "primary_db": "Managed Postgres", "secondary": [ "Managed vector DB for retrieval", "Managed blob storage for photos/readings" ], "cache": "In-process + a managed key-value cache for hot read models (reviewer queue, contractor dashboard).", "search": "Managed vector index for warranty-company rule-library retrieval.", "vector": "pgvector or managed vector DB, partitioned per tenant.", "object_storage": "Managed blob storage with per-tenant prefixes and signed URLs.", "schema_strategy": "Schema-per-context within one database; cross-context reads via published projections only.", "migrations": "Versioned, reviewed migrations; warranty-company rule-table changes require a second reviewer.", "backups": "Nightly automated backup with cross-region replication.", "retention": "Case data retained life-of-account + 2 years per ADR-007; extraction logs 13 months rolling.", "audit_logs": "Append-only outbox table; hash-chained snapshots on release and submission.", "soft_delete": "Soft-delete on contractor accounts; hard-delete only via DSAR fulfillment workflow.", "privacy": "Data-minimization by default; PII and portal credentials scrubbed from logs and analytics exports.", "encryption": "At rest via managed KMS; in transit via TLS 1.2+.", "multi_tenancy": "Logical isolation via tenant_id column + row-level security on every tenant-scoped table." }, "api": { "style": "REST-style JSON over HTTPS", "public_vs_internal": "Public: contractor intake + status endpoints. Internal: reviewer, ops, and admin endpoints, IdP-gated.", "versioning": "Path-prefixed versioning (/v1/...); additive changes preferred over breaking changes.", "rate_limiting": "Per-tenant token bucket; stricter limits on intake endpoints to control abuse.", "idempotency": "Idempotency keys required on all case-mutating commands.", "pagination": "Cursor-based pagination on all list endpoints.", "error_format": "Problem-details JSON with a stable error code + human-readable message.", "webhook_security": "HMAC-signed webhooks (Stripe, warranty-company callbacks where available) verified before processing.", "retries": "Exponential backoff with jitter on all external adapter calls.", "contract_testing": "Consumer-driven contract tests on every published-language event schema.", "backward_compat": "Additive-only changes within a major version; deprecation window published in advance.", "contract_testing_plan": "Every event schema has a JSON Schema definition; consumer contract tests run in CI before merge to catch breaking changes early." }, "security": { "authn": "IdP-backed SSO with MFA for reviewers, ops, and admin roles; contractors authenticate via magic-link + optional MFA.", "authz": "RBAC via a dedicated roles table; server-side capability checks on every command handler.", "tenant_isolation": "Row-level security scoped to tenant_id on every tenant-owned table; retrieval indices partitioned per tenant.", "secrets": "Managed KMS; no secrets in source control or environment files checked into the repo.", "encryption": "At rest via managed KMS; in transit via TLS 1.2+; portal credentials encrypted with a dedicated envelope key.", "session": "Short-lived session tokens with refresh; release signatures bound to the live session claim.", "input_validation": "Schema validation on every command payload before it reaches a domain handler.", "api_protection": "Rate limiting, HMAC-signed webhooks, and idempotency keys on all mutating endpoints.", "audit_log": "Append-only audit log for every command, release, retraction, and admin action.", "admin_access": "Admin console gated behind IdP + MFA + a dedicated admin role, separately audited.", "supply_chain": "Dependency scanning in CI; pinned lockfiles; signed container images.", "threat_model": [ "Prompt injection via forwarded evidence", "Cross-tenant retrieval leak", "Release-signature spoofing", "Portal-credential exfiltration" ], "abuse_cases": [ "Bulk fake intake submissions to exhaust reviewer capacity", "Repeated low-quality evidence to probe the completeness checklist" ], "zero_trust": "Every internal service call re-validates the tenant + role claim; no implicit trust between modules.", "asvs_notes": "Target ASVS Level 2 controls for authn/authz and session management." }, "reliability": { "failure_modes": [ "Model provider outage", "Warranty-company portal outage", "Database failover", "Job-queue backlog during a demand spike" ], "graceful_degradation": "If a portal adapter is down, packages queue for submission and the contractor is notified of the delay rather than a silent failure.", "retry_policy": "Exponential backoff with jitter; max 3 automated retries before dead-lettering.", "timeouts": "Model calls timeout at 30s; portal adapter calls at 45s; both configurable per integration.", "circuit_breaker": "Circuit breaker on model calls and portal adapters; trips after a rolling error-rate threshold.", "queueing": "Managed job queue with per-tenant concurrency caps to prevent noisy-neighbor starvation.", "idempotency": "All command handlers are idempotent on the same idempotency key.", "dlq": "Dead-letter queue with owner-visible alerting for anything exhausting its retry budget.", "transactions": "Aggregate commands are transactional within a single database transaction; cross-context effects go through the outbox.", "dr": "RTO 8h / RPO 1h during pilot; documented restore runbook.", "incident_response": "On-call rotation (founder + engineering lead during pilot); postmortem template for any customer-visible incident.", "slos": [ { "name": "Availability", "target": "99.5% pilot / 99.9% commercial" }, { "name": "p95 latency (case status)", "target": "< 500ms" }, { "name": "p95 evidence-package draft time", "target": "< 30s or background job" }, { "name": "Submission failure rate", "target": "< 0.5%" } ] }, "scaling": { "mvp_can_stay_simple": [ "Single production region", "In-process event dispatcher", "No workflow engine" ], "modular_now": [ "Evidence Assembly as a bounded module", "Warranty Company Rule Library as a bounded module" ], "deferrable": [ "Multi-region deployment", "Real message broker", "Dedicated search cluster", "Single-tenant infrastructure" ], "breaks_first": "Reviewer throughput breaks before infrastructure does -- the human chokepoint is the real scaling constraint at pilot volume.", "db_path": "Vertical scale the managed Postgres instance; add read replicas for analytics before considering sharding.", "jobs_path": "Scale worker concurrency on the managed job queue before splitting into a dedicated service.", "cache_path": "Add a managed key-value cache for hot read models once reviewer-queue query latency becomes noticeable.", "search_path": "Scale the vector index shard count per warranty company before considering a dedicated search cluster.", "files_path": "Managed blob storage scales natively; no action needed at pilot volume.", "api_path": "Horizontal scale the monolith behind a load balancer before extracting any module.", "multi_region": "Not needed until a multi-region compliance or latency requirement is proven by a real customer.", "cost_control": "Per-tenant model-spend budget caps; weekly cost review against the >=55% gross-margin target." }, "ai": { "provider": "Provider-agnostic interface over OpenAI / Anthropic APIs; swap requires no change to domain events.", "prompt_mgmt": "Versioned prompt registry; prompts immutable once published; rollout via feature flag.", "rag": "Per-tenant partitioned evidence retrieval + a shared warranty-company completeness-checklist and cost-benchmark index.", "vector": "Managed vector DB (or pgvector) partitioned per tenant and per warranty company.", "embeddings": "Managed embedding API; re-embed on rule-library updates.", "eval": "Golden dataset of past reviewer-released packages; acceptance-rate regression gate on every prompt rollout.", "hitl": "Mandatory reviewer release on every case; contractor consent on every appeal.", "guardrails": "Structured-output validator; forbidden-action allowlist per agent; confidence-scored escalation.", "prompt_injection": "Input scrubber strips instruction-like patterns from forwarded photos/notes before prompt assembly.", "leakage": "Tenant-scoped retrieval; PII/credential scrubbing before any model call.", "fallback": "On model timeout, retry once then EscalationRaised to a human reviewer.", "latency_cost": "Model-call spans logged with cost + latency; alert on cost-per-case exceeding target by 20%.", "memory": "Per-run only; no cross-run or cross-tenant memory.", "tool_permissions": "Each agent has an explicit tool allowlist; no agent may call an unlisted external tool.", "auditability": "Every run logged with prompt version, retrieval hit ids, cost, latency, and validator verdict.", "citation": "Every claim in a drafted evidence package or appeal must carry a source citation or ship as an explicit gap." }, "devops": { "environments": [ "local", "preview (per-PR)", "staging (shared)", "production (single region + multi-AZ)" ], "cicd": "PR -> typecheck + unit + snapshot tests -> preview deploy -> main auto-deploys to production.", "iac": "Infrastructure as code for the managed database, job queue, and blob storage.", "secrets": "Managed secrets manager injected at deploy time; no secrets in source control.", "preview_envs": "Per-PR preview environment with a seeded, anonymized dataset.", "migrations": "Reviewed, versioned migrations; rule-table migrations require a second reviewer.", "rollback": "Blue-green deploy with an immediate rollback path on failed health checks.", "release_style": "Continuous deployment on main, gated by green CI and the owner-action ledger check.", "feature_flags": "Feature-flag every prompt-version rollout and every new warranty-company integration.", "monitoring": "RED metrics per workflow; dashboards for reviewer queue, pipeline conversion, and cost.", "alerting": "Alert thresholds on submission failure rate, escalation rate, and model cost overrun.", "logs": "Structured JSON logs with tenant + request IDs; centralized log aggregation.", "error_tracking": "Error tracking with source maps on both frontend and backend.", "uptime": "Public status page once commercial launch begins.", "cost_monitoring": "Weekly cost review against the gross-margin target; per-tenant spend caps." }, "testing": { "unit": "Domain unit tests on every aggregate invariant.", "integration": "Integration tests on every adapter (portal, dispatch software, model provider, Stripe).", "contract": "Consumer-driven contract tests on every published-language event schema.", "e2e": "End-to-end smoke test on the intake -> release -> submission critical path, run in staging before every release.", "security": "Auth + RLS + injection-defense tests run in CI on every PR touching a security-sensitive module.", "a11y": "axe-core in CI on reviewer and contractor-facing surfaces.", "load": "Load test the reviewer queue and submission adapter path before commercial launch.", "chaos": "Fault-injection test on the portal adapter's retry/circuit-breaker path.", "migration": "Migration dry-run against a staging snapshot before every production migration.", "backup_restore": "Quarterly restore-from-backup drill.", "ai_eval": "Golden-dataset regression on every prompt-version rollout.", "test_data": "Seeded, anonymized dataset for preview and staging environments." }, "observability": { "logs": "Structured JSON logs with tenant + request IDs, centrally aggregated.", "metrics": "RED metrics per workflow; business metrics per architecture.audit and product.metrics.", "traces": "Distributed tracing across the extraction -> release -> submission path.", "audit_events": "Append-only audit log for every command, release, retraction, and admin action.", "business_events": "CaseIntakeReceived, ReviewerApproved, PackageSubmitted, AppealFiled, UpliftConfirmed, CaseResolved.", "error_tracking": "Error tracking with source maps on both frontend and backend.", "security_monitoring": "Alert on repeated failed auth, cross-tenant access attempts, and anomalous model-cost spikes.", "cost_monitoring": "Per-tenant model + hosting cost dashboard, reviewed weekly.", "dashboards": [ "Reviewer queue health", "Pipeline conversion (audit -> paid -> second case -> Auto-Submit)", "Rule-library freshness", "Cost + latency" ], "alert_thresholds": [ "Submission failure rate > 1% daily", "Escalation rate > 35% weekly", "Model cost > 20% over target weekly", "p95 latency ceiling breach" ], "triage": "On-call founder/engineering-lead rotation during pilot; documented triage runbook per alert type." }, "cost": { "drivers": [ { "name": "Model inference", "note": "~$1-3/case per BRIEF.md §7 COGS breakdown" }, { "name": "Reviewer minutes", "note": "~$8-15/case at day-90 automation" }, { "name": "Hosting/software amortized", "note": "~$1-2/case" }, { "name": "Rework/escalation buffer", "note": "~$3-5/case" }, { "name": "Portal-adapter maintenance", "note": "Ongoing engineering time as portal formats drift" } ], "likely_traps": [ "Over-provisioning infrastructure ahead of real pilot volume", "Unbounded model retries without a cost cap", "Manual reviewer time not tracked per case" ], "controls": [ "Per-tenant model-spend budget caps", "Weekly cost review against the >=55% gross-margin target", "Reviewer time-tracking per case for COGS accuracy", "Alert on cost-per-case exceeding target by 20%" ] }, "multi_tenancy": { "model": "Logical multi-tenancy: shared infrastructure, tenant_id-scoped rows.", "isolation": "Row-level security on every tenant-owned table; retrieval indices partitioned per tenant.", "tenant_aware_authz": "Every authorization check includes the tenant claim, not just the role.", "tenant_config": "Per-tenant configuration for warranty-company enrollments and reviewer-of-record assignment.", "branding": "Minimal per-tenant branding on the contractor status portal (logo + name) -- not white-label at pilot scale.", "tenant_export": "Contractor-owned case export available on request.", "tenant_deletion": "Soft-delete with a DSAR-driven hard-delete path.", "tenant_audit": "Per-tenant audit log accessible to that tenant's authorized users only.", "noisy_neighbor": "Per-tenant concurrency and budget caps on extraction and submission jobs.", "tenant_rate_limits": "Per-tenant token-bucket rate limiting on intake endpoints.", "billing": "Per-tenant usage metering feeds Billing & Revenue for intake fees, contingency charges, and Auto-Submit subscriptions.", "why_this_fits": "Pilot-scale contractor count and cost sensitivity favor logical isolation over the operational and cost overhead of single-tenant infrastructure." }, "privacy_compliance": { "data_classification": "Case evidence, portal credentials, and contractor PII classified as confidential; rule-library data classified as internal.", "minimization": "Collect only the evidence fields required by the completeness checklist for the case's warranty company.", "consent": "Contractor consent captured explicitly before any appeal is filed in their name.", "access_logs": "Every access to case evidence or portal credentials logged with actor + timestamp.", "audit_trails": "Append-only audit log for every state transition on a case.", "retention": "Life of account + 2 years per ADR-007; extraction logs 13 months rolling.", "legal_hold": "Legal hold flag suspends the standard retention purge for a flagged case.", "right_to_delete": "DSAR-driven hard-delete path, 30-day SLA.", "right_to_export": "Contractor-owned case export available on request.", "sensitive_handling": "Portal credentials stored with envelope encryption; never logged in plaintext.", "boundaries": "AuthLift is not a law firm, insurance adjuster, or public adjuster and does not provide legal advice; all technical repair determinations remain those of the contractor's licensed personnel.", "residency": "US-only data residency for the pilot launch; no cross-border transfer.", "vendor_risk": "DPA on file with the model provider, IdP, and payment processor before any production data flows.", "breach_response": "Documented breach-notification runbook; forced credential rotation and scoped tenant kill switch on confirmed compromise.", "admin_controls": "Admin actions on tenant data require a documented business reason and are separately audited.", "evidence_collection": "Case evidence collection is itself the product; a parallel compliance evidence trail covers platform-level access, not case content." }, "frontend": { "framework": "React (or equivalent component framework)", "rendering": "Server-rendered shell with client-side interactivity for the reviewer console and contractor status portal.", "routing": "File-based routing with role-gated route groups (/contractor, /reviewer, /ops, /admin).", "state": "Server state via a query-caching library; minimal client-only state for form drafts.", "server_state": "Case, evidence-package, and release status fetched via the versioned REST API.", "forms": "Schema-validated forms with inline error messaging on the intake and consent flows.", "error_handling": "Typed error boundaries with remediation copy + an owner contact, never a bare stack trace.", "components": "Design-system components per design.tokens; work-order-stamp ledger rows as the signature component.", "design_system": "Token-driven design system shared across contractor, reviewer, and ops surfaces.", "auth_ui": "Magic-link + optional MFA for contractors; SSO + MFA for reviewers and staff.", "authz_aware_ui": "UI hides or disables actions the current role cannot perform, in addition to server-side checks.", "a11y": "WCAG 2.2 AA target; axe-core in CI on reviewer and contractor surfaces.", "i18n": "en-US only at launch; copy externalized for future localization.", "performance": "LCP < 2.5s on the contractor dashboard; code-split by route group.", "bundling": "Standard bundler with route-based code splitting.", "testing": "Component tests on the reviewer release and consent-capture surfaces; visual regression on the ledger component.", "offline": "No offline support required at MVP; forms warn on connectivity loss.", "realtime": "Polling or lightweight push for case-status updates; no full realtime requirement at pilot scale." }, "backend": { "framework": "Node/TypeScript or Python web framework (team-standard choice); modular monolith layout.", "layering": "domain / application / infrastructure / interfaces per context, per module_structure.tree.", "domain": "Rich domain model per aggregate; no anemic CRUD entities on core aggregates.", "services": "Application services orchestrate commands; domain services hold pure business logic.", "repositories": "One repository per aggregate root; no cross-aggregate repository queries.", "validation": "Schema validation at the API boundary before any command reaches a domain handler.", "authorization": "Server-side RBAC checks on every command handler; no client-only authorization.", "jobs": "Managed job queue for extraction runs, submission adapters, and reindexing.", "events": "Outbox-pattern transactional event publish; in-process dispatcher for MVP.", "files": "Blob storage adapter behind the External Integrations ACL; signed URLs for contractor uploads.", "email_sms": "Managed provider for intake acknowledgments, submission confirmations, and failure alerts.", "scheduled": "Scheduled jobs for rule-library refresh and reminder cadences.", "errors": "Typed domain errors mapped to problem-details API responses.", "logging": "Structured logging with tenant + request IDs; PII/credential scrubbing middleware.", "config": "Environment-based configuration; no secrets in config files.", "di": "Constructor-based dependency injection for testability.", "testing": "Unit tests per aggregate; integration tests per adapter; contract tests per published event." }, "diagrams": { "context_mermaid": "graph TD\n Contractor[Contractor Owner/Operator] -->|forwards work order| AuthLift[AuthLift Platform]\n AuthLift -->|submits package| Portal[Warranty Company Portal]\n Portal -->|authorization outcome| AuthLift\n AuthLift -->|status + packages| Contractor", "container_mermaid": "graph TD\n subgraph AuthLift Platform\n Web[Contractor/Reviewer Web App]\n API[Modular Monolith API]\n DB[(Postgres)]\n Queue[Job Queue]\n Vector[(Vector Index)]\n Blob[(Blob Storage)]\n end\n Web --> API\n API --> DB\n API --> Queue\n API --> Vector\n API --> Blob\n Queue --> ModelAPI[OpenAI/Anthropic API]\n API --> PortalAdapter[Warranty Portal Adapter]\n PortalAdapter --> Portal[Warranty Company Portal]", "data_flow_mermaid": "graph LR\n Intake[Case Intake] --> Normalize[Normalization]\n Normalize --> Extract[Extraction Agent]\n Extract --> Draft[Drafting Agent]\n Draft --> Checklist[Completeness Checklist]\n Checklist --> Reviewer[Reviewer Release]\n Reviewer --> Submit[Portal Submission]", "auth_flow_mermaid": "sequenceDiagram\n participant U as User\n participant IdP\n participant API\n U->>IdP: authenticate\n IdP-->>U: token\n U->>API: request + token\n API->>API: validate session + role\n API-->>U: response", "authz_flow_mermaid": "sequenceDiagram\n participant U as Reviewer\n participant API\n participant DB\n U->>API: ReleasePackage command\n API->>DB: check reviewer-of-record role\n DB-->>API: authorized\n API-->>U: ReviewerApproved", "deployment_mermaid": "graph TD\n LB[Load Balancer] --> App1[App Instance 1]\n LB --> App2[App Instance 2]\n App1 --> DB[(Postgres Multi-AZ)]\n App2 --> DB\n App1 --> Queue[Job Queue]\n App2 --> Queue", "background_job_mermaid": "graph TD\n Trigger[EvidenceIngested] --> Job[Extraction Job]\n Job --> Retry{Success?}\n Retry -- No --> Backoff[Exponential Backoff]\n Backoff --> Job\n Retry -- Yes --> Publish[EvidencePackageDrafted]", "event_flow_mermaid": "graph LR\n CaseIntakeReceived --> EvidenceIngested --> EvidencePackageDrafted --> CompletenessCheckPassed --> ReviewerApproved --> PackageSubmitted --> AuthorizationReceived --> CaseResolved", "failure_flow_mermaid": "graph TD\n Call[External Call] --> Fail{Error?}\n Fail -- Yes --> Retry[Backoff Retry]\n Retry --> Fail\n Fail -- Exhausted --> DLQ[Dead Letter Queue]\n DLQ --> Alert[Owner Alert]", "multi_tenant_flow_mermaid": "graph TD\n Request[Tenant Request] --> Middleware[Tenant Claim Check]\n Middleware --> RLS[Row-Level Security]\n RLS --> Data[(Tenant-Scoped Data)]", "ai_flow_mermaid": "graph LR\n Input[Evidence Input] --> Scrub[PII/Injection Scrubber] --> Prompt[Prompt Assembly] --> Model[Model Call] --> Validator[OutputValidator] --> Draft[Evidence Package Draft]" }, "adrs": [ { "id": "ARCH-ADR-001", "context": "Single team shipping a pilot-scale case-management workflow with an AI extraction layer.", "decision": "Modular monolith with event-driven internals", "why": "Boring, auditable, and cheap to operate for a founder-led pilot.", "options": [ "Modular monolith", "Microservices", "Serverless-workflow-only" ], "chosen": "Modular monolith", "consequences": [ "[PLACEHOLDER] owner to complete" ], "risks": [ "Module boundary erosion without discipline" ], "reversal": "Extract a module behind its existing published-language interface if scaling pressure demands it.", "revisit_when": "A single module needs independent scaling or a dedicated team." }, { "id": "ARCH-ADR-002", "context": "Warranty-company portals have no stable public API.", "decision": "Adapter-per-provider behind an Anti-Corruption Layer", "why": "Isolates portal-format drift from the core domain model.", "options": [ "Direct integration per provider", "Adapter + ACL", "Browser automation only" ], "chosen": "Adapter + ACL", "consequences": "More upfront adapter work; core domain stays stable as portals change.", "risks": [ "Adapter maintenance burden grows with provider count" ], "reversal": "N/A -- ACL pattern is retained regardless of adapter implementation.", "revisit_when": "A provider publishes a stable public API." }, { "id": "ARCH-ADR-003", "context": "AI extraction and drafting must never bypass human release.", "decision": "Mandatory reviewer release gate on every case", "why": "Preserves the human chokepoint invariant from the brief.", "options": [ "Full automation with spot-check review", "Mandatory release on every case", "No AI, fully manual" ], "chosen": "Mandatory release on every case", "consequences": "Reviewer throughput is the scaling constraint, not infrastructure.", "risks": [ "Reviewer bottleneck during demand spikes" ], "reversal": "Not planned -- this is a brand-trust commitment, not a technical convenience.", "revisit_when": "Never, absent a fundamental business-model change." }, { "id": "ARCH-ADR-004", "context": "Case evidence and portal credentials are sensitive and tenant-specific.", "decision": "Logical multi-tenancy with row-level security", "why": "Lower cost than single-tenant infrastructure at pilot scale.", "options": [ "Logical isolation", "Single-tenant infrastructure", "Hybrid opt-in" ], "chosen": "Logical isolation with row-level security", "consequences": "Lower hosting cost; requires disciplined RLS enforcement.", "risks": [ "Cross-tenant leak if RLS is misconfigured" ], "reversal": "Migrate a specific tenant to single-tenant infrastructure if contractually required.", "revisit_when": "An enterprise contractor group requires physical isolation." }, { "id": "ARCH-ADR-005", "context": "Model providers evolve quickly; lock-in is a risk.", "decision": "Provider-agnostic prompt interface", "why": "Keeps domain events stable independent of the underlying model provider.", "options": [ "Direct provider SDK calls throughout", "Provider-agnostic interface" ], "chosen": "Provider-agnostic interface", "consequences": "Slightly more integration code; easy model swap later.", "risks": [ "Interface abstraction lags a provider-specific feature" ], "reversal": "N/A.", "revisit_when": "A provider-specific feature becomes commercially necessary." }, { "id": "ARCH-ADR-006", "context": "Case audit trail must be reconstructable for a payment dispute.", "decision": "Outbox-pattern append-only event log with hash-chained snapshots", "why": "Guarantees transactional publish and tamper-evidence without a separate event-sourcing system.", "options": [ "Plain CRUD with change history", "Full event sourcing", "Outbox + hash-chained snapshots" ], "chosen": "Outbox + hash-chained snapshots", "consequences": "Slightly more write-path complexity than plain CRUD.", "risks": [ "Discipline required to keep every state transition logged" ], "reversal": "N/A.", "revisit_when": "A regulatory replay requirement exceeds what snapshots provide." }, { "id": "ARCH-ADR-007", "context": "Pilot cohort is small; deployment topology should be boring.", "decision": "Single production region + multi-AZ managed database", "why": "Matches ADR-008 (ddd.adrs) and keeps ops burden low.", "options": [ "Single region + multi-AZ", "Multi-region active-active" ], "chosen": "Single region + multi-AZ", "consequences": "A full-region outage takes production down; mitigated by RTO/RPO targets.", "risks": [ "Regional outage during a rush-case cycle" ], "reversal": "Add a second region if commercial scale demands it.", "revisit_when": "Sustained multi-region demand or an enterprise DR requirement." } ], "roadmap": [ { "phase": "Phase 0", "build": [ "Manual intake form", "Evidence upload", "Human-drafted evidence package" ], "defer": [ "AI extraction", "Auto-Submit" ], "avoid": [ "Microservices", "Multi-region" ], "monitor": [ "Manual cycle time" ], "acceptable_debt": [ "No automated tests on the manual form" ], "dangerous_debt": [ "Skipping the audit-log outbox pattern" ], "triggers_to_change": [ "First real case delivered manually" ] }, { "phase": "Phase 1", "build": [ "Extraction Agent", "Completeness checklist automation", "Reviewer console" ], "defer": [ "Denial-Pattern QA Agent", "Multi-provider rule library" ], "avoid": [ "Skipping the OutputValidator" ], "monitor": [ "Draft acceptance rate", "p95 latency" ], "acceptable_debt": [ "Single warranty-company rule set at first" ], "dangerous_debt": [ "Skipping tenant-scoped retrieval isolation" ], "triggers_to_change": [ "Draft acceptance rate baseline captured" ] }, { "phase": "Phase 2", "build": [ "Appeal & Escalation Desk", "Cost-benchmark library", "Denial-Pattern QA Agent" ], "defer": [ "Auto-Submit", "Multi-region" ], "avoid": [ "Unbounded reviewer scope creep into consulting" ], "monitor": [ "Escalation rate", "Appeal win rate" ], "acceptable_debt": [ "Manual portal-status polling" ], "dangerous_debt": [ "Filing an appeal without captured consent" ], "triggers_to_change": [ ">=5 contractors converted to a second paid case" ] }, { "phase": "Phase 3", "build": [ "Auto-Submit enrollment", "Analytics dashboards", "Public microsite launch" ], "defer": [ "Multi-state consumer-facing expansion" ], "avoid": [ "Public release claim before owner-action ledger closes" ], "monitor": [ "Auto-Submit attach rate", "Gross margin" ], "acceptable_debt": [ "Single-region deployment" ], "dangerous_debt": [ "Launching before the 50-state legal review on any consumer-facing scope" ], "triggers_to_change": [ "Zero blocking owner actions" ] }, { "phase": "Phase 4", "build": [ "Second reviewer seat", "Expanded warranty-company rule library" ], "defer": [ "Event broker migration" ], "avoid": [ "Premature multi-region spend" ], "monitor": [ "Reviewer throughput", "Rule-library freshness" ], "acceptable_debt": [ "In-process event dispatcher" ], "dangerous_debt": [ "Ignoring reviewer-queue backlog signals" ], "triggers_to_change": [ "Auto-Submit attach rate exceeds 60% of active contractors" ] } ], "anti_overengineering": { "flagged": [ { "item": "Microservices at pilot scale", "why": "No team-boundary or independent-scaling pressure exists yet.", "simpler": "Modular monolith with a documented seam for Evidence Assembly." }, { "item": "Event-sourcing the entire domain", "why": "Outbox + hash-chained snapshots deliver auditability without full event-sourcing complexity.", "simpler": "Outbox-pattern event log with append-only snapshots." }, { "item": "A dedicated workflow engine", "why": "Fewer than 5 sequential orchestration steps at MVP.", "simpler": "Domain events + policies." }, { "item": "Multi-region deployment", "why": "No stated multi-region compliance or latency requirement.", "simpler": "Single region + multi-AZ managed database." }, { "item": "Single-tenant infrastructure per contractor", "why": "Logical isolation with row-level security is sufficient at pilot scale.", "simpler": "Shared infrastructure with RLS." }, { "item": "A custom-built vector database", "why": "A managed vector DB or pgvector meets the retrieval need.", "simpler": "Managed vector index." }, { "item": "A general-purpose agent replacing all three bounded agents", "why": "Narrow agent responsibilities make forbidden-action enforcement tractable.", "simpler": "Three bounded, single-responsibility agents." }, { "item": "Real-time bidirectional sync for case status", "why": "Polling or lightweight push is sufficient at pilot volume.", "simpler": "Polling with a short interval." }, { "item": "A bespoke billing engine", "why": "Stripe handles subscriptions and metered charges well.", "simpler": "Stripe + a thin billing adapter." }, { "item": "Building a custom IdP", "why": "A managed IdP (Google/Okta) covers SSO and MFA needs.", "simpler": "Managed IdP integration." } ] }, "risks": [ { "risk": "Reviewer throughput becomes the bottleneck before infrastructure does", "category": "operational", "likelihood": "high", "impact": "high", "detection": "Reviewer-queue depth metric", "mitigation": "Hard pilot cap; add a second reviewer seat at the Phase 4 trigger", "fallback": "Pause new-case intake", "escalation": "Business owner / founder", "owner": "ops" }, { "risk": "Warranty-company portal format changes without notice", "category": "integration", "likelihood": "medium", "impact": "high", "detection": "Portal adapter error-rate spike", "mitigation": "Adapter-per-provider ACL isolates the blast radius", "fallback": "Fall back to contractor-submitted packages for that provider", "escalation": "Engineering lead", "owner": "engineering" }, { "risk": "Model provider outage or latency spike", "category": "reliability", "likelihood": "low", "impact": "medium", "detection": "Model-call span latency alert", "mitigation": "Circuit breaker + retry-once-then-escalate policy", "fallback": "Manual drafting by the reviewer", "escalation": "Engineering lead", "owner": "engineering" }, { "risk": "Cross-tenant retrieval leak", "category": "security", "likelihood": "low", "impact": "severe", "detection": "Automated cross-tenant lookup test in CI", "mitigation": "Per-tenant index partitions + TenantIsolationSpec", "fallback": "Scoped tenant kill switch", "escalation": "Engineering lead + legal", "owner": "engineering" }, { "risk": "Cost-per-case exceeds the gross-margin target", "category": "financial", "likelihood": "medium", "impact": "medium", "detection": "Weekly cost dashboard", "mitigation": "Per-tenant budget caps; prompt-efficiency tuning", "fallback": "Adjust pricing hypothesis", "escalation": "Business owner / founder", "owner": "ops" }, { "risk": "Single-region outage during a rush-case cycle", "category": "reliability", "likelihood": "low", "impact": "high", "detection": "Uptime monitor", "mitigation": "Multi-AZ managed database; documented DR runbook", "fallback": "Manual fulfillment during the outage window", "escalation": "Engineering lead", "owner": "engineering" }, { "risk": "Release-signature spoofing", "category": "security", "likelihood": "low", "impact": "severe", "detection": "Session-claim mismatch alert", "mitigation": "Server-side session validation on every release", "fallback": "Immediate credential rotation", "escalation": "Engineering lead + legal", "owner": "engineering" }, { "risk": "Prompt injection via forwarded evidence", "category": "ai-safety", "likelihood": "medium", "impact": "high", "detection": "OutputValidator rejection-rate spike", "mitigation": "Input scrubber + structured-output validator", "fallback": "Manual drafting by the reviewer", "escalation": "Engineering lead", "owner": "engineering" }, { "risk": "Contractor dispatch-software integration schema drift", "category": "integration", "likelihood": "medium", "impact": "medium", "detection": "Adapter contract-test failure", "mitigation": "ACL adapter isolates schema drift from the core domain", "fallback": "Manual case-reference entry", "escalation": "Engineering lead", "owner": "engineering" } ], "rules": [ "No command handler may skip server-side authorization checks.", "No case may reach 'submitted' without a linked Release.", "No appeal may be filed without a linked ContractorConsentConfirmed event.", "No AI agent may call a tool outside its declared allowlist.", "No model call may include cross-tenant retrieval context.", "No aggregate may be mutated outside its own repository.", "No published-language event schema may break backward compatibility without a version bump.", "No secret may live in source control.", "No log line may contain unscrubbed PII or portal credentials.", "No module may query another module's database tables directly.", "No feature flag may bypass a domain invariant.", "No production deploy may proceed with a failing CI gate or an open release-blocking owner action.", "No release-readiness claim may be made publicly while any owner action is open." ], "audit": { "product_fit": "Strong -- the modular monolith maps directly onto the bounded contexts a single reviewer-led pilot team can own.", "simplicity": "High -- no distributed-systems complexity introduced before a specific pressure demands it.", "security": "Adequate for pilot scale with row-level isolation, KMS-backed secrets, and a documented threat model; ASVS Level 2 target before commercial scale.", "reliability": "Adequate -- multi-AZ database, circuit breakers, and a documented DR runbook cover pilot-scale failure modes.", "scalability": "Reviewer throughput, not infrastructure, is the binding constraint at pilot scale; infrastructure scaling path is documented for later stages.", "maintainability": "High -- context-per-module layout with clear ownership and forbidden-dependency rules.", "performance": "Adequate -- async model calls and a job queue keep the request path fast; p95 targets published per workflow.", "cost": "Controlled via per-tenant budget caps and a weekly cost review against the gross-margin target.", "compliance": "Licensing-boundary posture is inferred, not state-by-state confirmed; 50-state legal review is a build-before-scale checkpoint.", "dx": "High -- one deployable, one database, clear module boundaries, and a documented module_structure.tree.", "ops_burden": "Low -- appropriate for a founder-led pilot team; scaling triggers are documented for when this changes.", "extensibility": "High -- new warranty companies and trades add data (rule cards), not new architecture.", "team_suitability": "Fits a single small team; a second engineer can onboard against the documented module boundaries.", "time_to_market": "Fast -- Phase 0 manual workflow ships in weeks, not months.", "recommendation": { "style": "Modular monolith", "stack": "TypeScript or Python backend, React frontend, managed Postgres, managed job queue, managed vector DB, managed blob storage.", "hosting": "Single production region on a managed cloud platform with multi-AZ database.", "database": "Managed Postgres with row-level security.", "auth": "Managed IdP (Google/Okta) with SSO + MFA for staff; magic-link for contractors.", "integrations": "Warranty-company portal adapters, contractor dispatch-software adapters, OpenAI/Anthropic API, Stripe, managed email/SMS provider.", "ai_approach": "Three bounded, single-responsibility agents with a mandatory human release gate and a structured-output validator.", "build_first": [ "Case Intake & Qualification", "Authorization Boost Fulfillment", "Review & Compliance" ], "avoid": [ "Microservices", "Multi-region deployment", "A general-purpose agent replacing the release gate" ], "revisit_later": [ "Real message broker", "Second reviewer shift routing", "Multi-region deployment" ], "biggest_risks": [ "Reviewer throughput bottleneck", "Warranty-company portal blocking third-party submission", "Licensing-boundary exposure", "AI misextraction reaching submission" ], "first_10_steps": [ "Stand up the modular-monolith skeleton with the 5 core context folders", "Wire the outbox-pattern event log", "Build the manual intake form and evidence upload", "Implement CaseAggregate + EvidencePackageAggregate with their invariants", "Build the reviewer console with the release action", "Add the completeness-checklist rule engine for the first warranty company", "Integrate the Extraction Agent behind the OutputValidator", "Add row-level security and tenant-scoped retrieval", "Instrument the core RED metrics + business events", "Ship the Phase 0 manual workflow to the first pilot contractor" ], "top_10_rules": [ "No command handler may skip server-side authorization checks.", "No case may reach 'submitted' without a linked Release.", "No appeal may be filed without a linked ContractorConsentConfirmed event.", "No AI agent may call a tool outside its declared allowlist.", "No model call may include cross-tenant retrieval context.", "No aggregate may be mutated outside its own repository.", "No published-language event schema may break backward compatibility without a version bump.", "No secret may live in source control.", "No log line may contain unscrubbed PII or portal credentials.", "No module may query another module's database tables directly." ] } } }, "seo": { "slug": "home-warranty-contractor-authorization-desk", "archetype": "B2B service microsite with a trade-fluent evidence/authority content hub", "archetype_impact": "Buyer intent is narrow and high-value (independent contractors searching for payment/scope disputes); content strategy favors depth over volume, with every claim gated on evidence.", "authority_dna": { "site_archetype": "B2B service microsite with a trade-fluent evidence/authority content hub", "monetization_model": "Outcome-priced service (Authorization Boost Package + Auto-Submit subscription); content drives validation calls, not ad revenue", "main_search_intents": [ "commercial (under-authorized work order, right now)", "informational (understanding warranty-company payment/scope practices)" ], "topical_authority_opportunity": "No dedicated contractor-side authorization/appeal content hub exists today -- consumer-side denial-appeal content (Louis Law Group) and contractor-network onboarding guides (Housecall Pro, ServicePlus) both leave this specific query space open. A definitive guide to home-warranty work-order authorization plus per-warranty-company teardown pages is a genuinely underserved topical cluster.", "local_seo_opportunity": "Low -- the buyer relationship is national (contractor enrolled in a national warranty-company network); no meaningful local-intent search volume for this specific service.", "global_national_opportunity": "National (US) opportunity; international expansion out of scope until the licensing-boundary review and market validation are complete.", "easiest_ranking_path": "Long-tail, specific contractor pain queries (\"home warranty authorized amount too low,\" \"American Home Shield contractor payment delay\") with weak, generic SERPs dominated by consumer-side content not written for a contractor audience.", "hardest_ranking_path": "Broad head terms like \"home warranty companies\" -- dominated by consumer-review sites (ConsumerAffairs, Forbes Home) with years of domain authority AuthLift cannot match quickly.", "trust_credibility_requirements": [ "Named reviewer bio (role-title until named)", "Primary-source citations (IBISWorld, Forbes Home, trade press)", "Explicit disclaimer on every page with a compliance claim", "No fabricated testimonials or review stars", "Clear B2B-only, contractor-side scope statement" ], "ymyl": true, "expert_review_needed": true, "site_structure": "Homepage -> Product (Authorization Boost Package) -> Guides (pillar + supporting) -> Per-warranty-company pages -> Resources (checklists) -> About/trust -> Contact", "seo_moat": "Real, disclosed case-outcome data (once the pilot runs) plus a per-warranty-company denial-pattern and cost-benchmark library that a generic content site cannot replicate without doing the actual fulfillment work." }, "search_market": { "primary_markets": [ "US independent HVAC contractors", "US independent plumbing/electrical/appliance-repair contractors" ], "secondary_markets": [ "Contractor trade associations", "Field-service software communities (Housecall Pro, ServiceTitan users)", "Trade Facebook groups" ], "low_competition_subtopics": [ "home warranty contractor under-authorization appeal", "warranty company scope-limited repair dispute", "contractor evidence package for warranty claim" ], "high_commercial_intent": [ "home warranty authorized amount too low", "American Home Shield contractor payment delay", "how to appeal a home warranty scope denial as a contractor", "Authorization Boost Package" ], "informational": [ "what is a home warranty work order", "how home warranty companies authorize repairs", "home warranty industry statistics" ], "local_intent": [ "[PLACEHOLDER] owner to complete" ], "transactional": [ "Authorization Audit free", "AuthLift pricing", "start a case" ], "comparison": [ "AuthLift vs field-service software", "AuthLift vs consumer-side denial-appeal law firms" ], "problem_solution": [ "contractor under-authorized on warranty work order what to do", "warranty company forced band-aid repair how to appeal" ], "near_me": [ "[PLACEHOLDER] owner to complete" ], "long_tail": [ "how to document a home warranty compressor replacement for authorization", "Choice Home Warranty contractor payment dispute process", "2-10 HBW contractor authorization appeal" ], "questions": [ "what is an under-authorization on a home warranty work order", "can a contractor appeal a home warranty authorization", "how long does a home warranty appeal take", "is AuthLift an insurance adjuster" ], "emerging": [ "AI-assisted home warranty evidence packages", "contractor-side warranty payment recovery services" ], "seasonal": [ "HVAC compressor replacement authorization disputes (summer)", "furnace replacement authorization disputes (winter)" ], "underserved_serps": [ "home warranty contractor payment dispute", "warranty company scope-limited repair appeal" ], "weak_serps": [ "home warranty authorized amount too low" ], "forum_dominated_serps": [ "home warranty contractor complaints (Reddit, Facebook groups)" ], "winnable_authoritative_serps": [ "Authorization Boost Package", "AuthLift home warranty contractor authorization desk" ], "avoid_initially": [ "home warranty companies (broad consumer head term)", "best home warranty company" ], "easy_wins": [ "home warranty authorized amount too low", "American Home Shield contractor payment delay", "how to appeal a home warranty scope denial as a contractor" ], "moderate": [ "home warranty industry statistics 2026", "home warranty contractor network pay rates" ], "long_term_plays": [ "definitive guide to home warranty work order authorization", "per-warranty-company denial-pattern teardown series" ], "do_not_pursue": [ "homeowner-facing warranty claim denial content (wrong buyer)", "general home-improvement content unrelated to warranty authorization" ] }, "keyword_clusters": [ { "primary": "home warranty authorized amount too low", "related": [ "home warranty under-authorization", "warranty company lowball authorization" ], "intent": "commercial", "user_problem": "A contractor's diagnosed repair cost more than the warranty company authorized, and they don't know if it's worth fighting", "funnel": "BOFU", "business_value": "high", "ranking_difficulty": "low", "conversion_potential": "high", "content_effort": "medium", "serp_weakness": "SERP dominated by consumer-side denial content not written for a contractor audience", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Pillar / evidence guide", "reason": "High buyer intent + weak SERP + our unique reviewer-released evidence-package proof", "priority_score": 18, "priority": "P0", "bucket": "easy-win" }, { "primary": "how to appeal a home warranty scope denial as a contractor", "related": [ "home warranty scope-limited repair appeal", "band-aid fix warranty appeal" ], "intent": "commercial", "user_problem": "A warranty company scope-limited a repair to a temporary fix and the contractor needs the correct repair authorized", "funnel": "BOFU", "business_value": "high", "ranking_difficulty": "low", "conversion_potential": "high", "content_effort": "medium", "serp_weakness": "No dedicated contractor-side appeal content found", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Pillar / evidence guide", "reason": "Direct match to the Appeal & Escalation Desk product surface", "priority_score": 17, "priority": "P0", "bucket": "easy-win" }, { "primary": "American Home Shield contractor payment delay", "related": [ "American Home Shield contractor authorization", "AHS network vendor payment" ], "intent": "informational", "user_problem": "A contractor enrolled with American Home Shield wants to understand typical payment timelines and delay patterns", "funnel": "MOFU", "business_value": "high", "ranking_difficulty": "medium", "conversion_potential": "medium", "content_effort": "medium", "serp_weakness": "Sparse contractor-specific content on this exact provider relationship", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Per-warranty-company guide", "reason": "Named-provider long-tail with real search volume signal", "priority_score": 15, "priority": "P1", "bucket": "moderate" }, { "primary": "Authorization Boost Package", "related": [ "AuthLift pricing", "home warranty evidence package service" ], "intent": "commercial", "user_problem": "A contractor is evaluating AuthLift's specific paid offer", "funnel": "BOFU", "business_value": "high", "ranking_difficulty": "low", "conversion_potential": "high", "content_effort": "low", "serp_weakness": "Branded term, no real competition", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Product page", "reason": "Direct branded conversion page", "priority_score": 16, "priority": "P0", "bucket": "easy-win" }, { "primary": "home warranty industry statistics", "related": [ "home warranty market size", "home warranty premium average" ], "intent": "informational", "user_problem": "A contractor or trade journalist wants sourced industry figures", "funnel": "TOFU", "business_value": "medium", "ranking_difficulty": "high", "conversion_potential": "low", "content_effort": "medium", "serp_weakness": "Dominated by Forbes Home and IBISWorld directly; hard to outrank", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Data/statistics page", "reason": "Link-earning and topical-authority asset, not a primary conversion page", "priority_score": 9, "priority": "P2", "bucket": "long-term" }, { "primary": "Choice Home Warranty contractor payment dispute process", "related": [ "Choice Home Warranty network vendor", "Choice Home Warranty authorization appeal" ], "intent": "informational", "user_problem": "A contractor working with Choice Home Warranty wants to understand the dispute process", "funnel": "MOFU", "business_value": "medium", "ranking_difficulty": "medium", "conversion_potential": "medium", "content_effort": "medium", "serp_weakness": "Sparse contractor-specific content", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Per-warranty-company guide", "reason": "Named-provider long-tail", "priority_score": 12, "priority": "P1", "bucket": "moderate" }, { "primary": "is AuthLift an insurance adjuster", "related": [ "AuthLift licensing boundary", "AuthLift not a law firm" ], "intent": "informational", "user_problem": "A contractor or their counsel wants to confirm AuthLift's legal posture before engaging", "funnel": "BOFU", "business_value": "medium", "ranking_difficulty": "low", "conversion_potential": "medium", "content_effort": "low", "serp_weakness": "Branded term, no competition", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "FAQ / trust page", "reason": "Trust-clearing content required before a contractor commits", "priority_score": 11, "priority": "P1", "bucket": "moderate" }, { "primary": "2-10 HBW contractor authorization appeal", "related": [ "2-10 Home Buyers Warranty contractor network" ], "intent": "informational", "user_problem": "A contractor working with 2-10 HBW wants provider-specific appeal guidance", "funnel": "MOFU", "business_value": "medium", "ranking_difficulty": "medium", "conversion_potential": "medium", "content_effort": "medium", "serp_weakness": "Sparse contractor-specific content", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Per-warranty-company guide", "reason": "Named-provider long-tail", "priority_score": 10, "priority": "P2", "bucket": "long-term" } ], "topical_authority_map": { "core_topics": [ "Home warranty work order authorization", "Contractor evidence packages and appeals", "Home warranty industry structure and regulation" ], "pillars": [ { "name": "Home warranty work order authorization -- definitive guide", "core_intent": "informational", "audience": "independent HVAC, plumbing, electrical, and appliance-repair contractor owners and office/ops managers", "conversion_goal": "Free Authorization Audit signup -> paid Authorization Boost Package", "supporting_pages": [ "What counts as an under-authorization", "How warranty companies score authorization requests", "The photo/reading evidence that wins authorization on the first pass", "Home warranty work order authorization FAQs" ], "internal_links": [ "/product", "/guides/appeal-process", "/resources/checklist" ], "schema": [ "Article", "BreadcrumbList", "FAQPage (where genuine)" ], "evidence_needed": [ "Named reviewer", "Primary-source citations", "Worked example" ], "local_variants": [ "[PLACEHOLDER] owner to complete" ], "national_variants": [ "US-national (default)" ] }, { "name": "How to appeal a home warranty scope denial or under-authorization", "core_intent": "commercial", "audience": "contractors with a specific under-authorized or scope-limited work order in hand", "conversion_goal": "Start a case", "supporting_pages": [ "Under-authorization vs scope-limiting vs denial, explained", "What a structured appeal actually contains", "Contractor consent and the appeal-filing process" ], "internal_links": [ "/product", "/guides/authorization" ], "schema": [ "Article", "BreadcrumbList" ], "evidence_needed": [ "Named reviewer", "Worked example", "Licensing-boundary disclaimer" ], "local_variants": [], "national_variants": [ "US-national (default)" ] }, { "name": "Home warranty industry and regulation for contractors", "core_intent": "informational", "audience": "contractor owners evaluating whether warranty-channel work is worth it", "conversion_goal": "Newsletter / Authorization Audit signup", "supporting_pages": [ "Home warranty market size and structure", "How home warranty companies are regulated", "Why some contractors avoid warranty-channel work" ], "internal_links": [ "/guides/authorization", "/about" ], "schema": [ "Article", "BreadcrumbList" ], "evidence_needed": [ "IBISWorld citation", "Forbes Home citation", "Trade-press citation" ], "local_variants": [], "national_variants": [ "US-national (default)" ] } ], "supporting_page_types": [ "Per-warranty-company guide", "FAQ / trust page", "Data/statistics page", "Pillar / evidence guide", "Product page", "Comparison page", "About/reviewer bio", "Editorial policy", "Contact", "Pricing" ] }, "site_architecture": { "homepage_strategy": "State the outcome-priced offer, the licensing-boundary trust statement, and route to the free Authorization Audit or a validation call.", "main_nav": [ "Product", "How it works", "Pricing", "Guides", "About", "Contact" ], "footer_nav": [ "Editorial policy", "Trust & disclaimers", "Privacy", "Terms", "Per-warranty-company guides", "Contact" ], "hubs": [ { "name": "Product / Authorization Boost Package", "url": "/product", "purpose": "High-intent commercial page" }, { "name": "Guides", "url": "/guides", "purpose": "Topical-authority pillar hub" }, { "name": "Per-warranty-company pages", "url": "/warranty-companies", "purpose": "Named-provider long-tail hub" }, { "name": "Resources", "url": "/resources", "purpose": "Checklist and lead-magnet hub" }, { "name": "About / trust", "url": "/about", "purpose": "E-E-A-T and licensing-boundary trust surface" } ], "url_patterns": [ "/", "/product", "/pricing", "/guides/{slug}/", "/warranty-companies/{provider-slug}/", "/resources/{slug}/", "/about", "/contact" ], "avoid_url_patterns": [ "/blog/{random-id}/", "/category/{n}/", "duplicate provider pages under two different slugs", "thin auto-generated per-trade pages with no unique evidence" ] }, "global_national": { "national_clusters": [ "Home warranty work order authorization", "Contractor evidence packages and appeals", "Per-warranty-company authorization guides", "Home warranty industry and regulation" ], "linkable_assets": [ "Home warranty industry statistics roundup (sourced from IBISWorld/Forbes Home)", "Free photo-documentation checklist by trade", "Original Authorization Audit gap-analysis teardown (anonymized, once pilot data exists)", "Per-warranty-company denial-pattern summary (aggregated, anonymized)" ], "original_research_ideas": [ "Aggregate, anonymized average uplift secured by trade and warranty company (once pilot data exists)", "Cycle-time benchmark by warranty company (once pilot data exists)", "Photo/evidence completeness patterns that correlate with first-pass authorization (once pilot data exists)" ], "international_needed": false, "international_notes": "Out of scope until US market validation completes." }, "local_seo": { "justified": false, "reason": "The buyer relationship is a national contractor-to-warranty-company relationship, not a local search behavior; no meaningful near-me or location-page opportunity exists for this specific service.", "gbp_categories_primary": [ "[PLACEHOLDER] owner to complete" ], "gbp_categories_secondary": [ "[PLACEHOLDER] owner to complete" ], "location_page_rules": [ "Do not build location pages absent a genuine local-service signal", "If HVAC-trade-specific regional cost-benchmark content is published, tie it to the cost-benchmark library, not a location-page SEO play" ], "citations": [ "[PLACEHOLDER] owner to complete" ], "review_strategy": "No consumer-style review solicitation; any published outcome data must be real, disclosed, and consented to by the contractor.", "local_schema": [ "[PLACEHOLDER] owner to complete" ] }, "programmatic": { "recommended": true, "reason": "Per-warranty-company guides are a natural, evidence-backed programmatic pattern (one page per major provider) as long as each page carries genuinely distinct content, not templated filler.", "rules": [ "Every per-warranty-company page must cite real, sourced information specific to that provider", "No page ships without at least one unique data point or worked example", "No page auto-publishes without a content-lead review", "Providers without genuine differentiated content wait rather than ship thin" ], "per_page_requirements": [ "Named provider + trade coverage scope", "At least one sourced fact specific to that provider", "A clear CTA to the Authorization Audit or a case start" ], "quality_gates": [ "No duplicate content across provider pages beyond the shared template shell", "Minimum word count with genuine unique content, not padding", "Internal links to the relevant pillar guide" ] }, "page_templates": [ { "page_type": "Homepage", "purpose": "State the offer + route to a case start or validation call.", "target_intent": "commercial", "url_pattern": "/", "h1_pattern": "[One-sentence purpose]", "title_pattern": "[Brand] — [One-sentence purpose]", "meta_description_pattern": "One sentence outcome + CTA verb. ≤ 155 chars.", "above_the_fold": [ "H1", "Sub-headline (audience + outcome)", "Primary CTA (start a case)", "1 trust chip (reviewer / disclaimer)" ], "outline": [ "Problem framing", "3 pillar cards", "Evidence asset teaser", "Named reviewer statement", "Contact" ], "internal_links": [ "/product", "/guides", "/resources", "/about" ], "conversion_elements": [ "Calendar/case-start CTA", "Authorization Audit secondary" ], "schema": [ "Organization", "WebSite", "SearchAction" ], "trust_elements": [ "Reviewer role-title", "Editorial policy link", "Disclaimer" ], "media": [ "Original workflow diagram (SVG)" ], "faq_opportunities": [ "Top 3 buyer questions" ], "cta_strategy": "Above-the-fold soft + end-of-page primary", "quality_requirements": [ "Loads < 2.5s LCP", "Reviewer role-title visible" ], "anti_thin_rules": [ "No stock hero", "No generic 'we help X do Y' filler" ] }, { "page_type": "Product / Authorization Boost Package", "purpose": "Convert a qualified contractor to a case start.", "target_intent": "commercial", "url_pattern": "/product", "h1_pattern": "Authorization Boost Package — [outcome]", "title_pattern": "Authorization Boost Package — AuthLift", "meta_description_pattern": "Pricing + outcome + CTA. ≤ 155 chars.", "above_the_fold": [ "H1", "Pricing summary", "Guarantee statement", "Primary CTA" ], "outline": [ "What's included", "Pricing table", "Process steps", "Guarantee", "FAQ" ], "internal_links": [ "/guides/authorization", "/pricing", "/contact" ], "conversion_elements": [ "Start a case CTA", "Authorization Audit CTA" ], "schema": [ "Product", "FAQPage", "BreadcrumbList" ], "trust_elements": [ "Guarantee", "Disclaimer", "Reviewer role-title" ], "media": [ "Process diagram" ], "faq_opportunities": [ "Pricing questions", "Licensing-boundary questions" ], "cta_strategy": "Repeated CTA every 2 sections", "quality_requirements": [ "No hourly-pricing language anywhere" ], "anti_thin_rules": [ "No vague 'contact us for pricing'" ] }, { "page_type": "Pillar / evidence guide", "purpose": "Rank for a head informational/commercial term and route to conversion.", "target_intent": "informational/commercial", "url_pattern": "/guides/{slug}/", "h1_pattern": "[Primary keyword], explained", "title_pattern": "[Primary keyword] | AuthLift Guides", "meta_description_pattern": "Answer the query + CTA. ≤ 155 chars.", "above_the_fold": [ "H1", "TL;DR summary", "Jump-to-section nav" ], "outline": [ "Definition", "Why it happens", "What the evidence-based fix looks like", "Worked example", "FAQ" ], "internal_links": [ "/product", "/resources/checklist", "related guides" ], "conversion_elements": [ "Authorization Audit CTA", "Start a case CTA" ], "schema": [ "Article", "BreadcrumbList", "FAQPage (where genuine)" ], "trust_elements": [ "Reviewer role-title", "Primary-source citations" ], "media": [ "Original diagram or worked example" ], "faq_opportunities": [ "3-5 real buyer questions" ], "cta_strategy": "Mid-article + end-of-page", "quality_requirements": [ "Cites at least 2 primary sources" ], "anti_thin_rules": [ "No AI-generic filler paragraphs", "No unsupported statistics" ] }, { "page_type": "Per-warranty-company guide", "purpose": "Capture named-provider long-tail search intent with genuinely distinct content.", "target_intent": "informational/commercial", "url_pattern": "/warranty-companies/{provider-slug}/", "h1_pattern": "[Provider name] contractor authorization guide", "title_pattern": "[Provider name] Contractor Authorization Guide | AuthLift", "meta_description_pattern": "Provider-specific fact + CTA. ≤ 155 chars.", "above_the_fold": [ "H1", "Provider summary", "CTA" ], "outline": [ "Provider overview", "Known authorization/appeal process", "Common completeness-checklist requirements", "How AuthLift covers this provider" ], "internal_links": [ "/product", "/guides/appeal-process" ], "conversion_elements": [ "Start a case CTA" ], "schema": [ "Article", "BreadcrumbList" ], "trust_elements": [ "Sourced facts only", "Disclaimer" ], "media": [], "faq_opportunities": [ "Provider-specific questions" ], "cta_strategy": "End-of-page primary", "quality_requirements": [ "At least 1 unique sourced fact per provider" ], "anti_thin_rules": [ "No templated filler across providers" ] }, { "page_type": "FAQ / trust page", "purpose": "Clear licensing-boundary and trust objections before a contractor commits.", "target_intent": "informational", "url_pattern": "/trust", "h1_pattern": "Trust, disclaimers, and the licensing boundary", "title_pattern": "Trust & Disclaimers | AuthLift", "meta_description_pattern": "Licensing boundary + disclaimer summary. ≤ 155 chars.", "above_the_fold": [ "H1", "Disclaimer statement" ], "outline": [ "What AuthLift is and is not", "The disclaimer, verbatim", "Data handling", "Reviewer role" ], "internal_links": [ "/about", "/contact" ], "conversion_elements": [ "Contact CTA" ], "schema": [ "FAQPage" ], "trust_elements": [ "Full disclaimer text", "Reviewer role-title" ], "media": [], "faq_opportunities": [ "Licensing-boundary questions" ], "cta_strategy": "Soft, single CTA", "quality_requirements": [ "Disclaimer text matches BRIEF.md §5 verbatim" ], "anti_thin_rules": [ "No vague reassurance without the actual disclaimer text" ] }, { "page_type": "Data/statistics page", "purpose": "Earn links and establish topical authority with sourced figures.", "target_intent": "informational", "url_pattern": "/guides/home-warranty-industry-statistics/", "h1_pattern": "Home warranty industry statistics [year]", "title_pattern": "Home Warranty Industry Statistics | AuthLift", "meta_description_pattern": "Sourced figures + range framing. ≤ 155 chars.", "above_the_fold": [ "H1", "Headline stat range" ], "outline": [ "Market size (range, sources named)", "Premium and dispatch-fee figures", "Contractor pain data", "Source list" ], "internal_links": [ "/guides/authorization" ], "conversion_elements": [ "Newsletter / Authorization Audit CTA" ], "schema": [ "Article", "BreadcrumbList" ], "trust_elements": [ "Named sources (IBISWorld, Forbes Home)", "Update-cadence note" ], "media": [ "Sourced chart" ], "faq_opportunities": [], "cta_strategy": "End-of-page soft CTA", "quality_requirements": [ "Present ranges, not fabricated single figures, where sources disagree" ], "anti_thin_rules": [ "No reconciling conflicting source figures artificially" ] }, { "page_type": "About / reviewer bio", "purpose": "E-E-A-T trust surface naming the reviewer and editorial standards.", "target_intent": "informational", "url_pattern": "/about", "h1_pattern": "About AuthLift", "title_pattern": "About | AuthLift", "meta_description_pattern": "Who reviews the work + editorial policy. ≤ 155 chars.", "above_the_fold": [ "H1", "Reviewer role-title" ], "outline": [ "Mission", "Reviewer credentials (role-title until named)", "Editorial policy link", "Licensing boundary" ], "internal_links": [ "/trust", "/contact" ], "conversion_elements": [ "Contact CTA" ], "schema": [ "AboutPage" ], "trust_elements": [ "Reviewer role-title", "Editorial policy" ], "media": [], "faq_opportunities": [], "cta_strategy": "Soft CTA", "quality_requirements": [ "No fabricated credentials or headshots" ], "anti_thin_rules": [ "No generic stock 'our team' filler" ] }, { "page_type": "Pricing", "purpose": "State the outcome-based pricing exactly as in BRIEF.md §3.", "target_intent": "commercial", "url_pattern": "/pricing", "h1_pattern": "Pricing", "title_pattern": "Pricing | AuthLift", "meta_description_pattern": "Flat intake + contingency, no recovery no fee. ≤ 155 chars.", "above_the_fold": [ "H1", "Pricing table", "Guarantee" ], "outline": [ "Authorization Boost Package pricing", "Auto-Submit pricing", "Free Authorization Audit", "Guarantee" ], "internal_links": [ "/product", "/contact" ], "conversion_elements": [ "Start a case CTA" ], "schema": [ "Product", "FAQPage" ], "trust_elements": [ "Guarantee statement", "No-hourly-pricing statement" ], "media": [], "faq_opportunities": [ "Pricing objections" ], "cta_strategy": "Repeated CTA", "quality_requirements": [ "Figures match BRIEF.md §3 exactly" ], "anti_thin_rules": [ "No vague 'contact for a quote'" ] }, { "page_type": "Resources / checklist", "purpose": "Lead-magnet page for the photo-documentation checklist by trade.", "target_intent": "informational", "url_pattern": "/resources/{slug}/", "h1_pattern": "[Checklist name]", "title_pattern": "[Checklist name] | AuthLift Resources", "meta_description_pattern": "What the checklist covers + download CTA. ≤ 155 chars.", "above_the_fold": [ "H1", "Download CTA" ], "outline": [ "What's in the checklist", "Why it matters", "Download form" ], "internal_links": [ "/guides/authorization", "/product" ], "conversion_elements": [ "Email-gated download" ], "schema": [ "Article" ], "trust_elements": [ "Reviewer role-title" ], "media": [ "Checklist preview image" ], "faq_opportunities": [], "cta_strategy": "Single primary CTA", "quality_requirements": [ "Checklist content matches the actual intake requirements" ], "anti_thin_rules": [ "No lead-magnet bait unrelated to actual product content" ] } ], "on_page_rules": { "title_tag": "[Primary keyword] | AuthLift, ≤ 60 chars, no keyword stuffing.", "meta_description": "One sentence outcome + CTA verb, ≤ 155 chars, no fabricated claims.", "headings": "One H1 per page matching the primary keyword intent; H2s map to real subtopics, not keyword variants.", "intro": "Answer the core question in the first 2 sentences before any scene-setting.", "snippet_targeting": "Structure the first answer as a direct, quotable 40-60 word response for featured-snippet eligibility.", "tables_lists": "Use tables for pricing and comparison content; use ordered lists for process steps.", "images": "Original diagrams only; alt text describes content, not keywords; no stock photography of tools/toolboxes.", "internal_links": "Every page links to its parent pillar and at least one sibling supporting page.", "external_citations": "Cite primary sources by name (IBISWorld, Forbes Home, trade press) without requiring outbound links, per the external-request-free site constraint.", "author_attribution": "Every claim-bearing page shows the reviewer's role-title and the editorial-policy link.", "freshness": "Statistics pages carry an update-cadence note and are reviewed quarterly.", "cta_placement": "Above the fold soft CTA + a primary CTA at every natural conversion point.", "mobile": "Mobile-first layout; tables collapse to stacked cards under 480px.", "avoid": [ "\"AI-Native Blueprint\" as a title", "\"leverage AI\"", "\"streamline your workflow\"", "\"cutting-edge\"", "\"revolutionize\"", "\"unlock\"", "\"supercharge\"", "fabricated testimonials, logos, or review stars", "hourly pricing language anywhere" ] }, "entity_seo": { "main_entities": [ "AuthLift", "Authorization Boost Package", "work order", "evidence package", "warranty company", "under-authorization", "appeal", "Auto-Submit" ], "related_entities": [ "home warranty", "service contract", "contractor portal", "cost benchmark", "completeness checklist" ], "people": [ "Trade-Qualified Reviewer (role-title)", "Contractor Owner/Operator", "Business Owner/Founder" ], "orgs": [ "American Home Shield", "Cinch", "Choice Home Warranty", "First American" ], "tools": [ "Housecall Pro", "ServiceTitan", "Jobber" ], "regulations": [ "California Insurance Code Part 7 (home protection contracts)", "Texas Occupations Code Ch. 1304", "Texas TDLR", "National Home Service Contract Association", "California Department of Insurance" ], "problems": [ "under-authorization", "scope-limited band-aid repair", "delayed payment", "denied work order", "mandated low-cost parts" ], "solutions": [ "Authorization Boost Package", "Authorization Audit", "structured appeal", "Auto-Submit" ], "processes": [ "case intake", "evidence assembly", "completeness checklist", "reviewer release", "portal submission", "appeal filing" ], "alternatives": [ "consumer-side denial-appeal law firms", "contractor-network onboarding guides", "general field-service software" ], "synonyms": [ "home warranty = home service contract", "warranty company = service contract provider (never 'insurer')", "work order = service dispatch ticket (never 'claim')", "reviewer = trade-qualified reviewer or certified claims specialist" ] }, "schema_strategy": [ { "type": "Organization", "where": "Site-wide in head", "required_fields": [ "name", "url", "logo", "sameAs" ], "caution": "Keep in sync with visible About / contact; no fabricated aggregateRating." }, { "type": "WebSite", "where": "Homepage", "required_fields": [ "name", "url", "potentialAction" ], "caution": "SearchAction only if internal search actually exists." }, { "type": "Product", "where": "Product + Pricing pages", "required_fields": [ "name", "description", "offers" ], "caution": "No fabricated review or rating fields." }, { "type": "Article", "where": "Guides + statistics pages", "required_fields": [ "headline", "author", "datePublished", "dateModified" ], "caution": "Author must be the real reviewer role-title, not a fabricated name." }, { "type": "FAQPage", "where": "FAQ sections with genuine, on-page Q&A", "required_fields": [ "mainEntity" ], "caution": "Only mark up Q&A that is genuinely visible on the page; no hidden FAQ stuffing." }, { "type": "BreadcrumbList", "where": "All non-homepage pages", "required_fields": [ "itemListElement" ], "caution": "Must match the visible breadcrumb trail exactly." }, { "type": "AboutPage", "where": "About page", "required_fields": [ "name", "description" ], "caution": "No fabricated founding-date or team-size claims." } ], "internal_linking": { "pillar_to_cluster": "Every pillar guide links to all of its supporting pages in a visible 'related guides' block.", "cluster_to_pillar": "Every supporting page links back to its parent pillar in the intro or a breadcrumb.", "cluster_to_cluster": "Supporting pages cross-link where the topics genuinely relate (e.g. under-authorization guide links to the appeal-process guide).", "service_to_location": "N/A -- no location pages per local_seo.justified = false.", "faq_to_commercial": "Every FAQ answer that resolves a buying objection links to /product or /pricing.", "breadcrumbs": "Home > Guides > [Pillar] > [Supporting page], rendered visibly and in BreadcrumbList schema.", "anchor_text_rules": [ "Descriptive, keyword-relevant anchor text, never 'click here'", "No more than 2 links to the same target per page", "Anchor text varies naturally across links to the same target", "Never link with the exact-match keyword on every instance" ] }, "technical_seo": { "crawlability": "Clean XML sitemap; robots.txt allows all public routes; noindex on the pre-launch microsite until owner-action facts close.", "indexability": "Indexable only after schema_status flips from pending-owner-facts to ready.", "sitemaps": "Auto-generated sitemap.xml, split by content type (guides, provider pages, product).", "robots": "Disallow /admin, /reviewer, /ops; allow all public marketing routes once indexable.", "canonicals": "Self-referencing canonical on every page; no duplicate content across provider-page variants.", "pagination": "rel=next/prev not required at launch content volume; revisit if guide count exceeds 50.", "faceted_nav": "N/A at launch -- no faceted navigation in the initial site architecture.", "duplicate_control": "Per-warranty-company page template enforces unique required content per programmatic.quality_gates.", "redirects": "301 redirects on any URL-pattern change; no redirect chains longer than 1 hop.", "core_web_vitals": "LCP < 2.5s, CLS < 0.1, INP < 200ms as launch targets.", "mobile": "Mobile-first responsive layout; tables collapse to cards under 480px.", "accessibility": "WCAG 2.2 AA; axe-core in CI on all public marketing pages.", "js_seo": "Server-rendered content for all crawlable pages; no client-only rendering of primary content.", "rendering": "Static generation for guides and provider pages; server-rendering for dynamic pricing/product content.", "gsc_setup": "Google Search Console verified before any indexable launch; sitemap submitted.", "analytics_setup": "Privacy-respecting analytics with no PII in event payloads.", "rank_tracking": "Weekly rank tracking on the P0/P1 keyword cluster set once indexable." }, "eeat": { "author_bios": "Every claim-bearing page shows the reviewer's role-title (named once an engagement is confirmed) and a link to the editorial policy.", "expert_reviewers": "Trade-Qualified Reviewer (role-title until named) reviews all licensing-boundary and technical-accuracy content.", "editorial_policy": "Published editorial policy describing sourcing standards, update cadence, and correction process.", "fact_checking": "Every statistic cites a named primary source (IBISWorld, Forbes Home, trade press); conflicting figures presented as a range, not reconciled artificially.", "credentials": [ "Trade-Qualified Reviewer role-title", "Licensed-tradesperson attestation boundary explained on the trust page" ], "citations": "Primary sources cited by name per BRIEF.md §10; no outbound links required given the external-request-free site constraint.", "first_hand_proof": [ "Named reviewer statement", "Real, disclosed pilot outcome data once available (never fabricated in the interim)", "Original workflow diagrams" ], "update_cadence": "Statistics and per-warranty-company pages reviewed quarterly; guides reviewed on any material process change.", "monetization_disclosure": "Outcome-based pricing disclosed clearly on every commercial page; no hidden fee structure.", "ymyl_notes": "This is a YMYL-adjacent topic (contractor payment outcomes and a licensing-boundary-sensitive service). Every page with a compliance or outcome claim must carry the standing disclaimer, cite the reviewer's role, and avoid any guaranteed-outcome language. No fabricated testimonials, case results, or review stars until the pilot produces real, disclosed, consented-to data." }, "ai_search": { "principles": [ "Answer the exact query in the first 2 sentences", "Structure content so an AI answer engine can extract a clean, attributable summary", "Never state an inferred or unverified claim as settled fact", "Cite primary sources by name", "Keep the licensing-boundary disclaimer machine-readable and consistent" ], "tactics": [ "Use FAQPage schema only on genuine visible Q&A", "Write direct, quotable 40-60 word answers to head questions", "Maintain consistent entity naming (AuthLift, Authorization Boost Package, work order) across every page", "Publish an accessible, plain-language definition page for every glossary term" ], "do_not": [ "Do not claim to be the only or first company doing this (phrase as 'no dedicated competitor found in research')", "Do not state the 25-30% contingency rate as an industry-standard benchmark", "Do not fabricate case outcomes for AI-answer-engine consumption", "Do not use banned phrases from BRIEF.md §11" ] }, "conversion": { "primary_cta": "Start a case (forward a work order)", "secondary_cta": "Run a free Authorization Audit", "lead_magnets": [ "Free Authorization Audit (24-hour gap analysis)", "Free photo-documentation checklist by trade", "Home warranty industry statistics roundup" ], "trust_elements": [ "Standing disclaimer", "Reviewer role-title", "No-recovery-no-fee guarantee", "Editorial policy link" ], "per_page_paths": [ { "page_type": "Homepage", "path": "Hero CTA -> start a case. Secondary -> Authorization Audit." }, { "page_type": "Product", "path": "Pricing table -> start a case. FAQ objections -> start a case." }, { "page_type": "Pillar / evidence guide", "path": "Mid-article CTA -> Authorization Audit. End-of-page -> start a case." }, { "page_type": "Per-warranty-company guide", "path": "End-of-page -> start a case for that provider." }, { "page_type": "Resources / checklist", "path": "Email-gated download -> nurture sequence -> Authorization Audit." } ], "tracking": "Event tracking on every CTA click, form submit, and case-start; no PII in analytics payloads." }, "link_earning": { "digital_pr_ideas": [ "Aggregate, anonymized pilot-outcome data release (once available)", "Trade-press byline on contractor payment practices", "Original photo-documentation checklist as a linkable asset" ], "original_research": [ "Average uplift secured by trade and warranty company (once pilot data exists)", "Cycle-time benchmark by warranty company (once pilot data exists)" ], "directories": [ "Trade association directories", "Contractor-network resource lists" ], "expert_contributions": [ "Guest contributions to HVAC/plumbing trade publications on warranty-channel payment practices" ], "partnerships": [ "Trade association co-marketing", "Field-service software integration partner content" ], "avoid": [ "Paid link schemes", "Guest-post link farms", "Fabricated case-study link bait", "Reciprocal-link networks", "Any link-building tactic requiring an outbound request the site's external-request-free constraint prohibits" ] }, "roadmap_90d": [ { "phase": "Days 0-30: Foundation", "goal": "Establish trust + ship the product page + first pillar.", "pages": [ "Homepage", "Product page", "Pillar: Home warranty work order authorization -- definitive guide", "About + reviewer bio (role-title)", "Editorial policy", "Contact" ], "keywords_targeted": [ "home warranty authorized amount too low", "Authorization Boost Package" ], "why_first": "Without a trust surface + a real product page, everything else is unmoored.", "difficulty": "medium", "business_value": "high", "required_assets": [ "Reviewer bio", "Editorial policy", "One workflow diagram" ], "internal_links": [ "Homepage <-> Product <-> Pillar" ], "conversion_goal": "First Authorization Audit signups" }, { "phase": "Days 31-60: Evidence + trust depth", "goal": "Ship the appeal-process pillar and the trust/disclaimer page.", "pages": [ "Pillar: How to appeal a home warranty scope denial", "Trust & disclaimers page", "Pricing page", "2 per-warranty-company guides" ], "keywords_targeted": [ "how to appeal a home warranty scope denial as a contractor", "is AuthLift an insurance adjuster" ], "why_first": "Trust content clears the licensing-boundary objection before a contractor commits.", "difficulty": "medium", "business_value": "high", "required_assets": [ "Verbatim disclaimer text", "2 sourced provider facts" ], "internal_links": [ "Pillar <-> Trust <-> Pricing" ], "conversion_goal": "First 3-5 paid case starts" }, { "phase": "Days 61-90: Authority breadth", "goal": "Ship the industry/regulation pillar and a first original-research asset.", "pages": [ "Pillar: Home warranty industry and regulation for contractors", "Home warranty industry statistics page", "3 more per-warranty-company guides", "Resources: photo-documentation checklist" ], "keywords_targeted": [ "home warranty industry statistics", "American Home Shield contractor payment delay" ], "why_first": "Breadth content compounds link-earning and topical authority once the trust core is live.", "difficulty": "medium", "business_value": "medium", "required_assets": [ "Sourced statistics chart", "Checklist PDF" ], "internal_links": [ "Statistics <-> Industry pillar <-> provider guides" ], "conversion_goal": "Newsletter + checklist signups feeding the Authorization Audit funnel" } ], "roadmap_12m": [ { "phase": "Q1: Foundation + trust", "goal": "Ship the core pillar set, trust surfaces, and the first 5 per-warranty-company guides.", "pages": [ "3 pillars", "5 provider guides", "Trust/pricing/about" ], "keywords_targeted": [ "home warranty authorized amount too low", "how to appeal a home warranty scope denial", "Authorization Boost Package" ], "why_first": "Core buyer-intent content and trust surfaces must exist before scaling breadth.", "difficulty": "medium", "business_value": "high", "required_assets": [ "Reviewer bio", "Editorial policy", "5 sourced provider facts" ], "internal_links": [ "Full pillar <-> cluster <-> provider mesh" ], "conversion_goal": "Steady Authorization Audit signup rate" }, { "phase": "Q2: Provider breadth + first original research", "goal": "Cover all major warranty companies and publish the first real, disclosed pilot-outcome data if available.", "pages": [ "7 more provider guides", "Original-research statistics page" ], "keywords_targeted": [ "2-10 HBW contractor authorization appeal", "Choice Home Warranty contractor payment dispute process" ], "why_first": "Named-provider long-tail compounds once the core pillars rank.", "difficulty": "medium", "business_value": "medium", "required_assets": [ "Real pilot-outcome data (consented, disclosed)" ], "internal_links": [ "Provider guides <-> pillars" ], "conversion_goal": "Second-case conversion supported by provider-specific proof" }, { "phase": "Q3-Q4: Link earning + Auto-Submit content", "goal": "Publish linkable original-research assets and Auto-Submit-focused conversion content.", "pages": [ "Digital-PR research asset", "Auto-Submit product page", "Comparison page vs field-service software" ], "keywords_targeted": [ "AuthLift vs field-service software", "Auto-Submit subscription" ], "why_first": "Link-earning compounds domain authority once the core site is indexed and stable.", "difficulty": "high", "business_value": "high", "required_assets": [ "Aggregate anonymized outcome data", "Comparison content reviewed by the reviewer" ], "internal_links": [ "Comparison <-> product <-> pricing" ], "conversion_goal": "Auto-Submit attach rate growth" } ], "priority_pages": [ { "rank": 1, "page_title": "Home warranty authorized amount too low", "slug": "/guides/home-warranty-authorized-amount-too-low/", "page_type": "Pillar / evidence guide", "primary_keyword": "home warranty authorized amount too low", "secondary_keywords": [ "home warranty under-authorization", "warranty company lowball authorization" ], "intent": "commercial", "scope": "national", "funnel": "BOFU", "difficulty": "low", "business_value": "high", "conversion_potential": "high", "required_proof": [ "Named reviewer", "Primary-source cites", "Worked example" ], "internal_links": [ "/product", "/pricing", "/guides/appeal-process/" ], "schema": [ "Article", "BreadcrumbList" ], "cta": "Start a case", "production_priority": "P0", "why_opportunity": "High buyer intent + weak SERP + our unique reviewer-released evidence-package proof" }, { "rank": 2, "page_title": "Authorization Boost Package", "slug": "/product", "page_type": "Product page", "primary_keyword": "Authorization Boost Package", "secondary_keywords": [ "AuthLift pricing", "home warranty evidence package service" ], "intent": "commercial", "scope": "national", "funnel": "BOFU", "difficulty": "low", "business_value": "high", "conversion_potential": "high", "required_proof": [ "Guarantee statement", "Pricing table", "Disclaimer" ], "internal_links": [ "/pricing", "/guides/authorization/" ], "schema": [ "Product", "FAQPage" ], "cta": "Start a case", "production_priority": "P0", "why_opportunity": "Direct branded conversion page for the core offer" }, { "rank": 3, "page_title": "How to appeal a home warranty scope denial as a contractor", "slug": "/guides/appeal-process/", "page_type": "Pillar / evidence guide", "primary_keyword": "how to appeal a home warranty scope denial as a contractor", "secondary_keywords": [ "home warranty scope-limited repair appeal", "band-aid fix warranty appeal" ], "intent": "commercial", "scope": "national", "funnel": "BOFU", "difficulty": "low", "business_value": "high", "conversion_potential": "high", "required_proof": [ "Named reviewer", "Worked example", "Licensing-boundary disclaimer" ], "internal_links": [ "/product", "/guides/authorization/" ], "schema": [ "Article", "BreadcrumbList" ], "cta": "Start a case", "production_priority": "P0", "why_opportunity": "Direct match to the Appeal & Escalation Desk product surface" }, { "rank": 4, "page_title": "Trust & disclaimers", "slug": "/trust", "page_type": "FAQ / trust page", "primary_keyword": "is AuthLift an insurance adjuster", "secondary_keywords": [ "AuthLift licensing boundary" ], "intent": "informational", "scope": "national", "funnel": "TOFU", "difficulty": "low", "business_value": "medium", "conversion_potential": "medium", "required_proof": [ "Verbatim disclaimer", "Reviewer role-title" ], "internal_links": [ "/about", "/contact" ], "schema": [ "FAQPage" ], "cta": "Contact", "production_priority": "P0", "why_opportunity": "Clears the licensing-boundary objection before commercial commitment" }, { "rank": 5, "page_title": "Pricing", "slug": "/pricing", "page_type": "Pricing", "primary_keyword": "AuthLift pricing", "secondary_keywords": [ "home warranty contractor evidence package cost" ], "intent": "commercial", "scope": "national", "funnel": "BOFU", "difficulty": "low", "business_value": "high", "conversion_potential": "high", "required_proof": [ "Exact figures from BRIEF.md §3", "Guarantee statement" ], "internal_links": [ "/product", "/contact" ], "schema": [ "Product", "FAQPage" ], "cta": "Start a case", "production_priority": "P0", "why_opportunity": "Outcome-based pricing is itself a differentiator worth a dedicated page" }, { "rank": 6, "page_title": "American Home Shield contractor authorization guide", "slug": "/warranty-companies/american-home-shield/", "page_type": "Per-warranty-company guide", "primary_keyword": "American Home Shield contractor payment delay", "secondary_keywords": [ "American Home Shield contractor authorization" ], "intent": "informational", "scope": "national", "funnel": "MOFU", "difficulty": "medium", "business_value": "high", "conversion_potential": "medium", "required_proof": [ "Sourced provider-specific fact" ], "internal_links": [ "/product", "/guides/appeal-process/" ], "schema": [ "Article", "BreadcrumbList" ], "cta": "Start a case", "production_priority": "P1", "why_opportunity": "Named-provider long-tail with real search-volume signal" }, { "rank": 7, "page_title": "Home warranty industry and regulation for contractors", "slug": "/guides/home-warranty-industry-regulation/", "page_type": "Pillar / evidence guide", "primary_keyword": "home warranty industry statistics", "secondary_keywords": [ "home warranty market size" ], "intent": "informational", "scope": "national", "funnel": "TOFU", "difficulty": "high", "business_value": "medium", "conversion_potential": "low", "required_proof": [ "IBISWorld citation", "Forbes Home citation" ], "internal_links": [ "/guides/authorization/", "/about" ], "schema": [ "Article", "BreadcrumbList" ], "cta": "Authorization Audit", "production_priority": "P1", "why_opportunity": "Link-earning and topical-authority asset" }, { "rank": 8, "page_title": "Photo-documentation checklist by trade", "slug": "/resources/photo-documentation-checklist/", "page_type": "Resources / checklist", "primary_keyword": "home warranty repair photo documentation checklist", "secondary_keywords": [ "evidence package checklist" ], "intent": "informational", "scope": "national", "funnel": "TOFU", "difficulty": "low", "business_value": "medium", "conversion_potential": "medium", "required_proof": [ "Matches real intake requirements" ], "internal_links": [ "/guides/authorization/", "/product" ], "schema": [ "Article" ], "cta": "Download + Authorization Audit", "production_priority": "P1", "why_opportunity": "Lead-magnet asset feeding the Authorization Audit funnel" } ], "competitor_gaps": { "typical_competitor_types": [ "Consumer-side denial-appeal law firms and content sites", "Contractor-network onboarding guides", "General field-service software vendors" ], "common_weaknesses": [ "Wrong buyer (homeowner, not contractor)", "No warranty-specific evidence-package methodology", "No outcome-based pricing model", "No per-provider completeness-checklist content", "Generic dispatch/invoicing focus with no authorization-specific workflow", "No licensing-boundary transparency", "No named reviewer or editorial standard", "Thin, templated content with no worked examples" ], "how_to_beat_them": [ "Publish real, sourced, contractor-specific content no competitor has written", "Lead every page with the licensing-boundary disclaimer competitors omit", "Show the actual evidence-package methodology, not a generic 'we help you' pitch", "Cite primary sources by name instead of vague industry claims", "Name the reviewer's role explicitly", "Ship per-provider guides competitors have not written for this buyer", "Never claim a guaranteed outcome, which builds durable trust competitors' vaguer claims don't earn" ] }, "metrics": { "weekly": [ "New indexed pages", "Authorization Audit signups", "P0 keyword rank movement" ], "monthly": [ "Organic sessions", "Authorization-Audit-to-paid conversion rate", "Top 10 keyword count", "New referring domains" ], "quarterly": [ "Topical-authority coverage vs the pillar map", "Content freshness review completion", "Link-earning asset performance" ], "annual": [ "Domain authority trend", "Total organic-driven paid cases", "Content ROI vs founder-led outreach" ] }, "risks": [ { "risk": "YMYL classification triggers stricter search-quality scrutiny", "applies": true, "mitigation": "Named reviewer, primary-source citations, and the standing disclaimer on every claim-bearing page" }, { "risk": "Thin, templated per-provider pages get filtered or devalued", "applies": true, "mitigation": "Quality gates requiring at least one unique sourced fact per provider page" }, { "risk": "Fabricated or premature outcome claims damage trust and violate BRIEF.md §4", "applies": true, "mitigation": "No case-outcome claim published until the pilot produces real, disclosed, consented data" }, { "risk": "Licensing-boundary language drifts across pages over time", "applies": true, "mitigation": "Verbatim disclaimer sourced from a single content block, not re-typed per page" }, { "risk": "Competitor (a larger field-service software vendor) bundles a similar feature", "applies": true, "mitigation": "Differentiate on outcome-based pricing and the reviewer-release trust model, not just features" }, { "risk": "SERP volatility on YMYL-adjacent queries from a search-algorithm update", "applies": true, "mitigation": "Diversify traffic sources; do not rely on organic alone for the pilot cohort" }, { "risk": "External-request-free site constraint limits traditional outbound-link SEO tactics", "applies": true, "mitigation": "Lean on digital PR and original research over traditional link-building outreach" }, { "risk": "Programmatic per-provider pages mistaken for doorway pages", "applies": true, "mitigation": "Enforce genuine unique content per page per programmatic.quality_gates" }, { "risk": "Seasonal HVAC demand swings distort traffic and conversion metrics", "applies": true, "mitigation": "Report metrics with seasonal context, not raw month-over-month comparisons" }, { "risk": "Public relations risk from a warranty company objecting to published content", "applies": true, "mitigation": "Fact-check every named-provider claim against a primary source before publishing" }, { "risk": "Duplicate content across near-identical provider page templates", "applies": true, "mitigation": "Unique-content minimum enforced by the content lead before publish" }, { "risk": "Keyword cannibalization between the pillar and per-provider pages", "applies": true, "mitigation": "Clear canonical intent mapping per page in the topical_authority_map" }, { "risk": "Premature indexing before owner-action facts close", "applies": true, "mitigation": "noindex + sitemap_include=false until schema_status flips to ready" } ], "first_20_pages": [ "/", "/product", "/pricing", "/trust", "/about", "/guides/home-warranty-authorized-amount-too-low/", "/guides/appeal-process/", "/guides/home-warranty-industry-regulation/", "/warranty-companies/american-home-shield/", "/warranty-companies/cinch/", "/warranty-companies/choice-home-warranty/", "/warranty-companies/first-american/", "/warranty-companies/old-republic/", "/resources/photo-documentation-checklist/", "/resources/authorization-audit/", "/guides/home-warranty-industry-statistics/", "/contact", "/editorial-policy", "/privacy", "/terms" ], "first_10_tech_fixes": [ "Publish a clean XML sitemap covering only indexable pages", "Set noindex + sitemap_include=false until owner-action facts close", "Verify canonical tags on every page (self-referencing)", "Confirm Core Web Vitals targets on the homepage and product page", "Set up Google Search Console and submit the sitemap", "Add BreadcrumbList schema to every non-homepage page", "Ensure mobile-first responsive layout on the pricing table", "Add structured Organization schema in the site head", "Confirm robots.txt disallows /admin, /reviewer, /ops", "Set up privacy-respecting analytics with no PII in event payloads" ], "first_10_authority_actions": [ "Name the Trade-Qualified Reviewer's role-title on every claim-bearing page", "Publish the editorial policy page", "Cite IBISWorld and Forbes Home by name on the industry-statistics page", "Ship the licensing-boundary trust page with the verbatim disclaimer", "Publish the first pillar guide with a worked example", "Ship 2 per-warranty-company guides with genuinely unique sourced facts", "Publish the free photo-documentation checklist lead magnet", "Draft the aggregate anonymized outcome-data asset (publish once pilot data exists)", "Set up a quarterly content-freshness review cadence", "Identify 3 trade-press outlets for a future expert-contribution pitch" ], "final_recommendation": "Ship a narrow, evidence-led content core -- homepage, product, pricing, trust, and the two highest-intent pillar guides -- before any programmatic per-provider expansion. Treat this as a YMYL-adjacent topic: every claim-bearing page carries the standing disclaimer, cites the reviewer's role, and cites primary sources by name. Do not publish any case-outcome claim, testimonial, or review star until the pilot cohort produces real, disclosed, consented-to data. Hold per-warranty-company pages to a genuine-unique-content bar rather than shipping a templated doorway-page pattern. Prioritize the two BOFU pillars (under-authorization, appeal process) and the trust page in the first 30 days; expand to provider breadth and original research only after the trust core is live and indexable.", "disclaimers": [ "AuthLift is not a law firm, insurance adjuster, or public adjuster and does not provide legal advice; all technical repair determinations remain those of the contractor's licensed personnel.", "AuthLift does not guarantee a specific authorization outcome, warranty-company cooperation, or the accuracy of contractor-attested facts.", "No case outcomes, dollar amounts recovered, testimonials, contractor names, logos, or review stars are published until the pilot produces real, disclosed, consented-to data." ] }, "generated_at": "2026-07-15T00:00:00Z", "checksum": "35e15bc5392e8973" }