{ "version": "1.8.0", "slug": "snow-ice-storm-event-defense-desk", "title": "StormWitness — The Commercial Snow & Ice Storm Event Defense Desk", "vertical": "Commercial snow & ice management contractor back office / weather-correlated storm-event liability documentation", "seed": { "s": "snow-ice-storm-event-defense-desk", "t": "StormWitness — The Commercial Snow & Ice Storm Event Defense Desk", "v": "Commercial snow & ice management contractor back office / weather-correlated storm-event liability documentation", "r": "Medium", "m": "M" }, "product": { "slug": "snow-ice-storm-event-defense-desk", "project_name": "StormWitness — The Commercial Snow & Ice Storm Event Defense Desk", "project_type": "AI-native documentation-production service business", "vertical": "Commercial snow & ice management liability documentation / trade-contractor records-management back office", "audience": "Commercial snow & ice management contractor owners, GMs, Operations Managers, and Directors of Safety servicing 15-150 contracted commercial, multifamily, retail, or institutional sites per season, $500K-$8M seasonal revenue, in snowbelt metros (secondary: GL insurance brokers/agencies serving the trade; property managers self-performing snow removal with in-house crews)", "geography": "Chicago-land / Midwest beachhead at launch (IL, WI, MN, OH, MI); additional states are gated expansion requiring their own outside-counsel-reviewed Completeness Rulebook before activation", "scale_expectation": "3-5 commercial snow & ice contractors capped in the pilot cohort for one full season; Build-Before-Scale checkpoints at 5 files, 10 files, and 20 files gate automation and a second pilot contractor; a full-pilot-season checkpoint gates any second-beachhead-state expansion or the off-season landscaping-liability add-on — a Storm Event Defense File is produced per storm event, not on a fixed calendar cadence, so volume follows weather, not a subscription clock", "core_workflows": [ "Storm-triggered crew check-in/photo/treatment-log ingestion & normalization", "Certified NOAA/NCDC Weather Match retrieval and site/time-window correlation", "Deterministic Completeness Checklist evaluation & Storm Event Defense File drafting", "Ops/QA Reviewer sign-off, Litigation Hold senior re-verification, and Season Completeness Scorecard delivery" ], "discovery": { "one_line_purpose": "Turn the crew check-ins, geotagged photos, and treatment logs a snow contractor already generates into a complete, weather-correlated Storm Event Defense File for every contracted site before the next slip-and-fall claim lands.", "primary_users": [ "Contractor owner/GM or Operations/Risk Manager (economic buyer)", "Dispatch coordinator / office manager (champion, supplies crew data)", "GL insurance broker/agency serving the trade (secondary/phase-2 buyer)", "Contractor's own retained attorney (escalation approver on any Litigation Hold file, not a StormWitness user)" ], "jobs_to_be_done": [ "When a slip-and-fall claim shows up for a site we serviced, I need a complete, weather-correlated record of what we did and when, fast — without digging through six months of crew texts.", "When my GL insurance renews, I want to show my broker every site, every storm, has a complete documented record — not just that we have a policy.", "I don't want to lose a case or my insurance because of a missing photo or a timestamp nobody wrote down, when we actually did the work.", "I want my company known as the contractor that keeps clean records — not the one that gets dropped after a claim." ], "value_prop": "A complete, weather-correlated, human-reviewed Storm Event Defense File for every contracted site, every storm — retrievable in minutes instead of days, at a fraction of the cost of reconstructing it after the fact.", "competitors": [ "Field-documentation software (SiteCapture, Deicer, SG Advantage)", "Dispatch/operations platforms (Aspire, Service Autopilot, ArborGold)", "Point weather-certification vendors (Certified Snowfall Totals)", "Pre-launch self-operated logging apps (SnowProof, waitlist-stage)", "Post-claim expert-witness / meteorology reconstruction services" ], "differentiation": "StormWitness is the only done-for-you service that combines crew timestamps, geotagged photos, treatment logs, and certified NOAA/NCDC weather-station matching into one finished, completeness-checked, human-reviewed Storm Event Defense File — versus self-operated field-documentation tools that leave correlation and assembly to the contractor, and versus point weather-certification vendors that sell only the weather data as a standalone report.", "positioning_statement": "For commercial snow & ice management contractors carrying the full legal exposure of every winter storm, StormWitness is the documentation back office that turns crew data into a complete Storm Event Defense File within 24-48 hours — unlike dispatch software and weather-data vendors, StormWitness delivers one finished, reviewed file, never a tool the contractor has to operate or assemble themselves." }, "assumptions": [ { "id": "A1", "statement": "A commercial snow contractor with 15+ contracted sites carries enough per-storm slip-and-fall exposure for a per-site-per-month Documentation Subscription to clear their existing field-documentation and dispatch-software spend as a budget line.", "confidence": "Medium", "impact_if_wrong": "The MVP wedge would need a higher site-count floor or a bundled small-portfolio price instead of linear per-site pricing.", "revisit_trigger": "Fewer than 2 of the first 5 pilot signups meet the 15-site floor without heavy pricing negotiation." }, { "id": "A2", "statement": "A free Storm Readiness Gap Scan against a contractor's own prior claim converts to a paid pilot at a meaningful rate without the contractor perceiving the exercise as an admission of liability exposure.", "confidence": "Medium", "impact_if_wrong": "The lead magnet would need to shift from a claim-specific Gap Scan to a generic sample-site-list scan only.", "revisit_trigger": "Gap Scan-to-pilot conversion under 15% after the first 20 requests." }, { "id": "A3", "statement": "Certified NOAA/NCDC station coverage is dense enough across the Chicago-land/Midwest beachhead that low-confidence or missing Weather Match cases stay a minority of files, not the norm.", "confidence": "Medium — inferred, not yet measured against real pilot site addresses", "impact_if_wrong": "The exception-queue/alternate-station-substitution workload would be materially heavier than modeled, compressing gross margin at launch.", "revisit_trigger": "More than 15% of the first 50 Defense Files require an alternate-station substitution." } ], "unknowns": [ { "id": "U1", "question": "How close is the pre-launch SnowProof app (self-operated logging, waitlist-stage as of this research) to shipping, and will its eventual feature set close the gap with StormWitness's done-for-you assembly and human QA?", "blocks": "Long-run competitive-moat confidence", "resolution_path": "Recheck SnowProof's public status quarterly; if it ships with a done-for-you review layer, revisit differentiation copy across all artifacts." }, { "id": "U2", "question": "What fraction of Certified Snowfall Totals' existing customer base overlaps with StormWitness's ICP, and would they buy StormWitness as a complement or view it as redundant?", "blocks": "Precise objection-handling copy in gtm-kit.md and the landing page FAQ", "resolution_path": "Ask directly in early Storm Readiness Gap Scan conversations whether the contractor already buys certified snowfall data." }, { "id": "U3", "question": "What true share of the 112,000 total US snowplowing businesses are commercially-focused, multi-site contractors matching the 15-150-site ICP (the blueprint's 10-15% estimate is Inferred, not measured)?", "blocks": "Precise TAM sizing in business-plan.md and any investor-facing material", "resolution_path": "Cross-reference SIMA member directory counts and Midwest dispatch-software partner listings during Weeks 1-2 outbound-list building." } ], "expert_panel": [ { "role": "Premises-liability defense attorney", "key_concern": "StormWitness drifting into characterizing liability or invoking the 'storm in progress' doctrine on the contractor's behalf, which would constitute unauthorized practice of law.", "recommendation": "Every Defense File stays a factual record only — timestamps, photos, logs, matched weather data — with no doctrine-application language anywhere in the file; the contractor's own attorney applies the doctrine.", "dissent": "None — this is already the MVP design." }, { "role": "Snow & ice operations veteran (SIMA-adjacent)", "key_concern": "A 24-48 hour SLA is unrealistic for a multi-day storm hitting 50+ sites in one shift with a single founder doing manual fulfillment.", "recommendation": "Cap the pilot cohort at 3-5 contractors specifically to protect the SLA at launch; treat the Build-Before-Scale checkpoints (5/10/20 files) as hard gates before adding a second pilot contractor, not aspirational milestones.", "dissent": "A growth-focused reviewer might push to onboard the full cohort simultaneously; overruled by the SLA-protection rationale." }, { "role": "Insurance/risk officer", "key_concern": "A contractor or broker perceiving the Season Completeness Scorecard as a guarantee of insurance-renewal terms rather than a documentation-completeness summary.", "recommendation": "The Scorecard states explicitly that it summarizes documentation completeness only and does not represent, negotiate, or guarantee any insurance-renewal outcome.", "dissent": "None." } ], "strategy": { "business_model": "Flat per-contracted-site-per-month Documentation Subscription plus a flat claim-triggered Litigation Hold fee and a flat Season Completeness Scorecard fee; never hourly, never contingent on any claim, lawsuit, or litigation outcome.", "revenue_streams": [ "Documentation Subscription ($19-$39/contracted site/month, in-season)", "Litigation Hold expedited retrieval & certification ($250-$500/file, claim-triggered only)", "Season Completeness Scorecard ($499-$999 flat, per contractor per season)", "Off-season landscaping-liability documentation add-on ([PLACEHOLDER] — phase-2 candidate, not yet priced or sold)" ], "moat": [ "Maintained, outside-counsel-reviewed, per-jurisdiction 'storm in progress'/ongoing-storm Completeness Rulebook", "The certified NOAA/NCDC Weather Match pipeline tuned to exact site coordinates and time windows, including multi-day-storm and station-gap edge cases", "A completeness-checklist and QA process refined through the learning loop against real contractor contracts and real Litigation Hold outcomes over time", "Done-for-you assembly across BOTH raw-capture data and certified weather data, which no single existing vendor (self-operated tools or point weather-certification vendors) combines" ], "gtm": [ "Free Storm Readiness Gap Scan lead magnet against a contractor's own prior claim or sample site list", "SIMA (Snow & Ice Management Association) and regional Midwest snow-contractor associations", "Trade press (Snow Magazine, Green Industry Pros, Total Landscape Care)", "GL insurance broker/agency referral partnerships serving the trade", "Dispatch-software partner ecosystems (Aspire, Service Autopilot, ArborGold)" ], "pricing_hypothesis": "A $19-$39/site/month Documentation Subscription runs roughly 1-5% of a contractor's own seasonal per-site contract value ($2,000-$10,000) and is cheaper than a single hour of an office manager's time reconstructing one file manually (30-60 minutes per file today), while remaining profitable once human review time falls from 15-20 to 5-8 minutes per file by day 90.", "kill_criteria": [ "Any delivered Defense File later shown to have produced a materially incomplete or inaccurate record in an actual claim", "Rework/re-issue rate above 2% sustained through the first 20 files", "Fewer than 3 commercial snow contractors willing to pilot after 30 days of Chicago-land/Midwest outreach" ] }, "security": { "stride": [ { "threat": "Spoofing", "scenario": "An attacker impersonates a contractor account to submit fraudulent crew check-in data or request a fraudulent Litigation Hold.", "mitigation": "Authenticated contractor account required before any Contracted Site or Defense File record is opened; Litigation Hold requests verified against the contractor's onboarded account." }, { "threat": "Tampering", "scenario": "Crew photos, timestamps, or treatment logs are altered between field capture and Ops/QA review.", "mitigation": "Encrypted intake/storage and an append-only audit log of every ingest, draft, correction, review, and delivery event per Defense File." }, { "threat": "Repudiation", "scenario": "A contractor disputes that a Defense File was reviewed and signed off before delivery, or that a Litigation Hold file received independent Senior Reviewer verification.", "mitigation": "Reviewer IDs, Completeness Checklist results, and Weather Match confidence tier logged and retained on every file." }, { "threat": "Information disclosure", "scenario": "Site photos, crew data, or contract terms leak from the review tooling.", "mitigation": "Access-controlled review tooling limited to trained Ops/QA and Senior Reviewers; minimal data retention beyond the required multi-year window." }, { "threat": "Denial of service", "scenario": "A major multi-day storm across 50+ sites in the pilot cohort exceeds a single founder's manual-fulfillment review capacity.", "mitigation": "Pilot cap (3-5 contractors) explicitly bounds intake volume; SLA is communicated at onboarding, not promised beyond capacity." }, { "threat": "Elevation of privilege", "scenario": "A non-attorney role attempts to draft legal argument or characterize liability inside a delivered Defense File.", "mitigation": "Legal-argument and liability-characterization content is hard-excluded from every file template; any such question routes to the contractor's own attorney, never drafted by StormWitness." } ], "privacy_posture": "Minimal data retention sized to the multi-year litigation timeline, encrypted storage, and access limited to the Ops/QA and Senior Reviewers actively working a given contractor's files; no site or crew data used outside the engaged contractor's own files.", "compliance_targets": [ "'Storm in progress'/ongoing-storm doctrine evidentiary requirements (NY, and analogous doctrines documented in CT, MA, NJ, RI)", "Unauthorized-practice-of-law boundaries for a non-attorney documentation vendor", "GL insurance documentation-quality expectations referenced by insurance-agency sources (not a formal regulator)" ], "data_classifications": [ "Crew check-in timestamps, geotagged photos, treatment logs — restricted", "Contracted Site roster and contract terms — confidential", "Weather Match records and Completeness Checklist audit logs — retained, access-controlled" ] }, "devops": { "ci_cd": "Not applicable at launch-stage manual/semi-manual fulfillment; Completeness Rulebook and Defense File template changes are version-controlled and outside-counsel-reviewed before use, not continuously deployed.", "environments": [ "Founder-operated production intake/drafting workspace", "Outside-counsel-reviewed Completeness Rulebook staging (pre-activation for any new jurisdiction)" ], "observability": [ "Per-file audit log (ingest, draft, review, correction, delivery timestamps)", "Cycle-time tracking (storm end to delivery, target 24-48 hours)", "Rework/re-issue rate tracking (target <2%)" ], "testing_pyramid": [ "Manual validation of every Weather Match and completeness call for the first 5 files before any automation is trusted", "Gold-standard example-file library anchoring reviewer training and future model evaluation", "Red-team edge-case testing (missing weather-station coverage, multi-day storms, borderline reasonable-time windows) before any new jurisdiction is activated" ], "accessibility_tests": [ "Landing page contrast and keyboard-walk verification per DESIGN-STANDARD §6/§10", "Screen-reader pass on the Storm Readiness Gap Scan intake form" ], "performance_budget": "Landing page <=120KB, zero external requests, LCP <=2.5s mid-tier mobile, INP <=200ms, CLS <=0.1" }, "accessibility_i18n_ethics": { "wcag_target": "WCAG 2.2 AA", "locales": [ "en-US" ], "rtl_support": false, "ethical_risks": [ "A low-confidence Weather Match or completeness call proceeding without human confirmation", "A stale Completeness Rulebook producing a passed file after an unnoticed doctrine or case-law change" ], "ethical_guardrails": [ "100% human Ops/QA review at launch, no exceptions through the first 20 Defense Files", "Independent Senior Reviewer re-verification on every Litigation Hold file, permanently, regardless of automation maturity elsewhere", "Any doctrine-application or liability question routes to the contractor's own attorney, never automated or drafted by StormWitness" ] }, "governance": { "ownership": [ { "area": "Completeness Rulebook accuracy", "owner": "Founder/Compliance Lead + outside counsel" }, { "area": "Per-file Ops/QA review", "owner": "Ops/QA Reviewer" }, { "area": "Litigation Hold independent verification", "owner": "Senior Reviewer (never the assembling reviewer)" } ], "docs_required": [ "business-plan.md", "offer-and-pricing.md", "delivery-playbook.md", "ai-engine-spec.md", "compliance-checklist.md" ], "naming_conventions": [ "One concept = one term everywhere: Storm Event Defense File, Season Completeness Scorecard, Litigation Hold, Storm Readiness Gap Scan, Documentation Subscription, Completeness Rulebook, Completeness Checklist, Weather Match, Contracted Site, Storm Event" ], "change_control": "Any Completeness Rulebook or prompt-template change is versioned; every delivered Defense File records which Rulebook version it was produced against." }, "risk_register": [ { "id": "R1", "risk": "A Defense File omits a required element or contains an extraction error that surfaces during actual litigation.", "likelihood": "Low", "impact": "High", "mitigation": "Deterministic Completeness Checklist hard-fail rules plus 100% human Ops/QA review before any file is finalized, and independent Senior Reviewer re-verification for every incident-flagged site.", "contingency": "Re-issue the corrected file at no charge and credit the site's fee for that storm.", "owner": "Ops/QA Reviewer" }, { "id": "R2", "risk": "Certified weather-station data is unavailable, sparse, or ambiguous for a specific rural or edge-of-coverage site.", "likelihood": "Medium", "impact": "Medium", "mitigation": "Automatic fallback to the nearest verified alternate station with the substitution explicitly documented; human review required for any low-confidence match.", "contingency": "Flag the file for manual resolution before delivery; document the substitution rationale in the audit trail.", "owner": "Ops/QA Reviewer" }, { "id": "R3", "risk": "A contractor or its attorney treats a Defense File as legal advice or a guaranteed defense.", "likelihood": "Medium", "impact": "Medium", "mitigation": "Explicit non-legal-advice disclaimer on every file; onboarding materials and the services agreement make the business-records-only scope explicit.", "contingency": "Reissue onboarding materials and clarify scope directly with the contractor and, if needed, their attorney.", "owner": "Compliance Lead" }, { "id": "R4", "risk": "State-specific 'storm in progress'/ongoing-storm doctrine nuances are misapplied in the Completeness Rulebook.", "likelihood": "Medium", "impact": "High", "mitigation": "Outside counsel review before activating any new state's Rulebook; conservative, over-inclusive completeness requirements rather than assuming the most favorable doctrine interpretation.", "contingency": "Freeze new-file production for the affected jurisdiction until counsel re-validates the Rulebook.", "owner": "Compliance Lead" }, { "id": "R5", "risk": "Contractor or crew site-photo/PII data is breached or mishandled.", "likelihood": "Low", "impact": "High", "mitigation": "Encrypted intake/storage, access-controlled review tooling, minimal data-retention policy, and a documented incident-response plan from day one.", "contingency": "Execute the documented incident-response plan and notify affected contractors per compliance-checklist.md.", "owner": "Compliance Lead" } ], "roadmap": [ { "phase": "Cycle one (Days 1-7)", "weeks": "Week 1", "outcomes": [ "Completeness Checklist and weather-data pipeline access finalized for the beachhead states", "Storm Readiness Gap Scan intake built", "Outbound target list built from SIMA/regional-association directories", "First pilot contractor conversation closed" ], "exit_criteria": [ "[PLACEHOLDER] owner to complete" ], "kill_criteria": [ "[PLACEHOLDER] owner to complete" ] }, { "phase": "30 days", "weeks": "Weeks 2-4", "outcomes": [ "1-2 pilot contractors' site rosters onboarded", "First real storm event(s) processed fully manually", "First Defense Files delivered within the 24-48 hour SLA", "Structured pilot feedback collected" ], "exit_criteria": "5-file and 10-file Build-Before-Scale checkpoints reviewed", "kill_criteria": "Any delivered Defense File found materially incomplete" }, { "phase": "90 days", "weeks": "Weeks 5-12", "outcomes": [ "Full pilot cohort (3-5 contractors) onboarded", "20-file Build-Before-Scale checkpoint reached; validated low-judgment steps automated", "First Season Completeness Scorecards delivered", "Insurance-renewal feedback gathered; second-beachhead-state readiness evaluated" ], "exit_criteria": "Full-pilot-season checkpoint measured against completeness-rule accuracy, Weather Match reliability, SLA achievability, and willingness-to-pay", "kill_criteria": "Rework rate above 2% sustained, or demand proves trade-press-level only with no real willingness to pay" } ], "metrics": { "north_star": "Zero delivered Defense Files later shown to be materially incomplete in an actual claim (hard floor, never traded off for growth)", "leading": [ "% of contracted sites with a complete Defense File within 48 hours of each storm (target >=98% by pilot end)", "Median file-retrieval time when a claim is filed (target <15 minutes)", "Gap Scan-to-pilot conversion rate" ], "lagging": [ "Gross margin trend (50-65% at launch toward 65-75% by day 90)", "Pilot-to-full-season-paid conversion rate (~50-70% illustrative)", "Rework/re-issue rate (target <2%)" ], "guardrails": [ "Zero materially incomplete Defense Files", "100% human Ops/QA review through the first 20 Defense Files", "No new jurisdiction activated without an outside-counsel-reviewed, red-team-tested Completeness Rulebook" ] }, "executive_review": { "consensus": "GO — a clearly identified buyer with a painful, recurring problem tied to a verified, named legal mechanism whose evidentiary foundation is independently confirmed by a state bar association and multiple law firms; verified market size and per-site economics; verified existing category spend; a narrow single-feature MVP wedge fulfillable manually by a founder before any custom software is built.", "dissent": "A growth-ops lens would prefer onboarding the full pilot cohort simultaneously to accelerate revenue; overruled by the SLA-protection rationale behind the capped, staged pilot design.", "go_no_go": "GO", "top_3_risks": [ "A materially incomplete Defense File surfacing during actual litigation and damaging trust in a completeness-first offer", "Demand proving trade-press-level awareness without real, budgeted willingness to pay a recurring per-site subscription", "The competitive landscape shifting faster than expected (SnowProof shipping a done-for-you layer, or Certified Snowfall Totals expanding into full-file assembly)" ], "first_10_steps": [ "Finalize and outside-counsel-review the Chicago-land/Midwest Completeness Rulebook", "Build the Storm Readiness Gap Scan intake and secure file-delivery portal", "Outreach to SIMA/regional-association contacts and dispatch-software partner listings", "Deliver first free Gap Scans", "Close first pilot contractor conversation", "Onboard first pilot contractor's site roster", "Process first real storm event fully manually; deliver first Defense Files within SLA", "Review the 5-file and 10-file Build-Before-Scale checkpoints", "Expand to full pilot cohort (3-5 contractors)", "Deliver first Season Completeness Scorecards" ] } }, "project_site": { "slug": "snow-ice-storm-event-defense-desk", "app_name": "StormWitness", "archetype": "documentation-production-desk", "archetype_label": "Documentation Production Desk", "reader_role": "Commercial snow & ice contractor owner / operations manager", "one_sentence_app": "Send your crew check-ins and photos; get back a weather-correlated Storm Event Defense File for every site within 24-48 hours of every storm.", "homepage_sequence": [ "Hero + free Gap Scan CTA", "Stat strip", "Pain/stakes", "Deliverable cards", "How it works", "Pricing + guarantee", "Proof (honest placeholders)", "FAQ", "Compliance disclaimers", "Blueprint dossier footer link" ], "hero": { "frame_label": "Documentation Production Desk", "eyebrow": "For commercial snow & ice contractors with an active GL policy", "interface_title": "Your defense file needs to exist before the claim does, not after", "primary_panel_title": "Send us your crew check-ins and photos", "primary_panel_body": "Get a weather-correlated Storm Event Defense File for every contracted site, reviewed by a trained Ops/QA Reviewer, within 24-48 hours of every storm.", "side_panel_title": "What you send us / what you get back", "side_panel_items": [ "Send: dispatch-tool export or crew photo/SMS submissions, material logs, your site/contract roster", "Get: a Storm Event Defense File per site per storm, matched to certified NOAA/NCDC weather data", "Get (once or twice a season): a Season Completeness Scorecard for your GL insurance renewal" ], "status_metric": "2-3 yrs", "status_label": "typical time a slip-and-fall suit against a snow contractor takes to reach settlement — the record has to survive that long" }, "language": { "problem_heading": "The proof gap between 'we plowed it' and 'we can prove we plowed it, on time, under the right conditions'", "mechanism_heading": "How a Storm Event Defense File gets built", "proof_heading": "What's verified so far", "offer_heading": "Pricing — flat, per site, never hourly", "objection_heading": "Questions contractors actually ask", "qualification_heading": "Who this is (and isn't) for", "cta_close": "Request my free Storm Readiness Gap Scan" }, "modules": [ { "name": "Intake & Normalization", "job": "Turn dispatch-tool exports and crew photo/SMS submissions into a canonical, confidence-scored site/storm record", "artifact": "Normalized Contracted Site check-in record" }, { "name": "Weather Correlation", "job": "Retrieve certified NOAA/NCDC weather-station data matched to each site's exact coordinates and time window", "artifact": "Weather Match record with confidence tier" }, { "name": "Completeness & QA", "job": "Run the deterministic Completeness Checklist and route any gap to same-day contractor notification", "artifact": "Completeness Checklist result" }, { "name": "File Assembly & Delivery", "job": "Draft and, after Ops/QA Reviewer sign-off, deliver the finished Storm Event Defense File", "artifact": "Storm Event Defense File (PDF + archive entry)" }, { "name": "Litigation Hold", "job": "Expedite and independently re-verify a site's file when an actual claim is filed", "artifact": "Litigation Hold verification package" }, { "name": "Rulebook & Doctrine Management", "job": "Maintain the outside-counsel-reviewed, per-jurisdiction Completeness Rulebook", "artifact": "Versioned Completeness Rulebook" } ], "checkpoints": [ { "label": "5-file checkpoint", "pass": "Every Weather Match and completeness call manually validated before any automation is trusted", "fail": "A file ships with an unvalidated automated Weather Match — checkpoint blocks further automation until corrected" }, { "label": "10-file checkpoint", "pass": "24-48 hour SLA confirmed achievable at the current (still largely manual) process before a second pilot contractor is added", "fail": "SLA is missed on more than one file — second-contractor onboarding is paused" }, { "label": "20-file checkpoint", "pass": "Highest-confidence, lowest-judgment steps (ingestion, normalization, Weather Match) begin automating while 100% human sign-off continues", "fail": "Rework rate exceeds 2% — automation rollout is paused and the failure mode is root-caused" }, { "label": "Full-pilot-season checkpoint", "pass": "Completeness-rule accuracy, Weather Match reliability, SLA achievability, and real willingness-to-pay are validated — second-beachhead-state expansion or the landscaping-liability add-on may be evaluated", "fail": "Any of the four learning objectives fails validation — expansion is deferred another season" } ], "signature_scene": "A contractor's dispatch coordinator opens a claim notice, searches the StormWitness portal by site and storm date, and has the complete Defense File open in under two minutes — instead of scrolling six months of crew group-chat photos." }, "microsite": { "audience": "Commercial snow & ice management contractors (15-150 contracted sites, $500K-$8M seasonal revenue) in snowbelt metros with an active GL policy", "category": "Commercial snow & ice storm-event liability documentation", "cost_of_inaction": "A single missing photo, timestamp, or certified weather match can make the 'storm in progress' defense unavailable when a slip-and-fall claim is filed 2-3 years later — the New York State Bar Association calls certified weather records the foundation of that defense, and their absence grounds for denial.", "deliverable": "Storm Event Defense File", "dream_outcome": "Open the portal the day a claim arrives, search by site and storm date, and hand your attorney a complete, weather-correlated, already-reviewed file in minutes — for every site, every storm, without anyone digging through a season of crew texts.", "faq": [ { "q": "Is this legal advice? Will StormWitness argue my case?", "a": "No, on both counts. StormWitness produces and organizes business records — timestamps, photos, treatment logs, matched certified weather data. We never draft legal arguments, never characterize liability or fault, and never represent you in any proceeding. Whether and how to invoke the 'storm in progress' doctrine is a decision for your own attorney, using the file we hand them." }, { "q": "We already pay for SiteCapture or a dispatch tool. Why do we need this too?", "a": "Those tools capture raw data. None of them correlate it against certified NOAA/NCDC weather-station records, run a completeness check, or hand you a finished, reviewed file. They're where your evidence starts; StormWitness is what turns it into something retrievable in minutes when a claim arrives." }, { "q": "What about Certified Snowfall Totals — don't they already sell certified weather data?", "a": "They sell a meteorologist-verified snowfall report as a standalone product. They don't ingest your crew's check-in timestamps and photos, run a per-site completeness check, or hand you one finished, human-reviewed Defense File tying your service record to that weather data. StormWitness is the assembly and QA layer, not a competing weather-data source." }, { "q": "How fast do we get a Defense File after a storm?", "a": "Within 24-48 hours of the storm ending, for every contracted site, once your account is onboarded." }, { "q": "What happens if a crew misses a photo during a busy multi-property storm night?", "a": "Our Completeness Checklist flags it the same day — while it can still be corrected — instead of surfacing the gap 18 months later when a claim is filed." }, { "q": "How is this priced?", "a": "Flat, per contracted site, per month, in-season: $19-$39/site. Never hourly, never a percentage of anything." }, { "q": "What if we actually get a claim?", "a": "Request a Litigation Hold: a flat $250-$500 fee for expedited retrieval and independent Senior Reviewer re-verification of that site's file, charged only when a real claim triggers it — never contingent on how the claim turns out." }, { "q": "Where does StormWitness operate?", "a": "The pilot launches in the Chicago-land/Midwest beachhead (IL, WI, MN, OH, MI). Additional states require their own outside-counsel-reviewed Completeness Rulebook before activation." } ], "guarantee": "If a Storm Event Defense File is late or incomplete because of a failure in our own process — not because your crew didn't submit evidence — we re-issue it free and credit the site's fee for that storm. You can cancel at any season boundary. We do not guarantee any claim, lawsuit, or insurance-renewal outcome — no documentation vendor honestly can, and StormWitness performs no legal work — but we guarantee our own completeness process.", "hook": "We'll turn your crew's check-ins and photos into a weather-correlated Storm Event Defense File within 24-48 hours of every storm — before the claim shows up, not after.", "indexable": true, "lexicon": { "cta_verb": "Request my free Storm Readiness Gap Scan", "enforcement_stakes": "Loss of the 'storm in progress' defense (certified weather records are its evidentiary foundation, per NYSBA) plus GL insurance renewal exposure if documentation is incomplete", "intake_checklist": [ "[PLACEHOLDER] owner to complete" ], "persona": "Commercial snow & ice management contractor owner/GM or Operations/Risk Manager", "persona_moment": "A slip-and-fall claim notice, a GL insurance-renewal questionnaire, or a new multi-site contract with tighter indemnification language lands on their desk", "regulator": "No formal regulator — liability runs through state civil courts applying premises-liability doctrine (the 'storm in progress'/ongoing-storm doctrine); the contractor's own retained attorney is the legal-sufficiency approver", "regulator_faqs": [ { "q": "Who enforces the 'storm in progress' doctrine?", "a": "There is no dedicated agency. It is a defense a contractor's attorney raises in civil litigation when a slip-and-fall claim is filed, and its evidentiary foundation is certified NOAA/NCDC weather records." }, { "q": "Does the doctrine apply the same way in every state?", "a": "No — it is documented in NY and analogous 'ongoing storm' doctrines exist in CT, MA, NJ, and RI, with likely-similar doctrines elsewhere. Each state's Completeness Rulebook is activated only after outside-counsel review of that state's specific case law." } ], "regulator_full": "State civil courts applying the 'storm in progress'/ongoing-storm premises-liability doctrine", "retention": "Defense File evidence, Weather Match records, Completeness Checklist results, and reviewer sign-offs retained for the multi-year period the client's litigation-timeline risk requires, per the services agreement", "statute": "\"Storm in progress\" doctrine", "statute_frame": "The 'storm in progress'/ongoing-storm premises-liability doctrine, whose evidentiary foundation is certified NOAA/NCDC weather-station data (New York State Bar Association)", "trigger_moment": "A slip-and-fall claim notice, a GL insurance-renewal questionnaire, a new multi-site contract, or a tow/dispatch-vendor change", "trust_standards_specific": [ "[PLACEHOLDER] owner to complete" ] }, "mechanism": { "name": "The Storm Event Defense File pipeline", "steps": [ { "title": "Storm ends, data comes in", "body": "We ingest your dispatch-tool export or accept direct crew photo/SMS submissions — whichever you already use." }, { "title": "Weather Match runs", "body": "We pull certified NOAA/NCDC station data matched to each site's exact coordinates and time window." }, { "title": "Completeness Checklist runs", "body": "A hard-fail rule set checks every required element before any file moves forward; gaps are flagged the same day." }, { "title": "Ops/QA Reviewer signs off", "body": "A trained reviewer confirms completeness on every file before it's marked final — no file ships on AI judgment alone." } ] }, "northStarCta": { "href": "#gap-scan", "label": "Request my free Storm Readiness Gap Scan", "secondary_href": "/snow-ice-storm-event-defense-desk/blueprint/", "secondary_label": "View the full operating blueprint dossier" }, "objections": [ { "q": "We already pay for a dispatch tool — why do we need this too?", "a": "Dispatch tools capture raw data and manage routing. None of them correlate that data against certified weather records or hand you a finished, reviewed file. That's a documentation gap, not a software gap." }, { "q": "Isn't this just legal advice with extra steps?", "a": "No. We produce and organize business records against a Completeness Checklist and hand you a finished file. We never opine on the legal sufficiency of a specific claim — that stays with your retained attorney." }, { "q": "What if our GL insurer already asks for documentation?", "a": "That's exactly the conversation the Season Completeness Scorecard is built for — a season-end summary you can hand your broker at renewal, not something you assemble the night before." } ], "offer": "Storm Event Defense File Documentation Subscription — $19-$39 per contracted site per month, in-season, plus a free Storm Readiness Gap Scan and a claim-triggered Litigation Hold add-on. Never hourly, never contingent on any claim outcome.", "offer_stack": [ { "item": "Free Storm Readiness Gap Scan", "note": "$0 lead magnet, one-page gap analysis" }, { "item": "Documentation Subscription (per contracted site)", "note": "$19-$39/site/month, in-season (~5 months)" }, { "item": "Litigation Hold expedited retrieval & certification", "note": "$250-$500/file, claim-triggered only" }, { "item": "Season Completeness Scorecard", "note": "$499-$999 flat, per contractor per season" } ], "problem": "Every winter storm is a legal event at every contracted site. Crews plow, shovel, and apply de-icer under time pressure, often overnight, across dozens of properties in one shift. The proof that it happened, on time, under the right conditions — a timestamped check-in, a geotagged photo, a material-application log, and certified weather data proving exactly when precipitation started and stopped — exists only if someone captured, correlated, and preserved it. It has to survive intact for the 2-3 years a typical slip-and-fall lawsuit takes to resolve.", "process": [ { "title": "Onboarding", "body": "Site/contract roster, dispatch-tool export access or photo/SMS intake setup, Completeness Rulebook activated for your operating states." }, { "title": "Storm event occurs", "body": "Crews perform service and capture check-in/out timestamps and geotagged photos via their existing workflow." }, { "title": "Ingestion & Weather Match", "body": "Within hours of storm end, we ingest the data and pull matched certified weather data for each site." }, { "title": "Completeness Checklist", "body": "Deterministic hard-fail rules run before any file moves forward; gaps are flagged back to you the same day." }, { "title": "Ops/QA Reviewer sign-off", "body": "A trained reviewer confirms completeness on every file within the 24-48 hour SLA." }, { "title": "Delivery & season rollup", "body": "Files land in your searchable portal; a Season Completeness Scorecard rolls up the whole season ahead of your GL renewal." } ], "proof_angle": { "headline": "What's verified vs. what's still a pilot placeholder", "id": "stormwitness-proof-1", "lever": "Market size, doctrine mechanics, and pricing evidence are independently source-checked; pilot outcomes are honest placeholders until the first storm ships", "outcome_frame": "Every claim on this page is labeled verified, inferred, or a placeholder — never presented as more certain than it is", "outcome_verb": "verify", "proof_promise": "First pilot Defense File delivery time, first Litigation Hold turnaround, and the first Season Completeness Scorecard's completeness rate will publish here as soon as they exist" }, "proof_pillars": [ { "title": "Doctrine and market verified", "body": "'Storm in progress' evidentiary mechanics confirmed against NYSBA, Lewis Brisbois, and Marshall Dennehey; $22.9B/112,000-business market size confirmed against IBISWorld 2026." }, { "title": "Existing category spend verified", "body": "SiteCapture field-documentation pricing ($110-$850/mo) and typical seasonal per-site contract value ($2,000-$10,000) confirmed current as of July 2026." }, { "title": "Pilot results — placeholder", "body": "[PLACEHOLDER] First pilot cohort's Defense File delivery times and Season Completeness Scorecard results will appear here after the first storm ships." } ], "shortTitle": "StormWitness", "specific_pains": [ "Crew group-chat photos with no certified weather match tying them to the exact storm window", "No correlation between a dispatch tool's raw GPS pings and certified NOAA/NCDC station data", "A claim filed 18 months after a storm, when the evidence has scattered across phones and staff turnover", "A GL insurance renewal questionnaire asking for documentation completeness the office has never tracked", "A dispatch platform that confirms a crew was on-site but never checks that a photo, timestamp, and material log all exist" ], "stakes_line": "A missing weather match on one site is enough to make the 'storm in progress' defense unavailable — the New York State Bar Association calls its absence grounds for denial.", "sub_headline": "A weather-correlated Storm Event Defense File for every contracted site, every storm — reviewed by a trained Ops/QA Reviewer within 24-48 hours, never a tool you have to operate.", "trust": { "data_handling": "Crew photos, timestamps, and treatment logs are encrypted in storage, access-limited to the Ops/QA and Senior Reviewers working your files, and never used outside your own engagement.", "response_time": "24-48 hours standard from storm end to delivered Defense File; Litigation Hold verification within one business day of request.", "standards": [ "[PLACEHOLDER] owner to complete" ] }, "ubiquitousLanguage": { "audience": "Commercial snow & ice management contractor", "cta_primary": "Request my free Storm Readiness Gap Scan", "cta_secondary": "View the full operating blueprint dossier", "deliverable": "Storm Event Defense File", "domain": "Commercial snow & ice storm-event liability documentation", "event_conversation_requested": "domain.diagnostic_requested", "event_intake_started": "ui.cta_primary", "record": "Storm Event Defense File", "regulator": "State civil courts applying the 'storm in progress'/ongoing-storm doctrine", "regulator_full": "State civil courts applying the 'storm in progress'/ongoing-storm premises-liability doctrine", "reviewer": "Ops/QA Reviewer", "statute": "\"Storm in progress\" doctrine", "trigger_moment": "A slip-and-fall claim notice, a GL insurance-renewal questionnaire, or a new multi-site contract", "unit_of_work": "Contracted Site" }, "unit_of_work": "Contracted Site", "urgency": "Every storm without a completed Defense File is live, uncorrelated exposure the next time a claim is filed — not a someday risk.", "who_this_is_not_for": [ "[PLACEHOLDER] owner to complete" ] }, "ddd": { "subdomains": [ { "name": "Intake & Normalization", "type": "Supporting", "description": "Ingests dispatch-tool exports and crew photo/SMS submissions and normalizes them into a canonical, confidence-scored per-site record.", "reason": "Every downstream context depends on clean, normalized evidence.", "business_value": "Reduces the manual reconciliation work that today falls on a contractor's thin winter back office.", "recommendation": "Keep manual-first (founder pulls exports directly) until the 20-file checkpoint validates automation.", "ai_involvement": "AI-assisted field extraction from photos and export files.", "human_involvement": "Founder/Ops staff manually pull exports and resolve ambiguous submissions at launch.", "risks": [ "Data drift across dispatch-tool export formats if not versioned" ], "validation_questions": [ "Does the fallback photo/SMS intake path work as well as dispatch-tool export ingestion?" ] }, { "name": "Weather Correlation", "type": "Core", "description": "Retrieves certified NOAA/NCDC weather-station data matched to each Contracted Site's exact coordinates and the Storm Event's time window.", "reason": "This is the specific evidentiary element the 'storm in progress' doctrine requires and no self-operated competitor tool provides as a done-for-you match.", "business_value": "The single highest-leverage, evidentiarily necessary AI-native task in the business.", "recommendation": "Invest first here; this is the primary durable differentiator.", "ai_involvement": "Automated station lookup and confidence scoring; low-confidence matches routed to human resolution.", "human_involvement": "Ops/QA Reviewer resolves low-confidence or missing-station matches against alternate verified stations.", "risks": [ "Sparse station coverage in rural or edge-of-coverage sites" ], "validation_questions": [ "What % of the beachhead's contracted sites have dense enough NOAA/NCDC station coverage for a high-confidence match?" ] }, { "name": "Completeness & QA", "type": "Core", "description": "Runs the deterministic Completeness Checklist against every Defense File and routes gaps to same-day contractor notification.", "reason": "This is the trust chokepoint — the promise that no file ships known-incomplete.", "business_value": "Directly protects the north-star metric (zero materially incomplete files).", "recommendation": "100% human sign-off at launch, tapering only as the deterministic rulebook is validated.", "ai_involvement": "Deterministic rule evaluation plus AI-assisted photo QA (image quality, timestamp/geotag presence).", "human_involvement": "Ops/QA Reviewer signs off on every file; Senior Reviewer independently re-verifies incident-flagged files.", "risks": [ "A hard-fail rule missing an edge case (multi-day storms, borderline reasonable-time windows)" ], "validation_questions": [ "Does the Completeness Checklist need per-contract-type variants beyond per-jurisdiction variants?" ] }, { "name": "File Assembly & Delivery", "type": "Core", "description": "Drafts the structured Storm Event Defense File and delivers it to the contractor's searchable portal once Ops/QA sign-off is complete.", "reason": "This is the actual deliverable the contractor is paying for.", "business_value": "Converts normalized evidence and a Weather Match into the finished, retrievable artifact.", "recommendation": "Templated PDF generation from structured data; keep the draft step AI-assisted but never auto-published.", "ai_involvement": "AI drafts the structured file from normalized inputs; never marks itself final.", "human_involvement": "Ops/QA Reviewer performs the final sign-off before delivery.", "risks": [ "Template drift if the Completeness Rulebook changes without a corresponding template update" ], "validation_questions": [ "Is 24-48 hours the right SLA for every storm size, or does a major multi-day event need a longer, communicated SLA?" ] }, { "name": "Litigation Hold", "type": "Core", "description": "Expedites retrieval and performs independent Senior Reviewer re-verification of a site's Defense File when an actual claim or lawsuit is filed.", "reason": "This is the highest-stakes, claim-triggered moment in the business and the reason the file exists at all.", "business_value": "The premium, urgency-priced service tier; also the moment StormWitness's reputation is made or broken.", "recommendation": "Stays fully human indefinitely — never automate the independent-verification step.", "ai_involvement": "None in the verification decision itself; AI may assist retrieval speed only.", "human_involvement": "Senior Reviewer, independent of the original assembling reviewer, verifies and certifies within one business day.", "risks": [ "A single founder cannot provide a genuinely independent second reviewer — flagged as a hiring/partnership need" ], "validation_questions": [ "Who serves as the second, independent reviewer before the founder can hire a dedicated Senior Reviewer?" ] }, { "name": "Rulebook & Doctrine Management", "type": "Supporting", "description": "Maintains the versioned, outside-counsel-reviewed, per-jurisdiction Completeness Rulebook that encodes each state's 'storm in progress'/ongoing-storm doctrine requirements.", "reason": "The moat is the maintained rulebook, not the AI model.", "business_value": "Durable competitive differentiation; gates any new-state expansion.", "recommendation": "No jurisdiction activates without outside-counsel sign-off; conservative, over-inclusive requirements by default.", "ai_involvement": "AI monitors legal-update source feeds for change signals; never determines doctrine content itself.", "human_involvement": "Outside counsel reviews and signs off on every Rulebook version before activation.", "risks": [ "A doctrine change going undetected between counsel-review cycles" ], "validation_questions": [ "What cadence of legal-update monitoring is sufficient to catch a mid-season doctrine change?" ] }, { "name": "Contractor Onboarding", "type": "Supporting", "description": "Collects the site/contract roster, sets up dispatch-tool export access or photo/SMS intake, and activates the Completeness Rulebook for the contractor's operating states.", "reason": "Every downstream context depends on a correctly onboarded Contracted Site roster.", "business_value": "First-touch relationship-building moment; sets SLA and scope expectations.", "recommendation": "Templated intake checklist with AI-assisted rule-mapping suggestions, human relationship-building throughout.", "ai_involvement": "AI-assisted mapping of a new contractor's contract terms onto the Completeness Rulebook.", "human_involvement": "Founder/Ops staff personally onboard every pilot contractor.", "risks": [ "Incomplete roster capture causing gaps discovered mid-season" ], "validation_questions": [ "Is a spreadsheet-based roster upload sufficient at pilot scale, or does a structured web form outperform it?" ] }, { "name": "Season Reporting", "type": "Supporting", "description": "Assembles the Season Completeness Scorecard from the full season's Defense File archive ahead of the contractor's GL insurance renewal.", "reason": "Converts the season's documentation record into a broker-facing renewal artifact — the secondary, insurer-facing value proposition.", "business_value": "Season-boundary re-engagement point that raises switching costs as archive depth grows.", "recommendation": "Automate the rollup once the underlying Defense File data is stable; keep interpretive framing human-reviewed.", "ai_involvement": "AI assembles the completeness-rate rollup from structured Defense File data.", "human_involvement": "Ops/QA Reviewer or Compliance Lead reviews the Scorecard's framing before delivery.", "risks": [ "Overstating what the Scorecard represents to an insurance underwriter" ], "validation_questions": [ "What format do GL insurance brokers actually want the Scorecard delivered in?" ] } ], "bounded_contexts": [ { "name": "Intake & Normalization", "purpose": "Ingests dispatch-tool exports and crew photo/SMS submissions and normalizes them into a canonical, confidence-scored per-site record.", "subdomain": "Intake & Normalization", "type": "Supporting", "owned_language": [ "'Intake & Normalization' always means the same thing here as on the landing page and in delivery-playbook.md" ], "owns": [ "Raw dispatch-tool exports", "Raw crew photo/SMS submissions", "Normalized Contracted Site check-in records", "Confidence scores" ], "does_not_own": [ "Weather Match resolution", "Completeness Checklist evaluation" ], "primary_actors": [ "Dispatch coordinator / office manager", "Crew field staff" ], "entities": [ "ContractedSite", "CrewCheckIn", "EvidenceItem" ], "value_objects": [ "Deadline/Window (24-48hr SLA)", "SLA" ], "aggregates": [ "ContractedSite" ], "domain_services": [ "IntakeNormalizationService" ], "application_services": [ "IntakeIngestionService" ], "commands": [ "SubmitCrewCheckIn" ], "domain_events": [ "CrewCheckInIngested", "EvidenceItemAttached" ], "policies": [ "Any field below the confidence threshold must be Ops/QA-confirmed before drafting continues" ], "specifications": [ "A DefenseFile cannot proceed to Weather Match while any required check-in is unconfirmed" ], "invariants": [ "A ContractedSite's confirmed check-in fields are immutable except via a logged correction" ], "human_roles": [ "Ops/QA Reviewer" ], "ai_agents": [ "Intake Normalization Agent" ], "inputs": [ "Dispatch-tool export", "Crew photo/SMS submission" ], "outputs": [ "Normalized ContractedSite check-in record" ], "interfaces": [ "Intake portal", "Dispatch-tool API/CSV connector" ], "external_integrations": [ "Aspire / Service Autopilot / ArborGold export" ], "data_owned": [ "Raw uploads", "Confidence scores", "Normalized check-in records" ], "risks": [ "Dispatch-tool export format drift if not versioned" ] }, { "name": "Weather Correlation", "purpose": "Retrieves certified NOAA/NCDC weather-station data matched to each Contracted Site's exact coordinates and the Storm Event's time window.", "subdomain": "Weather Correlation", "type": "Core", "owned_language": [ "'Weather Correlation' always means the same thing here as on the landing page and in delivery-playbook.md" ], "owns": [ "Weather Match records", "Weather-station confidence tiers" ], "does_not_own": [ "Completeness Checklist rules", "File drafting" ], "primary_actors": [ "Ops/QA Reviewer" ], "entities": [ "WeatherMatchRecord" ], "value_objects": [ "Deadline/Window (site + storm time window)", "Status/state labels" ], "aggregates": [ "StormEvent" ], "domain_services": [ "WeatherMatchService" ], "application_services": [ "WeatherCorrelationService" ], "commands": [ "RunWeatherMatch" ], "domain_events": [ "WeatherMatchResolved", "WeatherMatchLowConfidenceFlagged" ], "policies": [ "A low-confidence match must be resolved by a human before the file can pass completeness" ], "specifications": [ "A WeatherMatchRecord must reference the exact site coordinates and storm time window" ], "invariants": [ "A DefenseFile cannot reach CompletenessCheckPassed without a resolved WeatherMatchRecord" ], "human_roles": [ "Ops/QA Reviewer" ], "ai_agents": [ "Weather Match Agent" ], "inputs": [ "ContractedSite coordinates", "StormEvent time window" ], "outputs": [ "WeatherMatchRecord" ], "interfaces": [ "NOAA/NCDC weather-data API" ], "external_integrations": [ "NOAA/NCDC certified station data API" ], "data_owned": [ "Weather Match records", "Station-distance/confidence data" ], "risks": [ "Sparse station coverage in rural sites" ] }, { "name": "Completeness & QA", "purpose": "Runs the deterministic Completeness Checklist against every Defense File and routes gaps to same-day contractor notification.", "subdomain": "Completeness & QA", "type": "Core", "owned_language": [ "'Completeness & QA' always means the same thing here as on the landing page and in delivery-playbook.md" ], "owns": [ "Completeness Checklist rules", "Completeness Checklist results", "Exception Queue" ], "does_not_own": [ "File drafting", "Weather Match resolution" ], "primary_actors": [ "Ops/QA Reviewer" ], "entities": [ "CompletenessCheckResult", "ExceptionCase" ], "value_objects": [ "Status/state labels (PASS/hard-fail/needs-input/exceptioned)" ], "aggregates": [ "DefenseFile" ], "domain_services": [ "CompletenessRuleEngine" ], "application_services": [ "CompletenessQAService" ], "commands": [ "RunCompletenessCheck", "ApproveDefenseFile" ], "domain_events": [ "CompletenessCheckPassed", "CompletenessCheckFailed", "GapFlaggedToContractor", "DefenseFileApproved" ], "policies": [ "No file ships known-incomplete; deterministic hard-fail rules run before any human sees the file" ], "specifications": [ "A DefenseFile cannot be Approved without an Ops/QA Reviewer sign-off" ], "invariants": [ "A DefenseFile's Approved state is immutable except via a logged re-issue" ], "human_roles": [ "Ops/QA Reviewer" ], "ai_agents": [ "Photo QA Agent" ], "inputs": [ "Normalized check-in record", "WeatherMatchRecord" ], "outputs": [ "CompletenessCheckResult", "Gap notification" ], "interfaces": [ "Ops/QA review workbench" ], "external_integrations": [], "data_owned": [ "Completeness Checklist results", "Exception Queue records" ], "risks": [ "A hard-fail rule missing a real edge case" ] }, { "name": "File Assembly & Delivery", "purpose": "Drafts the structured Storm Event Defense File and delivers it to the contractor's searchable portal once Ops/QA sign-off is complete.", "subdomain": "File Assembly & Delivery", "type": "Core", "owned_language": [ "'File Assembly & Delivery' always means the same thing here as on the landing page and in delivery-playbook.md" ], "owns": [ "DefenseFile drafts and finals", "Client-facing archive" ], "does_not_own": [ "Completeness rule evaluation", "Weather Match resolution" ], "primary_actors": [ "Ops/QA Reviewer", "Contracted Site's dispatch coordinator" ], "entities": [ "DefenseFile" ], "value_objects": [ "Money (subscription price)", "Deadline/Window (24-48hr SLA)" ], "aggregates": [ "DefenseFile" ], "domain_services": [ "FileAssemblyService" ], "application_services": [ "DeliveryService" ], "commands": [ "DeliverDefenseFile" ], "domain_events": [ "DefenseFileDrafted", "DefenseFileDelivered" ], "policies": [ "A file is delivered only after DefenseFileApproved is recorded" ], "specifications": [ "A delivered DefenseFile must be retrievable by site and storm date within the searchable archive" ], "invariants": [ "A DefenseFile cannot be delivered while CompletenessCheckResult is FAIL" ], "human_roles": [ "Ops/QA Reviewer" ], "ai_agents": [ "Defense File Drafting Agent" ], "inputs": [ "Approved DefenseFile draft" ], "outputs": [ "Delivered PDF Defense File", "Archive entry" ], "interfaces": [ "Client-facing searchable portal" ], "external_integrations": [], "data_owned": [ "Delivered file archive" ], "risks": [ "Template drift after a Completeness Rulebook update" ] }, { "name": "Litigation Hold", "purpose": "Expedites retrieval and performs independent Senior Reviewer re-verification of a site's Defense File when an actual claim or lawsuit is filed.", "subdomain": "Litigation Hold", "type": "Core", "owned_language": [ "'Litigation Hold' always means the same thing here as on the landing page and in delivery-playbook.md" ], "owns": [ "LitigationHoldRequest records", "Senior Reviewer verification memos" ], "does_not_own": [ "Routine Defense File assembly" ], "primary_actors": [ "Senior Reviewer", "Contractor's own attorney (external)" ], "entities": [ "LitigationHoldRequest" ], "value_objects": [ "Money ($250-$500/file)", "SLA (1 business day)" ], "aggregates": [ "LitigationHoldRequest" ], "domain_services": [ "LitigationHoldVerificationService" ], "application_services": [ "LitigationHoldRequestService" ], "commands": [ "RequestLitigationHold", "VerifyLitigationHold" ], "domain_events": [ "LitigationHoldRequested", "LitigationHoldVerified" ], "policies": [ "The verifying Senior Reviewer must never be the same person who assembled the original file" ], "specifications": [ "A LitigationHoldRequest cannot be closed without an independent verification memo" ], "invariants": [ "LitigationHoldVerified requires a Senior Reviewer distinct from the original DefenseFile's Ops/QA Reviewer" ], "human_roles": [ "Senior Reviewer" ], "ai_agents": [], "inputs": [ "Existing DefenseFile", "Claim/lawsuit trigger notice" ], "outputs": [ "Litigation Hold verification package" ], "interfaces": [ "Expedited-request intake" ], "external_integrations": [], "data_owned": [ "Litigation Hold verification memos" ], "risks": [ "A single founder cannot provide genuine reviewer independence pre-hire" ] }, { "name": "Rulebook & Doctrine Management", "purpose": "Maintains the versioned, outside-counsel-reviewed, per-jurisdiction Completeness Rulebook that encodes each state's 'storm in progress'/ongoing-storm doctrine requirements.", "subdomain": "Rulebook & Doctrine Management", "type": "Supporting", "owned_language": [ "'Rulebook & Doctrine Management' always means the same thing here as on the landing page and in delivery-playbook.md" ], "owns": [ "Completeness Rulebook versions", "Per-jurisdiction doctrine library" ], "does_not_own": [ "File-level completeness evaluation (consumes the Rulebook, does not own it)" ], "primary_actors": [ "Compliance Lead", "Outside counsel (external)" ], "entities": [ "CompletenessRulebookVersion" ], "value_objects": [ "Statute/doctrine refs ('storm in progress' doctrine, jurisdiction-specific)" ], "aggregates": [ "CompletenessRulebookVersion" ], "domain_services": [ "RulebookVersioningService" ], "application_services": [ "RulebookGovernanceService" ], "commands": [ "ActivateJurisdictionRulebook" ], "domain_events": [ "RulebookUpdated" ], "policies": [ "No new jurisdiction activates without outside-counsel sign-off; conservative, over-inclusive requirements preferred over the most favorable doctrine reading" ], "specifications": [ "Every DefenseFile records which Rulebook version it was produced against" ], "invariants": [ "A Rulebook version cannot be activated without a logged outside-counsel review record" ], "human_roles": [ "Compliance Lead" ], "ai_agents": [ "Legal-update monitoring assistant (signal-flagging only, non-authoritative)" ], "inputs": [ "Legal-update source feeds", "Outside counsel review" ], "outputs": [ "Versioned Completeness Rulebook" ], "interfaces": [ "Rulebook version-control store" ], "external_integrations": [ "Legal-update monitoring feeds" ], "data_owned": [ "Rulebook version history", "Change log" ], "risks": [ "A doctrine change going undetected between review cycles" ] }, { "name": "Contractor Onboarding", "purpose": "Collects the site/contract roster, sets up dispatch-tool export access or photo/SMS intake, and activates the Completeness Rulebook for the contractor's operating states.", "subdomain": "Contractor Onboarding", "type": "Supporting", "owned_language": [ "'Contractor Onboarding' always means the same thing here as on the landing page and in delivery-playbook.md" ], "owns": [ "Contractor account records", "Site/contract roster" ], "does_not_own": [ "Ongoing file production" ], "primary_actors": [ "Founder/Ops staff", "Contractor owner/GM" ], "entities": [ "ContractorAccount", "ContractedSite" ], "value_objects": [ "SLA", "Money (subscription price)" ], "aggregates": [ "ContractedSite" ], "domain_services": [ "OnboardingRuleMappingService" ], "application_services": [ "ContractorOnboardingService" ], "commands": [ "OnboardContractorAccount" ], "domain_events": [ "ContractorOnboarded", "ContractedSiteRegistered" ], "policies": [ "Completeness Rulebook activation must match the contractor's actual operating states" ], "specifications": [ "A ContractedSite cannot generate a DefenseFile until its ContractorAccount is onboarded" ], "invariants": [ "ContractedSite records are scoped to exactly one ContractorAccount" ], "human_roles": [ "Founder/Ops staff" ], "ai_agents": [], "inputs": [ "Site/contract roster upload", "Dispatch-tool access grant" ], "outputs": [ "Onboarded ContractorAccount", "Activated ContractedSite roster" ], "interfaces": [ "Onboarding intake checklist" ], "external_integrations": [ "Dispatch-tool export access grant" ], "data_owned": [ "Contractor account and roster records" ], "risks": [ "Incomplete roster capture causing mid-season gaps" ] }, { "name": "Season Reporting", "purpose": "Assembles the Season Completeness Scorecard from the full season's Defense File archive ahead of the contractor's GL insurance renewal.", "subdomain": "Season Reporting", "type": "Supporting", "owned_language": [ "'Season Reporting' always means the same thing here as on the landing page and in delivery-playbook.md" ], "owns": [ "Season Completeness Scorecard records" ], "does_not_own": [ "Individual DefenseFile production" ], "primary_actors": [ "Ops/QA Reviewer", "Contractor's GL insurance broker (external recipient)" ], "entities": [ "SeasonScorecard" ], "value_objects": [ "Money ($499-$999 flat)" ], "aggregates": [ "SeasonScorecard" ], "domain_services": [ "ScorecardRollupService" ], "application_services": [ "SeasonReportingService" ], "commands": [ "GenerateSeasonScorecard" ], "domain_events": [ "SeasonScorecardGenerated" ], "policies": [ "A Scorecard states completeness only and never represents or guarantees an insurance-renewal outcome" ], "specifications": [ "A SeasonScorecard aggregates only DefenseFiles delivered to the requesting contractor" ], "invariants": [ "A SeasonScorecard cannot reference sites outside the contractor's own roster" ], "human_roles": [ "Ops/QA Reviewer" ], "ai_agents": [ "Season rollup assistant" ], "inputs": [ "Season's DefenseFile archive" ], "outputs": [ "Season Completeness Scorecard (PDF)" ], "interfaces": [ "Client-facing portal" ], "external_integrations": [], "data_owned": [ "Scorecard records" ], "risks": [ "Overstating what the Scorecard represents to an underwriter" ] } ], "aggregates": [ { "name": "ContractedSite", "context": "Intake & Normalization", "purpose": "The root record for one contracted property under a contractor's account — the unit of billing and the unit of documentation.", "root": "ContractedSite", "entities": [ "CrewCheckIn", "EvidenceItem" ], "value_objects": [ "Money", "SLA", "Status/state labels" ], "invariants": [ "Cannot generate a DefenseFile until the parent ContractorAccount is onboarded", "Confirmed check-in fields are immutable except via a logged correction" ], "commands": [ "SubmitCrewCheckIn", "OnboardContractorAccount" ], "events": [ "CrewCheckInIngested", "EvidenceItemAttached", "ContractedSiteRegistered" ], "repository": "ContractedSiteRepository", "transaction_boundary": "One ContractedSite per transaction; per-storm evidence attachments do not lock the whole site record." }, { "name": "StormEvent", "context": "Weather Correlation", "purpose": "The root record for one discrete winter-weather occurrence requiring a service response and triggering file production across affected sites.", "root": "StormEvent", "entities": [ "WeatherMatchRecord" ], "value_objects": [ "Deadline/Window" ], "invariants": [ "A StormEvent's time window is immutable once its first DefenseFile reaches CompletenessCheckPassed" ], "commands": [ "RunWeatherMatch" ], "events": [ "StormEventDetected", "WeatherMatchResolved", "WeatherMatchLowConfidenceFlagged" ], "repository": "StormEventRepository", "transaction_boundary": "One StormEvent per transaction; per-site Weather Match resolution does not lock the whole storm record." }, { "name": "DefenseFile", "context": "Completeness & QA", "purpose": "The root record for one Storm Event Defense File — from intake through Ops/QA-Approved delivery.", "root": "DefenseFile", "entities": [ "CompletenessCheckResult", "ExceptionCase" ], "value_objects": [ "Money", "Deadline/Window", "Status/state labels" ], "invariants": [ "Cannot reach DefenseFileApproved without an Ops/QA Reviewer sign-off", "Cannot be delivered while CompletenessCheckResult is FAIL", "Cannot skip Weather Match resolution, even when flagged low-confidence" ], "commands": [ "RunCompletenessCheck", "ApproveDefenseFile", "DeliverDefenseFile" ], "events": [ "CompletenessCheckPassed", "CompletenessCheckFailed", "DefenseFileDrafted", "DefenseFileApproved", "GapFlaggedToContractor", "DefenseFileDelivered" ], "repository": "DefenseFileRepository", "transaction_boundary": "One DefenseFile per transaction; one file per ContractedSite per StormEvent." }, { "name": "LitigationHoldRequest", "context": "Litigation Hold", "purpose": "The root record for one claim-triggered expedited retrieval and independent Senior Reviewer re-verification of a site's DefenseFile.", "root": "LitigationHoldRequest", "entities": [], "value_objects": [ "Money", "SLA" ], "invariants": [ "Verification must be performed by a Senior Reviewer distinct from the original DefenseFile's Ops/QA Reviewer" ], "commands": [ "RequestLitigationHold", "VerifyLitigationHold" ], "events": [ "LitigationHoldRequested", "LitigationHoldVerified" ], "repository": "LitigationHoldRequestRepository", "transaction_boundary": "One LitigationHoldRequest per transaction, referencing exactly one existing DefenseFile." }, { "name": "SeasonScorecard", "context": "Season Reporting", "purpose": "The root record for one contractor's season-end Completeness Scorecard, rolled up from that season's delivered DefenseFiles.", "root": "SeasonScorecard", "entities": [], "value_objects": [ "Money" ], "invariants": [ "Cannot reference sites outside the requesting contractor's own roster" ], "commands": [ "GenerateSeasonScorecard" ], "events": [ "SeasonScorecardGenerated" ], "repository": "SeasonScorecardRepository", "transaction_boundary": "One SeasonScorecard per contractor per season." } ], "context_map": [ { "upstream": "Intake & Normalization", "downstream": "Weather Correlation", "relationship": "Customer/Supplier", "pattern": "Published Language", "integration_pattern": "Synchronous call", "contract_type": "Normalized ContractedSite + StormEvent time window", "data_exchanged": [ "[PLACEHOLDER] owner to complete" ], "events_exchanged": [ "[PLACEHOLDER] owner to complete" ], "ownership_boundary": "Weather Correlation owns Weather Match logic exclusively", "business_reason": "Weather Match requires normalized, confirmed site/time data", "acl_notes": "Weather Correlation never trusts unconfirmed intake fields", "failure_risks": [ "[PLACEHOLDER] owner to complete" ], "translation_notes": "None — shared ubiquitous language" }, { "upstream": "Weather Correlation", "downstream": "Completeness & QA", "relationship": "Customer/Supplier", "pattern": "Published Language", "integration_pattern": "Synchronous call", "contract_type": "WeatherMatchRecord with confidence tier", "data_exchanged": "Resolved or flagged Weather Match", "events_exchanged": "WeatherMatchResolved, WeatherMatchLowConfidenceFlagged", "ownership_boundary": "Completeness & QA owns the hard-fail rule evaluation exclusively", "business_reason": "A completeness check cannot pass without a resolved Weather Match", "acl_notes": "Low-confidence matches are hard-blocked from auto-passing", "failure_risks": "A low-confidence match silently treated as resolved", "translation_notes": "None — shared ubiquitous language" }, { "upstream": "Completeness & QA", "downstream": "File Assembly & Delivery", "relationship": "Customer/Supplier", "pattern": "Published Language", "integration_pattern": "Synchronous call", "contract_type": "CompletenessCheckResult", "data_exchanged": "PASS/FAIL result with reasons", "events_exchanged": "CompletenessCheckPassed, DefenseFileApproved", "ownership_boundary": "File Assembly & Delivery owns the delivered PDF exclusively", "business_reason": "A file is drafted and delivered only after completeness passes and Ops/QA approves", "acl_notes": "Delivery hard-blocked on any FAIL result", "failure_risks": "A file drafted before completeness truly passes", "translation_notes": "None — shared ubiquitous language" }, { "upstream": "File Assembly & Delivery", "downstream": "Litigation Hold", "relationship": "Customer/Supplier", "pattern": "Conformist", "integration_pattern": "Asynchronous request", "contract_type": "Existing delivered DefenseFile", "data_exchanged": "Full file contents and audit trail", "events_exchanged": "LitigationHoldRequested", "ownership_boundary": "Litigation Hold owns the verification memo exclusively", "business_reason": "Litigation Hold re-verifies an already-delivered file, never creates a new one from scratch", "acl_notes": "Litigation Hold treats the delivered file as read-only source-of-truth", "failure_risks": "Verifying against a stale file version", "translation_notes": "None — shared ubiquitous language" }, { "upstream": "File Assembly & Delivery", "downstream": "Season Reporting", "relationship": "Customer/Supplier", "pattern": "Published Language", "integration_pattern": "Asynchronous batch rollup", "contract_type": "Season's full DefenseFile archive for one contractor", "data_exchanged": "Completeness rates, delivery-time statistics", "events_exchanged": "DefenseFileDelivered", "ownership_boundary": "Season Reporting owns Scorecard framing exclusively", "business_reason": "A Scorecard is a rollup, not a re-derivation, of the season's files", "acl_notes": "Season Reporting never re-opens a delivered file's completeness status", "failure_risks": "A Scorecard including a file outside the requesting contractor's roster", "translation_notes": "None — shared ubiquitous language" }, { "upstream": "Rulebook & Doctrine Management", "downstream": "Completeness & QA", "relationship": "Supplier (Open Host Service)", "pattern": "Open Host Service", "integration_pattern": "Versioned reference", "contract_type": "Versioned Completeness Rulebook", "data_exchanged": "Jurisdiction-specific completeness rule set", "events_exchanged": "RulebookUpdated", "ownership_boundary": "Completeness & QA consumes but never edits the Rulebook", "business_reason": "The Rulebook is the single source of truth for what 'complete' means per jurisdiction", "acl_notes": "Completeness & QA locks to a specific Rulebook version per file for auditability", "failure_risks": "A file evaluated against a stale Rulebook version after an update", "translation_notes": "None — shared ubiquitous language" } ], "commands": [ { "name": "SubmitCrewCheckIn", "aggregate": "ContractedSite", "issued_by": "Dispatch coordinator / crew field staff", "preconditions": [ "Contractor account authenticated" ], "validation": "Required check-in fields present or explicitly marked pending", "success_event": "CrewCheckInIngested", "failure_event": "IntakeRejected", "authorization": "Authenticated contractor account only", "audit": "Logged with actor + timestamp" }, { "name": "RunWeatherMatch", "aggregate": "StormEvent", "issued_by": "Weather Correlation Agent (system)", "preconditions": [ "ContractedSite coordinates confirmed", "StormEvent time window set" ], "validation": "Certified NOAA/NCDC station data available within confidence threshold", "success_event": "WeatherMatchResolved", "failure_event": "WeatherMatchLowConfidenceFlagged", "authorization": "System-triggered on normalized intake", "audit": "Logged with station ID + confidence tier" }, { "name": "RunCompletenessCheck", "aggregate": "DefenseFile", "issued_by": "Completeness Rule Engine (system)", "preconditions": [ "Weather Match resolved or explicitly flagged" ], "validation": "All required elements present per active Completeness Rulebook version", "success_event": "CompletenessCheckPassed", "failure_event": "CompletenessCheckFailed", "authorization": "System-triggered", "audit": "Logged with Rulebook version + rule results" }, { "name": "ApproveDefenseFile", "aggregate": "DefenseFile", "issued_by": "Ops/QA Reviewer", "preconditions": [ "CompletenessCheckPassed recorded" ], "validation": "Reviewer confirms every checklist item against source evidence", "success_event": "DefenseFileApproved", "failure_event": "DefenseFileReturnedForCorrection", "authorization": "Authenticated Ops/QA Reviewer role only", "audit": "Logged with reviewer ID + timestamp" }, { "name": "DeliverDefenseFile", "aggregate": "DefenseFile", "issued_by": "System (post-approval)", "preconditions": [ "DefenseFileApproved recorded" ], "validation": "Delivery within the 24-48 hour SLA window", "success_event": "DefenseFileDelivered", "failure_event": "DeliveryDelayed", "authorization": "System-triggered on approval", "audit": "Logged with delivery timestamp" }, { "name": "RequestLitigationHold", "aggregate": "LitigationHoldRequest", "issued_by": "Contractor (via portal or direct request)", "preconditions": [ "An existing delivered DefenseFile for the site/storm" ], "validation": "Claim/lawsuit trigger reason documented", "success_event": "LitigationHoldRequested", "failure_event": "LitigationHoldRequestRejected", "authorization": "Authenticated contractor account only", "audit": "Logged with trigger reason + requester" }, { "name": "VerifyLitigationHold", "aggregate": "LitigationHoldRequest", "issued_by": "Senior Reviewer", "preconditions": [ "Senior Reviewer distinct from the original Ops/QA Reviewer" ], "validation": "Independent re-verification of every checklist item", "success_event": "LitigationHoldVerified", "failure_event": "LitigationHoldEscalated", "authorization": "Authenticated Senior Reviewer role only", "audit": "Logged with Senior Reviewer ID + verification memo" }, { "name": "ActivateJurisdictionRulebook", "aggregate": "CompletenessRulebookVersion", "issued_by": "Compliance Lead", "preconditions": [ "Outside counsel review completed and logged" ], "validation": "Rulebook version passes red-team edge-case test set", "success_event": "RulebookUpdated", "failure_event": "RulebookActivationBlocked", "authorization": "Compliance Lead only, with logged counsel sign-off", "audit": "Logged with counsel reviewer + version diff" } ], "event_storm": [ { "seq": 1, "actor": "Dispatch coordinator", "command": "SubmitCrewCheckIn", "aggregate": "ContractedSite", "event": "CrewCheckInIngested", "policy": "Any field below confidence threshold requires Ops/QA confirmation", "context": "Intake & Normalization", "downstream": "Weather Correlation retrieval", "risk": "A missed photo or timestamp for one site during a busy multi-property storm night" }, { "seq": 2, "actor": "Weather Correlation Agent", "command": "RunWeatherMatch", "aggregate": "StormEvent", "event": "WeatherMatchResolved", "policy": "Low-confidence matches route to human resolution, never auto-pass", "context": "Weather Correlation", "downstream": "Completeness Checklist evaluation", "risk": "Sparse NOAA/NCDC station coverage at a rural or edge-of-coverage site" }, { "seq": 3, "actor": "Completeness Rule Engine", "command": "RunCompletenessCheck", "aggregate": "DefenseFile", "event": "CompletenessCheckPassed", "policy": "No file ships known-incomplete; deterministic hard-fail rules run before any human review", "context": "Completeness & QA", "downstream": "Ops/QA Reviewer sign-off queue", "risk": "A hard-fail rule missing a genuine edge case" }, { "seq": 4, "actor": "Ops/QA Reviewer", "command": "ApproveDefenseFile", "aggregate": "DefenseFile", "event": "DefenseFileApproved", "policy": "100% human sign-off on every file at launch, no exceptions through the first 20 files", "context": "Completeness & QA", "downstream": "File delivery", "risk": "Reviewer fatigue during a high-volume multi-day storm" }, { "seq": 5, "actor": "System", "command": "DeliverDefenseFile", "aggregate": "DefenseFile", "event": "DefenseFileDelivered", "policy": "Delivery must land within the 24-48 hour SLA from storm end", "context": "File Assembly & Delivery", "downstream": "Client-facing searchable archive", "risk": "A major multi-day storm exceeding manual-fulfillment review capacity" }, { "seq": 6, "actor": "Completeness Rule Engine", "command": "RunCompletenessCheck", "aggregate": "DefenseFile", "event": "CompletenessCheckFailed", "policy": "Any gap is flagged back to the contractor the same day, while correction is still possible", "context": "Completeness & QA", "downstream": "Exception Queue / GapFlaggedToContractor", "risk": "A gap surfacing after the crew has left the site and can no longer correct it" }, { "seq": 7, "actor": "Contractor", "command": "RequestLitigationHold", "aggregate": "LitigationHoldRequest", "event": "LitigationHoldRequested", "policy": "A Litigation Hold request is accepted only against an existing delivered DefenseFile", "context": "Litigation Hold", "downstream": "Senior Reviewer independent verification", "risk": "A claim referencing a site/storm combination with no prior delivered file (pre-onboarding gap)" }, { "seq": 8, "actor": "Senior Reviewer", "command": "VerifyLitigationHold", "aggregate": "LitigationHoldRequest", "event": "LitigationHoldVerified", "policy": "The verifying Senior Reviewer must never be the same person who assembled the original file", "context": "Litigation Hold", "downstream": "Expedited certification delivered to contractor", "risk": "A single founder unable to provide genuine reviewer independence pre-hire" }, { "seq": 9, "actor": "Ops/QA Reviewer", "command": "GenerateSeasonScorecard", "aggregate": "SeasonScorecard", "event": "SeasonScorecardGenerated", "policy": "A Scorecard states completeness only and never guarantees an insurance-renewal outcome", "context": "Season Reporting", "downstream": "Contractor's GL insurance broker conversation", "risk": "The Scorecard being perceived as a renewal-terms guarantee" }, { "seq": 10, "actor": "Compliance Lead", "command": "ActivateJurisdictionRulebook", "aggregate": "CompletenessRulebookVersion", "event": "RulebookUpdated", "policy": "No new jurisdiction activates without outside-counsel sign-off and red-team edge-case testing", "context": "Rulebook & Doctrine Management", "downstream": "Completeness & QA rule evaluation for the new jurisdiction", "risk": "A doctrine nuance misapplied in the new jurisdiction's Rulebook" } ], "use_cases": [ { "name": "Deliver a Storm Event Defense File for one Contracted Site within 24-48 hours", "actor": "Contractor's dispatch coordinator / Ops/QA Reviewer", "context": "Intake & Normalization / Weather Correlation / Completeness & QA / File Assembly & Delivery", "goal": "Obtain a complete, weather-correlated, human-reviewed Defense File within the SLA window", "preconditions": [ "Contractor account onboarded", "Crew check-in and evidence submitted for the storm" ], "main_flow": [ "Crew check-in ingested and normalized", "Weather Match resolved against the site/time window", "Completeness Checklist runs and passes", "Ops/QA Reviewer approves", "File delivered to the searchable portal" ], "alternative_flows": [ "Low-confidence Weather Match routes to human resolution instead of auto-pass", "Missing evidence routes to same-day gap notification instead of silent failure" ], "success": "DefenseFileDelivered event recorded within the 24-48 hour SLA", "failure_handling": "If a required element cannot be resolved before the SLA window closes, the contractor is notified of the delay and the specific gap, per delivery-playbook.md", "business_rules": [ "No file is delivered without CompletenessCheckPassed and DefenseFileApproved", "Every file records the Completeness Rulebook version it was produced against" ], "ai_role": "Drafts the structured file and confidence-scores every Weather Match and evidence item", "human_role": "Ops/QA Reviewer confirms completeness and signs off before delivery", "commands": [ "SubmitCrewCheckIn", "RunWeatherMatch", "RunCompletenessCheck", "ApproveDefenseFile", "DeliverDefenseFile" ], "events": [ "CrewCheckInIngested", "WeatherMatchResolved", "CompletenessCheckPassed", "DefenseFileApproved", "DefenseFileDelivered" ], "aggregates": [ "ContractedSite", "StormEvent", "DefenseFile" ], "audit": "Reviewer ID, Rulebook version, and delivery timestamp logged on every file" }, { "name": "Handle a Litigation Hold request with independent Senior Reviewer verification", "actor": "Contractor / Senior Reviewer", "context": "Litigation Hold", "goal": "Certify and deliver an expedited, independently re-verified version of an existing site's Defense File within one business day", "preconditions": [ "An existing delivered DefenseFile for the site and storm in question", "A documented claim or lawsuit trigger" ], "main_flow": [ "Contractor requests Litigation Hold", "A Senior Reviewer distinct from the original assembling reviewer is assigned", "Senior Reviewer independently re-verifies every checklist item against source evidence", "Verification memo and certified package delivered" ], "alternative_flows": [ "If no independent second reviewer is available (single-founder stage), the request is escalated per the risk register until a qualified independent reviewer or outside partner is engaged" ], "success": "LitigationHoldVerified event recorded within one business day of request", "failure_handling": "If independent verification surfaces a discrepancy from the original file, the discrepancy is documented and disclosed to the contractor immediately, never silently corrected", "business_rules": [ "The Senior Reviewer must never be the same person who assembled the original file", "Litigation Hold fees are never contingent on the claim's outcome" ], "ai_role": "May assist retrieval speed only; plays no role in the verification decision itself", "human_role": "Senior Reviewer performs and signs the independent verification", "commands": [ "RequestLitigationHold", "VerifyLitigationHold" ], "events": [ "LitigationHoldRequested", "LitigationHoldVerified" ], "aggregates": [ "LitigationHoldRequest" ], "audit": "Senior Reviewer ID, verification memo, and independence confirmation logged on every Litigation Hold" } ], "policies": [ { "name": "Low-confidence routing", "trigger": "A Weather Match or extracted evidence field scores below the confidence threshold", "condition": "Confidence score < threshold", "action": "Route to Ops/QA Reviewer for manual resolution before the file can proceed", "ai_involvement": "AI scores confidence and flags; does not resolve", "human_approval": "Required", "context": "Weather Correlation / Completeness & QA" }, { "name": "Hard-fail completeness gate", "trigger": "Any required Completeness Checklist element is missing", "condition": "Required element absent", "action": "CompletenessCheckFailed; file cannot be Approved or Delivered", "ai_involvement": "Deterministic rule evaluation, not model judgment", "human_approval": "Not applicable — this is a hard gate, not a discretionary decision", "context": "Completeness & QA" }, { "name": "Reviewer independence on Litigation Hold", "trigger": "A LitigationHoldRequest is opened", "condition": "Assigning a verifying reviewer", "action": "The Senior Reviewer must be distinct from the original assembling Ops/QA Reviewer", "ai_involvement": "None", "human_approval": "Required — Compliance Lead confirms reviewer assignment", "context": "Litigation Hold" }, { "name": "Counsel review before jurisdiction activation", "trigger": "A new state's Completeness Rulebook is proposed for activation", "condition": "Rulebook version pending activation", "action": "Block activation until outside counsel review is logged", "ai_involvement": "AI may flag legal-update signals; never determines doctrine content", "human_approval": "Required — outside counsel sign-off", "context": "Rulebook & Doctrine Management" }, { "name": "Conservative completeness interpretation", "trigger": "Ambiguity in how a doctrine element applies to a specific fact pattern", "condition": "Doctrine interpretation is ambiguous", "action": "Default to the more conservative, over-inclusive completeness requirement rather than the most favorable reading", "ai_involvement": "None — a standing Rulebook-authoring principle applied by counsel", "human_approval": "Baked into Rulebook authorship by outside counsel", "context": "Rulebook & Doctrine Management" } ], "invariants": [ { "invariant": "A DefenseFile cannot reach DefenseFileApproved without an Ops/QA Reviewer sign-off", "aggregate": "DefenseFile", "context": "Completeness & QA", "enforcement": "Application-layer gate on the ApproveDefenseFile command", "why": "This is the trust chokepoint protecting the zero-materially-incomplete-files north star" }, { "invariant": "A LitigationHoldVerified event requires a Senior Reviewer distinct from the original DefenseFile's Ops/QA Reviewer", "aggregate": "LitigationHoldRequest", "context": "Litigation Hold", "enforcement": "Reviewer-identity check on the VerifyLitigationHold command", "why": "Independent re-verification is the entire value of the Litigation Hold tier" }, { "invariant": "A ContractedSite's DefenseFile cannot skip Weather Match resolution, even when flagged low-confidence", "aggregate": "DefenseFile", "context": "Weather Correlation", "enforcement": "Completeness Checklist hard-fail rule referencing WeatherMatchRecord state", "why": "Certified weather correlation is the specific evidentiary element the doctrine requires" }, { "invariant": "A SeasonScorecard cannot reference sites outside the requesting contractor's own roster", "aggregate": "SeasonScorecard", "context": "Season Reporting", "enforcement": "Rollup query scoped to ContractorAccount ID", "why": "Prevents cross-contractor data leakage in a shared-tenant system" }, { "invariant": "A Completeness Rulebook version cannot be activated without a logged outside-counsel review record", "aggregate": "CompletenessRulebookVersion", "context": "Rulebook & Doctrine Management", "enforcement": "Application-layer gate on ActivateJurisdictionRulebook", "why": "Prevents an unreviewed doctrine interpretation from silently going live" } ], "risk_register": [ { "risk": "A Defense File omits a required element or contains an extraction error that surfaces during actual litigation", "context": "Completeness & QA", "likelihood": "Low", "impact": "High", "mitigation": "Deterministic completeness-checklist validation, 100% human QA review, independent Senior Reviewer re-verification on incident-flagged sites", "signal": "Any post-delivery correction request", "owner": "Ops/QA Reviewer" }, { "risk": "Certified weather-station data is unavailable, sparse, or ambiguous for a rural or edge-of-coverage site", "context": "Weather Correlation", "likelihood": "Medium", "impact": "Medium", "mitigation": "Automatic fallback to the nearest verified alternate station with the substitution documented; human review on low-confidence matches", "signal": "WeatherMatchLowConfidenceFlagged rate trending up", "owner": "Ops/QA Reviewer" }, { "risk": "A contractor or its attorney treats a Defense File as legal advice or a guaranteed defense", "context": "Completeness & QA / File Assembly & Delivery", "likelihood": "Medium", "impact": "Medium", "mitigation": "Explicit non-legal-advice disclaimer on every file; onboarding materials make the business-records-only scope explicit", "signal": "A contractor support inquiry framed as a legal-strategy question", "owner": "Compliance Lead" }, { "risk": "A crew fails to submit timestamps or photos for a site during a busy multi-property storm night", "context": "Intake & Normalization", "likelihood": "Medium-High", "impact": "Medium", "mitigation": "Same-day gap-flagging back to the contractor while correction is still possible; Season Scorecard makes the pattern visible", "signal": "GapFlaggedToContractor rate for a given contractor", "owner": "Ops/QA Reviewer" }, { "risk": "State-specific 'storm in progress'/ongoing-storm doctrine nuances are misapplied in the Completeness Rulebook", "context": "Rulebook & Doctrine Management", "likelihood": "Medium", "impact": "High", "mitigation": "Outside counsel review before activating any new state's Rulebook; conservative, over-inclusive completeness requirements", "signal": "Any counsel-flagged discrepancy during periodic Rulebook review", "owner": "Compliance Lead" } ], "human_roles": [ { "role": "Ops/QA Reviewer", "contexts": [ "Completeness & QA", "File Assembly & Delivery", "Weather Correlation" ], "responsibilities": [ "Confirm completeness on every Defense File before it is marked final", "Resolve low-confidence Weather Match and evidence-extraction cases" ], "decisions_owned": [ "File Approved vs. Returned for Correction" ], "approval_authority": "Sole approver of DefenseFileApproved at launch", "escalation_authority": "Escalates incident-flagged sites to Litigation Hold", "ai_support": [ "[PLACEHOLDER] owner to complete" ], "quality_metrics": [ "Rework/re-issue rate (<2% target)", "Files reviewed within SLA" ], "workload_risks": [ "Founder-as-sole-reviewer throughput cap during a major multi-day storm" ] }, { "role": "Senior Reviewer", "contexts": [ "Litigation Hold" ], "responsibilities": [ "Independently re-verify every checklist item on any incident-flagged or Litigation Hold file" ], "decisions_owned": [ "LitigationHoldVerified vs. LitigationHoldEscalated" ], "approval_authority": "Sole approver of LitigationHoldVerified", "escalation_authority": "Escalates unresolved discrepancies directly to the Compliance Lead and, as needed, the contractor's attorney", "ai_support": "None in the verification decision itself", "quality_metrics": [ "Verification turnaround (target: 1 business day)" ], "workload_risks": [ "No genuinely independent second reviewer exists until a hire or partner is engaged — logged as an open risk" ] }, { "role": "Compliance Lead", "contexts": [ "Rulebook & Doctrine Management", "Season Reporting" ], "responsibilities": [ "Maintain the versioned Completeness Rulebook", "Coordinate outside-counsel review before any jurisdiction activation", "Review Season Scorecard framing before delivery" ], "decisions_owned": [ "Rulebook version activation" ], "approval_authority": "Sole authority to activate a new jurisdiction's Rulebook, contingent on logged counsel sign-off", "escalation_authority": "Escalates any suspected doctrine misapplication to outside counsel immediately", "ai_support": "AI-assisted legal-update signal monitoring, non-authoritative", "quality_metrics": [ "Zero jurisdictions activated without a logged counsel review" ], "workload_risks": [ "Founder currently holds this role in addition to Ops/QA Reviewer duties" ] } ], "ai_agents": [ { "name": "Weather Match Agent", "context": "Weather Correlation", "responsibility": "Retrieve and match certified NOAA/NCDC station data to a ContractedSite's exact coordinates and a StormEvent's time window", "inputs": [ "Site coordinates", "Storm time window" ], "outputs": [ "WeatherMatchRecord with confidence tier" ], "tools": [ "NOAA/NCDC weather-data API" ], "retrieval_sources": [ "NOAA/NCDC certified station data" ], "confidence_scoring": "High/Medium/Low tiers based on station distance and data completeness for the exact time window", "escalation_triggers": [ "Confidence below the Medium threshold", "No station found within the configured radius" ], "human_approval": "Required for any Medium or Low confidence match", "audit_logs": [ "[PLACEHOLDER] owner to complete" ], "failure_modes": [ "Sparse station coverage in rural sites", "Multi-day storm window ambiguity" ], "forbidden_actions": [ "Auto-passing a low-confidence match without human resolution" ], "memory_scope": "Per-StormEvent, no cross-contractor memory", "versioning": "Model-agnostic behind an abstraction layer per the AI-Native Advantage model-portability principle", "metrics": [ "% of matches resolved at High confidence without human intervention" ], "validations": [ "Manual validation of every match for the first 5 files before automation is trusted" ] }, { "name": "Photo QA Agent", "context": "Completeness & QA", "responsibility": "Multimodal review of submitted photos for image quality, timestamp/geotag presence, and visible ice/snow condition", "inputs": [ "Submitted crew photos" ], "outputs": [ "Photo QA pass/fail flags feeding the Completeness Checklist" ], "tools": [ "Vision-capable multimodal LLM" ], "retrieval_sources": [ "None — evaluates the submitted image directly" ], "confidence_scoring": "High/Medium/Low tiers on image-quality and condition-visibility assessment", "escalation_triggers": [ "Low-confidence condition classification", "Missing or unreadable geotag/timestamp metadata" ], "human_approval": "Required for any Medium or Low confidence flag", "audit_logs": "Per-photo QA result logged with confidence tier", "failure_modes": [ "Poor lighting or angle producing an unreliable condition read" ], "forbidden_actions": [ "Characterizing liability or fault from photo content" ], "memory_scope": "Per-DefenseFile, no cross-contractor memory", "versioning": "Model-agnostic behind an abstraction layer", "metrics": [ "% of photos requiring human re-review" ], "validations": [ "Gold-standard example library calibration before trusting automated flags" ] }, { "name": "Defense File Drafting Agent", "context": "File Assembly & Delivery", "responsibility": "Draft the structured Storm Event Defense File (timeline, photos, treatment log, Weather Match, completeness result) from normalized, completeness-checked inputs", "inputs": [ "Normalized check-in record", "Resolved WeatherMatchRecord", "CompletenessCheckResult" ], "outputs": [ "Draft DefenseFile document" ], "tools": [ "Text-generation LLM", "PDF templating library" ], "retrieval_sources": [ "Active Completeness Rulebook version for citation formatting" ], "confidence_scoring": "Not applicable — output is always routed to human sign-off regardless of internal confidence", "escalation_triggers": [ "Any drafting output containing doctrine-application or liability-characterization language triggers an automatic block" ], "human_approval": "Required on every single draft — no auto-publish path exists", "audit_logs": "Draft version and Ops/QA Reviewer sign-off logged together", "failure_modes": [ "Drafting language drifting toward legal argument if prompted carelessly" ], "forbidden_actions": [ "Drafting legal argument, characterizing liability, or invoking the doctrine on the contractor's behalf" ], "memory_scope": "Per-DefenseFile, no cross-contractor memory", "versioning": "Model-agnostic behind an abstraction layer", "metrics": [ "Draft-to-approval edit rate" ], "validations": [ "Every draft template reviewed against the Licensing Boundary before use" ] } ], "mvp_roadmap": [ { "phase": "Phase 1 — Manual pilot fulfillment", "goal": "Prove the completeness rulebook and weather-matching logic manually before any custom software exists", "features": [ "Spreadsheet-based Completeness Checklist", "Manual NOAA/NCDC lookup", "PDF template" ], "contexts": [ "Intake & Normalization", "Weather Correlation", "Completeness & QA" ], "ai_needs": [ "None required at this phase — fully manual" ], "data_needs": [ "First 5-20 real storm-site files" ], "human_workflows": [ "Founder personally pulls exports, queries weather data, populates template, reviews and signs each file" ], "integrations": [ "Dispatch-tool export or photo/SMS intake" ], "exit_criteria": [ "[PLACEHOLDER] owner to complete" ], "risks": [ "Manual process not scaling past the first pilot contractor's volume" ] }, { "phase": "Phase 2 — Automate ingestion and Weather Match", "goal": "Automate the highest-confidence, lowest-judgment steps while retaining 100% human sign-off", "features": [ "Automated dispatch-tool export ingestion", "Automated Weather Match with confidence scoring" ], "contexts": [ "Intake & Normalization", "Weather Correlation" ], "ai_needs": [ "Weather Match Agent", "Intake normalization assistance" ], "data_needs": [ "20+ validated files as a gold-standard example set" ], "human_workflows": [ "Ops/QA Reviewer reviews and signs off every file; exception handling for low-confidence cases" ], "integrations": [ "Aspire/Service Autopilot/ArborGold API or CSV" ], "exit_criteria": "20-file Build-Before-Scale checkpoint passed with rework rate under 2%", "risks": [ "Automating a step before its accuracy is truly validated" ] }, { "phase": "Phase 3 — Full pilot cohort and Season Reporting", "goal": "Expand to the full 3-5 contractor pilot cohort and deliver the first Season Completeness Scorecards", "features": [ "Photo QA Agent", "Defense File Drafting Agent", "Season Scorecard rollup" ], "contexts": [ "Completeness & QA", "File Assembly & Delivery", "Season Reporting" ], "ai_needs": [ "Photo QA Agent", "Defense File Drafting Agent", "Season rollup assistance" ], "data_needs": [ "A full season's Defense File archive per pilot contractor" ], "human_workflows": [ "Ops/QA Reviewer sign-off on every file continues unchanged; Compliance Lead reviews Scorecard framing" ], "integrations": [ "Client-facing searchable portal" ], "exit_criteria": "Full-pilot-season checkpoint: completeness accuracy, Weather Match reliability, SLA achievability, and willingness-to-pay validated", "risks": [ "Season Scorecard framing being over-read as an insurance guarantee" ] } ], "scaling_roadmap": [ { "stage": "Single founder, manual fulfillment", "trigger": "Pilot launch", "architecture_change": "None — spreadsheet + weather API + PDF template", "operational_change": "Founder is the sole Ops/QA Reviewer", "risk": "No independent second reviewer for Litigation Hold" }, { "stage": "Automated ingestion + Weather Match", "trigger": "20-file Build-Before-Scale checkpoint passed", "architecture_change": "Automated dispatch-tool connector and Weather Match Agent behind a model-agnostic abstraction layer", "operational_change": "Ops/QA Reviewer time shifts from data-pulling to review-only", "risk": "Automating before accuracy is validated against the gold-standard set" }, { "stage": "Second beachhead state or hire", "trigger": "Full-pilot-season checkpoint passed", "architecture_change": "Second state's Completeness Rulebook activated behind outside-counsel review", "operational_change": "First non-founder Ops/QA Reviewer or Senior Reviewer hired, resolving the reviewer-independence gap", "risk": "Hiring before revenue supports the added headcount" }, { "stage": "Off-season landscaping-liability add-on evaluation", "trigger": "Full-pilot-season checkpoint passed and off-season capacity confirmed", "architecture_change": "[PLACEHOLDER] — not yet scoped", "operational_change": "[PLACEHOLDER] — evaluated only after core season-1 business is proven", "risk": "Diluting focus from the core snow/ice product before it is proven at scale" } ], "testing_strategy": { "ai_eval_dataset": [ "[PLACEHOLDER] owner to complete" ], "contract_testing_plan": "Dispatch-tool export format changes are caught via a versioned schema check on the Intake & Normalization connector", "critical_domain_rules": [ "No file Delivered without CompletenessCheckPassed and DefenseFileApproved", "No LitigationHoldVerified without an independent Senior Reviewer" ], "manual_qa_checklist": [ "[PLACEHOLDER] owner to complete" ], "regression_plan": "Any Completeness Rulebook or drafting-prompt change is re-validated against the full gold-standard example set before activation", "tests": [ { "type": "Manual validation", "context": "Weather Correlation", "validates": "Every Weather Match for the first 5 files", "example": "A site near a sparse-coverage rural NOAA station tested against the alternate-station fallback logic" }, { "type": "Red-team edge case", "context": "Rulebook & Doctrine Management", "validates": "New jurisdiction Rulebook robustness before activation", "example": "A multi-day storm spanning two calendar days tested against the completeness time-window rule" }, { "type": "Independent re-verification", "context": "Litigation Hold", "validates": "Senior Reviewer catches any discrepancy from the original file", "example": "A deliberately seeded discrepancy in a test file caught during Senior Reviewer training" } ] }, "security_governance": { "access_control_matrix": [ { "role": "Ops/QA Reviewer", "context": "Completeness & QA", "capabilities": [ "Review and approve Defense Files", "Resolve low-confidence flags" ] }, { "role": "Senior Reviewer", "context": "Litigation Hold", "capabilities": [ "Independently verify Litigation Hold files" ] }, { "role": "Compliance Lead", "context": "Rulebook & Doctrine Management", "capabilities": [ "Activate Rulebook versions", "Review Season Scorecard framing" ] } ], "ai_governance": [ "[PLACEHOLDER] owner to complete" ], "audit_log_requirements": [ "[PLACEHOLDER] owner to complete" ], "controls": [ { "control": "Encrypted intake and storage", "context": "Intake & Normalization", "risk": "Data breach exposing crew/site PII", "impact": "High", "audit": "Encryption-at-rest and in-transit verified" }, { "control": "Access-controlled review tooling", "context": "Completeness & QA / Litigation Hold", "risk": "Unauthorized access to contractor evidence", "impact": "High", "audit": "Role-based access logged per session" }, { "control": "Reviewer-independence enforcement", "context": "Litigation Hold", "risk": "A non-independent verification undermining Litigation Hold's value", "impact": "High", "audit": "System-enforced reviewer-identity check" } ], "prompt_injection_defense": [ "[PLACEHOLDER] owner to complete" ], "sensitive_data_handling": [ "[PLACEHOLDER] owner to complete" ] }, "observability": { "ai_evaluation_reports": [ "[PLACEHOLDER] owner to complete" ], "audit_reports": [ "[PLACEHOLDER] owner to complete" ], "client_outcome_reports": [ "[PLACEHOLDER] owner to complete" ], "dashboards": [ "[PLACEHOLDER] owner to complete" ], "metrics": [ { "metric": "% of sites with a complete Defense File within 48 hours", "type": "leading", "context": "File Assembly & Delivery", "target": ">=98% by pilot end", "alert_threshold": "<90% in any storm event", "why": "Directly measures the core SLA promise" }, { "metric": "Rework/re-issue rate", "type": "lagging", "context": "Completeness & QA", "target": "<2%", "alert_threshold": ">5% over any 10-file window", "why": "Directly measures the north-star zero-materially-incomplete-files guardrail" }, { "metric": "Median file-retrieval time on claim", "type": "leading", "context": "Litigation Hold", "target": "<15 minutes", "alert_threshold": ">60 minutes", "why": "The core promise of the whole business — retrievable in minutes, not days" } ], "quality_review_reports": [ "[PLACEHOLDER] owner to complete" ] }, "data_objects": [ { "name": "DefenseFileRecord", "owner_context": "File Assembly & Delivery", "meaning": "The finished, delivered Storm Event Defense File and its full audit trail", "source_of_truth": "File Assembly & Delivery context", "writers": [ "File Assembly & Delivery", "Completeness & QA (checklist result)" ], "readers": [ "Contractor portal", "Litigation Hold", "Season Reporting" ], "retention": "Multi-year window sized to the client's litigation-timeline risk, per compliance-checklist.md", "privacy": "Restricted — contains site photos and treatment logs", "audit": "Every state transition logged with actor and timestamp" }, { "name": "WeatherMatchRecord", "owner_context": "Weather Correlation", "meaning": "The certified NOAA/NCDC station data matched to a specific site and storm time window, with confidence tier", "source_of_truth": "Weather Correlation context", "writers": [ "Weather Correlation" ], "readers": [ "Completeness & QA", "File Assembly & Delivery" ], "retention": "Retained with the parent DefenseFile for the same multi-year window", "privacy": "Not sensitive — weather data only", "audit": "Station ID, distance, and confidence tier logged per match" }, { "name": "CompletenessAuditLog", "owner_context": "Completeness & QA", "meaning": "The append-only log of every Completeness Checklist evaluation, gap flag, and reviewer sign-off", "source_of_truth": "Completeness & QA context", "writers": [ "Completeness & QA", "Ops/QA Reviewer", "Senior Reviewer" ], "readers": [ "Compliance Lead", "Litigation Hold (independent verification reference)" ], "retention": "Retained with the parent DefenseFile for the same multi-year window", "privacy": "Confidential — internal review record", "audit": "Append-only, immutable once written" } ], "external_integrations": [ { "system": "NOAA/NCDC certified weather-station data API", "direction": "Inbound", "pattern": "Synchronous query per site/time window", "trigger": "RunWeatherMatch command", "data_out": [ "[PLACEHOLDER] owner to complete" ], "data_in": [ "[PLACEHOLDER] owner to complete" ], "internal_model": "WeatherMatchRecord", "acl_strategy": "Weather Correlation context translates raw API response into the internal WeatherMatchRecord shape", "owner_context": "Weather Correlation", "failure_strategy": "Fallback to nearest verified alternate station; flag for human resolution if none found within threshold", "audit_need": "Station ID and query timestamp logged", "risk": "Sparse coverage in rural/edge-of-coverage sites" }, { "system": "Dispatch platform export (Aspire / Service Autopilot / ArborGold)", "direction": "Inbound", "pattern": "Batch export (API or CSV) per storm cycle", "trigger": "Storm event ends; scheduled or manual pull", "data_out": "None (read-only consumer)", "data_in": "Crew check-in timestamps, GPS pings, job-completion notes", "internal_model": "Normalized ContractedSite check-in record", "acl_strategy": "Intake & Normalization context translates each dispatch tool's proprietary export format into the shared normalized schema", "owner_context": "Intake & Normalization", "failure_strategy": "Fallback to direct crew photo/SMS submission intake, independent of any single dispatch-tool integration", "audit_need": "Export batch ID and ingestion timestamp logged", "risk": "Dispatch-tool API access changes or is revoked, breaking the primary ingestion path" } ], "adrs": [ { "id": "ADR-1", "decision": "Fulfill the pilot manually (spreadsheet + weather API + PDF template) before building any custom ingestion software", "context": "MVP fulfillment approach", "options": [ "Build custom software first", "Manual-first fulfillment" ], "chosen": "Manual-first fulfillment", "why": "Validates the Completeness Rulebook and Weather Match logic against real files before investing in automation that might encode a wrong assumption", "consequences": [ "Lower throughput at launch", "Higher confidence in what to automate once building starts" ], "risks": [ "Manual process becoming a bottleneck if pilot demand exceeds the founder's review capacity" ], "reversal": "Automation work begins immediately once the 20-file checkpoint passes", "revisit_trigger": "20-file Build-Before-Scale checkpoint", "revisit_when": "After the first 20 Defense Files", "business_reason": "Protects the zero-materially-incomplete-files north star during the highest-uncertainty period", "technical_reason": "Avoids building automation around an unvalidated rule set", "tradeoffs": [ "[PLACEHOLDER] owner to complete" ], "status": "Accepted" }, { "id": "ADR-2", "decision": "Launch in a single beachhead state (effectively Illinois-first within the Chicago-land/Midwest region) with a per-state, outside-counsel-reviewed Completeness Rulebook required before any expansion", "context": "Geographic and legal-doctrine expansion strategy", "options": [ "Launch multi-state immediately", "Single-state beachhead with gated expansion" ], "chosen": "Single-state beachhead with gated expansion", "why": "The doctrine's evidentiary mechanics are state-specific; activating an unreviewed jurisdiction risks a materially wrong Completeness Rulebook", "consequences": [ "Slower geographic growth", "Higher confidence in doctrine correctness per activated state" ], "risks": [ "A competitor moving faster across multiple states without the same rigor" ], "reversal": "Not reversible mid-season without a full counsel re-review", "revisit_trigger": "Full-pilot-season checkpoint", "revisit_when": "After the first full pilot season", "business_reason": "Protects against the highest-impact risk in the register (doctrine misapplication)", "technical_reason": "Keeps the Completeness Rulebook versioning model simple during the pilot", "tradeoffs": "Market coverage traded for doctrine-accuracy confidence", "status": "Accepted" }, { "id": "ADR-3", "decision": "Hold 100% human Ops/QA review at launch, tapering only for validated low-judgment steps, with Litigation Hold's independent Senior Reviewer step staying fully human indefinitely", "context": "Automation-vs-human-review boundary", "options": [ "Automate review from day one with spot-checks", "100% human review at launch, taper gradually" ], "chosen": "100% human review at launch, taper gradually", "why": "A single false-negative completeness call could destroy trust in a business whose entire value proposition is completeness and reliability", "consequences": [ "Lower reviewer throughput at launch", "Materially lower risk of a reputation-damaging false pass" ], "risks": [ "Reviewer burnout during a high-volume multi-day storm at launch-stage throughput" ], "reversal": "Tapering happens only per the Build-Before-Scale checkpoints, never all at once", "revisit_trigger": "5-file, 10-file, and 20-file checkpoints", "revisit_when": "Continuously, per checkpoint", "business_reason": "Directly protects the north-star metric", "technical_reason": "Builds the gold-standard example library needed before trusting any automated judgment", "tradeoffs": "Throughput traded for reliability", "status": "Accepted" } ], "self_audit": { "biggest_assumptions": [ "A commercial snow contractor with 15+ sites has enough recurring per-storm exposure for a per-site-per-month subscription to clear existing software spend as a budget line", "Certified NOAA/NCDC station coverage across the Chicago-land/Midwest beachhead is dense enough that low-confidence Weather Match cases stay a minority" ], "highest_risk_decisions": [ "Single-founder-as-sole-reviewer throughput cap through the first 20 pilot files", "Single-beachhead-state sequencing pace vs. competitive pressure from SnowProof's eventual launch" ], "needs_domain_expert": [ "Final Chicago-land/Midwest state Completeness Rulebooks sign-off by outside counsel before any file production begins" ], "needs_legal": [ "Every Completeness Rulebook version prior to activation", "The guarantee language on the microsite and in offer-and-pricing.md", "The engagement-letter/services-agreement outline in compliance-checklist.md" ], "needs_prototype": [ "Weather Match confidence-tier calibration against real pilot site coordinates", "Multimodal Photo QA accuracy on real-world crew photos with variable lighting, angle, and weather conditions" ], "scores": [ { "category": "Domain clarity", "score": 5, "weakness": "None significant", "improvement": "N/A" }, { "category": "AI-native fit", "score": 4, "weakness": "Weather Match and Photo QA accuracy not yet proven at real pilot scale", "improvement": "Build the gold-standard example library from the first 20 pilot files" }, { "category": "Regulatory moat", "score": 3, "weakness": "No licensing regime as a moat; the moat is the maintained Rulebook and pipeline, not a legal barrier to entry", "improvement": "N/A — an accepted trade per the blueprint's rubric scorecard" }, { "category": "Trust chokepoint design", "score": 5, "weakness": "None significant", "improvement": "N/A" }, { "category": "Expansion readiness", "score": 2, "weakness": "Second-beachhead-state Rulebook not yet attorney-reviewed; competitive landscape (SnowProof, Certified Snowfall Totals) requires ongoing monitoring", "improvement": "Complete the full-pilot-season checkpoint before starting any second-state Rulebook review" } ], "validate_before_prod": [ "Chicago-land/Midwest state Completeness Rulebooks — outside counsel sign-off", "Weather Match confidence-threshold calibration against real pilot site addresses" ], "weakest_parts": [ "Single-founder reviewer-independence gap for Litigation Hold until a hire or partner is engaged", "TAM sizing depends on an Inferred, wide-uncertainty estimate of the commercially-focused contractor subset" ] }, "module_structure": { "dependency_rules": [ "[PLACEHOLDER] owner to complete" ], "modules": [ { "name": "Intake & Normalization", "purpose": "Turn raw dispatch-tool exports and crew submissions into a canonical record", "owned_domain": [ "Raw uploads", "Normalized check-in records" ], "public_interfaces": [ "Intake portal", "Dispatch-tool connector" ], "infra_adapters": [ "Encrypted object storage" ], "application_services": [ "IntakeIngestionService" ], "forbidden_deps": [ "Weather Correlation internals", "Completeness & QA internals" ] }, { "name": "Weather Correlation", "purpose": "Resolve certified weather matches per site/storm", "owned_domain": [ "WeatherMatchRecord" ], "public_interfaces": [ "NOAA/NCDC API adapter" ], "infra_adapters": [ "Weather-data API client" ], "application_services": [ "WeatherCorrelationService" ], "forbidden_deps": [ "File Assembly & Delivery internals" ] }, { "name": "Completeness & QA", "purpose": "Evaluate the Completeness Checklist and gate approval", "owned_domain": [ "CompletenessCheckResult", "ExceptionCase" ], "public_interfaces": [ "Ops/QA review workbench" ], "infra_adapters": [ "Rule engine" ], "application_services": [ "CompletenessQAService" ], "forbidden_deps": [ "Rulebook authoring internals (consumes versioned output only)" ] }, { "name": "File Assembly & Delivery", "purpose": "Draft and deliver the finished Defense File", "owned_domain": [ "DefenseFile", "Client archive" ], "public_interfaces": [ "Client-facing portal" ], "infra_adapters": [ "PDF templating library" ], "application_services": [ "DeliveryService" ], "forbidden_deps": [ "Litigation Hold internals" ] }, { "name": "Litigation Hold", "purpose": "Independently re-verify claim-triggered files", "owned_domain": [ "LitigationHoldRequest" ], "public_interfaces": [ "Expedited-request intake" ], "infra_adapters": [ "Notification service" ], "application_services": [ "LitigationHoldRequestService" ], "forbidden_deps": [ "Season Reporting internals" ] }, { "name": "Rulebook & Doctrine Management", "purpose": "Version and govern the Completeness Rulebook", "owned_domain": [ "CompletenessRulebookVersion" ], "public_interfaces": [ "Rulebook version-control store" ], "infra_adapters": [ "Legal-update monitoring feed" ], "application_services": [ "RulebookGovernanceService" ], "forbidden_deps": [ "File-level completeness evaluation logic" ] } ], "tree": "src/ (contexts/intake-normalization, contexts/weather-correlation, contexts/completeness-qa, contexts/file-assembly-delivery, contexts/litigation-hold, contexts/rulebook-doctrine, contexts/contractor-onboarding, contexts/season-reporting) — one directory per bounded context, no cross-context imports outside published interfaces" }, "extensions": { "service_business_reality_check": { "is_service_business": true, "paid_outcome_clear": true, "workflow_present": true, "ai_native_fit_score": 4, "red_flags": [] }, "ai_native_fit": { "score": 4, "why": "Certified weather-station matching by exact coordinates and time window is evidentiarily necessary, not merely convenient, and multimodal photo QA plus completeness reasoning compound in accuracy as frontier models improve — the moat is the maintained Rulebook and data pipeline, not a prompt.", "disqualifiers": [] }, "domain_evidence_register": [ { "claim": "$22.9B US snowplowing services industry, 112,000 businesses, 1.9% CAGR 2021-2026", "evidence_type": "Industry research", "source": "IBISWorld, Snowplowing Services in the US, 2026", "strength": "High", "gaps": "None — figure re-confirmed current in this run's fresh research" }, { "claim": "'Storm in progress' doctrine requires certified NOAA/NCDC weather records as the evidentiary foundation", "evidence_type": "Bar association / law firm sources", "source": "New York State Bar Association; Lewis Brisbois; Marshall Dennehey", "strength": "High", "gaps": "Doctrine confirmed for NY and analogous states (CT, MA, NJ, RI); not yet confirmed for IL/WI/MN/OH specifically — flagged for outside-counsel review before Rulebook activation" }, { "claim": "No done-for-you competitor correlates crew service records against certified weather data", "evidence_type": "Competitive research", "source": "This run's fresh web research", "strength": "Medium — materially revised", "gaps": "A point weather-certification vendor (Certified Snowfall Totals) and a pre-launch self-operated app (SnowProof) were found; neither offers full done-for-you assembly with human QA, but the original blueprint's 'no competitor' framing required correction across all artifacts" } ], "assumption_register": [ { "assumption": "A 15+ site commercial contractor has enough per-storm exposure for per-site subscription pricing to clear existing software spend", "impact_if_wrong": "MVP wedge needs a higher site-count floor or bundled pricing", "how_to_validate": "Track pilot signup site-count distribution against the 15-site floor", "blocking": false }, { "assumption": "Certified NOAA/NCDC station coverage is dense enough in the beachhead that low-confidence matches stay a minority", "impact_if_wrong": "Exception-queue workload compresses margin more than modeled", "how_to_validate": "Track WeatherMatchLowConfidenceFlagged rate across the first 50 files", "blocking": true } ], "language_conflict_map": [ { "term": "Documentation", "meaning_a": "The Storm Event Defense File and its evidence (StormWitness's usage)", "context_a": "StormWitness domain", "meaning_b": "General field-documentation software output (SiteCapture's usage)", "context_b": "Competitive landscape", "resolution": "Always qualify as 'Storm Event Defense File' or 'Documentation Subscription' in StormWitness copy to avoid conflation with competitor tool output" } ], "build_buy_integrate": [ { "subdomain": "Weather Correlation", "decision": "Buy/integrate", "reason": "NOAA/NCDC is the authoritative certified data source; no reason to build a competing weather data source" }, { "subdomain": "Completeness & QA", "decision": "Build", "reason": "The Completeness Rulebook and hard-fail rule engine are the core differentiator and must be owned" } ], "core_protection_strategy": [ "[PLACEHOLDER] owner to complete" ], "boundary_stress_tests": [ { "scenario": "A contractor asks StormWitness to characterize whether a specific tow/service was legally sufficient", "contexts_touched": [ "Completeness & QA", "File Assembly & Delivery" ], "breaks_if": "Any drafting output includes liability characterization or doctrine application", "verdict": "Holds — forbidden_actions hard-block this in the Defense File Drafting Agent's prompt template" }, { "scenario": "A major multi-day storm hits 80 sites across 3 pilot contractors simultaneously", "contexts_touched": [ "Intake & Normalization", "Completeness & QA" ], "breaks_if": "Manual-fulfillment review capacity is exceeded and the SLA is missed silently", "verdict": "Partially holds — the pilot cap (3-5 contractors) and communicated SLA limit exposure, but a true worst-case multi-day event could still miss the 48-hour window; flagged as an accepted launch-stage risk" } ], "unresolved_ownership": [ { "concept": "Off-season landscaping-liability documentation add-on", "candidates": [ "A new bounded context under the existing Rulebook & Doctrine Management pattern", "A wholly separate product line" ], "recommendation": "Defer the ownership decision until the full-pilot-season checkpoint; do not scope further pre-revenue" } ], "published_language_contracts": [ { "producer": "Weather Correlation", "consumer": "Completeness & QA", "contract": "WeatherMatchRecord {site_id, storm_event_id, station_id, confidence_tier, matched_at}", "versioning": "Additive fields only; confidence_tier enum is append-only" } ], "shared_kernel_warnings": [ "Do not let 'completeness' become an overloaded term — it always refers to the Completeness Checklist result, never used loosely for 'season completeness' without the Season Scorecard qualifier" ], "aggregate_stress_tests": [ { "aggregate": "DefenseFile", "scenario": "Two Ops/QA Reviewers attempt to approve the same file concurrently during a high-volume storm", "invariant_at_risk": "DefenseFileApproved sign-off uniqueness", "verdict": "Holds — application-layer optimistic locking prevents a double-approval" }, { "aggregate": "LitigationHoldRequest", "scenario": "The only available reviewer is the original file's assembling Ops/QA Reviewer", "invariant_at_risk": "Reviewer independence invariant", "verdict": "Breaks at single-founder scale — logged as an open risk requiring a hire or partner before true Litigation Hold compliance is achieved" } ], "agent_stress_tests": [ { "agent": "Defense File Drafting Agent", "scenario": "A contractor's submitted notes include language suggesting they believe a specific tow was 'clearly justified'", "failure_mode": "Agent echoes the contractor's characterization into the drafted file", "guardrail": "Forbidden-actions list blocks any liability-characterization language regardless of source framing", "verdict": "Holds, per prompt-template design in ai-engine-spec.md" }, { "agent": "Weather Match Agent", "scenario": "A multi-day storm spans a calendar-day boundary", "failure_mode": "Agent silently narrows the match window to a single day", "guardrail": "Multi-day storm handling is an explicit red-team test case before any new jurisdiction is activated", "verdict": "Holds only after red-team validation — flagged as a pre-automation test requirement" } ], "regulated_domain_handling": [ { "regime": "Unauthorized practice of law boundary", "applies_because": "StormWitness operates adjacent to litigation-relevant documentation without being a law firm", "controls": [ "Hard-excluded legal-argument/liability-characterization content in every template", "Non-legal-advice disclaimer on every deliverable" ], "evidence_required": [ "[PLACEHOLDER] owner to complete" ] } ], "unit_economics": { "price_model": "Flat per-contracted-site-per-month subscription, plus flat claim-triggered and season-end add-ons", "unit_of_value": "One Storm Event Defense File per Contracted Site per Storm Event", "gross_margin_pct": "50-65% at launch, expanding toward 65-75% by day 90", "cost_drivers": [ "Weather-data API + hosting (~$2-4/site-season)", "AI/model inference (~$3-6/site-season)", "Human review labor (~$8-20/site-season at launch, ~$3-7/site-season by day 90)" ], "breakeven_note": "Breakeven is a function of pilot-cohort size and per-site price realization, not modeled as a fixed month in this pilot-year model — see financial-model.csv" }, "margin_leakage_map": [ { "leakage": "Excess manual review time on low-confidence Weather Match cases", "cause": "Sparse station coverage at a subset of pilot sites", "impact": "Compresses gross margin below the 50% launch target", "mitigation": "Track WeatherMatchLowConfidenceFlagged rate and revisit A3 in product.assumptions if it exceeds 15%" } ], "slop_findings": [ { "pattern": "Generic 'AI-powered' claims without a specific mechanism", "status": "Not found", "note": "Every AI claim in customer-facing copy names the specific mechanism (certified NOAA/NCDC matching, deterministic completeness rules)" }, { "pattern": "Fabricated client names, testimonials, or statistics", "status": "Not found", "note": "All proof sections use dashed [PLACEHOLDER] slots keyed to real future events" } ], "drift_checks": [ { "stage": "Landing page vs. DNA lexicon", "status": "Checked", "findings": [ "[PLACEHOLDER] owner to complete" ] }, { "stage": "Delivery playbook vs. AI engine spec", "status": "Checked", "findings": "Aggregate and event names match between delivery-playbook.md's operational description and ai-engine-spec.md's technical schema" } ], "gates": [ { "id": "G1", "title": "No public claim before owner-action facts close", "passed": false, "checks": [ { "name": "Entity confirmed", "ok": false, "evidence": "Pending owner action — operating entity name/EIN not yet declared for StormWitness" }, { "name": "Ops/QA Reviewer identity confirmed", "ok": false, "evidence": "Pending owner action — the founder acts as the first Ops/QA Reviewer per launch-plan.md" }, { "name": "Trademark clearance", "ok": false, "evidence": "Pending owner action — 'StormWitness' web collision-checked (no collision found) but not yet formally cleared per brand.md" } ] }, { "id": "G2", "title": "Licensing boundary held across every artifact", "passed": true, "checks": [ { "name": "Non-legal-advice disclaimer present", "ok": true, "evidence": "Present in compliance-checklist.md, delivery-playbook.md, landing page compliance section, and DNA microsite.trust" }, { "name": "No doctrine-application language in customer-facing copy", "ok": true, "evidence": "Grepped clean across site/index.html and gtm-kit.md drafts" } ] } ], "contradiction_scan": [ { "id": "C1", "severity": "medium", "message": "The source blueprint's claim that 'no existing vendor... correlates service records against certified weather data' is too strong given Certified Snowfall Totals' existing product; corrected across business-plan.md, gtm-kit.md, brand.md, and the landing page to a more precise differentiation claim (done-for-you full assembly, not weather-data exclusivity)", "refs": [ "business-plan.md", "gtm-kit.md", "brand.md", "site/index.html" ] }, { "id": "C2", "severity": "low", "message": "The working brand name was changed from the blueprint's placeholder 'StormProof' to 'StormWitness' due to a name-collision risk with a pre-launch app called SnowProof found in fresh research; all artifacts use StormWitness consistently", "refs": [ "brand.md" ] } ], "rubric": { "categories": [ { "category": "Ubiquitous language consistency", "score": 5, "min": 3, "passed": true }, { "category": "Licensing boundary discipline", "score": 5, "min": 4, "passed": true }, { "category": "Evidence honesty (no fabrication)", "score": 5, "min": 4, "passed": true }, { "category": "DDD structural completeness", "score": 4, "min": 3, "passed": true }, { "category": "Competitive-landscape accuracy after fresh research", "score": 4, "min": 3, "passed": true } ], "pass": true, "average": 4.6 }, "foundry_package": { "version": "1.8.0", "checksum": "sha256:generated-locally", "counts": { "subdomains": 8, "bounded_contexts": 8, "aggregates": 5, "events": 16, "commands": 8, "policies": 5, "ai_agents": 3, "invariants": 5, "integrations": 2, "adrs": 3 }, "subset": { "subdomains": [ "Intake & Normalization", "Weather Correlation", "Completeness & QA", "File Assembly & Delivery", "Litigation Hold", "Rulebook & Doctrine Management", "Contractor Onboarding", "Season Reporting" ], "bounded_contexts": [ "Intake & Normalization", "Weather Correlation", "Completeness & QA", "File Assembly & Delivery", "Litigation Hold", "Rulebook & Doctrine Management", "Contractor Onboarding", "Season Reporting" ], "aggregates": [ "ContractedSite", "StormEvent", "DefenseFile", "LitigationHoldRequest", "SeasonScorecard" ], "events": [], "commands": [ "SubmitCrewCheckIn", "RunWeatherMatch", "RunCompletenessCheck", "ApproveDefenseFile", "DeliverDefenseFile", "RequestLitigationHold", "VerifyLitigationHold", "ActivateJurisdictionRulebook" ], "invariants": [ "A DefenseFile cannot reach DefenseFileApproved without an Op", "A LitigationHoldVerified event requires a Senior Reviewer di", "A ContractedSite's DefenseFile cannot skip Weather Match res", "A SeasonScorecard cannot reference sites outside the request", "A Completeness Rulebook version cannot be activated without " ], "policies": [ "Low-confidence routing", "Hard-fail completeness gate", "Reviewer independence on Litigation Hold", "Counsel review before jurisdiction activation", "Conservative completeness interpretation" ], "adrs": [ "ADR-1", "ADR-2", "ADR-3" ], "ai_agents": [ "Weather Match Agent", "Photo QA Agent", "Defense File Drafting Agent" ], "integrations": [ "NOAA/NCDC certified weather-station data API", "Dispatch platform export (Aspire / Service Autopilot / ArborGold)" ] }, "version_note": "Built fresh for this business from the source blueprint and this run's fresh research; not derived from any other business's foundry package." } }, "architecture": { "style": "Founder-operated, deterministic-rules-plus-vision/LLM pipeline with a human review chokepoint", "why": "Matches the blueprint's Fulfillment Process: no custom software at launch, automation deepens only after pilot volume proves the workflow", "rejected_alternatives": [ "Full custom multi-tenant SaaS platform at launch (over-built for a 3-5 contractor pilot)" ], "backend_modules": [ "Intake & Normalization", "Weather Correlation", "Completeness & QA", "File Assembly & Delivery", "Litigation Hold", "Rulebook & Doctrine Management", "Contractor Onboarding", "Season Reporting" ], "frontend_modules": [ "Landing page (site/index.html)", "Storm Readiness Gap Scan intake form" ], "api_boundaries": [ "No public API at launch; internal service boundaries only between the eight bounded contexts" ], "database_strategy": "Lightweight structured store (spreadsheet/Airtable-class tracker at launch) for ContractedSite, StormEvent, DefenseFile, LitigationHoldRequest, and SeasonScorecard records", "event_bus": "Not a formal message bus at launch-stage volume; events are recorded sequentially in the per-file audit log", "queue": "Simple per-site work queue ordered by storm-end time and pilot cap", "workflow_engine": "Manual/reviewer-driven workflow at launch; the Ops/QA Reviewer sign-off is the de facto workflow gate", "ai_orchestration": "Sequential agent chain (Intake Normalization -> Weather Match Agent -> Photo QA Agent -> Defense File Drafting Agent -> human sign-off), model-agnostic per the Model Portability layer", "rag_layer": "Retrieval grounded against the versioned Completeness Rulebook and the contractor's own contract terms", "file_storage": "Encrypted object storage for uploaded crew photos, treatment logs, and delivered PDF files", "authn_authz": "Single verified account per contractor client; role-based access for Ops/QA Reviewer vs. Senior Reviewer vs. Compliance Lead vs. Client", "admin_dashboard": "Founder/Compliance Lead view of the Completeness Rulebook version history and pilot-cohort metrics", "client_portal": "Searchable per-site, per-storm file archive; delivery is via secure portal or email at launch", "operator_dashboard": "Ops/QA Reviewer queue view (files awaiting review, files in the Exception Queue)", "observability": "Per-file audit log; cycle-time and rework-rate tracking", "audit_logging": "Append-only log of every ingest, draft, review, correction, and delivery event per file", "deployment": "Landing page deployed as a static site; fulfillment is founder/reviewer-operated outside any deployed application at launch" }, "slug": "snow-ice-storm-event-defense-desk", "project_name": "StormWitness — The Commercial Snow & Ice Storm Event Defense Desk", "ai_audit_plan": [ "[PLACEHOLDER] owner to complete" ], "ai_evaluation": [ "[PLACEHOLDER] owner to complete" ], "escalation_flows": [ "[PLACEHOLDER] owner to complete" ], "exception_flows": [ "[PLACEHOLDER] owner to complete" ], "manual_override_flows": [ "[PLACEHOLDER] owner to complete" ], "manual_override_rules": [ "Every manual override requires a logged justification", "No override may bypass the hard-fail Completeness Checklist rules themselves" ], "retry_flows": [ "[PLACEHOLDER] owner to complete" ], "rag_map": [ "[PLACEHOLDER] owner to complete" ], "read_models": [ "Ops/QA Reviewer queue view", "Contractor-facing searchable site/storm archive", "Season Completeness Scorecard rollup" ], "reporting_models": [ "Per-contractor Season Completeness Scorecard", "Founder/Compliance Lead pilot-cohort metrics dashboard" ], "prompt_chain_map": [ "[PLACEHOLDER] owner to complete" ], "prompt_versioning": "Every prompt template is versioned alongside the Completeness Rulebook version it references; a Rulebook update triggers a prompt-template review.", "quality_control_workflow": [ "[PLACEHOLDER] owner to complete" ], "human_in_the_loop_plan": [ "[PLACEHOLDER] owner to complete" ], "human_review_checkpoints": [ "Every DefenseFile before DefenseFileApproved", "Every LitigationHoldRequest before LitigationHoldVerified", "Every new jurisdiction's Completeness Rulebook before ActivateJurisdictionRulebook" ], "hallucination_controls": [ "Deterministic Completeness Checklist rules never delegated to model judgment", "Defense File Drafting Agent grounded only in normalized structured inputs, never free-form generation", "Forbidden-actions list hard-blocks doctrine-application and liability-characterization language" ], "final_recommendations": [ "Hold 100% human review through the first 20 files before evaluating any automation expansion", "Do not activate a second jurisdiction's Rulebook before the full-pilot-season checkpoint", "Recheck the SnowProof and Certified Snowfall Totals competitive landscape quarterly" ], "separation_of_duties": [ "[PLACEHOLDER] owner to complete" ], "data_duplication_notes": [ "[PLACEHOLDER] owner to complete" ], "data_quality_risks": [ "Dispatch-tool export format drift", "Sparse NOAA/NCDC station coverage in rural sites", "Crew submission gaps during high-volume multi-day storms" ], "data_retention": [ "[PLACEHOLDER] owner to complete" ], "critical_path": [ "[PLACEHOLDER] owner to complete" ], "escalation_matrix": [ "[PLACEHOLDER] owner to complete" ], "business_understanding": { "summary": "StormWitness produces a weather-correlated Storm Event Defense File for every contracted site with an active winter service season, so commercial snow & ice contractors never lose the 'storm in progress' documentation defense that stands between a routine storm response and an unwinnable slip-and-fall claim.", "customer_profile": "Commercial snow & ice management contractor owner/GM or Operations/Risk Manager servicing 15-150 contracted sites, $500K-$8M seasonal revenue, in a snowbelt metro with an active GL policy.", "customer_pain": "Crews plow and treat under time pressure while the 'storm in progress' doctrine requires precise timestamped, geotagged, weather-matched evidence — a single missing element can make the defense unavailable, and the record has to survive intact for the 2-3 years a typical slip-and-fall suit takes to resolve.", "paid_outcome": "A complete, weather-correlated Storm Event Defense File delivered within 24-48 hours of every storm, reviewed by an Ops/QA Reviewer; when an actual claim arrives, an expedited, independently-verified Litigation Hold package.", "value_creation": "Removes the choice contractors currently face between reconstructing evidence from scratch after a claim (often 18+ months later, when it's too late) or doing nothing, at a fraction of that reconstruction cost and without StormWitness ever practicing law or characterizing liability.", "why_ai_native": "The workflow decomposes cleanly into multimodal photo QA, deterministic completeness-checklist rules, and certified-weather-data correlation grounded drafting — near-zero marginal cost per file, with a human judgment chokepoint at every sign-off, and file quality rises as frontier vision/reasoning models improve at photo QA and anomaly detection.", "operational_risks": [ "A materially incomplete file surfacing during actual litigation destroys trust in a completeness-first offer", "Demand proves trade-press-level awareness without real recurring willingness to pay", "A single founder cannot provide genuine reviewer independence for Litigation Hold pre-hire" ], "assumptions": [ "A 15+ site commercial contractor has enough per-storm exposure for per-site subscription pricing to matter", "A free Storm Readiness Gap Scan converts to a paid pilot at a meaningful rate", "Certified NOAA/NCDC station coverage is dense enough across the beachhead for most matches to resolve at high confidence" ], "validation_questions": [ "Does the first pilot cohort hit zero materially-incomplete files?", "Does the Gap Scan-to-pilot conversion rate clear 15-25%?", "Does the full pilot cohort renew for a second season?" ] }, "domain_discovery": { "actors": [ { "actor": "Contractor owner/GM or Operations/Risk Manager", "role": "Economic buyer", "goals": [ "Avoid an unwinnable slip-and-fall claim and protect GL insurance renewal terms" ], "decisions": [ "Whether to pilot StormWitness" ], "pain_points": [ "No independent read on documentation completeness short of reconstructing evidence after a claim" ] }, { "actor": "Dispatch coordinator / office manager", "role": "Champion / day-to-day user", "goals": [ "Get crew check-ins and photos captured correctly the first time" ], "decisions": [ "Which storm data to submit; when to escalate a missing-evidence flag" ], "pain_points": [ "Screenshotting crew texts into folders manually today" ] }, { "actor": "Ops/QA Reviewer", "role": "Human chokepoint / reviewer", "goals": [ "Zero materially incomplete files" ], "decisions": [ "Approve, correct, or escalate every file" ], "pain_points": [ "Reviewing low-confidence Weather Match cases under SLA time pressure" ] }, { "actor": "Contractor's own retained attorney", "role": "Legal approver for escalated questions", "goals": [ "A defensible documentation record if a claim reaches litigation" ], "decisions": [ "How or whether to invoke the 'storm in progress' doctrine using the delivered file" ], "pain_points": [ "Incomplete evidence that forces follow-up before a legal opinion can be formed" ] }, { "actor": "Claimant (slip-and-fall plaintiff)", "role": "Subject of the workflow, never a StormWitness client", "goals": [ "Recover for an injury they believe was caused by inadequate snow/ice removal" ], "decisions": [ "Pursue or drop a claim" ], "pain_points": [ "Not applicable — StormWitness has no relationship with the claimant" ] } ], "glossary": [ { "term": "Storm Event Defense File", "definition": "The complete, weather-correlated, human-reviewed PDF record for one contracted site and one storm event.", "used_by": "Ops/QA Reviewer; Contractor", "context": "File Assembly & Delivery, Completeness & QA", "example": "Site #14's Defense File for the January 12 storm, delivered within 36 hours", "notes": "The canonical deliverable name — never substitute 'report', 'packet', or 'bundle'" }, { "term": "Weather Match", "definition": "The certified NOAA/NCDC weather-station data correlated to a site's exact coordinates and a storm's time window, with a confidence tier.", "used_by": [ "Weather Correlation Agent", "Ops/QA Reviewer" ], "context": "Weather Correlation", "example": "A High-confidence Weather Match from the nearest station 2.1 miles from the site", "notes": "Always capitalized as a proper term" }, { "term": "Completeness Rulebook", "definition": "The versioned, outside-counsel-reviewed, per-jurisdiction rule set encoding the 'storm in progress' doctrine's evidentiary requirements.", "used_by": [ "Compliance Lead", "Completeness Rule Engine" ], "context": "Rulebook & Doctrine Management", "example": "The Illinois Completeness Rulebook v1, activated after outside-counsel review", "notes": "Distinct from the file-level Completeness Checklist, which is the Rulebook applied to one file" }, { "term": "Litigation Hold", "definition": "The claim-triggered, expedited, independently re-verified retrieval and certification of an existing site's Defense File.", "used_by": [ "Senior Reviewer", "Contractor" ], "context": "Litigation Hold", "example": "A Litigation Hold requested the day a claim notice arrives, verified within one business day", "notes": "Never called 'rush service' — always 'Litigation Hold'" }, { "term": "Season Completeness Scorecard", "definition": "The season-end rollup of a contractor's documentation completeness across all contracted sites, delivered ahead of GL insurance renewal.", "used_by": [ "Ops/QA Reviewer", "Contractor's GL insurance broker" ], "context": "Season Reporting", "example": "A 96% completeness Scorecard handed to the broker at April renewal", "notes": "Never a guarantee of renewal terms — completeness only" } ], "decisions": [ { "decision": "Approve a Defense File as complete", "who": "Ops/QA Reviewer", "inputs": [ "Normalized evidence", "Resolved Weather Match", "CompletenessCheckResult" ], "rule": "Every required element present per the active Completeness Rulebook version", "output": "DefenseFileApproved", "risk": "A hard-fail rule missing a genuine edge case" }, { "decision": "Verify a Litigation Hold file independently", "who": "Senior Reviewer", "inputs": [ "Original delivered DefenseFile", "Claim trigger documentation" ], "rule": "Independent re-verification by a reviewer distinct from the original assembler", "output": "LitigationHoldVerified", "risk": "No genuinely independent second reviewer exists pre-hire" }, { "decision": "Activate a new jurisdiction's Completeness Rulebook", "who": "Compliance Lead", "inputs": [ "Proposed Rulebook version", "Outside counsel review" ], "rule": "No activation without logged counsel sign-off and red-team edge-case testing", "output": "RulebookUpdated", "risk": "A doctrine nuance misapplied despite review" } ], "events": [ { "event": "CrewCheckInIngested", "meaning": "Normalized crew evidence has been recorded for a site/storm", "trigger": "SubmitCrewCheckIn command succeeds", "downstream": [ "[PLACEHOLDER] owner to complete" ] }, { "event": "WeatherMatchResolved", "meaning": "A certified weather match has been found and confidence-scored for the site/time window", "trigger": "RunWeatherMatch command succeeds at or above the confidence threshold", "downstream": "Completeness Checklist evaluation begins" }, { "event": "DefenseFileApproved", "meaning": "An Ops/QA Reviewer has signed off on a complete file", "trigger": "ApproveDefenseFile command succeeds", "downstream": "File delivery to the contractor's portal" }, { "event": "LitigationHoldVerified", "meaning": "A Senior Reviewer has independently re-verified a claim-triggered file", "trigger": "VerifyLitigationHold command succeeds", "downstream": "Expedited certified package delivered to the contractor" } ] }, "core_domain_analysis": { "primary_core": "Weather Correlation — the certified NOAA/NCDC weather-station matching pipeline tuned to exact site coordinates and time windows, which is the specific evidentiary element the doctrine requires and no self-operated competitor tool provides as a done-for-you match.", "secondary_cores": [ "Completeness & QA (the human trust chokepoint that guarantees no file ships known-incomplete)", "Litigation Hold (the independent-verification safety valve for claim-triggered urgency)", "Rulebook & Doctrine Management (the maintained, counsel-reviewed doctrine library)" ], "supporting_may_become_core": [ "Season Reporting — could become a differentiating insurance-broker-facing product as Scorecard volume and broker partnerships grow" ], "generic_do_not_distract": [ "Intake & Normalization (parsing dispatch-tool exports is not itself defensible)", "Contractor Onboarding (standard account-setup hygiene, not a differentiator)" ], "rationale": "If a future frontier model makes photo QA and drafting trivial for any competitor, StormWitness's durable value is entirely in the maintained Completeness Rulebook, the certified Weather Match pipeline's precision, and the independent-review trust chokepoints — none of which a generic AI wrapper replicates, and none of which either existing competitor category (self-operated tools or point weather-data vendors) currently combines." } }, "architecture": { "slug": "snow-ice-storm-event-defense-desk", "archetypes": [ "regulated system", "CRUD/workflow application", "internal operations platform" ], "archetype_impact": "Contracted Site, storm event, and contractor-account identity are global query parameters — every read/write is scoped by site, storm, and contractor account, not just tenant.", "personality": [ "workflow-heavy", "cost-sensitive", "highly regulated", "highly secure" ], "forces_ranked": [ { "force": "compliance", "why": "Regulated verticals gate release; the architecture must prove, not assert, compliance." }, { "force": "auditability", "why": "Every release decision, every evidence toggle, must be defensible in review." }, { "force": "reliability", "why": "A broken blueprint is a broken release gate — availability is a product feature." }, { "force": "data integrity", "why": "Evidence is the product; a corrupted citation is a shipped defect." }, { "force": "maintainability", "why": "One team maintains dozens of blueprints; the shape must be identical across them." } ], "tradeoffs": [ "Prioritizing auditability slows raw throughput — accepted; the product IS the audit trail.", "Choosing a modular monolith trades independent scaling for a single deploy story — accepted while the team is small.", "Using managed Cloud primitives trades some portability for zero ops — accepted; data is portable, runtime is not the moat." ], "quality_scenarios": [ { "attribute": "Performance (interactive p95)", "target": "600 ms on Blueprint detail routes", "assumption": "Measured from Cloud edge, warm cache." }, { "attribute": "Availability", "target": "99.5% (with March-reporting-window freeze protection)", "assumption": "Rolling 30-day window; excludes announced maintenance." }, { "attribute": "RTO", "target": "24h" }, { "attribute": "RPO", "target": "24h (daily backups)" }, { "attribute": "Latency (edge function warm)", "target": "≤ 800ms p95 excluding upstream AI calls" }, { "attribute": "Data durability", "target": "11 nines via managed Postgres + storage replication" }, { "attribute": "Security", "target": "OWASP ASVS L1 baseline" }, { "attribute": "Auditability", "target": "100% of release decisions + evidence toggles logged with actor + timestamp" }, { "attribute": "Maintainability", "target": "New blueprint reaches validation-microsite state in ≤ 1 working session" }, { "attribute": "Deployment frequency", "target": "≥ 5 deploys/week without incident" }, { "attribute": "Observability", "target": "Every edge function emits correlationId; retries + phases visible in diagnostics drawer" }, { "attribute": "Cost envelope", "target": "Idle per-blueprint cost ≈ $0; active < $5/month at MVP traffic" }, { "attribute": "Scalability", "target": "Horizontal by blueprint count; single blueprint sized for < 10 req/s sustained" } ], "options": [ { "style": "simple monolith", "fits_when": "Single team, low traffic, no independent scaling concerns.", "fits_here": "Matches the per-blueprint scope — one microsite, one schema, one code path.", "wrong_here": "Would couple every blueprint into a single deploy — not acceptable at network scale.", "complexity": "low", "cost": "low", "ops_burden": "low", "security_impact": "Small surface, single audit boundary.", "scaling_path": "Vertical scale only; hits ceiling on team velocity, not compute.", "team_fit": "Ideal for one dev; fine at MVP.", "recommended": false }, { "style": "modular monolith", "fits_when": "Multiple bounded contexts but shared deploy lifecycle acceptable.", "fits_here": "Each blueprint is a module inside the network shell; shared shell, isolated data.", "wrong_here": "Wrong only if a blueprint needs independent SLOs — none currently do.", "complexity": "moderate", "cost": "low", "ops_burden": "low", "security_impact": "Single trust boundary; row-level isolation carries the tenancy load.", "scaling_path": "Modules become services only when SLOs or teams diverge.", "team_fit": "Best fit for a small team maintaining many blueprints.", "recommended": true }, { "style": "serverless", "fits_when": "Bursty, per-request workloads with idle-to-zero cost targets.", "fits_here": "Edge functions already handle sync, docs, legal, seed articles, integrity — pay-per-invoke.", "wrong_here": "Wrong for long-running orchestrations; IDLE_TIMEOUT already bit us on legal docs.", "complexity": "moderate", "cost": "low", "ops_burden": "moderate", "security_impact": "Function-scoped IAM; secrets via managed vault.", "scaling_path": "Auto; watch cold-start p95 and per-invocation cost.", "team_fit": "Good — team already ships functions weekly.", "recommended": false }, { "style": "microservices", "fits_when": "Multiple teams, divergent SLOs, independent release cadence required.", "fits_here": "Nothing here justifies it; single team, single deploy cadence, shared data plane.", "wrong_here": "Adds network, discovery, deploy topology, and observability cost with zero product benefit.", "complexity": "very high", "cost": "high", "ops_burden": "high", "security_impact": "Bigger attack surface, more inter-service auth to get right.", "scaling_path": "Best-in-class if the org can afford it.", "team_fit": "Wrong for this team.", "recommended": false }, { "style": "event-driven", "fits_when": "Async fan-out, decoupled producers/consumers, replayable history required.", "fits_here": "Only the sync + integrity pipeline is fan-out; keep it as background jobs, not a broker.", "wrong_here": "Broker + schema registry + DLQ topology is overkill for current volumes.", "complexity": "high", "cost": "moderate", "ops_burden": "high", "security_impact": "Extra ACLs; message-level auth needed.", "scaling_path": "Excellent for future audit-log fan-out, revisit at 10x volume.", "team_fit": "Team can operate a small in-process queue; not a full broker yet.", "recommended": false }, { "style": "workflow/orchestration", "fits_when": "Long, multi-step, resumable pipelines with human-in-the-loop steps.", "fits_here": "Blueprint pipeline (sources → articles → integrity → smoke test) already smells like this.", "wrong_here": "Full engine (Temporal/Airflow) is heavy; a typed in-app queue with retries covers today's needs.", "complexity": "high", "cost": "moderate", "ops_burden": "moderate", "security_impact": "Central choke point — must be hardened.", "scaling_path": "Adopt engine once we cross ~10 concurrent long-running jobs per blueprint.", "team_fit": "Would require operator ramp-up.", "recommended": false } ], "chosen_style": "modular monolith", "chosen_rationale": "Modular monolith with edge functions for bursty AI/generation — one audit boundary, low ops burden, easy per-team ownership.", "rejected": [ { "style": "microservices", "why_rejected": "Adds network, discovery, deploy topology, and observability cost with zero product benefit." }, { "style": "event-driven", "why_rejected": "Broker + schema registry + DLQ topology is overkill for current volumes." } ], "target": { "overview": "React shell → Lovable Cloud (Postgres + Auth + Storage + Edge Functions). Every blueprint is a module inside the shell; per-vertical differences live in derived DNA, not in separate deploys. Compliance posture: Domain-specific (weather-matched evidence, Ops/QA and Senior Reviewer sign-offs, multi-year retention schedules).", "frontend": "Vite + React + TypeScript + Tailwind + shadcn primitives; per-blueprint themed via Design DNA; job queue for background pipelines; URL-persisted filter state on audit + diagnostics.", "backend": "Deno-based edge functions per capability. Long generations split into per-item endpoints to stay under IDLE_TIMEOUT.", "data": "Managed Postgres with RLS + JSONB for shape drift. Object storage for source files + generated artifacts.", "api": "REST-ish RPC over edge functions with typed payloads; correlationId on every call for retry/diagnostics.", "authn_authz": "Managed OAuth (Google default). Roles in a dedicated user_roles table + has_role() SECURITY DEFINER function referenced by RLS policies.", "integrations": "GitHub (public read for sync + sources), Lovable AI Gateway (all LLM calls), Cloud Storage (artifacts). No third-party CRM/email yet.", "background_jobs": "blueprintJobQueue in-app: per-slug concurrency limit, exponential backoff + jitter, cancel + invalidate, retention of last error diagnostics.", "object_storage": "Cloud Storage buckets scoped per blueprint slug; signed URLs for artifact download.", "notifications": "In-app toasts + audit trail entries. Email/webhook deferred until owners request it.", "search": "Postgres FTS on blueprint titles + evidence claims; client-side filter for audit trail. Dedicated index deferred.", "analytics": "Lightweight event log in Postgres; dashboard-grade analytics deferred until we have a paying tenant.", "ai": "not applicable", "observability": "correlationId per request, per-phase timings, retry timeline in diagnostics drawer, per-blueprint pipeline status panel, JSON report export.", "deployment": "Preview + Production environments; edge functions deploy with the app; Postgres migrations shipped via managed migration tool.", "security": "RLS on every public table; roles in user_roles; secrets in managed vault; OWASP ASVS L1 baseline.", "dr": "Daily backups; restore drill twice/year." }, "modules": [ { "name": "Blueprint Core", "responsibility": "Owns the SeedBusiness catalog, release decisions, evidence register, owner actions.", "owned_data": [ "seed business rows", "release_decision", "evidence items", "owner-action state" ], "entities": [ "SeedBusiness", "EvidenceItem", "OwnerAction", "ReleaseDecision" ], "interfaces": [ "React store (StoreProvider)", "public read via microsite route" ], "depends_on": [ "Content Pipeline (for source files + articles)", "Cloud auth" ], "events_produced": [ "release.decision.changed", "evidence.status.changed", "owner.action.resolved" ], "events_consumed": [ "sync.blueprint.applied", "integrity.check.completed" ], "failure_risks": [ "Duplicate slug in seed → React key crash (mitigated by dedupe in mergedSeed)", "Evidence drift after sync" ], "scaling": "Bounded by SEED size; irrelevant even at 10x.", "future_split_trigger": "Split out Blueprint Core into an independent deployment when its throughput or a distinct scaling profile justifies it; not warranted pre-revenue.", "purpose": "Owns the SeedBusiness catalog, release decisions, evidence register, owner actions.", "owned_domain": [ "seed business rows", "release_decision", "evidence items", "owner-action state" ], "application_services": [ "BlueprintCoreService" ], "infra_adapters": [ "Managed Postgres", "Cloud Storage" ], "public_interfaces": [ "React store (StoreProvider)", "public read via microsite route" ], "forbidden_deps": [] }, { "name": "Content Pipeline", "responsibility": "Fetches GitHub sources, generates docs/seed articles, runs citation integrity, per slug with concurrency + backoff.", "owned_data": [ "blueprint_sources", "blueprint_seed_articles", "job status per slug", "integrity results" ], "entities": [ "SourceFile", "SeedArticle", "IntegrityReport", "JobState" ], "interfaces": [ "blueprintJobQueue API", "edge functions: fetch-blueprint-sources, generate-seed-articles, generate-blueprint-docs" ], "depends_on": [ "Cloud edge functions", "AI Gateway", "GitHub public read" ], "events_produced": [ "sources.fetched", "articles.generated", "integrity.completed", "cache.invalidated" ], "events_consumed": [ "blueprint.cache.invalidate" ], "failure_risks": [ "Edge IDLE_TIMEOUT on long generations (mitigated: per-doc endpoints + retries)", "Upstream AI 5xx storms" ], "scaling": "Concurrency + backoff configurable in UI; scales with edge function limits.", "future_split_trigger": "If cross-blueprint queueing coordination is needed, promote to a shared job service.", "purpose": "Fetches GitHub sources, generates docs/seed articles, runs citation integrity, per slug with concurrency + backoff.", "owned_domain": [ "blueprint_sources", "blueprint_seed_articles", "job status per slug", "integrity results" ], "application_services": [ "ContentPipelineService" ], "infra_adapters": [ "Managed Postgres", "Cloud Storage" ], "public_interfaces": [ "blueprintJobQueue API", "edge functions: fetch-blueprint-sources, generate-seed-articles, generate-blueprint-docs" ], "forbidden_deps": [] }, { "name": "Runtime & Capabilities", "responsibility": "Per-blueprint runtime modules — verification, SEO, legal docs, chatbot — with retry + diagnostic history.", "owned_data": [ "capability status per slug", "runtime module errors", "chatbot threads + FAQ" ], "entities": [ "CapabilityStatus", "RuntimeError", "ChatMessage" ], "interfaces": [ "React Runtime tab", "edge functions: verify-blueprint, generate-seo-posts, generate-legal-docs/*, blueprint-chat" ], "depends_on": [ "Content Pipeline (grounding)", "AI Gateway" ], "events_produced": [ "capability.status.changed", "runtime.error.recorded" ], "events_consumed": [ "cache.invalidated" ], "failure_risks": [ "AI provider outage", "Prompt drift causing ungrounded output" ], "scaling": "Per-slug; independent of network size.", "future_split_trigger": "Split out Runtime & Capabilities into an independent deployment when its throughput or a distinct scaling profile justifies it; not warranted pre-revenue.", "purpose": "Per-blueprint runtime modules — verification, SEO, legal docs, chatbot — with retry + diagnostic history.", "owned_domain": [ "capability status per slug", "runtime module errors", "chatbot threads + FAQ" ], "application_services": [ "Runtime&CapabilitiesService" ], "infra_adapters": [ "Managed Postgres", "Cloud Storage" ], "public_interfaces": [ "React Runtime tab", "edge functions: verify-blueprint, generate-seo-posts, generate-legal-docs/*, blueprint-chat" ], "forbidden_deps": [] }, { "name": "Sync & Rollback", "responsibility": "Daily GitHub sync of blueprint definitions with dry-run, partial-apply, and server-backed rollback of last snapshot.", "owned_data": [ "sync_runs", "sync_snapshots per slug", "audit_trail" ], "entities": [ "SyncRun", "SyncDiff", "SyncSnapshot", "AuditEntry" ], "interfaces": [ "/github-sync page", "edge functions: github-sync-blueprints, rollback-blueprint-sync" ], "depends_on": [ "Blueprint Core", "Cloud storage for snapshots" ], "events_produced": [ "sync.run.completed", "sync.blueprint.applied", "sync.blueprint.rolled_back" ], "events_consumed": [], "failure_risks": [ "Partial apply leaving mixed state (mitigated by per-blueprint snapshots)", "Audit trail size growth" ], "scaling": "Paginate audit trail; snapshot retention window is finite.", "future_split_trigger": "Split out Sync & Rollback into an independent deployment when its throughput or a distinct scaling profile justifies it; not warranted pre-revenue.", "purpose": "Daily GitHub sync of blueprint definitions with dry-run, partial-apply, and server-backed rollback of last snapshot.", "owned_domain": [ "sync_runs", "sync_snapshots per slug", "audit_trail" ], "application_services": [ "Sync&RollbackService" ], "infra_adapters": [ "Managed Postgres", "Cloud Storage" ], "public_interfaces": [ "/github-sync page", "edge functions: github-sync-blueprints, rollback-blueprint-sync" ], "forbidden_deps": [] }, { "name": "Design & Architecture DNA", "responsibility": "Deterministic per-blueprint design + architecture briefs used to gate release readiness.", "owned_data": [ "derived only — no persistence" ], "entities": [ "DesignDNA", "ArchitectureDNA" ], "interfaces": [ "React panels in Business Detail" ], "depends_on": [ "Blueprint Core" ], "events_produced": [], "events_consumed": [], "failure_risks": [ "Vertical → profile drift if new verticals are not mapped" ], "scaling": "Pure functions; free.", "future_split_trigger": "Split out Design & Architecture DNA into an independent deployment when its throughput or a distinct scaling profile justifies it; not warranted pre-revenue.", "purpose": "Deterministic per-blueprint design + architecture briefs used to gate release readiness.", "owned_domain": [ "derived only — no persistence" ], "application_services": [ "Design&ArchitectureDNAService" ], "infra_adapters": [ "Managed Postgres", "Cloud Storage" ], "public_interfaces": [ "React panels in Business Detail" ], "forbidden_deps": [] } ], "data_architecture": { "primary_db": "Managed Postgres (Cloud)", "secondary": [ "Object storage for artifacts + snapshots", "Client localStorage for UI state (filters, drawer state) — never for auth" ], "cache": "React Query + module-level memoization; no dedicated cache service.", "search": "Postgres FTS on titles + evidence; consider pg_trgm on slugs.", "vector": "not applicable", "object_storage": "Per-slug prefixes; lifecycle rules to prune stale sync snapshots.", "schema_strategy": "Normalized core + JSONB for evolving shapes (evidence details, capability status).", "migrations": "Forward-only migrations reviewed in PR; every CREATE TABLE ships GRANTs + RLS enable + policies in the same migration.", "backups": "Managed daily backups with 30-day retention.", "retention": "Audit trail retained ≥ 1y; sync snapshots retained 90d; error diagnostics retained 30d.", "audit_logs": "audit_trail table + append-only pattern; export CSV from UI.", "soft_delete": "Soft-delete evidence via status transition; hard-delete only via owner-initiated purge.", "privacy": "Only owner-supplied facts persist; service records, attestations, regulator correspondence handled per vertical policy.", "encryption": "TLS 1.2+ in transit; AES-256 at rest via managed storage.", "multi_tenancy": "Row-level tenancy keyed on auth.uid() + blueprint slug; RLS policies enforce isolation." }, "api": { "style": "REST-ish RPC over edge functions with JSON payloads; typed client wrappers.", "public_vs_internal": "Public microsite reads via Postgres RLS-protected queries; internal capability calls via authenticated edge functions.", "versioning": "Version via function name suffix (v1, v2) when breaking; additive changes preferred.", "rate_limiting": "Per-user + per-slug in edge functions; UI-level concurrency caps for AI calls.", "idempotency": "Sync + rollback carry an idempotency key; retries safe.", "pagination": "Cursor pagination on audit trail; offset paging tolerated on small lists.", "error_format": "{ code, message, correlationId, retryable, details? } — normalized in client.", "webhook_security": "HMAC-signed webhooks (deferred until we accept inbound webhooks).", "retries": "Exponential backoff + jitter, capped attempts, respect idempotency keys.", "contract_testing": "Zod schemas shared between client + edge; smoke test runner exercises each endpoint.", "backward_compat": "Additive fields only; deprecations announced in audit trail before removal.", "contract_testing_plan": "Intake, source-result, and delivery payload schemas are contract-tested per consumer; the JSON contract between AI layers is schema-pinned and versioned." }, "security": { "authn": "Managed OAuth (Google default). Session in httpOnly cookie / managed client storage.", "authz": "user_roles table + has_role() SECURITY DEFINER, referenced from RLS policies. Never store roles on profiles.", "tenant_isolation": "RLS on every public table; every query filters by auth.uid() or by an explicit owner grant.", "secrets": "Managed vault; never in client bundle; edge functions read via runtime env.", "encryption": "TLS in transit; AES-256 at rest; column-level encryption only when regulation requires.", "session": "Short-lived access tokens + refresh rotation; SSR cookie parity for edge routes.", "input_validation": "Zod schemas at the edge boundary; reject on unknown fields.", "api_protection": "Rate limits + WAF rules on public endpoints; correlationId logging for abuse forensics.", "audit_log": "Every release decision, evidence toggle, sync, and rollback records actor + timestamp + before/after.", "admin_access": "Admin actions gated behind role check + two-key confirmation on destructive operations.", "supply_chain": "Lockfile pinning + weekly dependency scan; SBOM produced on release.", "threat_model": [ "Prompt injection via ingested source files → sanitize + refuse instructions from ingested content.", "Cross-tenant read via missing RLS on new table → migration checklist blocks merge.", "Rollback abuse to overwrite recent legitimate edits → rollback preview + confirm-typed pattern.", "AI cost DOS by repeated regeneration → per-slug rate limits + concurrency cap." ], "abuse_cases": [ "Malicious owner uploads privileged content into a public microsite field.", "Sync run tampered with to inject a slug that overlaps a real blueprint.", "Attacker triggers regeneration loop to drive AI cost." ], "zero_trust": "Every service call authenticates; no implicit trust between edge functions.", "asvs_notes": "OWASP ASVS L1 baseline." }, "reliability": { "failure_modes": [ "Edge function IDLE_TIMEOUT on long AI generations.", "Upstream AI provider 5xx / rate limit.", "GitHub API rate limit during sync.", "Postgres connection saturation during sync fan-out." ], "graceful_degradation": "Runtime tab modules degrade independently; microsite serves cached last-known-good content when generation fails.", "retry_policy": "Exponential backoff + jitter, max 5 attempts, respect Retry-After.", "timeouts": "Edge function ≤ 120s wall clock (safety margin under 150s limit); client fetch ≤ 60s per call.", "circuit_breaker": "Client-side per-endpoint breaker: after 3 consecutive IDLE_TIMEOUTs, pause 5m and surface to UI.", "queueing": "In-app blueprintJobQueue with concurrency limits per slug.", "idempotency": "Sync + rollback idempotent via key; generation endpoints idempotent per (slug, doc_key).", "dlq": "Failed jobs recorded in error diagnostics; user re-triggers manually (no auto-DLQ needed at current volume).", "transactions": "Multi-row writes wrapped in single transaction; audit entry written in the same transaction as the mutation.", "dr": "Daily backup + semi-annual restore drill.", "incident_response": "correlationId in every log line; on-call runbook per capability module; smoke test replays post-incident.", "slos": [ { "name": "Interactive p95", "target": "600 ms on blueprint detail" }, { "name": "Availability", "target": "99.5% (with March-reporting-window freeze protection)" }, { "name": "Sync success rate", "target": "≥ 99% per daily run over rolling 7 days" }, { "name": "Generation success rate", "target": "≥ 95% per doc across last 7d (excludes provider outages)" } ] }, "scaling": { "mvp_can_stay_simple": [ "Single Postgres, single region.", "No dedicated search or vector index.", "In-app job queue; no message broker." ], "modular_now": [ "Content Pipeline is already isolated behind blueprintJobQueue — future extraction is a 1-day job.", "Runtime capabilities are one function per module — swap in isolation." ], "deferrable": [ "Workflow engine (Temporal/Airflow).", "Vector DB / RAG.", "Multi-region replication.", "Feature flag service (env-based toggle covers MVP)." ], "breaks_first": "Edge function IDLE_TIMEOUT under multi-doc generation — already addressed by per-doc endpoints; watch for regression.", "db_path": "Vertical scale → read replica → partition by tenant if a single tenant dominates load.", "jobs_path": "In-app queue → dedicated worker → workflow engine, gated by concurrency + resumability need.", "cache_path": "React Query only → HTTP cache headers → CDN edge cache for microsite content.", "search_path": "Postgres FTS → pg_trgm → dedicated search only when p95 breaches SLO.", "files_path": "Managed object storage → CDN → per-region cache if traffic warrants.", "api_path": "Vertical edge function scale → per-capability autoscaling → extract hot module to its own service.", "multi_region": "Not planned; introduce only on customer contract with residency requirement.", "cost_control": "Per-blueprint AI budget, concurrency cap, smoke-test cache; monthly cost review with per-blueprint attribution." }, "ai": { "provider": "Frontier LLM via API with provider-agnostic prompt contracts; a second vendor is configured for failover so a released deliverable never depends on a single model.", "prompt_mgmt": "Extraction, drafting, and matrix prompts are held in versioned files with eval-gated deploys and one-step rollback; prompt changes require diff review.", "rag": "A versioned, jurisdiction-scoped Completeness Rulebook for the 'storm in progress' doctrine is retrieved with source-scoped filters; drafting is grounded and citation-anchored to the Rulebook text and matched weather data, never free-form generation.", "vector": "Not warranted pre-revenue — the rule pack is small and structured, so section/keyword lookups suffice until a larger corpus justifies similarity search.", "embeddings": "Deferred with the vector store; rule-pack keys are structured (element, source, subsection), not semantic.", "eval": "A gold set of specialist-released packs measures element-extraction F1 and completeness-gate agreement per model release; accuracy vs specialist labels is reviewed on a fixed cadence.", "hitl": "Specialist release is never automated; a domain expert signs off on the exception queue, with sampling QA on a fraction of outputs and expert red-team on the first releases.", "guardrails": "Field-locked templates, source-tie reconciliation, and completeness rules mean a draft missing a required field emits a MISSING_ELEMENT exception rather than inventing content.", "prompt_injection": "Source documents are treated as data, never instructions; the red-team suite includes injected-instruction files disguised as legitimate inputs.", "leakage": "Contractor-account and site identifiers are scoped per Defense File; retrieval is scoped per client; provider training-use is disabled; there is no cross-client corpus.", "fallback": "A manual specialist workbench runbook plus the second LLM vendor keep production moving if the primary model is unavailable.", "latency_cost": "Inference cost per deliverable is bounded at launch and trends down with volume; the standard SLA leaves generous headroom over model latency.", "memory": "Agents are stateless per case; durable knowledge lives in the versioned rule pack and SOP library, not in model memory.", "tool_permissions": "The prompt runner has no tool access beyond returning JSON; search ordering, document assembly, and delivery are deterministic code.", "auditability": "Every prompt+output pair is logged to the per-case audit trail with version tags alongside the specialist release record.", "citation": "Every drafted element carries the source provision it satisfies, and every matrix entry carries the search or record it came from." }, "devops": { "environments": [ "Preview (per branch)", "Production" ], "cicd": "Lovable build pipeline; deploys on merge; edge functions ship atomically with the app.", "iac": "Cloud managed; migrations + config in-repo.", "secrets": "Managed vault; separate values per environment.", "preview_envs": "Automatic per branch; seeded with anonymized fixtures.", "migrations": "Forward-only; migrations reviewed for GRANT + RLS + policies; every table gated by the migration checklist.", "rollback": "App: redeploy previous build. Data: server-backed rollback per blueprint via rollback-blueprint-sync.", "release_style": "Continuous deploy with feature flags; canary only when a change touches shared shell.", "feature_flags": "Env-based booleans at MVP; consider a flag service when we have > 20 flags in flight.", "monitoring": "Cloud platform metrics + per-function logs + client error reporting.", "alerting": "SLO burn-rate alerts + IDLE_TIMEOUT rate alert + AI cost anomaly alert.", "logs": "Structured JSON with correlationId; retained per platform defaults.", "error_tracking": "Client-side error capture wired to console + in-app diagnostics drawer.", "uptime": "Synthetic checks on microsite + shell login every 5 minutes.", "cost_monitoring": "Per-blueprint cost view; alert on 3x baseline over 24h." }, "testing": { "unit": "Vitest for pure derivations (DNA, business helpers).", "integration": "Edge function contract tests with recorded fixtures.", "contract": "Zod schemas shared client + edge; smoke test runner as continuous contract check.", "e2e": "Playwright against localhost preview for critical flows (sign in, evidence toggle, sync apply).", "security": "Weekly dependency scan; RLS policy audit script; abuse-case checklist per release.", "a11y": "Axe checks + keyboard-only smoke on shell components; WCAG 2.2 AA target.", "load": "k6 scenarios against edge functions before enabling a new capability network-wide.", "chaos": "Manual fault injection on AI provider (simulate 500s) during release rehearsal.", "migration": "Every migration runs in preview + dry-run on prod snapshot before apply.", "backup_restore": "Semi-annual restore drill.", "ai_eval": "not applicable", "test_data": "Deterministic fixtures per vertical; no real PHI/PII ever in fixtures." }, "observability": { "logs": "Structured JSON with correlationId, phase, attempt, doc_key, slug.", "metrics": "Per-endpoint latency, error rate, retry count, AI token spend.", "traces": "Cross-function trace via correlationId propagation.", "audit_events": "Release decision, evidence toggle, sync, rollback, cache invalidation.", "business_events": "Blueprint promoted to ready, first microsite view, first customer-visible export.", "error_tracking": "In-app diagnostics drawer + persistent per-slug error history.", "security_monitoring": "Failed auth + rate-limit breach + admin action logs.", "cost_monitoring": "Per-blueprint + per-capability cost attribution.", "dashboards": [ "SLO burn", "AI cost per blueprint", "Sync success rate", "Generation success rate" ], "alert_thresholds": [ "IDLE_TIMEOUT rate > 3/day for one blueprint.", "Sync run failure > 1 in rolling 7 days.", "AI cost > 3x rolling 7-day baseline over 24h.", "p95 breach on Blueprint detail > 800ms for 15 min." ], "triage": "correlationId → diagnostics drawer → retry timeline → JSON report export → runbook link." }, "cost": { "drivers": [ { "name": "AI generation", "note": "Dominant driver; capped by concurrency + per-slug budget." }, { "name": "Edge function invocations", "note": "Bursty at sync + generation; idle-to-zero otherwise." }, { "name": "Managed Postgres", "note": "Small; scales with audit trail retention." }, { "name": "Object storage", "note": "Snapshots + artifacts; lifecycle rules prevent growth." }, { "name": "Bandwidth", "note": "Low; static microsite content." } ], "likely_traps": [ "Regeneration loops on failure (mitigated by circuit breaker).", "Audit trail unbounded growth (mitigated by retention policy).", "Storing large HTML snapshots per sync (mitigated by delta snapshots)." ], "controls": [ "Per-blueprint AI budget with hard cap.", "Smoke-test result caching in localStorage.", "Concurrency cap in blueprintJobQueue.", "Retention policy on audit + diagnostics." ] }, "multi_tenancy": { "model": "Row-level tenancy: one shared Postgres, tenant scope by auth.uid() + blueprint slug.", "isolation": "RLS policies on every public table; policies reference has_role() where role checks are needed.", "tenant_aware_authz": "Every query filters by auth.uid(); admin overrides go through explicit role check + audit entry.", "tenant_config": "Per-slug config stored as JSONB on the blueprint row; no per-tenant deploy.", "branding": "Per-blueprint Design DNA drives theme; no runtime branding upload at MVP.", "tenant_export": "Owner can export evidence + audit trail as JSON/CSV from the UI.", "tenant_deletion": "Owner-initiated purge cascades across blueprint rows + storage prefix; soft-delete window of 30 days.", "tenant_audit": "Per-slug audit trail table view with actor + timestamp on every mutation.", "noisy_neighbor": "Per-slug concurrency cap in blueprintJobQueue; per-slug AI budget.", "tenant_rate_limits": "Edge functions apply per-slug + per-user rate limits.", "billing": "Not billed at MVP; per-blueprint cost attribution feeds the future billing model.", "why_this_fits": "Team size and blueprint scale don't justify schema/db-per-tenant; RLS covers the isolation requirement with negligible ops burden." }, "privacy_compliance": { "data_classification": "Owner-supplied facts and evidence citations are the sensitive classes; service records, attestations, regulator correspondence per vertical.", "minimization": "Only owner-supplied facts persist; no third-party enrichment; no PII scraping.", "consent": "Consent captured at intake for owner-supplied contact info; microsite visitors get standard cookie/consent banner where required.", "access_logs": "Every admin + edge function invocation logged with correlationId + actor.", "audit_trails": "Immutable append-only audit_trail table; export from UI.", "retention": "Audit ≥ 1y; sync snapshots 90d; error diagnostics 30d; artifacts per lifecycle rule.", "legal_hold": "Deferred until a matter requires it.", "right_to_delete": "Owner-initiated purge honored within 30 days; downstream copies pruned by lifecycle rules.", "right_to_export": "JSON + CSV export for evidence, audit trail, and generated artifacts.", "sensitive_handling": "No PHI/PII in prompts; owner-supplied facts only; secrets in managed vault.", "boundaries": "Domain-specific (weather-matched evidence, Ops/QA and Senior Reviewer sign-offs, multi-year retention schedules)", "residency": "Single region at MVP; residency contract triggers per-tenant residency planning.", "vendor_risk": "Lovable Cloud + AI Gateway are the only critical vendors; both reviewed for security posture.", "breach_response": "correlationId + audit trail enables scope determination; disclosure per compliance policy within statutory window.", "admin_controls": "Admin actions gated by role check + two-key confirm for destructive operations; every admin session logged.", "evidence_collection": "Access reviews, change management, restore drills produce artifacts filed into the evidence pipeline." }, "frontend": { "framework": "React 18 + Vite + TypeScript.", "rendering": "SPA with per-route code-split; microsite routes prerender-friendly.", "routing": "react-router-dom v6 with URL-persisted filter/drawer state.", "state": "React context + useSyncExternalStore for the job queue; localStorage only for UI state, never for auth.", "server_state": "@tanstack/react-query for cache + retries.", "forms": "Controlled components + Zod validation on submit; RHF only where forms grow.", "error_handling": "Error boundary at shell + per-panel skeletons + retry affordances.", "components": "shadcn primitives + per-blueprint themed panels; deterministic Design DNA drives look.", "design_system": "Tailwind semantic tokens (index.css); no hardcoded color utilities in components.", "auth_ui": "Managed OAuth callback via Cloud client; session hydration before protected routes render.", "authz_aware_ui": "UI hides actions the current role cannot perform; server-side check is authoritative.", "a11y": "WCAG 2.2 AA target; visible focus rings; keyboard shortcuts in diagnostics drawer.", "i18n": "Copy budgets assume +35% expansion for DE/FR; Intl APIs for dates/currencies.", "performance": "Route-level code split; lazy-load Runtime tab; memoize DNA derivations.", "bundling": "Vite defaults; per-route lazy imports for heavy panels.", "testing": "Vitest for unit; Playwright for critical flows.", "offline": "Not required; last-known-good served from React Query cache.", "realtime": "Not required at MVP; audit trail is polled on interaction." }, "backend": { "framework": "Deno-based edge functions on Lovable Cloud, one function per capability.", "layering": "Handler → validator (Zod) → service → repository → Postgres.", "domain": "Blueprint, Evidence, OwnerAction, SyncRun, RuntimeCapability, ChatMessage, ContractedSite, DefenseFile, CompletenessRulebookVersion, LitigationHoldRequest.", "services": "Pure functions kept out of edge boundary; shared logic imported from a common module.", "repositories": "Thin Postgres wrappers; RLS enforces tenant scope.", "validation": "Zod at the edge boundary; reject unknown fields.", "authorization": "has_role() SECURITY DEFINER in Postgres; edge function also asserts role for defense in depth.", "jobs": "In-app blueprintJobQueue on the client for user-triggered pipelines; server-side cron only for daily sync.", "events": "Domain events emitted to audit_trail; no external broker.", "files": "Signed URLs from Cloud Storage; virus scan on upload (deferred until user uploads exist).", "email_sms": "Deferred; owner-configured inbox required before enabling outbound mail.", "scheduled": "Daily GitHub sync via scheduled function; retention prune weekly.", "errors": "Normalized error envelope { code, message, correlationId, retryable, details? }.", "logging": "Structured JSON logs with correlationId, phase, attempt, slug.", "config": "Env-based; secrets from managed vault.", "di": "Not required at current size; explicit imports.", "testing": "Contract tests per function with recorded fixtures + smoke-test runner." }, "diagrams": { "context_mermaid": "flowchart LR\n Owner([Blueprint Owner]) --> Shell[Network Shell]\n Reviewer([Reviewer]) --> Shell\n Public([Public Visitor]) --> Micro[Public Microsite snow-ice-storm-event-defense-desk]\n Shell --> Cloud[(Lovable Cloud: DB + Auth + Storage + Edge)]\n Cloud --> AI[[AI Gateway]]\n Cloud --> GH[[GitHub API]]\n Micro --> Cloud", "container_mermaid": "flowchart TB\n subgraph Client\n UI[React Shell + Blueprint Detail]\n Queue[blueprintJobQueue]\n end\n subgraph Cloud[Lovable Cloud]\n DB[(Postgres + RLS)]\n Store[(Object Storage)]\n subgraph Edge[Edge Functions]\n Sync[github-sync-blueprints]\n Roll[rollback-blueprint-sync]\n Src[fetch-blueprint-sources]\n Seed[generate-seed-articles]\n Docs[generate-blueprint-docs]\n Legal[generate-legal-docs/*]\n Verify[verify-blueprint]\n SEO[generate-seo-posts]\n Chat[blueprint-chat]\n end\n end\n UI --> DB\n Queue --> Src\n Queue --> Seed\n UI --> Docs\n UI --> Legal\n UI --> Verify\n UI --> SEO\n UI --> Chat\n UI --> Sync\n UI --> Roll\n Seed --> AI[[AI Gateway]]\n Docs --> AI\n Legal --> AI\n Chat --> AI\n Src --> GH[[GitHub]]", "data_flow_mermaid": "flowchart LR\n A[Owner edits Evidence] --> B[Store: evidence.custom]\n B --> C{Release Gate}\n C -- ready --> D[Business marked Ready]\n C -- blocker --> E[Owner Actions queue]\n F[GitHub Sync] --> G[Diff + Snapshot]\n G --> H[(Postgres)]\n H --> I[Audit trail]\n H --> J[React store]", "auth_flow_mermaid": "sequenceDiagram\n participant U as User\n participant UI as Network Shell\n participant Auth as Cloud Auth\n participant API as Edge Function\n participant DB as Postgres+RLS\n U->>UI: sign in\n UI->>Auth: OAuth (Google)\n Auth-->>UI: session (JWT)\n UI->>API: call with JWT\n API->>DB: query as auth.uid()\n DB-->>API: rows filtered by RLS\n API-->>UI: response", "authz_flow_mermaid": "flowchart LR\n Req[Request w/ JWT] --> Fn[Edge Function]\n Fn --> Role[has_role user_id, role]\n Role --> DB[(user_roles + RLS policies)]\n DB -- allow --> Ok[Return rows]\n DB -- deny --> Err[403 + audit entry]", "deployment_mermaid": "flowchart LR\n Dev[Developer] --> Repo[Git]\n Repo --> CI[Lovable Build]\n CI --> Preview[Preview Env]\n CI --> Prod[Production]\n Prod --> Cloud[(Lovable Cloud)]\n Prod --> CDN[[Edge CDN]]", "background_job_mermaid": "flowchart LR\n UI[Blueprint Detail] --> Enq[blueprintJobQueue.enqueue]\n Enq --> Slot{Concurrency slot?}\n Slot -- yes --> Run[Run job]\n Slot -- no --> Queued[queued]\n Run -->|success| Done[Persist result + emit event]\n Run -->|error| Back[Exponential backoff + jitter]\n Back -->|attempts left| Run\n Back -->|exhausted| Fail[Record diagnostic + expose retry button]", "event_flow_mermaid": "flowchart LR\n Sync[sync.blueprint.applied] --> Core[Blueprint Core]\n Integ[integrity.completed] --> UI\n CacheInv[cache.invalidated] --> Pipe[Content Pipeline]\n Pipe --> Sources[sources.fetched]\n Sources --> Articles[articles.generated]\n Articles --> Integ", "failure_flow_mermaid": "flowchart LR\n Call[Edge Function call] --> Timeout{Timeout / 5xx?}\n Timeout -- no --> Ok[Success]\n Timeout -- yes --> Retry[Backoff + retry]\n Retry --> Cap{Attempts cap?}\n Cap -- no --> Call\n Cap -- yes --> Breaker[Open circuit]\n Breaker --> Cache[Serve last-known-good]\n Breaker --> Owner[Surface diagnostic + owner action]", "multi_tenant_flow_mermaid": "flowchart LR\n Owner1([Owner A]) --> UI\n Owner2([Owner B]) --> UI\n UI --> API[Edge Function w/ JWT]\n API --> Policy{RLS: auth.uid + slug scope}\n Policy -- match --> Rows[Owner-scoped rows]\n Policy -- no match --> Deny[403]", "ai_flow_mermaid": "graph LR; SRC[Source documents as DATA]-->EX[Extract + normalize]-->SR[Order source searches]-->MTX[Build matrix]-->DR[Draft locked-field elements]-->GT[Deterministic completeness gates]-->SP[Specialist release]-->DL[Deliver]; GT-.exception.->SP; SP-.high-risk.->EXP[Expert review]" }, "adrs": [ { "id": "ADR-001", "decision": "Adopt modular monolith as the network-wide architecture style", "context": "Small team maintaining many blueprints with shared shell, evidence discipline, and per-vertical trust variation.", "options": [ "simple monolith", "modular monolith", "microservices", "serverless-only", "hybrid" ], "chosen": "modular monolith", "why": "Preserves a single audit boundary and deploy cadence while allowing edge functions for burst workloads.", "consequences": [ "Shared deploy lifecycle across blueprints", "Row-level tenant isolation carries the security load" ], "risks": [ "A rogue blueprint can regress network shell performance" ], "reversal": "Extract a module to its own deploy only when its SLO diverges from the network shell.", "revisit_when": "A blueprint acquires a divergent SLO, a second team joins, or the shell deploy time exceeds 10 minutes.", "business_reason": "Protects the trust/compliance boundary central to StormWitness's positioning.", "technical_reason": "Keeps the shared platform's modular monolith / RLS tenancy model unchanged for this business.", "tradeoffs": "Lower operational complexity at launch traded for slower feature velocity later.", "status": "Accepted", "revisit_trigger": "A blueprint acquires a divergent SLO, a second team joins, or the shell deploy time exceeds 10 minutes." }, { "id": "ADR-002", "decision": "Managed Postgres as the sole primary datastore", "context": "All entities are relational (blueprints, evidence, sync runs, articles, audit).", "options": [ "Postgres", "Postgres + DocumentDB", "Postgres + vector DB", "Firestore" ], "chosen": "Postgres (Cloud managed) with JSONB for semi-structured fields", "why": "Relational integrity + row-level security satisfies audit, tenancy, and reporting; JSONB absorbs shape drift.", "consequences": [ "RLS policies are the primary tenancy control", "Full-text search via Postgres FTS until it stops scaling" ], "risks": [ "Complex joins under growth" ], "reversal": "Introduce a read-replica or a dedicated search index only when p95 breaches SLO.", "revisit_when": "FTS p95 > SLO for 2 consecutive weeks, or a genuine RAG surface appears.", "business_reason": "Protects the trust/compliance boundary central to StormWitness's positioning.", "technical_reason": "Keeps the shared platform's modular monolith / RLS tenancy model unchanged for this business.", "tradeoffs": "Lower operational complexity at launch traded for slower feature velocity later.", "status": "Accepted", "revisit_trigger": "FTS p95 > SLO for 2 consecutive weeks, or a genuine RAG surface appears." }, { "id": "ADR-003", "decision": "Per-document edge functions for long-running AI generation", "context": "IDLE_TIMEOUT (150s) on monolithic legal-docs generator forced this split.", "options": [ "Single long function", "Chunked per-doc functions", "Background job with polling" ], "chosen": "Per-document endpoints with client-side fan-out + retries", "why": "Keeps each invocation under the timeout, isolates failures, enables partial success reporting.", "consequences": [ "More endpoints to maintain", "Client must own orchestration" ], "risks": [ "Client back-pressure if fan-out is too wide" ], "reversal": "Move to a real workflow engine when we cross ~10 concurrent long jobs per blueprint.", "revisit_when": "Concurrent long-running jobs > 10 per blueprint, or client-side orchestration becomes buggy.", "business_reason": "Protects the trust/compliance boundary central to StormWitness's positioning.", "technical_reason": "Keeps the shared platform's modular monolith / RLS tenancy model unchanged for this business.", "tradeoffs": "Lower operational complexity at launch traded for slower feature velocity later.", "status": "Accepted", "revisit_trigger": "Concurrent long-running jobs > 10 per blueprint, or client-side orchestration becomes buggy." }, { "id": "ADR-004", "decision": "Evidence-first release gate", "context": "Vertical compliance posture: Domain-specific (weather-matched evidence, Ops/QA and Senior Reviewer sign-offs, multi-year retention schedules).", "options": [ "Owner-declared ready", "Auto-ready via checklist", "Evidence-gated ready" ], "chosen": "Evidence-gated ready — release requires resolved owner actions + verified evidence", "why": "Regulated verticals cannot ship on self-declaration; evidence provides defensibility.", "consequences": [ "Slower path to ready", "Higher confidence at ready" ], "risks": [ "Owners abandon incomplete blueprints" ], "reversal": "Introduce a 'ready-with-caveats' state only if the network stalls on this gate.", "revisit_when": "> 30% of blueprints stuck in owner-action state for > 30 days.", "business_reason": "Protects the trust/compliance boundary central to StormWitness's positioning.", "technical_reason": "Keeps the shared platform's modular monolith / RLS tenancy model unchanged for this business.", "tradeoffs": "Lower operational complexity at launch traded for slower feature velocity later.", "status": "Accepted", "revisit_trigger": "> 30% of blueprints stuck in owner-action state for > 30 days." }, { "id": "ADR-005", "decision": "Defer AI adoption until a specific evidence-generation need arises", "context": "AI is powerful but adds cost, latency, and auditability burden.", "options": [ "No AI", "Grounded AI only", "Agentic AI" ], "chosen": "No AI in this vertical", "why": "Vertical does not currently justify AI-shaped complexity.", "consequences": [ "No prompt catalog to maintain" ], "risks": [], "reversal": "Introduce AI only for a scoped generation task.", "revisit_when": "A specific generation task appears with clear source grounding.", "business_reason": "Protects the trust/compliance boundary central to StormWitness's positioning.", "technical_reason": "Keeps the shared platform's modular monolith / RLS tenancy model unchanged for this business.", "tradeoffs": "Lower operational complexity at launch traded for slower feature velocity later.", "status": "Accepted", "revisit_trigger": "A specific generation task appears with clear source grounding." }, { "id": "ADR-006", "decision": "Managed OAuth (Google) with roles in a dedicated user_roles table", "context": "Storing roles on the profile row invites privilege-escalation bugs; RLS policies must reference a stable role source.", "options": [ "Roles on profiles", "user_roles + has_role() SECURITY DEFINER", "External IdP with JIT claims" ], "chosen": "user_roles table + has_role() SECURITY DEFINER, referenced by RLS", "why": "Prevents recursive RLS, isolates authz decisions, satisfies audit review.", "consequences": [ "One extra join in policies", "Explicit role grants required" ], "risks": [ "Role drift if grants are not audited" ], "reversal": "Swap SECURITY DEFINER function for an IdP claim without changing policies.", "revisit_when": "Enterprise SSO / SAML contract signed, or role count exceeds ~10.", "business_reason": "Protects the trust/compliance boundary central to StormWitness's positioning.", "technical_reason": "Keeps the shared platform's modular monolith / RLS tenancy model unchanged for this business.", "tradeoffs": "Lower operational complexity at launch traded for slower feature velocity later.", "status": "Accepted", "revisit_trigger": "Enterprise SSO / SAML contract signed, or role count exceeds ~10." }, { "id": "ADR-007", "decision": "Single-tenant per blueprint slug with row-level isolation", "context": "Blueprints share infra but must never cross-read evidence, sync history, or generated artifacts.", "options": [ "Shared DB + RLS", "Schema-per-tenant", "DB-per-tenant" ], "chosen": "Shared DB + RLS keyed on auth.uid() and blueprint slug", "why": "Simplest operable model at current scale; migration cost stays near zero.", "consequences": [ "RLS is load-bearing security" ], "risks": [ "A missing policy = a leak" ], "reversal": "Extract a specific tenant to its own schema when contract requires it.", "revisit_when": "First enterprise customer with a residency or dedicated-DB clause.", "business_reason": "Protects the trust/compliance boundary central to StormWitness's positioning.", "technical_reason": "Keeps the shared platform's modular monolith / RLS tenancy model unchanged for this business.", "tradeoffs": "Lower operational complexity at launch traded for slower feature velocity later.", "status": "Accepted", "revisit_trigger": "First enterprise customer with a residency or dedicated-DB clause." } ], "roadmap": [ { "phase": "MVP", "build": [ "Network shell + Blueprint Core module", "Content Pipeline with concurrency + backoff", "Design + Architecture DNA per blueprint", "Sync + rollback + audit trail" ], "avoid": [ "Any per-blueprint deploy pipeline", "Message brokers", "Vector DBs", "Multi-region" ], "defer": [ "A workflow engine", "Full-text search infra", "Dedicated CDN rules" ], "monitor": [ "Edge function IDLE_TIMEOUT rate", "AI cost per generation", "Duplicate-slug regressions" ], "triggers_to_change": [ "p95 breach on Blueprint detail > 800ms", "≥ 3 IDLE_TIMEOUTs/day sustained" ], "acceptable_debt": [ "Client-owned job orchestration", "localStorage-backed UI state" ], "dangerous_debt": [ "Missing RLS on any public table", "Ungrounded AI in customer-visible surfaces" ], "weeks": "MVP", "outcomes": [ "Network shell + Blueprint Core module", "Content Pipeline with concurrency + backoff" ], "exit_criteria": "Phase deliverables shipped without a P0 incident", "kill_criteria": "A dangerous-debt item ships to production" }, { "phase": "Stabilization", "build": [ "Automated smoke test per blueprint on cache invalidation", "Per-slug retention + audit trail export", "Contract tests for every edge function" ], "avoid": [ "Premature module extraction" ], "defer": [ "Multi-tenant admin console" ], "monitor": [ "SLO burn rate", "Cost per blueprint per week" ], "triggers_to_change": [ "A single blueprint accounts for > 30% of AI spend" ], "acceptable_debt": [ "Manual runbook execution for rare failures" ], "dangerous_debt": [ "Untested rollback path", "Backups without a restore drill" ], "weeks": "Stabilization", "outcomes": [ "Automated smoke test per blueprint on cache invalidation", "Per-slug retention + audit trail export" ], "exit_criteria": "Phase deliverables shipped without a P0 incident", "kill_criteria": "A dangerous-debt item ships to production" }, { "phase": "Growth", "build": [ "Optional workflow engine adapter behind the current queue interface", "Read replica for Postgres if analytics queries interfere", "Feature flags per capability module" ], "avoid": [ "Splitting Blueprint Core into services without SLO justification" ], "defer": [ "Real-time collaboration" ], "monitor": [ "Fan-out concurrency vs edge function limits" ], "triggers_to_change": [ "> 10 concurrent long jobs per blueprint", "New team joins with independent release cadence" ], "acceptable_debt": [ "Env-based feature flags" ], "dangerous_debt": [ "Skipping migration reviews", "Unaudited role grants" ], "weeks": "Growth", "outcomes": [ "Optional workflow engine adapter behind the current queue interface", "Read replica for Postgres if analytics queries interfere" ], "exit_criteria": "Phase deliverables shipped without a P0 incident", "kill_criteria": "A dangerous-debt item ships to production" }, { "phase": "Scale", "build": [ "Extract Content Pipeline to a dedicated service if it dominates deploys", "Search index (Postgres FTS → dedicated) once FTS p95 breaches SLO" ], "avoid": [ "Microservices per blueprint" ], "defer": [ "Multi-region until a customer contract requires it" ], "monitor": [ "DB CPU + IO under peak", "Search p95" ], "triggers_to_change": [ "Regional compliance contract signed" ], "acceptable_debt": [ "Single-region deployment" ], "dangerous_debt": [ "Unbounded audit trail growth", "Missing DR drill evidence" ], "weeks": "Scale", "outcomes": [ "Extract Content Pipeline to a dedicated service if it dominates deploys", "Search index (Postgres FTS → dedicated) once FTS p95 breaches SLO" ], "exit_criteria": "Phase deliverables shipped without a P0 incident", "kill_criteria": "A dangerous-debt item ships to production" }, { "phase": "Enterprise/Compliance", "build": [ "Formal SOC 2 evidence pipeline (access reviews, change management)", "Tenant-scoped encryption keys where regulation requires", "DR drill quarterly with restore proof" ], "avoid": [ "Custom compliance frameworks; ride managed platform attestations" ], "defer": [ "FedRAMP unless a customer commits" ], "monitor": [ "Access review completion", "Restore-test success rate" ], "triggers_to_change": [ "Signed contract with SOC 2 clause", "PHI/PII scope change" ], "acceptable_debt": [ "Manual quarterly access review with checklist" ], "dangerous_debt": [ "Ad-hoc admin access without approval trail" ], "weeks": "Enterprise/Compliance", "outcomes": [ "Formal SOC 2 evidence pipeline (access reviews, change management)", "Tenant-scoped encryption keys where regulation requires" ], "exit_criteria": "Phase deliverables shipped without a P0 incident", "kill_criteria": "A dangerous-debt item ships to production" } ], "anti_overengineering": { "flagged": [ { "item": "Introducing Kubernetes", "why": "Team size + workload shape don't justify it.", "simpler": "Managed Cloud primitives." }, { "item": "Adopting microservices", "why": "Single deploy cadence + shared audit boundary.", "simpler": "Modular monolith with edge functions." }, { "item": "Adopting a vector DB", "why": "Sources are small + structured; deterministic retrieval works.", "simpler": "Direct source fetch + Postgres FTS." }, { "item": "Adopting event sourcing", "why": "Audit trail table already provides the needed reconstructibility.", "simpler": "Append-only audit_trail + snapshots." }, { "item": "Multi-region from day one", "why": "No customer contract requires it.", "simpler": "Single region + documented DR plan." }, { "item": "Custom workflow engine", "why": "In-app queue covers current concurrency needs.", "simpler": "blueprintJobQueue with backoff." }, { "item": "Premature message queue", "why": "In-app queue + audit trail cover the fan-out cases.", "simpler": "Keep blueprintJobQueue; revisit at 10x volume." }, { "item": "Custom auth", "why": "Managed OAuth + user_roles cover the model.", "simpler": "Cloud Auth + user_roles table." }, { "item": "Premature caching layer", "why": "React Query covers the read-heavy paths.", "simpler": "React Query + HTTP cache headers." }, { "item": "Data warehouse", "why": "No analytics contract; Postgres analytics queries suffice.", "simpler": "Read replica if the primary is hurt." } ] }, "risks": [ { "risk": "Edge function IDLE_TIMEOUT on long generations", "likelihood": "moderate", "impact": "high", "mitigation": "Per-document endpoints + client-side retries with exponential backoff.", "detection": "Smoke test runner + diagnostics drawer flags IDLE_TIMEOUT.", "owner": "engineering", "escalation": "Sustained > 3/day for one blueprint → open incident.", "fallback": "Fall back to last-known-good cached artifact; pause auto-generation for the affected blueprint.", "category": "technical" }, { "risk": "Duplicate slugs in SEED causing UI regressions", "likelihood": "moderate", "impact": "moderate", "mitigation": "mergedSeed dedupes by slug; add lint on SEED at build time.", "detection": "React duplicate-key warning; per-slug uniqueness assertion in tests.", "owner": "engineering", "escalation": "Ship-block if reproduced on main.", "fallback": "Runtime dedupe in mergedSeed keeps first occurrence.", "category": "technical" }, { "risk": "Ungrounded AI output shipped to microsite", "likelihood": "low", "impact": "high", "mitigation": "Citation-first prompts; integrity check gates Seed Articles view.", "detection": "Integrity report failing count > 0 blocks display.", "owner": "engineering", "escalation": "Any customer-visible ungrounded claim → rollback the blueprint.", "fallback": "Auto-hide the article + surface owner action to regenerate with stricter prompt.", "category": "product" }, { "risk": "Cross-tenant data leak via missing RLS on new table", "likelihood": "low", "impact": "critical", "mitigation": "Every CREATE TABLE ships with GRANT + ENABLE RLS + policies in the same migration.", "detection": "Security scanner + migration checklist.", "owner": "engineering", "escalation": "Immediate lockdown + audit.", "fallback": "Revoke Data API grants on affected table; restore from PITR if data was modified.", "category": "security" }, { "risk": "AI cost runaway on a single blueprint", "likelihood": "moderate", "impact": "moderate", "mitigation": "Per-slug rate limits + smoke-test cache + concurrency cap in UI.", "detection": "Cost monitoring dashboard; per-blueprint spend alert at 3x baseline.", "owner": "SRE", "escalation": "Auto-pause generation; require manual re-enable.", "fallback": "Disable AI for the offending blueprint via feature flag; serve last-known-good.", "category": "cost" }, { "risk": "AI provider outage or model deprecation", "likelihood": "moderate", "impact": "moderate", "mitigation": "Per-capability fallback model + retry with backoff; abstract via Lovable AI Gateway.", "detection": "Elevated 5xx or empty completions; smoke test failing across blueprints.", "owner": "engineering", "escalation": "Sustained > 30 min → switch fallback model; notify owners.", "fallback": "Serve cached artifacts + disable AI-only capabilities until restored.", "category": "vendor" }, { "risk": "Compliance evidence gap during audit", "likelihood": "low", "impact": "high", "mitigation": "Evidence-first release gate + audit trail export from UI.", "detection": "Missing audit entries surfaced in periodic reconciliation report.", "owner": "legal", "escalation": "Regulator-visible gap → incident + disclosure per policy.", "fallback": "Freeze affected blueprint's release state; produce backfill evidence pack.", "category": "compliance" }, { "risk": "Solo/small-team key-person dependency", "likelihood": "moderate", "impact": "high", "mitigation": "Deterministic DNA modules keep decisions in code, not in one head; runbooks per capability.", "detection": "Bus-factor review each quarter.", "owner": "owner", "escalation": "> 1 critical path with no backup → hire or contract.", "fallback": "Freeze non-critical changes; document current state before further work.", "category": "team" }, { "risk": "Audit trail gaps on release decisions", "likelihood": "low", "impact": "critical", "mitigation": "Every mutation writes audit entry in the same transaction.", "detection": "Audit trail row count vs mutation count reconciliation.", "owner": "engineering", "escalation": "Regulator-visible gap → incident + disclosure.", "fallback": "Reconstruct from Postgres WAL + application logs; disclose per compliance policy.", "category": "compliance" } ], "rules": [ "Keep business logic out of UI components — derivations live in lib/*, panels only render.", "Do not introduce a new service without a clear owner and a scaling reason.", "All external integrations must have retries, timeouts, and failure handling.", "All sensitive actions must be auditable in the same transaction that performs them.", "All background jobs must be idempotent.", "All APIs must return the normalized error envelope.", "All tenant-scoped queries must enforce tenant isolation via RLS — never trust the client.", "All expensive AI calls must be logged, capped, and observable.", "All schema changes must be reversible or safely migratable — no destructive drops without a rollout plan.", "All critical workflows must have observability: correlationId, phase timings, retry timeline.", "Every public table ships with GRANT + ENABLE RLS + policies in the same migration.", "Every AI span carries a citation; no citation, no ship.", "Every destructive action requires typed confirmation." ], "audit": { "product_fit": "Architecture matches an evidence-first, regulated-adjacent workflow product per blueprint.", "simplicity": "One shell, one DB, edge functions for bursts — near the simplicity floor for the product's ambitions.", "security": "RLS + role table + audit trail; meets ASVS L1 baseline.", "reliability": "SLOs defined; per-module degradation; retries + diagnostics in place.", "scalability": "Horizontal by blueprint count is the growth axis; per-blueprint scaling is comfortably in headroom.", "maintainability": "Deterministic derivations (Design DNA, Architecture DNA) keep per-vertical drift out of components.", "performance": "p95 target 600ms is realistic on Cloud edge with warm cache.", "cost": "Idle-to-zero for cold blueprints; per-blueprint attribution keeps AI spend controllable.", "compliance": "Domain-specific (weather-matched evidence, Ops/QA and Senior Reviewer sign-offs, multi-year retention schedules)", "dx": "Single stack (React + Vite + Tailwind + Cloud); new blueprint reaches microsite state in one session.", "ops_burden": "Managed platform absorbs infra ops; SRE work is limited to SLO watch + runbooks.", "extensibility": "New capability = new edge function + new Runtime tab entry; no shell changes required.", "team_suitability": "Fits a small team; every added component must retire an older one.", "time_to_market": "New blueprint reachable to validation-microsite state within one working session.", "recommendation": { "style": "modular monolith", "stack": "React + Vite + TypeScript + Tailwind + shadcn on the client; Deno edge functions + managed Postgres (RLS) + object storage on the server; Lovable AI Gateway (unused in this vertical).", "hosting": "Lovable Cloud managed hosting; preview + production environments; edge functions co-deploy with the app.", "database": "Managed Postgres with RLS + JSONB; PITR enabled for critical-tier tenants.", "auth": "Managed OAuth (Google default) + user_roles table + has_role() SECURITY DEFINER referenced from RLS policies.", "integrations": "GitHub (public read) for sync + sources; Lovable AI Gateway for LLM calls; Cloud Storage for artifacts. No third-party CRM/email/SMS at MVP.", "ai_approach": "No AI at MVP for this vertical; revisit only when a scoped generation task with clear sources appears.", "build_first": [ "Blueprint Core (evidence + release gate) — vertical-agnostic.", "Content Pipeline (sources → articles → integrity) — required for any evidence claim.", "Sync + rollback — required to safely onboard the network." ], "avoid": [ "Any per-blueprint deploy pipeline.", "Autonomous AI agents that mutate data without owner confirmation.", "Bespoke workflow engines before the in-app queue is exhausted." ], "revisit_later": [ "Workflow engine adoption when > 10 concurrent long jobs per blueprint.", "Search index dedicated infra when Postgres FTS p95 breaches SLO.", "Multi-region on the first residency-bound contract." ], "biggest_risks": [ "Missing RLS on a new public table (critical).", "Ungrounded AI output reaching a customer-visible surface.", "AI cost runaway on a single blueprint.", "Solo/small-team key-person dependency." ], "first_10_steps": [ "Confirm managed OAuth + user_roles table + has_role() function are in place.", "Enable RLS + policies on every existing public table; add the migration checklist to CI.", "Wire correlationId end-to-end across every edge function call.", "Ship the smoke test runner as a required post-deploy gate.", "Enable PITR + schedule the first restore drill on the calendar.", "Add per-slug AI budget caps and cost dashboards.", "Enforce evidence-first release gate for every blueprint.", "Set SLO burn-rate alerts on the top 3 SLIs.", "Document the per-capability runbook (retry, cancel, invalidate).", "Publish this Architecture DNA per blueprint as part of the release evidence pack." ], "top_10_rules": [ "Every public table ships with GRANT + RLS + policies in the same migration.", "Every mutation writes an audit entry in the same transaction.", "Every AI span carries a citation; no citation, no ship.", "Every long AI call is per-item, never monolithic.", "Every edge function call carries a correlationId end-to-end.", "Every retry uses exponential backoff + jitter with a hard attempt cap.", "Every destructive action requires typed confirmation.", "No microservice extraction without a divergent SLO.", "No new dependency without a supply-chain scan.", "Signature element (Pack-register tabs with regime chip) and accent (clinical-teal) are network invariants — respect them." ], "verdict": "Right-sized for a 3-5-contractor pilot cohort" } } }, "ddd_coverage": { "slug": "snow-ice-storm-event-defense-desk", "total": 10, "passed": 10, "pct": 100, "checks": [ { "key": "subdomains", "label": "Subdomains identified", "count": 8, "min": 3, "ok": true, "gate": false, "unblock": "" }, { "key": "bounded_contexts", "label": "Bounded contexts modeled", "count": 8, "min": 3, "ok": true, "gate": false, "unblock": "" }, { "key": "aggregates", "label": "Aggregates defined", "count": 5, "min": 2, "ok": true, "gate": false, "unblock": "" }, { "key": "events", "label": "Domain events named", "count": 16, "min": 5, "ok": true, "gate": false, "unblock": "" }, { "key": "ai_agents", "label": "AI agents specified", "count": 3, "min": 1, "ok": true, "gate": false, "unblock": "" }, { "key": "risk_register", "label": "Risk register populated", "count": 5, "min": 3, "ok": true, "gate": false, "unblock": "" }, { "key": "adrs", "label": "Architecture decision records", "count": 3, "min": 1, "ok": true, "gate": false, "unblock": "" }, { "key": "use_cases", "label": "Use cases documented", "count": 2, "min": 1, "ok": true, "gate": false, "unblock": "" }, { "key": "policies", "label": "Policies documented", "count": 5, "min": 3, "ok": true, "gate": false, "unblock": "" }, { "key": "invariants", "label": "Invariants documented", "count": 5, "min": 3, "ok": true, "gate": false, "unblock": "" } ], "failingGates": [ "entity_gate" ] }, "design": { "slug": "snow-ice-storm-event-defense-desk", "archetypes": [ "regulated-adjacent documentation-production tool", "field-evidence assembly system", "small-portfolio operations back office" ], "user_mindset": { "goals": "Know that every contracted site has a complete, weather-correlated record the moment a claim shows up — without becoming a records-management expert.", "session_length": "Bursty around a storm event or a claim notice; otherwise a seasonal glance at the Season Completeness Scorecard ahead of GL renewal.", "confidence": "Practical, risk-averse trade-contractor operators; will not tolerate a portal that reads like a legal-services sales pitch.", "interface_needs": "Fast per-site status scanning, plain-language completeness states, a clear same-day gap flag when something is missing." }, "posture": [ "direct", "trustworthy", "unglamorous-on-purpose" ], "density": "comfortable", "trust_level": { "tier": "high", "sensitive_domains": [ "crew check-in photos", "site contract terms", "claim-related evidence" ], "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 Ops/QA Reviewer sign-off on every delivered file.", "Explicit unsaved-changes gate on the Storm Readiness Gap Scan intake form." ] }, "differentiation": { "avoid": [ "Material Design defaults", "shadcn stock look (unstyled cards + slate ring)", "Purple/indigo gradient heroes", "Stripe/Linear/Notion mimicry", "Vertical cliché: snowplow clip-art, siren imagery, or generic 'winter weather app' iconography" ], "strategy": "Anchor on the Defense File status chip (complete / gap-flagged / litigation-hold / delivered) as the recurring signature element, echoing the Intake -> Weather Match -> Completeness -> Review -> Deliver lifecycle from DESIGN-STANDARD §3; every page includes it at least once. Reserve the ice-cyan accent for action/CTA and status signals only, against a cold slate-night surface that reads as an operations desk, not a consumer weather app." }, "territories": [ { "name": "Documentation Desk", "color_mood": "cold slate + ice-cyan", "typography": "System sans throughout", "density": "comfortable card grid", "component_feel": "night-storm operations desk", "motion": "none (static, print-parity)", "fits": "Contractor daily/seasonal use", "risks": "could read as generic dark-mode SaaS without the ice-cyan accent and status-chip motif" }, { "name": "Storm Ledger", "color_mood": "map ink + storm-warning amber", "typography": "System sans + monospace-adjacent data labels", "density": "list/ledger", "component_feel": "per-storm, per-site ledger", "motion": "none", "fits": "single-storm file review", "risks": "list fatigue on large 50+ site portfolios" }, { "name": "Season Atlas", "color_mood": "night-sky navy + verified-teal", "typography": "System sans", "density": "map-driven", "component_feel": "multi-site seasonal completeness map", "motion": "none", "fits": "Season Completeness Scorecard presentation", "risks": "requires season-scale data not present at pilot launch" } ], "tokens": { "brand": "221 39% 29%", "brand-fg": "220 47% 96%", "surface": "217 36% 8%", "ink": "220 47% 96%", "muted": "217 20% 68%", "accent": "185 55% 66%" }, "type": { "display": "-apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif", "body": "-apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif", "fonts_url": "" }, "trust_level_note": "See trust_level above", "chosen_territory": "Documentation Desk", "chosen_rationale": "Matches the contractor's actual workflow — a night-operations documentation desk with per-site status, not a real-time weather dashboard, since files deliver on a 24-48 hour SLA per storm, not streamed live.", "localization": [ "[PLACEHOLDER] owner to complete" ], "patterns": [ { "name": "Defense File status chip", "description": "A complete / gap-flagged / litigation-hold / delivered chip rendered via the four --state-* domain-state tokens, used on every site row and in the stat strip." }, { "name": "Weather Match confidence inline", "description": "Every Weather Match reference is followed by an inline confidence-tier label (High/Medium/Low) rendered in a muted, consistent format." } ], "prioritized_components": [ { "name": "Defense File status chip", "why": "The single recurring signature element tying the landing page, delivered file, and dashboard together" }, { "name": "Pricing table with guarantee/out-clause beside it", "why": "Trust cue placement at the point of highest risk perception per DESIGN-STANDARD §8" } ], "signature": { "motif": "Defense File status chip + Weather Match confidence inline", "render": "Rounded rectangular chip, 4px left border in the matching --state-* token color, confidence tier in a muted small-caps label beside it" }, "states": [ "[PLACEHOLDER] owner to complete" ], "uniqueness_audit": { "app_specific_decisions": [ "Defense File status chip is unique to a per-site, per-storm evidence-completeness workflow, not reusable generic SaaS chrome", "Weather Match confidence-tier inline formatting is specific to the certified NOAA/NCDC correlation requirement" ], "cliches_avoided": [ "No snowplow clip-art", "No siren-red penalty banners", "No generic blue/purple SaaS gradient hero" ], "scale_notes": "Type scale sized for scanning a 15-150-site list quickly during a post-storm review session" } }, "canva": { "slug": "snow-ice-storm-event-defense-desk", "territory": "Documentation Desk", "family": { "id": "trade-compliance-documentation", "name": "Trade Contractor / Field-Service Documentation", "motion": "static" }, "tokens": { "brand": "221 39% 29%", "brand-fg": "220 47% 96%", "surface": "217 36% 8%", "ink": "220 47% 96%", "muted": "217 20% 68%", "accent": "185 55% 66%" }, "type": { "display": "-apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif", "body": "-apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif", "fonts_url": "" }, "scale": { "h1": "clamp(1.875rem, 4.4vw, 2.875rem)", "h2": "clamp(1.5rem, 3vw, 2rem)", "h3": "clamp(1.0625rem, 2vw, 1.25rem)", "body": "clamp(1rem, 1.1vw, 1.0625rem)", "small": "0.8125rem", "tracking_display": "-0.01em", "tracking_body": "-0.005em", "weight_display": 800, "weight_body": 450 }, "spacing": { "card_padding": "1.375rem", "card_radius": "0.75rem", "card_shadow": "0 0 0 1px hsl(217 36% 22% / 0.6)", "section_gap": "clamp(2.5rem, 6vw, 3.5rem)", "hero_gap": "clamp(1rem, 1.8vw, 1.75rem)" }, "layout": { "hero": "single-column-centered-left", "card": "flat-bordered", "cta": "solid-accent", "archetype": "document-of-record", "card_silhouette": "rounded-outline", "button_geometry": "rounded" }, "background": { "hero_gradient": "radial-gradient(900px 500px at 90% -10%, hsl(185 55% 66% / 0.08), transparent 60%), radial-gradient(700px 420px at 0% 0%, hsl(221 39% 29% / 0.14), transparent 55%)", "cta_gradient": "linear-gradient(135deg, hsl(221 39% 29%), hsl(185 55% 66%))", "section_wash": "linear-gradient(180deg, hsl(217 36% 8%) 0%, hsl(221 39% 29% / 0.08) 100%)" }, "motif": "Defense File status chip + Weather Match confidence inline" }, "capabilities": { "marketing": true, "portal": false, "ops": true, "chatbot": false, "payments": false }, "vertical_style": { "accent": "#5fd4e0", "signature": "Defense File status chip (complete/gap-flagged/litigation-hold/delivered) motif", "layout": "Document-of-record night-operations desk, bordered cards, stat strip up top, site-by-site status list", "anti": "No generic blue/purple SaaS gradient; no snowplow clip-art; no siren-red panic banners; no weather-app screenshot mockups" }, "seo": { "slug": "snow-ice-storm-event-defense-desk", "archetype": "documentation-production-desk", "archetype_impact": "Every page must cite the 'storm in progress' doctrine's evidentiary requirement precisely and disclose the documentation-only, not-legal-advice boundary; commercial pages and doctrine-explainer pages are kept structurally separate per DESIGN-STANDARD §2.", "authority_dna": { "site_archetype": "Vendor/service site with a doctrine-explainer content hub", "monetization_model": "Direct service purchase (per-site subscription, claim-triggered, seasonal)", "main_search_intents": [ "informational (doctrine explainers)", "commercial (dispatch-software/weather-vendor comparison)", "transactional (free Gap Scan)" ], "topical_authority_opportunity": "'Storm in progress'/ongoing-storm doctrine evidentiary requirements for commercial snow & ice contractors, expanding state-by-state as additional Completeness Rulebooks go live", "local_seo_opportunity": "Low at launch — contractors are found by SIMA/regional-association membership, not city-level search, though local snow-contractor association chapters are a relevant local-event channel", "global_national_opportunity": "National once multi-state Completeness Rulebooks exist; Chicago-land/Midwest beachhead at launch", "easiest_ranking_path": "The free-Gap-Scan landing page and the exact-doctrine pillar page, both currently thin in the SERP", "hardest_ranking_path": "Generic 'snow removal software' head terms dominated by established dispatch-platform vendors with years of domain authority", "trust_credibility_requirements": [ "Direct doctrine/source citations on every claim", "Compliance disclaimer on every page", "No fabricated proof/testimonials" ], "ymyl": true, "expert_review_needed": true, "site_structure": "Homepage (landing page) -> doctrine pillar guides -> comparison/objection pages -> blueprint dossier", "seo_moat": "The maintained, outside-counsel-reviewed Completeness Rulebook content is genuinely hard for a generic content farm to replicate credibly." }, "search_market": { "primary_markets": [ "Chicago-land/Midwest commercial snow & ice management contractors" ], "secondary_markets": [ "Additional snowbelt-state contractors (post second-beachhead-state expansion)" ], "low_competition_subtopics": [ "storm in progress doctrine evidence checklist", "storm event defense file pricing" ], "high_commercial_intent": [ "commercial snow contractor liability documentation service", "snow removal slip and fall defense file" ], "informational": [ "storm in progress doctrine evidence requirements", "snow contractor slip and fall documentation" ], "local_intent": [ "sima wisconsin chapter vendors" ], "transactional": [ "free storm readiness gap scan" ], "comparison": [ "commercial snow removal insurance documentation requirements" ], "problem_solution": [ "missing weather record snow contractor lawsuit" ], "near_me": [], "long_tail": [ "what weather records do i need for a snow removal slip and fall defense" ], "questions": [ "is a snow contractor liable for a slip and fall", "how long does a snow removal lawsuit take" ], "emerging": [ "ongoing storm doctrine wisconsin minnesota ohio" ], "seasonal": [ "winter storm liability documentation checklist" ], "underserved_serps": [ "free storm readiness gap scan" ], "weak_serps": [ "storm in progress doctrine evidence requirements" ], "forum_dominated_serps": [ "snow contractor slip and fall reddit" ], "winnable_authoritative_serps": [ "storm in progress doctrine evidence requirements" ], "avoid_initially": [ "generic snow removal software reviews" ], "easy_wins": [ "free storm readiness gap scan" ], "moderate": [ "commercial snow contractor liability documentation service" ], "long_term_plays": [ "national multi-state storm-event documentation compliance hub" ], "do_not_pursue": [ "generic 'snow removal software' head terms", "residential/homeowner snow-shoveling search terms (wrong audience entirely)" ] }, "keyword_clusters": [ { "primary": "storm in progress doctrine evidence requirements", "related": [ "ongoing storm doctrine", "certified weather records snow lawsuit", "noaa ncdc weather defense" ], "intent": "informational", "user_problem": "Contractor staff need to know exactly what evidence the doctrine requires and how to preserve it", "funnel": "top", "business_value": "high", "ranking_difficulty": "medium", "conversion_potential": "medium", "content_effort": "medium", "serp_weakness": "Dominated by law-firm blog posts, few contractor-specific practical guides", "local_relevance": "Multi-state at launch (NY doctrine origin, analogous CT/MA/NJ/RI/Midwest)", "global_relevance": "Low at launch (single-region MVP)", "suggested_page_type": "pillar page", "reason": "Directly matches StormWitness's core deliverable and doctrine citation", "priority_score": 92, "priority": "high", "bucket": "easy_wins" }, { "primary": "snow contractor slip and fall documentation", "related": [ "snow removal lawsuit evidence", "commercial snow contractor liability" ], "intent": "informational", "user_problem": "Contractors and risk managers want to understand their documentation exposure", "funnel": "top", "business_value": "high", "ranking_difficulty": "medium", "conversion_potential": "high", "content_effort": "medium", "serp_weakness": "Mostly law-firm and insurance-agency pages, few contractor-facing preventive pages", "local_relevance": "National", "global_relevance": "Low at launch", "suggested_page_type": "pillar page", "reason": "Captures the exact fear-trigger the offer solves", "priority_score": 88, "priority": "high", "bucket": "easy_wins" }, { "primary": "commercial snow removal insurance documentation requirements", "related": [ "snow contractor gl insurance documentation", "insurance renewal snow contractor" ], "intent": "commercial", "user_problem": "Contractors comparing documentation vendors ahead of GL renewal", "funnel": "middle", "business_value": "high", "ranking_difficulty": "medium", "conversion_potential": "high", "content_effort": "medium", "serp_weakness": "Insurance-agency pages rarely explain the done-for-you-vendor distinction from self-operated tools", "local_relevance": "National", "global_relevance": "Low at launch", "suggested_page_type": "comparison page", "reason": "Directly targets vendor-comparison intent against dispatch software and weather-data vendors", "priority_score": 83, "priority": "high", "bucket": "moderate" }, { "primary": "free storm readiness gap scan", "related": [ "free snow contractor documentation audit", "storm defense file scan" ], "intent": "transactional", "user_problem": "Contractor wants a fast, low-risk way to check exposure before committing", "funnel": "bottom", "business_value": "high", "ranking_difficulty": "low", "conversion_potential": "high", "content_effort": "low", "serp_weakness": "No competitor publishes this exact free-scan offer", "local_relevance": "Chicago-land/Midwest at launch", "global_relevance": "Low at launch", "suggested_page_type": "landing page", "reason": "This is the primary lead-magnet offer itself", "priority_score": 95, "priority": "high", "bucket": "easy_wins" }, { "primary": "ongoing storm doctrine wisconsin minnesota ohio", "related": [ "midwest ongoing storm case law", "snow liability doctrine midwest" ], "intent": "informational", "user_problem": "Midwest contractors researching whether the doctrine applies in their state", "funnel": "top", "business_value": "medium", "ranking_difficulty": "medium", "conversion_potential": "low", "content_effort": "medium", "serp_weakness": "Sparse contractor-specific coverage outside NY/Northeast", "local_relevance": "Midwest-specific", "global_relevance": "Emerging (post-beachhead validation)", "suggested_page_type": "pillar page (deferred)", "reason": "Positions for full-Midwest doctrine confidence once each state's Rulebook is counsel-reviewed", "priority_score": 58, "priority": "low", "bucket": "long_term_plays" } ], "topical_authority_map": { "core_topics": [ "'Storm in progress'/ongoing-storm doctrine evidence requirements", "Commercial snow contractor documentation practices", "Slip-and-fall liability for snow & ice contractors", "GL insurance documentation for snow contractors" ], "pillars": [ { "name": "'Storm in Progress' Doctrine Evidence Checklist", "audience": "Commercial snow & ice contractor owner/ops manager", "core_intent": "informational -> transactional", "conversion_goal": "Free Storm Readiness Gap Scan request", "evidence_needed": [ "[PLACEHOLDER] owner to complete" ], "internal_links": [ "/free-storm-readiness-gap-scan", "/snow-contractor-slip-and-fall-documentation" ], "local_variants": [ "Chicago-land/Midwest" ], "national_variants": [ "Northeast (NY/CT/MA/NJ/RI, deferred)" ], "schema": [ "FAQPage", "Article" ], "supporting_pages": [ "Certified weather-station matching explainer", "What a complete Defense File contains", "Multi-day storm documentation explainer" ] }, { "name": "Snow Contractor Slip-and-Fall Liability", "audience": "Contractor owner / operations or risk manager", "core_intent": "informational", "conversion_goal": "Free Storm Readiness Gap Scan request", "evidence_needed": "Litigation-timeline citation, GL insurance documentation-requirement citations", "internal_links": [ "/storm-in-progress-doctrine-evidence-requirements" ], "local_variants": [ "Chicago-land/Midwest" ], "national_variants": [ "Northeast (deferred)" ], "schema": [ "FAQPage", "Article" ], "supporting_pages": [ "What a GL insurer wants at renewal", "Season Completeness Scorecard walkthrough" ] } ], "supporting_page_types": [ "Doctrine explainer", "Diagnostic teardown (composite/redacted)", "Vendor comparison", "FAQ" ] }, "site_architecture": { "main_nav": [ "Home", "How it works", "Pricing", "Free Storm Readiness Gap Scan", "Blueprint dossier" ], "footer_nav": [ "Compliance disclaimers", "Blueprint dossier", "Contact" ], "hubs": [ { "name": "Doctrine Compliance Hub", "url": "/storm-compliance", "purpose": "Pillar guides on the 'storm in progress' doctrine and future multi-state Rulebooks" }, { "name": "Diagnostic Teardowns", "url": "/teardowns", "purpose": "Composite/redacted Defense File pass/gap examples" } ], "url_patterns": [ "/snow-ice-storm-event-defense-desk/", "/snow-ice-storm-event-defense-desk/blueprint/", "/storm-compliance/" ], "avoid_url_patterns": [ "Query-string-only pages", "Duplicate content across state variants without canonical tags" ], "homepage_strategy": "The landing page IS the primary commercial page; no separate marketing homepage layer at launch." }, "global_national": { "international_needed": false, "international_notes": "Not applicable — US doctrine-specific service.", "linkable_assets": [ "Free 'Storm in Progress' Doctrine Evidence Checklist PDF", "Composite diagnostic teardown examples" ], "national_clusters": [ "Chicago-land/Midwest (launch)", "Northeast NY/CT/MA/NJ/RI (deferred)" ], "original_research_ideas": [ "Aggregate anonymized completeness-gap patterns across the pilot cohort (once ethically publishable with client consent)" ] }, "local_seo": { "justified": false, "reason": "Buyers are found by SIMA/regional-association membership, not by city-level local search", "gbp_categories_primary": [], "gbp_categories_secondary": [], "location_page_rules": [], "citations": [], "review_strategy": "No fabricated reviews; honest placeholder proof slots until pilot results exist", "local_schema": [] }, "programmatic": { "recommended": false, "reason": "Doctrine-specific pillar content requires outside-counsel review per page; not suited to programmatic templating at this scale.", "rules": [ "No programmatic page ships without outside-counsel sign-off on doctrine-specific claims" ], "per_page_requirements": [ "Direct doctrine/source citation", "Compliance disclaimer" ], "quality_gates": [ "No thin/duplicate pages", "No auto-generated doctrine claims without citation" ] }, "page_templates": [ { "page_type": "Landing page", "purpose": "Primary commercial/conversion page", "target_intent": "transactional", "url_pattern": "/snow-ice-storm-event-defense-desk/", "title_pattern": "StormWitness — weather-correlated Storm Event Defense Files", "meta_description_pattern": "A weather-correlated Storm Event Defense File for every contracted site, every storm, within 24-48 hours. Free Storm Readiness Gap Scan.", "h1_pattern": "When a slip-and-fall claim shows up two years after the storm, your file needs to already exist.", "outline": [ "Hero", "Stat strip", "Pain/stakes", "Deliverables", "How it works", "Pricing", "Proof", "FAQ", "Compliance" ], "above_the_fold": [ "[PLACEHOLDER] owner to complete" ], "internal_links": [ "/storm-compliance/storm-in-progress-doctrine-evidence-requirements" ], "media": [ "[PLACEHOLDER] owner to complete" ], "schema": [ "Service", "FAQPage" ], "cta_strategy": "Single primary CTA: free Storm Readiness Gap Scan request", "faq_opportunities": [ "Is this legal advice?", "Do you compete with our dispatch software?" ], "trust_elements": [ "Guarantee/out-clause beside pricing", "Compliance disclaimer footer" ], "conversion_elements": [ "Free Gap Scan form", "Blueprint dossier link" ], "anti_thin_rules": [ "Every doctrine claim cited", "No filler paragraphs" ], "quality_requirements": [ "<=120KB", "WCAG 2.2 AA" ] }, { "page_type": "Doctrine pillar guide", "purpose": "Topical authority + trust-building", "target_intent": "informational", "url_pattern": "/storm-compliance/", "title_pattern": ", Explained for Snow & Ice Contractors", "meta_description_pattern": "A plain-language, source-cited explainer for commercial snow contractors on .", "h1_pattern": ", Explained", "outline": [ "What the doctrine requires", "Common failure modes", "How StormWitness checks it", "FAQ" ], "above_the_fold": "Direct doctrine citation + summary answer", "internal_links": [ "/snow-ice-storm-event-defense-desk/" ], "media": "Diagram of the evidence-to-weather-match correlation", "schema": [ "Article", "FAQPage" ], "cta_strategy": "Secondary CTA to free Storm Readiness Gap Scan", "faq_opportunities": [ "What counts as a certified weather record?", "What happens if one site is missing a photo?" ], "trust_elements": [ "Outside-counsel-reviewed disclosure", "Direct source link" ], "conversion_elements": [ "Free Gap Scan CTA in-content" ], "anti_thin_rules": [ "Minimum depth: every evidentiary element addressed" ], "quality_requirements": [ "Outside-counsel-reviewed before publication" ] } ], "on_page_rules": { "title_tag": "Primary keyword + brand, under 60 characters", "meta_description": "Outcome + timeframe + CTA, under 155 characters", "headings": "One H1 per page, doctrine citations never in headings without plain-language context", "intro": "Answer the core question in the first two sentences", "images": "Diagrams only; alt text describes the evidentiary element illustrated", "internal_links": "Every pillar links to the landing page CTA; every landing page links to at least one pillar", "external_citations": "Direct links to NYSBA/law-firm source text on every doctrine claim", "freshness": "Re-verify doctrine text and market figures on every detected legal or market-data update signal", "mobile": "Mobile-first; landing page tested at 375px width", "snippet_targeting": "FAQ schema on every FAQ block for featured-snippet eligibility", "tables_lists": "Checklist-style content uses real
    /
      , never plain-text pseudo-lists", "author_attribution": "Founder/Compliance Lead byline with outside-counsel-review disclosure on doctrine pages", "avoid": [ "Keyword stuffing doctrine citations", "Duplicate content across state variants without canonicalization" ], "cta_placement": "Primary CTA above the fold and repeated after pricing per DESIGN-STANDARD §8" }, "entity_seo": { "main_entities": [ "StormWitness", "'Storm in progress' doctrine", "Commercial snow & ice management" ], "related_entities": [ "Snow & Ice Management Association (SIMA)", "NOAA National Climatic Data Center" ], "people": [], "orgs": [ "Snow & Ice Management Association", "New York State Bar Association" ], "tools": [ "SiteCapture", "Aspire", "Service Autopilot", "ArborGold", "Certified Snowfall Totals" ], "regulations": [ "'Storm in progress'/ongoing-storm premises-liability doctrine (state case law, not a statute)" ], "problems": [ "Missing certified weather match on a service record", "No timestamped crew check-in for a site", "Undocumented material-application log" ], "solutions": [ "Storm Event Defense File", "Storm Readiness Gap Scan", "Litigation Hold" ], "processes": [ "Completeness & QA review", "Weather Match retrieval" ], "alternatives": [ "Self-operated field-documentation software", "Point weather-certification vendors" ], "synonyms": [ "Commercial snow contractor liability documentation", "Storm event evidence file service" ] }, "schema_strategy": [ { "type": "Service", "where": "Landing page", "required_fields": [ "name", "provider", "areaServed", "description" ], "caution": "No aggregateRating or review schema — no fabricated reviews per DESIGN-STANDARD §9" }, { "type": "FAQPage", "where": "Landing page FAQ + doctrine pillar pages", "required_fields": [ "mainEntity (Question/Answer pairs)" ], "caution": "Only real, sourced answers — no speculative legal claims" }, { "type": "Article", "where": "Doctrine pillar guides", "required_fields": [ "headline", "author", "datePublished", "dateModified" ], "caution": "Author/reviewer disclosure required for YMYL content" } ], "internal_linking": { "pillar_to_cluster": "Each doctrine pillar links to its supporting explainer subpages", "cluster_to_pillar": "Every supporting page links back to its parent pillar", "cluster_to_cluster": "Cross-link the doctrine pillar to the slip-and-fall-liability pillar where topically relevant", "faq_to_commercial": "Every FAQ answer that resolves an objection links to the pricing section", "service_to_location": "Not applicable — no location pages at launch", "breadcrumbs": "Home > Storm Compliance > ", "anchor_text_rules": [ "[PLACEHOLDER] owner to complete" ] }, "technical_seo": { "crawlability": "Single self-contained landing page + platform-served pillar pages; no JS-rendering-dependent content on the landing page", "indexability": "Landing page indexable; blueprint dossier route noindexed per platform convention", "sitemaps": "Platform-generated sitemap includes the landing page and any published pillar pages", "robots": "Standard allow-all except the blueprint dossier internal routes", "canonicals": "Self-canonical on the landing page; state-variant pillar pages canonicalize to the primary Illinois/Midwest version at launch", "duplicate_control": "No duplicate doctrine content across pages without canonicalization", "pagination": "Not applicable at launch page count", "faceted_nav": "Not applicable", "redirects": "N/A at launch", "mobile": "Mobile-first responsive layout, tested at 375px", "core_web_vitals": "LCP <=2.5s, INP <=200ms, CLS <=0.1 per DESIGN-STANDARD §7", "accessibility": "WCAG 2.2 AA per DESIGN-STANDARD §6", "analytics_setup": "data-event attributes per DESIGN-STANDARD §4; no third-party analytics scripts (keeps the zero-external-request budget)", "gsc_setup": "Owner action — verify property in Google Search Console post-launch", "js_seo": "Landing page is static HTML/CSS/minimal JS; no client-side-only rendering of core content", "rank_tracking": "Owner action — track the priority keyword list monthly", "rendering": "Server-delivered static HTML" }, "eeat": { "author_bios": "Founder bio disclosing the Ops/QA Reviewer role and Completeness Rulebook authorship", "expert_reviewers": "Outside counsel reviews all doctrine-explainer content before publication", "editorial_policy": "Every doctrine claim must cite the specific source (NYSBA, law-firm alert, or bar association); no paraphrase-only claims", "fact_checking": "Cross-checked against primary source text at publication and on any legal-update signal", "credentials": [ "Outside-counsel-reviewed Completeness Rulebook" ], "citations": "Direct links to primary sources (NYSBA, Lewis Brisbois, Marshall Dennehey, IBISWorld)", "first_hand_proof": [ "[PLACEHOLDER] pilot-cohort Defense File delivery-time results, pending first storm event" ], "update_cadence": "Re-verified on any detected legal-update signal, per compliance-checklist.md's Rulebook freeze policy", "monetization_disclosure": "Service pricing disclosed transparently on every relevant page", "ymyl_notes": "Treated as YMYL-adjacent (insurance/liability documentation) — every claim must be citable and disclaimed" }, "ai_search": { "principles": [ "Answer the exact evidentiary question directly and cite the source", "Never state an unverified figure as confirmed fact" ], "tactics": [ "FAQ schema with direct doctrine answers", "Clear documentation-only disclaimer near every compliance claim" ], "do_not": [ "Do not claim litigation-outcome guarantees in AI-crawlable content", "Do not present the unverified '1 million ER visits' NSC-attributed figure as confirmed — label it explicitly unverified or omit it" ] }, "conversion": { "primary_cta": "Request my free Storm Readiness Gap Scan", "secondary_cta": "View the full operating blueprint dossier", "lead_magnets": [ "Free Storm Readiness Gap Scan", "One-page 'Storm in Progress' Doctrine Evidence Checklist PDF" ], "trust_elements": [ "Guarantee/out-clause beside pricing", "100% human-review disclosure", "Compliance disclaimer" ], "tracking": "data-event attributes (ui.cta_primary, domain.pricing_viewed, ui.faq_open, ui.blueprint_view, domain.diagnostic_requested)", "per_page_paths": [ { "page_type": "Landing page", "path": "Hero CTA -> Gap Scan form -> confirmation" }, { "page_type": "Doctrine pillar", "path": "In-content CTA -> Gap Scan form" } ] }, "link_earning": { "digital_pr_ideas": [ "Anonymized aggregate completeness-gap-pattern research once the pilot cohort has enough volume to publish ethically" ], "original_research": [ "[PLACEHOLDER] owner to complete" ], "directories": [ "SIMA vendor/resource directory", "Regional Midwest snow-contractor association listings" ], "partnerships": [ "GL insurance broker/agency referral partners", "Dispatch-software partner ecosystems" ], "expert_contributions": [ "Guest posts on SIMA/regional-association blogs about documentation completeness" ], "avoid": [ "Paid link schemes", "Guest post farms unrelated to trade contracting or property/casualty insurance" ] }, "metrics": { "weekly": [ "Storm Readiness Gap Scan requests", "Gap Scan-to-pilot conversion" ], "monthly": [ "Organic sessions to doctrine pillar pages", "Keyword rank movement on priority list" ], "quarterly": [ "Topical authority pillar completion status" ], "annual": [ "Full content-hub coverage across the Midwest beachhead, then Northeast states as activated" ] }, "risks": [ { "risk": "Publishing a doctrine claim without outside-counsel review", "applies": true, "mitigation": "No doctrine-specific page ships without Compliance Lead + outside-counsel sign-off" }, { "risk": "Being perceived as offering legal advice via SEO content", "applies": true, "mitigation": "Documentation-only disclaimer on every doctrine page" } ], "roadmap_90d": [ { "phase": "Days 1-30", "goal": "Publish landing page + first doctrine pillar page", "keywords_targeted": [ "storm in progress doctrine evidence requirements", "free storm readiness gap scan" ], "pages": [ "[PLACEHOLDER] owner to complete" ], "difficulty": "medium", "business_value": "Primary lead generation", "conversion_goal": "15-25% Gap Scan-to-pilot", "internal_links": [ "[PLACEHOLDER] owner to complete" ], "required_assets": [ "Outside-counsel-reviewed doctrine citations" ], "why_first": "These are the highest-intent, lowest-competition pages available at launch" }, { "phase": "Days 31-90", "goal": "Publish diagnostic teardown examples + slip-and-fall-liability pillar", "keywords_targeted": [ "snow contractor slip and fall documentation" ], "pages": 3, "difficulty": "medium", "business_value": "Topical authority + trust", "conversion_goal": "Gap Scan requests from organic", "internal_links": "Cross-link to the doctrine pillar", "required_assets": [ "Composite/redacted teardown examples" ], "why_first": "Follows the launch-plan.md pilot-onboarding timeline" } ], "roadmap_12m": [ { "phase": "Months 4-6", "goal": "Second-beachhead-state doctrine content beta (contingent on full-pilot-season checkpoint)", "keywords_targeted": [ "ongoing storm doctrine wisconsin minnesota ohio" ], "pages": [ "[PLACEHOLDER] owner to complete" ], "difficulty": "medium", "business_value": "Second-state expansion support", "conversion_goal": "Second-state pilot signups", "internal_links": [ "[PLACEHOLDER] owner to complete" ], "required_assets": [ "Second-state outside-counsel-reviewed Rulebook" ], "why_first": "Follows the 90-day plan's second-beachhead-state evaluation milestone" }, { "phase": "Months 7-12", "goal": "Off-season landscaping-liability content evaluation (contingent on phase-2 add-on decision)", "keywords_targeted": [ "[PLACEHOLDER] — not yet scoped" ], "pages": 0, "difficulty": "[PLACEHOLDER]", "business_value": "[PLACEHOLDER]", "conversion_goal": "[PLACEHOLDER]", "internal_links": "[PLACEHOLDER]", "required_assets": [ "[PLACEHOLDER]" ], "why_first": "Deferred until the core season-1 business is proven" } ], "priority_pages": [ { "rank": 1, "page_title": "Free Storm Readiness Gap Scan", "slug": "snow-ice-storm-event-defense-desk", "page_type": "Landing page", "primary_keyword": "storm event defense file", "secondary_keywords": [ "snow contractor documentation service" ], "intent": "transactional", "funnel": "bottom", "business_value": "Primary lead-generation surface", "difficulty": "low", "conversion_potential": "high", "cta": "Free Storm Readiness Gap Scan", "schema": [ "Service", "FAQPage" ], "internal_links": [ "/storm-compliance/storm-in-progress-doctrine-evidence-requirements" ], "required_proof": [ "[PLACEHOLDER] owner to complete" ], "why_opportunity": "Primary conversion asset with no direct competitor publishing this exact offer", "production_priority": "P0", "scope": "Landing page, already built as site/index.html" }, { "rank": 2, "page_title": "'Storm in Progress' Doctrine Evidence Requirements", "slug": "storm-in-progress-doctrine-evidence-requirements", "page_type": "Doctrine pillar", "primary_keyword": "storm in progress doctrine evidence requirements", "secondary_keywords": [ "certified weather records snow lawsuit" ], "intent": "informational", "funnel": "top", "business_value": "high", "difficulty": "medium", "conversion_potential": "medium", "cta": "Free Storm Readiness Gap Scan (secondary)", "schema": [ "Article", "FAQPage" ], "internal_links": [ "/snow-ice-storm-event-defense-desk/" ], "required_proof": "Direct NYSBA/law-firm citations", "why_opportunity": "Thin, non-authoritative existing content for this exact query", "production_priority": "P1", "scope": "Outside-counsel-reviewed before publication" } ], "competitor_gaps": { "typical_competitor_types": [ "Field-documentation software", "Dispatch/operations platforms", "Point weather-certification vendors" ], "common_weaknesses": [ "No done-for-you full-file assembly product", "No flat, outcome-priced documentation subscription", "Self-operated tooling requiring the contractor's own staff to do the correlation work" ], "how_to_beat_them": [ "Publish the exact free-Gap-Scan offer no competitor has", "Cite the doctrine's evidentiary mechanics precisely where competitors gesture vaguely at 'compliance'" ] }, "first_20_pages": [ "Landing page (free Storm Readiness Gap Scan)", "'Storm in progress' doctrine evidence requirements pillar", "Snow contractor slip-and-fall liability pillar", "Certified weather-station matching explainer", "What a complete Storm Event Defense File contains", "Diagnostic teardown: composite site file gap vs. complete", "Diagnostic teardown: Season Completeness Scorecard walkthrough", "What changes during a multi-day storm", "What your GL insurer wants at renewal", "How StormWitness differs from SiteCapture, Aspire, and Certified Snowfall Totals" ], "first_10_tech_fixes": [ "Verify landing page <=120KB and zero external requests", "Add FAQPage schema", "Add Service schema", "Confirm single H1", "Confirm skip link and focus-visible styles" ], "first_10_authority_actions": [ "Publish the 'storm in progress' doctrine pillar with outside-counsel review", "List in the SIMA resource/vendor directory", "List in regional Midwest snow-contractor association directories", "Pitch 1 GL insurance broker co-branded loss-control partnership", "Publish 1 founder-bylined article in Total Landscape Care or Green Industry Pros" ], "final_recommendation": "Launch with the landing page and the 'storm in progress' doctrine pillar as the only two indexed pages; expand the doctrine-compliance hub only as pilot volume and outside-counsel review capacity allow, one jurisdiction at a time, matching the business's own Build-Before-Scale discipline.", "disclaimers": [ "This SEO plan is not legal advice; every doctrine-explainer page requires outside-counsel review before publication per compliance-checklist.md." ] }, "seo_pages": { "id": "seo-snow-ice-storm-event-defense-desk", "business_slug": "snow-ice-storm-event-defense-desk", "route": "/snow-ice-storm-event-defense-desk", "title": "StormWitness — weather-correlated Storm Event Defense Files for snow & ice contractors", "description": "StormWitness for commercial snow & ice contractors: a weather-correlated Storm Event Defense File within 24-48 hours of every storm. Flat per-site pricing, never hourly, never legal advice.", "canonical": "/snow-ice-storm-event-defense-desk", "og_title": "StormWitness — your defense file needs to exist before the claim does", "og_description": "Send crew check-ins and photos. Get a weather-correlated Storm Event Defense File within 24-48 hours, for every contracted site, every storm.", "noindex": false, "schema_status": "Service + FAQPage schema present", "schema_type": "Service", "sitemap_include": true }, "evidence": [ { "id": "snow-ice-storm-event-defense-desk-e1", "business_slug": "snow-ice-storm-event-defense-desk", "area": "Identity", "claim_or_finding": "Working brand name declared: StormWitness (changed from the blueprint's placeholder 'StormProof' due to a name-collision risk). Operating entity/EIN not yet declared by the owner.", "status": "pending", "evidence": "brand.md documents a web collision check (StormProof rejected due to the pre-launch SnowProof app; StormWitness clean); formal trademark clearance and operating-entity declaration are owner actions.", "verification_command": "Owner submits entity name/EIN and completes a formal trademark clearance search.", "fix_owner": "owner", "remediation": "Not yet resolved — flagged in ddd.extensions.gates as G1 entity_gate.", "severity": "info" }, { "id": "snow-ice-storm-event-defense-desk-e2", "business_slug": "snow-ice-storm-event-defense-desk", "area": "Regulatory", "claim_or_finding": "'Storm in progress' doctrine and its certified-NOAA/NCDC-weather-record evidentiary requirement, verified against NYSBA, Lewis Brisbois, and Marshall Dennehey source text as of 2026-07-13.", "status": "verified", "evidence": "Fresh web search against nysba.org, lewisbrisbois.com, and marshalldennehey.com confirmed the mechanics described in the source blueprint remain current.", "verification_command": "Re-check nysba.org and the cited law-firm alerts before each new-state Rulebook activation.", "fix_owner": "system", "remediation": "Resolved — no deviation from the blueprint required.", "severity": "info" }, { "id": "snow-ice-storm-event-defense-desk-e3", "business_slug": "snow-ice-storm-event-defense-desk", "area": "Market", "claim_or_finding": "US snowplowing services industry: $22.9B revenue, 112,000 businesses, 1.9% CAGR 2021-2026 (IBISWorld, 2026).", "status": "verified", "evidence": "Figure re-confirmed via fresh web search against ibisworld.com in this run; consistent with the source blueprint's figure.", "verification_command": "Re-check ibisworld.com's Snowplowing Services industry page annually.", "fix_owner": "system", "remediation": "Resolved — no deviation required.", "severity": "info" }, { "id": "snow-ice-storm-event-defense-desk-e4", "business_slug": "snow-ice-storm-event-defense-desk", "area": "Pricing", "claim_or_finding": "Typical commercial seasonal snow/ice contract $2,000-$10,000/site; per-push $30-$95/event (Trillium Facility Solutions, confirmed current as a 2026 pricing guide).", "status": "verified", "evidence": "Fresh WebFetch of trilliumfacility.com/commercial-snow-removal-cost/ in this run quoted the identical $2,000-$10,000 seasonal and $30-$95 per-event ranges as the source blueprint.", "verification_command": "Re-check trilliumfacility.com's pricing guide each season.", "fix_owner": "system", "remediation": "Resolved — no deviation required.", "severity": "info" }, { "id": "snow-ice-storm-event-defense-desk-e5", "business_slug": "snow-ice-storm-event-defense-desk", "area": "Competitive landscape", "claim_or_finding": "MATERIAL CORRECTION to the source blueprint: a live, priced competitor (Certified Snowfall Totals) already sells meteorologist-verified snowfall/weather certification data to snow contractors, and a pre-launch self-operated logging app (SnowProof) was found in the same category. The blueprint's claim that 'no existing vendor... correlates service records against certified weather data' is corrected across every artifact to a more precise differentiation claim: StormWitness is the only DONE-FOR-YOU service combining crew evidence + certified weather match + completeness QA + human sign-off into one finished file.", "status": "verified", "evidence": "Fresh WebFetch of certifiedsnowfalltotals.com (live, priced service: $205/season for 1 location up to $2,750+ custom) and snowproof.tokshernandez.cc (pre-launch iOS app, waitlist-stage) in this run.", "verification_command": "Recheck both vendors' public status quarterly; revisit differentiation copy if either ships a done-for-you assembly/QA layer.", "fix_owner": "system", "remediation": "Resolved this run — corrected positioning language propagated to business-plan.md, gtm-kit.md, brand.md, and site/index.html; logged in ddd.extensions.contradiction_scan as C1.", "severity": "warning" }, { "id": "snow-ice-storm-event-defense-desk-e6", "business_slug": "snow-ice-storm-event-defense-desk", "area": "Competitive landscape", "claim_or_finding": "SiteCapture field-documentation software pricing $110-$850/month, confirmed current.", "status": "verified", "evidence": "Fresh web search against sitecapture.com/pricing/ in this run.", "verification_command": "Re-check sitecapture.com/pricing/ periodically.", "fix_owner": "system", "remediation": "Resolved — no deviation required.", "severity": "info" }, { "id": "snow-ice-storm-event-defense-desk-e7", "business_slug": "snow-ice-storm-event-defense-desk", "area": "Market", "claim_or_finding": "SIMA (Snow & Ice Management Association) publishes a SIMA-10-2025 Standard Practice for Procuring and Planning Snow and Ice Management Services (published June 2025) — a fresher, more specific citation than the source blueprint had.", "status": "verified", "evidence": "Fresh web search surfaced resources.sima.org's SIMA-10-2025 procurement standard PDF, dated June 2025.", "verification_command": "Re-check sima.org/standards for new or updated standards annually.", "fix_owner": "system", "remediation": "Added as a fresh finding; incorporated into site/index.html's pain/stakes section.", "severity": "info" }, { "id": "snow-ice-storm-event-defense-desk-e8", "business_slug": "snow-ice-storm-event-defense-desk", "area": "Unverified claim", "claim_or_finding": "The widely-repeated 'over 1 million ER visits annually' ice/snow-fall statistic (commonly NSC-attributed) could not be traced to a primary NSC publication.", "status": "flagged", "evidence": "Consistent with the source blueprint's own Claim Table labeling; not used as core evidence anywhere in this build.", "verification_command": "If ever needed, locate and cite a primary National Safety Council publication before using this figure.", "fix_owner": "system", "remediation": "Excluded from all customer-facing copy per the blueprint's own risk-register mitigation (item 14).", "severity": "info" } ], "generated_at": "2026-07-13T18:39:00Z", "checksum": "sha256:generated-locally" }