{ "version": "1.8.0", "slug": "specialty-trade-cor-tm-completeness-desk", "title": "CORReady Clear — First-Pass COR Completeness Pack for one change order", "vertical": "Construction / specialty-trade subcontracting — COR / T&M change-order completeness", "seed": { "s": "specialty-trade-cor-tm-completeness-desk", "t": "CORReady Clear — First-Pass COR Completeness Pack for one change order", "v": "Construction / specialty-trade subcontracting — COR / T&M change-order completeness", "r": "Medium-high", "m": "M" }, "product": { "slug": "specialty-trade-cor-tm-completeness-desk", "project_name": "CORReady Clear", "project_type": "outcome-priced, per-section COR/T&M completeness desk", "vertical": "Construction / specialty-trade subcontracting — COR / T&M change-order completeness", "audience": "US commercial specialty-trade subcontractors (electrical, mechanical/HVAC, plumbing, fire protection), 5-100 employees, submitting CORs and T&M tickets through GC portals without a dedicated change-order administrator", "geography": "United States commercial construction; beachhead in TX, FL, and the Southeast/Sun Belt, no single-state licensing required for documentation work", "scale_expectation": "8-firm / 20-pack pilot cap in the first 60-90 days; 40+ packs/month by year 1 as per-trade SOPs and templates harden", "core_workflows": [ "Intake and qualification of one COR / T&M set + T&M tickets + certificates", "OCR, page classification, and requirement extraction from the COR / T&M set", "Attribute crosswalk into a page-cited evidence matrix + chase list", "Deterministic rules gate, specialist QA, contractor attestation, and pack delivery" ], "discovery": { "one_line_purpose": "Turn a specialty-trade sub's field tickets, photos, emails, and rate sheets into a first-pass, GC-ready COR Completeness Pack, priced per COR.", "primary_users": [ "Owner/principal of a 5-100 employee commercial specialty-trade sub", "Project executive or project engineer handling CORs without a dedicated administrator", "Controller feeling the cash pressure of unpriced extras and write-downs" ], "jobs_to_be_done": [ "When the GC rejects my COR for missing docs, help me rebuild a complete evidence pack in days, not another 2-3 revision rounds.", "When field tickets pile up on paper, turn tags, photos, and emails into a priced-COR-ready pack before the 8-14 day window slips.", "When I run multiple projects, keep COR packages consistent without hiring a full-time change-order engineer for intermittent volume." ], "value_prop": "A done-for-you, per-COR completeness pack that removes the missing-documentation reason CORs bounce — AI-assembled, deterministically gated, and specialist-QA'd — for less than one write-down cycle.", "competitors": [ "Clearstory (COR/T&M SaaS the customer operates)", "Procore Change Events / Autodesk Construction Cloud (workflow tracking)", "Rhumbix (field T&M capture)", "An in-house project engineer or change-order engineer ($65-100k+)" ], "differentiation": "Outcome-priced per COR, AI-compressed assembly, and a change-order specialist QA signature without a full-time hire — owning the deadline and the accountability that SaaS seats and generic AI do not.", "positioning_statement": "For commercial specialty-trade subs who lose weeks and cash when CORs bounce for missing documentation, CORReady Clear is a done-for-you completeness desk that manufactures a first-pass, GC-ready COR Completeness Pack — unlike COR software, which still leaves the assembly on your project engineer." }, "assumptions": [ { "id": "specialty-trade-cor-tm-completeness-desk-a1", "statement": "Subcontractor principals will pay for a done-for-you Completeness outcome over continuing to book T&M ticket totals unverified, once shown a concrete Gap Scan finding.", "confidence": "medium", "impact_if_wrong": "severe", "revisit_trigger": "First 10 pilot Gap Scan sales conversations — reject the wedge if willingness-to-pay signal is absent." }, { "id": "specialty-trade-cor-tm-completeness-desk-a2", "statement": "A pack cycle can hit the 5-business-day (10 at pilot) delivery SLA from Subcontractor-supplied Spec section and T&M tickets alone, without Subcontractor-side software integration.", "confidence": "medium", "impact_if_wrong": "high", "revisit_trigger": "First 3-6 pilot Gap Scans." }, { "id": "specialty-trade-cor-tm-completeness-desk-a3", "statement": "Subcontractors tolerate AI-assisted T&M ticket parsing and Gap drafting when an trade-specialist QA reviewer's approval and signature are explicit on every COR Pack.", "confidence": "medium", "impact_if_wrong": "high", "revisit_trigger": "First GC-comment dispute resolved off a CORReady Clear Pack." }, { "id": "specialty-trade-cor-tm-completeness-desk-a4", "statement": "Scan-to-desk conversion reaches at least 25-40% among qualified, warm-led Subcontractors.", "confidence": "low", "impact_if_wrong": "severe", "revisit_trigger": "Day-90 pilot-cohort conversion measurement (explicit kill/pivot gate at 25%)." }, { "id": "specialty-trade-cor-tm-completeness-desk-a5", "statement": "Logical, row-level tenant isolation (not single-tenant infrastructure per client) is acceptable to the pilot cohort.", "confidence": "medium", "impact_if_wrong": "high", "revisit_trigger": "Any prospect (e.g. a multi-Subcontractor network) with a hard single-tenant compliance clause." } ], "unknowns": [ { "id": "specialty-trade-cor-tm-completeness-desk-u1", "question": "Which specific trade-specialist QA reviewer signs off on the first cohort's COR Packs?", "blocks": "Any commercial engagement; the reviewer signature invariant.", "resolution_path": "Named reviewer + engagement letter on file before the first paid scan." }, { "id": "specialty-trade-cor-tm-completeness-desk-u2", "question": "What is the true scan-to-desk conversion rate among warm, qualified leads?", "blocks": "Pricing hypothesis; scaling decision.", "resolution_path": "10-Subcontractor pilot cohort with explicit pricing conversation, measured against the Day-90 checkpoint (25% kill gate, 40% target)." }, { "id": "specialty-trade-cor-tm-completeness-desk-u3", "question": "How much does per-section parser coverage actually reduce review minutes by day 90?", "blocks": "Unit-economics model; throughput assumptions.", "resolution_path": "Instrument reviewer minutes per cycle from pilot 1; compare to the 3.8h-launch to 1.9h-day-90 target." } ], "expert_panel": [ { "role": "Product Strategy", "key_concern": "Is the Gap Scan narrow enough to sell in weeks without a custom integration?", "recommendation": "Launch scoped to a 3-month T&M ticket lookback against a single Spec section; expand scope only after the pilot converts.", "dissent": "May understate the recurring-revenue story to early prospects expecting an always-on dashboard." }, { "role": "Software Architecture", "key_concern": "Are we defaulting to a client-facing portal the pilot doesn't need yet?", "recommendation": "Single deployable modular monolith; upload-link/email intake only at launch, no client portal.", "dissent": "May read as under-built to a referral partner expecting a branded dashboard." }, { "role": "Frontend / UX", "key_concern": "Is the evidence chain (T&M ticket line to spec policy to reviewer approval) visible in every reviewer-facing view?", "recommendation": "Every Gap ComplianceMatrix line renders its T&M ticket citation, matched requirement, and reviewer decision in one glance.", "dissent": "Adds density a non-Construction reviewer might call cluttered." }, { "role": "Backend / Data", "key_concern": "Is the audit trail append-only and reconstructable for a GC comment dispute or diligence request years later?", "recommendation": "Event-sourced audit log for every pack-cycle state transition; hash-chained artifact snapshots.", "dissent": "More write-path complexity than plain CRUD; requires schema discipline as manufacturer formats evolve." }, { "role": "AI / ML", "key_concern": "Are Gap classifications grounded in the spec requirement and never a free-form guess?", "recommendation": "Retrieval-first classification citing the specific COR-schedule line; deterministic money math in code, never the model; mandatory reviewer gate before any client- or vendor-facing claim.", "dissent": "Slower per-cycle than a fully automated tool; may frustrate a prospect expecting instant results." }, { "role": "Security", "key_concern": "Is one subcontractor's financial and policy data isolated from every other subcontractor's?", "recommendation": "Row-level auth, per-tenant retrieval indices, log-scrubbing of financial figures.", "dissent": "None recorded this run." } ], "strategy": { "business_model": "Flat per-COR-section pack fee ($149-$249; beachhead $249) plus a Resubmittal Sprint, a per-project Continuity Desk retainer, and a rush add-on; the free Gap Scan is the wedge.", "revenue_streams": [ "Gap Scan (free wedge / primary CTA)", "First-Pass COR Completeness Pack ($149-$249 per COR / T&M set; beachhead $249)", "Resubmittal Sprint ($99-$149 when GC comments are completeness-driven)", "Continuity Desk ($149-$299 per active project per month) + rush add-on (+$75-$125)" ], "moat": [ "Per-section requirement/attribute library and per-GC/per-GC packaging-quirk knowledge, compounding with every pack", "Trade-specialist QA signature that converts a skeptical GC reviewer's default", "A defensible documentation-only boundary that keeps AEs comfortable and us out of design-practice risk", "Gold-standard pack library per trade/section that speeds each new pack" ], "gtm": [ "Founder-led educational content + anonymized Gap Scan teardowns", "State AGC/ABC association webinars and Subcontractor-network member-benefit pilots", "Trade user-community how-to content + CPA/bookkeeper referral partnerships" ], "pricing_hypothesis": "Scan free; First-Pass Pack $249 beachhead (Div 22/23/26), $229-$249 for complex equipment sections; blended ~$190 by year 1 at 50%+ gross margin as specialist minutes/pack fall.", "kill_criteria": [ "No signed pilot Subcontractor in 4 weeks of qualified outreach", "Reviewer median cycle time exceeds 115 minutes/client after pilot 5", "No paid standard-price conversion by Day 90", "A released COR Pack or vendor chase email causes a documented, CORReady Clear-caused reputational or client-relationship incident" ] }, "security": { "stride": [ { "threat": "Spoofing", "scenario": "Attacker impersonates an trade-specialist QA reviewer to approve a fabricated Gap or sign a COR Pack.", "mitigation": "SSO with MFA; reviewer signatures bound to a cryptographic session claim, not a form field." }, { "threat": "Tampering", "scenario": "Historical T&M ticket or Pack entries edited after the fact to hide a bad match.", "mitigation": "Append-only audit log; hash-chained artifact snapshots; diff view on every reviewer surface." }, { "threat": "Repudiation", "scenario": "Reviewer denies approving a Gap or signing a Pack that later proves wrong.", "mitigation": "Signed attestations with server-side timestamp + reviewer identity; export bundle includes signature manifest." }, { "threat": "Information Disclosure", "scenario": "Cross-tenant leak of one subcontractor's COR/policy data through shared indices, logs, or prompts.", "mitigation": "Tenant-scoped row-level auth; PII/financial-data scrubbing in logs; retrieval indices partitioned per Subcontractor." }, { "threat": "Denial of Service", "scenario": "A runaway extraction job or bulk export exhausts shared workers during a month-end delivery crunch.", "mitigation": "Per-tenant concurrency + budget caps; circuit breaker on model calls; degrade-gracefully queue." }, { "threat": "Elevation of Privilege", "scenario": "A standard operator acquires reviewer-approval or vendor-chase-send capability via a workflow shortcut.", "mitigation": "Roles stored in a separate table; capability checks server-side; no client-only role checks." } ], "privacy_posture": "Data-minimization by default; per-Subcontractor isolation; data-processing terms on file; deletion-schedule runbook published.", "compliance_targets": [ "Confidential project-data handling program", "SOC 2 Type I (year 2 roadmap)", "Engineering-practice boundary + collection-Subcontractor-statute review per state before scaling", "Manufacturer-portal terms-of-service log for any automated T&M ticket pull" ], "data_classifications": [ "Subcontractor spec basis-of-design set (sensitive business data)", "Manufacturer COR T&M tickets (sensitive, third-party-sourced)", "Trade scope splits / furnish decision data (sensitive, HR-adjacent)", "Contact/PII (standard)" ] }, "devops": { "ci_cd": "PR -> typecheck + unit + snapshot tests -> preview deploy -> main auto-deploys to a single production region; migrations gated on review.", "environments": [ "local", "preview (per-PR)", "staging (shared)", "production (single region + multi-AZ)" ], "observability": [ "Structured logs with tenant + request IDs", "RED metrics per workflow", "Error tracking with source maps", "Model-call spans with cost + latency", "Weekly SLO review, with a month-end delivery-crunch capacity review" ], "testing_pyramid": [ "Unit tests on matching-derivation and source-page check validation modules", "Component tests on reviewer exception-queue surfaces", "Contract tests on manufacturer-T&M ticket-schema parsers", "End-to-end smoke test on the intake -> match -> reviewer-signoff -> delivery path" ], "accessibility_tests": [ "axe-core in CI on reviewer-facing surfaces", "Keyboard-only walkthrough per workflow", "Prefers-reduced-motion honored" ], "performance_budget": "p95 workflow latency published per module; T&M ticket-extraction cold-path under 30s or shown as a background job." }, "accessibility_i18n_ethics": { "wcag_target": "AA", "locales": [ "en-US" ], "rtl_support": false, "ethical_risks": [ "A Gap or recovered-dollar claim released without reviewer approval", "Vendor-chase language read as a demand or collection threat rather than an chase email", "An error in a GC comment record attributed to AI rather than owned by the reviewer" ], "ethical_guardrails": [ "Human trade-specialist QA reviewer approval required before any Gap or vendor chase email ships", "Deterministic output filter blocks demand/collection-style language in every drafted vendor chase email", "AI-usage disclosure available in the engagement letter where relevant" ] }, "governance": { "ownership": [ { "area": "Product + roadmap", "owner": "Executive Sponsor" }, { "area": "Architecture + platform", "owner": "Engineering Lead" }, { "area": "Completeness + reviewer workflow", "owner": "Named trade-specialist QA reviewer" }, { "area": "Compliance + privacy", "owner": "Compliance Lead" }, { "area": "Design system", "owner": "Design Lead" }, { "area": "SEO + content", "owner": "Content Lead" } ], "docs_required": [ "ADR log (checked in)", "Owner-action Pack", "Evidence register", "STRIDE threat model", "Runbook: incident, restore, breach notification", "Reviewer playbook + signature policy" ], "naming_conventions": [ "kebab-case slugs for blueprints and routes", "camelCase for TypeScript identifiers", "SCREAMING_SNAKE_CASE for environment variables", "Verb-first action names (e.g., generate-Completeness-pack)" ], "change_control": "ADR-per-major-decision; migrations require review; production deploys gated on green CI + owner-action Pack check." }, "risk_register": [ { "id": "specialty-trade-cor-tm-completeness-desk-r1", "risk": "A vendor-facing claim proves incorrect", "likelihood": "medium", "impact": "severe", "mitigation": "Every Gap claim linked to a cited COR-schedule version + reviewer signoff", "contingency": "Cover narrative workflow; Subcontractor-notification template; audit-log export within 24 hours", "owner": "legal" }, { "id": "specialty-trade-cor-tm-completeness-desk-r2", "risk": "AI hallucination in a delivered Gap line or vendor chase email", "likelihood": "medium", "impact": "high", "mitigation": "Retrieval-first pipeline + structured output validation + reviewer gate", "contingency": "Reviewer-triggered rollback + regeneration; incident postmortem published to the Subcontractor", "owner": "engineering" }, { "id": "specialty-trade-cor-tm-completeness-desk-r3", "risk": "Cross-tenant Subcontractor financial data leak", "likelihood": "low", "impact": "severe", "mitigation": "Row-level auth + per-tenant retrieval indices + log-scrubbing", "contingency": "Breach-notification runbook; forced credential rotation; scoped tenant kill switch", "owner": "engineering" }, { "id": "specialty-trade-cor-tm-completeness-desk-r4", "risk": "Pilot Subcontractor churns before converting to a paid desk", "likelihood": "medium", "impact": "high", "mitigation": "Weekly working-session cadence during pilot; documented value moments; owner-action Pack", "contingency": "Structured exit interview; write learnings into ICP + pricing hypothesis", "owner": "owner" }, { "id": "specialty-trade-cor-tm-completeness-desk-r5", "risk": "a GC-portal vendor ships free, good-enough Completeness with a chase workflow", "likelihood": "medium-high", "impact": "high", "mitigation": "Portal-agnostic positioning; resubmittal/chase as the human moat software won't replicate", "contingency": "Reposition as \"we operate whatever spec tool exists\"; lean harder into the Diligence Source-page check line", "owner": "owner" } ], "roadmap": [ { "phase": "Phase 0 — Discovery + pilot LOI", "weeks": "Weeks 1-2", "outcomes": [ "3-5 pilot Subcontractor LOIs", "Evidence pack from each pilot Subcontractor", "Written ICP + pricing hypothesis" ], "exit_criteria": [ "≥3 LOIs signed", "Owner-action Pack populated per Subcontractor", "Reviewer identity confirmed" ], "kill_criteria": [ "<2 LOIs after 2 weeks", "No willingness-to-pay signal above pilot price" ] }, { "phase": "Phase 1 — Thin vertical slice", "weeks": "Weeks 3-4", "outcomes": [ "Intake -> match -> reviewer signoff -> delivery working end-to-end for one spec format", "Audit trail wired", "Instrumentation live" ], "exit_criteria": [ "1 real Gap Scan delivered + reviewer-signed", "p95 workflow latency published" ], "kill_criteria": [ "Reviewer signoff cycle >10 business days", "Evidence bundle cannot be reconstructed on demand" ] }, { "phase": "Phase 2 — Pilot cohort", "weeks": "Weeks 3-8", "outcomes": [ "10 pilot Subcontractors scanned", "First standard-price desk conversion", "SOC 2 Type I scoping" ], "exit_criteria": [ "≥1 standard-price contract", "Post-scan debrief trust signal captured", "Postmortem cadence in place" ], "kill_criteria": [ "No standard-price conversion by Day 90", "Scan-to-desk conversion below 25%" ] }, { "phase": "Phase 3 — Recurring-desk scale-up", "weeks": "Weeks 9-13 (Day 90 checkpoint)", "outcomes": [ "Public commercial launch of the microsite as 'ready'", "Rush rider and Diligence Source-page check line active", "Owner-action Pack closed for launch" ], "exit_criteria": [ "COGS/rework/cycle-time measured against target", "Expansion beyond the pilot cohort gated on targets, not calendar time" ], "kill_criteria": [ "Rework rate persistently above 3%", "Reviewer minutes per client not falling with volume" ] } ], "metrics": { "north_star": "Signed Monthly Completeness Packs delivered per week, per client, with zero client-caught material errors", "leading": [ "Pilot Subcontractor LOIs signed", "Scan-request-to-delivered-scan cycle time", "Reviewer signoff cycle time", "Evidence coverage per Gap ComplianceMatrix line", "Owner-action Pack closure rate" ], "lagging": [ "Paid standard-price desk contracts signed", "Scan-to-desk conversion (target ≥40%, pilot gate 25%)", "Client-caught material error rate (target <0.5%)", "Logo retention (target ≥85% annualized)" ], "guardrails": [ "Model spend per tenant per week", "PII/financial data in logs (target: 0)", "Cross-tenant access attempts (target: 0)", "p95 workflow latency ceiling" ] }, "executive_review": { "consensus": "Ship a thin, evidence-linked, reviewer-gated vertical slice for CORReady Clear, wedged on the Gap Scan. Prefer a boring, single-region modular monolith. Do not launch commercially until owner-action facts close and at least one reviewer-signed COR Pack has shipped.", "dissent": "Executive Sponsor and Privacy/Compliance disagree on launch tempo — Privacy recommends waiting for the full state-by-state collection-Subcontractor-statute review before enabling the rush rider anywhere.", "go_no_go": "conditional-go", "top_3_risks": [ "A vendor-facing claim proves incorrect", "AI hallucination in a delivered Gap line or vendor chase email", "Cross-tenant Subcontractor financial data leak" ], "first_10_steps": [ "Confirm the named trade-specialist QA reviewer + engagement letter on file", "Populate owner-action Pack with entity, jurisdiction, contact inbox, privacy inbox", "Open pilot-cohort intake (cap 10) with explicit pricing conversation", "Write ICP + kill/pivot criteria in the plan file", "Stand up the evidence-linked intake -> match -> reviewer signoff loop", "Wire append-only audit log + hash-chained snapshots", "Add row-level auth + tenant-scoped retrieval indices", "Instrument scan-request, pack-delivery, and reviewer-signoff events", "Publish the microsite with FAQPage schema only and noindex until owner-facts close", "Schedule the Day-90 kill/pivot review with executive sponsor" ] } }, "project_site": { "slug": "specialty-trade-cor-tm-completeness-desk", "app_name": "CORReady Clear completeness desk", "archetype": "COR/T&M completeness desk", "archetype_label": "COR/T&M completeness desk", "reader_role": "Specialty-trade subcontractor principal or project engineer", "one_sentence_app": "CORReady Clear is a COR / T&M completeness desk for specialty-trade subcontractors who need a GC-ready pack for one change order, delivered before the COR due date.", "homepage_sequence": [ "scene", "workflow", "instrument", "offer", "proof", "qualification", "objections" ], "hero": { "frame_label": "Commercial specialty-trade subcontracting · COR / T&M completeness desk", "eyebrow": "Specialty-trade subcontractor / CORs bounce for missing documentation", "interface_title": "CORReady Clear completeness desk", "primary_panel_title": "Pack #CRC-000142 · COR-118 added circuits · pack cycle open", "primary_panel_body": "Open pack: extract the COR's required evidence, link each T&M ticket line to a supporting exhibit, and chase any missing signature, photo, or authorization email before the due date.", "side_panel_title": "Before this ships", "side_panel_items": [ "Every ticket line matched to a supporting exhibit or on the gap chase list", "Every T&M ticket signed; every photo linked to a ticket line or work day", "Authorization trail present; cost backups attached; contractor attestation captured" ], "status_metric": "QA", "status_label": "specialist QA gate active" }, "language": { "problem_heading": "The subcontractor's moment", "mechanism_heading": "Inside the CORReady Clear completeness desk", "proof_heading": "Why this survives a GC review and a resubmittal deadline deadline", "offer_heading": "What leaves the room", "objection_heading": "The hard questions", "qualification_heading": "Who should not use this", "cta_close": "Start a free Gap Scan — reviewed and signed by a trade-aware specialist before delivery." }, "modules": [ { "name": "Section intake", "job": "Turns one COR / T&M set, the T&M tickets, and held certificates into a named pack with an intake checklist and qualification (trade, due date, private commercial).", "artifact": "pack intake record" }, { "name": "Crosswalk & completeness", "job": "Extracts required items, OCRs and links the T&M tickets, and drafts a page-cited evidence matrix and chase list — every row tied to a source page.", "artifact": "evidence matrix + chase list" }, { "name": "Specialist QA & delivery", "job": "Runs the deterministic rules gate, gets a trade-specialist QA signature and the contractor's attestation, then delivers the pack with a rejection-risk score.", "artifact": "delivered First-Pass COR Completeness Pack" } ], "checkpoints": [ { "label": "required-item match", "pass": "matched with a cited source page", "fail": "routed to the specialist exception queue" }, { "label": "required signatureificate", "pass": "attached or on the chase list with a draft vendor email", "fail": "hard-fail: missing required signature blocks delivery" }, { "label": "cover narrative fields", "pass": "all fields complete with the spec-section reference", "fail": "hard-fail: blank cover narrative field blocks delivery" } ], "signature_scene": "You run a 20-person electrical sub. It's the week after a COR-118 conductor package came back returned for missing docs — an unmarked exhibit page and a missing ticket signature, not the product. resubmittal deadline on the added scope is three weeks out. You send CORReady Clear the COR / T&M set and the T&M tickets, and a GC-ready pack comes back, specialist-QA signed, before your due date." }, "ddd": { "slug": "specialty-trade-cor-tm-completeness-desk", "project_name": "CORReady Clear", "business_understanding": { "summary": "CORReady Clear is a done-for-you desk that manufactures a first-pass, GC-ready COR Completeness Pack for one Change Order Request or T&M ticket set, so specialty-trade subs stop losing weeks and cash to missing-documentation rejections.", "customer_profile": "US commercial specialty-trade subcontractors (electrical, mechanical/HVAC, plumbing, fire protection), 5-100 employees, submitting CORs and T&M through GC portals without a dedicated change-order administrator.", "customer_pain": "57% of delayed or rejected CORs cite missing documentation; the COR runs 2-3 revision rounds and the priced change slips from 8-14 days into 15-30 days while the cash on the extra work sits unpaid.", "paid_outcome": "A first-pass, GC-ready COR Completeness Pack for one COR / T&M set — evidence matrix, exhibit index, gap chase list, completeness-risk score, draft narrative — delivered before the due date, priced per COR.", "value_creation": "Removes the missing-documentation reason CORs bounce by combining AI extraction and crosswalk with deterministic completeness rules and a change-order specialist QA signature, for less than one write-down cycle.", "why_ai_native": "Frontier models compress multi-hour evidence assembly across 97% paper T&M into minutes of OCR and crosswalk, improving as handwriting OCR and multi-document reasoning improve; humans remain at entitlement attestation and edge-case GC packaging.", "operational_risks": [ "Entitlement disputes masquerading as completeness work.", "Handwriting-OCR failure on illegible paper tickets.", "Rate or quantity hallucination if attestation gates are weak.", "Scope creep into legal claims or contingency recovery.", "GC preference subjectivity beyond documentation completeness." ], "assumptions": [ "Beachhead subs will pay $249 per COR to avoid a revision round and weeks of slipped cash.", "First-pass completeness acceptance can reach >=70% by pack 20 with hardened SOPs.", "Specialist minutes per pack can fall from ~58 to ~25-30 by day 90.", "Free Gap Scan converts to paid packs at 15-25%.", "The desk stays out of UPL and PE scope with attestation and hard boundaries." ], "validation_questions": [ "What is the true first-pass completeness acceptance rate across the first 20 packs?", "What is the scan-to-paid conversion after 100 qualified scans?", "Can human minutes stay under ~40 without quality collapse on paper tickets?", "Which ticket formats are AI-tractable versus escalation-bound?", "Does pack-to-Continuity conversion reach 25-35%?" ] }, "domain_discovery": { "actors": [ { "actor": "Subcontractor principal", "role": "Owns the subcontractor's COR-Completeness engagement; supplies records and authorizes vendor-chase sends", "goals": [ "Recover missing/rejected CORs", "Avoid losing staff hours to T&M ticket matching", "Have a defensible Pack for subcontractors, CPA, and acquirers" ], "decisions": [ "Whether to engage CORReady Clear", "Which records to supply", "Whether to authorize vendor chase emails and the rush rider" ], "pain_points": [ "No time for line-item T&M ticket verification", "Doesn't know which of 40+ manufacturer formats are shortchanging the Subcontractor" ] }, { "actor": "Trade-specialist QA reviewer", "role": "Reviews AI-matched T&M tickets and drafted gaps; signs off before delivery or manufacturer send", "goals": [ "Release only evidence-backed, source-page-complete Packs", "Protect Subcontractor and manufacturer relationships" ], "decisions": [ "Approve, escalate, or reject a Gap", "Sign or withhold the COR Pack" ], "pain_points": [ "Volume spikes during month-end delivery windows", "Ambiguous fuzzy matches requiring judgment" ] }, { "actor": "Subcontractor", "role": "Receives furnish decision T&M tickets computed from verified data; may dispute a furnish decision", "goals": [ "Get paid correctly and on time" ], "decisions": [ "Whether to escalate a furnish decision dispute" ], "pain_points": [ "No T&M ticket-backed answer when a furnish decision looks wrong" ] }, { "actor": "Manufacturer COR Department (external)", "role": "Receives chase emails about missing/rejected CORs", "goals": [ "Resolve chase emails without escalation" ], "decisions": [ "Confirm, correct, or dispute an chase email" ], "pain_points": [ "High chase email volume across many Subcontractors and formats" ] } ], "glossary": [ { "term": "Gap Scan", "definition": "The one-time, $495 Completeness of the last 3 months of T&M tickets against the Spec set.", "used_by": "Subcontractor principal", "context": "Completeness & Matching", "example": "Scan for Subcontractor #AG-2291 across 34 COR / T&M sets", "notes": "Never called 'audit', 'check', or 'review'." }, { "term": "Completeness cycle", "definition": "One calendar month's worth of T&M ticket collection, matching, and pack delivery for one client.", "used_by": "Trade-specialist QA reviewer", "context": "Completeness & Matching", "example": "The July pack cycle for Subcontractor #AG-2291", "notes": "The unit of recurring work." }, { "term": "COR Pack", "definition": "The signed source-page check artifact: every T&M ticket line matched to a policy, balanced to the penny.", "used_by": "Trade-specialist QA reviewer, Subcontractor principal", "context": "Completeness & Matching", "example": "July COR Pack, 34 manufacturers, traces to $128,410 in stated CORs", "notes": "Never called 'report' or 'T&M ticket'." }, { "term": "Gap ComplianceMatrix", "definition": "The list of missing, rejected, late, or resubmittal lines with dollar value and evidence.", "used_by": "Trade-specialist QA reviewer, Subcontractor principal", "context": "Completeness & Matching", "example": "3 rejected lines, 1 missing renewal, est. $2,140", "notes": "Never called 'exceptions report'." } ], "decisions": [ { "decision": "Is this T&M ticket line a real Gap or a normal spec quirk (e.g. as-earned lag)?", "who": "AI drafts, Reviewer confirms", "inputs": [ "[PLACEHOLDER] owner to complete" ], "rule": "Classification thresholds per transaction type; spec-quirk map consulted before flagging", "output": "Gap classification with evidence citation", "risk": "False Gap sent to a manufacturer" }, { "decision": "Is the COR Pack ready to sign?", "who": "Deterministic code gates, Reviewer signs", "inputs": "All T&M ticket lines matched or exception-coded, Pack source-page check to T&M ticket totals", "rule": "Source-page-complete rule: Pack must tie to T&M ticket totals before release", "output": "Signed COR Pack", "risk": "Signed pack with an unresolved source-page check gap" } ], "events": [ { "event": "CORReadyExtracted", "meaning": "A T&M ticket is extracted and source-checked, ready for matching", "trigger": "Extraction Agent completes parsing + source-page check check", "downstream": [ "[PLACEHOLDER] owner to complete" ] }, { "event": "MatrixDrafted", "meaning": "A flagged Gap is reviewer-confirmed and evidenced", "trigger": "Trade-specialist QA reviewer approves the classification", "downstream": "Vendor chase email drafted; Chase list line finalized" } ] }, "subdomains": [ { "name": "Completeness & Matching", "type": "core", "description": "CORReady normalization, Spec-requirement matching, expected-COR computation, and Gap classification.", "reason": "This is the paid outcome — the completed Pack and Chase list are what the Subcontractor is buying.", "business_value": "Direct revenue driver; every tier maps to a delivered Monthly Completeness Pack.", "recommendation": "Build in-house, deterministic-rules-first.", "ai_involvement": "Extraction, matching, Gap classification, drafting", "human_involvement": "Reviewer approval, Pack signature", "risks": [ "Missed cycle-delivery SLA", "Incomplete evidence causing a client-caught error" ], "validation_questions": [ "What is the real reviewer review time per cycle at volume?" ] }, { "name": "Delivery", "type": "core", "description": "Vendor-chase drafting/sending, aging/tracking, Monthly Completeness Pack assembly, Resubmittal Pack.", "reason": "Differentiates CORReady Clear from a generic bookkeeping service — this is the chase-and-collect layer.", "business_value": "Drives conversion (free scan -> paid desk) and the rush rider.", "recommendation": "Build in-house; maintain a per-section contact/quirk map from day one.", "ai_involvement": "Drafts chase emails and Resubmittal reports", "human_involvement": "Reviewer approves every outbound chase email; escalation judgment", "risks": [ "Stalled recoveries with no tracked follow-up" ], "validation_questions": [ "How often do manufacturers respond within the 60-day aging window?" ] }, { "name": "Evidence & Compliance", "type": "supporting", "description": "Audit trail, engagement-letter authorization, licensing-boundary enforcement.", "reason": "Necessary complement to Completeness but not itself the differentiated value proposition.", "business_value": "Protects the licensing boundary and supports diligence/source-page check sales.", "recommendation": "Build thin; keep tightly scoped to documentation, never advice.", "ai_involvement": "Assembles audit exports", "human_involvement": "Compliance lead maintains state-by-state tracker", "risks": [ "Scope creep into unlicensed Subcontractor or collection activity" ], "validation_questions": [ "Which states need counsel review before the rush rider is offered?" ] }, { "name": "Referral & Outreach", "type": "generic", "description": "CRM, outbound sequencing, and content publishing.", "reason": "Not differentiating; off-the-shelf tools suffice at this stage.", "business_value": "Supports pipeline but not the core value proposition.", "recommendation": "Buy (lightweight CRM), do not build.", "ai_involvement": "Content drafting assistance", "human_involvement": "Founder-led outreach and content", "risks": [ "Low differentiation risk if under-invested" ], "validation_questions": [ "Which channel actually converts at the assumed rate?" ] } ], "core_domain_analysis": { "primary_core": "Completeness & Matching", "secondary_cores": [ "Delivery" ], "supporting_may_become_core": [ "Evidence & Compliance" ], "generic_do_not_distract": [ "Referral & Outreach", "CRM/pipeline tracking" ], "rationale": "The paid outcome is a signed COR Pack, so Completeness & Matching is the primary core. Delivery is a secondary core because manufacturer chase and tracked Resubmittal is the human-plus-AI moat that differentiates CORReady Clear from software the Subcontractor has to operate itself. Evidence & Compliance could become core if the Diligence Source-page check line grows into a larger revenue stream, but starts as supporting. Referral & Outreach uses off-the-shelf tooling deliberately to keep engineering focus on the COR/T&M completeness engine." }, "bounded_contexts": [ { "name": "Intake context", "purpose": "Receive and normalize customer submissions into classified documents.", "subdomain": "Intake", "type": "supporting", "owned_language": [ "submission", "document", "page-class" ], "owns": [ "submission record", "document normalization", "page classification" ], "does_not_own": [ "evidence rules", "delivery packaging" ], "primary_actors": [ "Customer", "Intake bot" ], "entities": [ "Submission", "Document", "Page" ], "aggregates": [ "Submission" ], "domain_services": [ "Intake service" ], "application_services": [ "submission record", "document normalization", "page classification" ], "commands": [ "NormalizeDocuments", "SubmitCORSet" ], "domain_events": [ "DocumentsNormalized", "SubmissionReceived" ], "policies": [ "Start SLA on complete intake" ], "specifications": [ "IntakeCompletenessSpec" ], "invariants": [ "A pack cannot advance while an open hard fail exists in this context" ], "ai_agents": [ "Intake classifier" ], "human_roles": [ "Customer", "Intake bot" ], "data_owned": [ "Submission", "Document", "Page" ], "inputs": [ "Upstream context output" ], "outputs": [ "Downstream context input" ], "external_integrations": [ "Drive/Dropbox intake", "GC portals (customer-submitted, not auto-pushed)" ], "risks": [ "Illegible handwriting mis-extracted", "Ambiguous exhibit link accepted silently" ], "interfaces": [ "-> next context via domain event" ], "value_objects": [] }, { "name": "Evidence context", "purpose": "Extract required evidence and crosswalk each ticket line to supporting exhibits.", "subdomain": "Evidence", "type": "core", "owned_language": [ "evidence item", "matrix line", "exhibit", "gap" ], "owns": [ "Evidence Matrix", "Exhibit Index", "gap detection" ], "does_not_own": [ "hard-fail thresholds", "attestation" ], "primary_actors": [ "AI workbench", "Specialist" ], "entities": [ "EvidenceMatrix", "MatrixLine", "Exhibit" ], "aggregates": [ "EvidenceMatrix" ], "domain_services": [ "Evidence service" ], "application_services": [ "Evidence Matrix", "Exhibit Index", "gap detection" ], "commands": [ "CrosswalkExhibits", "ExtractEvidence" ], "domain_events": [ "EvidenceExtracted", "MatrixCrosswalked" ], "policies": [ "Never invent a rate", "Code every rejection" ], "specifications": [ "EvidenceCompletenessSpec" ], "invariants": [ "A pack cannot advance while an open hard fail exists in this context" ], "ai_agents": [ "Extraction & crosswalk agent" ], "human_roles": [ "AI workbench", "Specialist" ], "data_owned": [ "EvidenceMatrix", "MatrixLine", "Exhibit" ], "inputs": [ "Upstream context output" ], "outputs": [ "Downstream context input" ], "external_integrations": [ "Drive/Dropbox intake", "GC portals (customer-submitted, not auto-pushed)" ], "risks": [ "Illegible handwriting mis-extracted", "Ambiguous exhibit link accepted silently" ], "interfaces": [ "-> next context via domain event" ], "value_objects": [] }, { "name": "Completeness context", "purpose": "Apply deterministic completeness rules and score submission readiness.", "subdomain": "Completeness", "type": "core", "owned_language": [ "hard fail", "soft flag", "completeness-risk score" ], "owns": [ "rules engine", "completeness-risk score" ], "does_not_own": [ "entitlement judgment", "GC review" ], "primary_actors": [ "Rules engine", "Specialist" ], "entities": [ "RuleResult", "CompletenessScore" ], "aggregates": [ "RuleResult" ], "domain_services": [ "Completeness service" ], "application_services": [ "rules engine", "completeness-risk score" ], "commands": [ "RunCompletenessRules" ], "domain_events": [ "CompletenessScored" ], "policies": [ "Block on hard fail" ], "specifications": [ "CompletenessCompletenessSpec" ], "invariants": [ "A pack cannot advance while an open hard fail exists in this context" ], "ai_agents": [ "Extraction & crosswalk agent" ], "human_roles": [ "Rules engine", "Specialist" ], "data_owned": [ "RuleResult", "CompletenessScore" ], "inputs": [ "Upstream context output" ], "outputs": [ "Downstream context input" ], "external_integrations": [ "Drive/Dropbox intake", "GC portals (customer-submitted, not auto-pushed)" ], "risks": [ "Illegible handwriting mis-extracted", "Ambiguous exhibit link accepted silently" ], "interfaces": [ "-> next context via domain event" ], "value_objects": [] }, { "name": "Review & Fulfillment context", "purpose": "Specialist QA, customer attestation, packaging, and delivery.", "subdomain": "Review", "type": "core", "owned_language": [ "QA checklist", "attestation", "COR Completeness Pack", "upload checklist" ], "owns": [ "QA sign-off", "AttestationRecord", "delivered pack" ], "does_not_own": [ "GC submission", "entitlement decisions" ], "primary_actors": [ "Specialist", "Customer" ], "entities": [ "CORPackage", "AttestationRecord" ], "aggregates": [ "CORPackage" ], "domain_services": [ "Review service" ], "application_services": [ "QA sign-off", "AttestationRecord", "delivered pack" ], "commands": [ "AttestAndDeliver" ], "domain_events": [ "PackDelivered" ], "policies": [ "Block on hard fail" ], "specifications": [ "ReviewCompletenessSpec" ], "invariants": [ "A pack cannot advance while an open hard fail exists in this context" ], "ai_agents": [ "Extraction & crosswalk agent" ], "human_roles": [ "Specialist", "Customer" ], "data_owned": [ "CORPackage", "AttestationRecord" ], "inputs": [ "Upstream context output" ], "outputs": [ "Downstream context input" ], "external_integrations": [ "Drive/Dropbox intake", "GC portals (customer-submitted, not auto-pushed)" ], "risks": [ "Illegible handwriting mis-extracted", "Ambiguous exhibit link accepted silently" ], "interfaces": [ "-> next context via domain event" ], "value_objects": [] } ], "context_map": [ { "upstream": "Intake & Normalization", "downstream": "Completeness & Matching", "relationship": "Customer-Supplier", "integration_pattern": "Domain event (CORReadyExtracted) consumed by matching engine", "translation_notes": "Canonical T&M ticket schema is the shared contract; no direct database coupling.", "pattern": "Customer-Supplier", "contract_type": "domain event", "data_exchanged": [ "[PLACEHOLDER] owner to complete" ], "events_exchanged": [ "Domain event (CORReadyExtracted) consumed by matching engine" ], "ownership_boundary": "Downstream never writes to upstream's tables", "acl_notes": "Anti-corruption translation not needed — shared canonical schema", "business_reason": "Keeps each context's invariants enforceable independently", "failure_risks": [ "[PLACEHOLDER] owner to complete" ] }, { "upstream": "Completeness & Matching", "downstream": "Delivery", "relationship": "Customer-Supplier", "integration_pattern": "Domain event (MatrixDrafted) triggers chase email drafting", "translation_notes": "Only reviewer-approved gaps cross the boundary.", "pattern": "Customer-Supplier", "contract_type": "domain event", "data_exchanged": "Canonical schema payload only", "events_exchanged": [ "Domain event (MatrixDrafted) triggers chase email drafting" ], "ownership_boundary": "Downstream never writes to upstream's tables", "acl_notes": "Anti-corruption translation not needed — shared canonical schema", "business_reason": "Keeps each context's invariants enforceable independently", "failure_risks": "Downstream stalls if upstream event delivery fails" }, { "upstream": "Completeness & Matching", "downstream": "Quality Assurance", "relationship": "Conformist", "integration_pattern": "SignPack command with synchronous validation", "translation_notes": "QA enforces the source-page-complete invariant; Completeness & Matching conforms to QA's signature contract.", "pattern": "Conformist", "contract_type": "domain event", "data_exchanged": "Canonical schema payload only", "events_exchanged": [ "SignPack command with synchronous validation" ], "ownership_boundary": "Downstream never writes to upstream's tables", "acl_notes": "Anti-corruption translation not needed — shared canonical schema", "business_reason": "Keeps each context's invariants enforceable independently", "failure_risks": "Downstream stalls if upstream event delivery fails" }, { "upstream": "Delivery", "downstream": "Quality Assurance", "relationship": "Conformist", "integration_pattern": "PackReadyForSignoff event", "translation_notes": "Pack cannot deliver without QA signoff.", "pattern": "Conformist", "contract_type": "domain event", "data_exchanged": "Canonical schema payload only", "events_exchanged": [ "PackReadyForSignoff event" ], "ownership_boundary": "Downstream never writes to upstream's tables", "acl_notes": "Anti-corruption translation not needed — shared canonical schema", "business_reason": "Keeps each context's invariants enforceable independently", "failure_risks": "Downstream stalls if upstream event delivery fails" } ], "external_integrations": [ { "system": "Subcontractor management system (spec) export", "direction": "inbound", "pattern": "File-based export, no live API at launch", "risk": "Schema drift per Spec version", "owner_context": "Delivery", "data_in": [ "[PLACEHOLDER] owner to complete" ], "data_out": [ "[PLACEHOLDER] owner to complete" ], "trigger": "Completeness cycle start", "internal_model": "Canonical T&M ticket/pack schema", "acl_strategy": "Per-section parser translates external format to canonical schema", "failure_strategy": "Retry then manual fallback", "audit_need": "Every external call logged with timestamp and payload hash" }, { "system": "T&M ticket portals", "direction": "inbound", "pattern": "Subcontractor-authorized credentialed pull or client-forwarded file", "risk": "Portal ToS friction; credential expiry", "owner_context": "Intake & Normalization", "data_in": "T&M ticket content", "data_out": "N/A", "trigger": "Completeness cycle start", "internal_model": "Canonical T&M ticket/pack schema", "acl_strategy": "Per-section parser translates external format to canonical schema", "failure_strategy": "Retry then manual fallback", "audit_need": "Every external call logged with timestamp and payload hash" }, { "system": "QuickBooks / spec posting-file import", "direction": "outbound", "pattern": "Generated posting file, Subcontractor-side import", "risk": "Format mismatch per bookkeeping software version", "owner_context": "Delivery", "data_in": "N/A", "data_out": "Posting file or chase email email", "trigger": "Reviewer approval", "internal_model": "Canonical T&M ticket/pack schema", "acl_strategy": "Per-section parser translates external format to canonical schema", "failure_strategy": "Retry then manual fallback", "audit_need": "Every external call logged with timestamp and payload hash" }, { "system": "Manufacturer COR-department mailbox", "direction": "outbound", "pattern": "Subcontractor-authorized email send", "risk": "ChaseItem misread as a demand", "owner_context": "Delivery", "data_in": "N/A", "data_out": "Posting file or chase email email", "trigger": "Reviewer approval", "internal_model": "Canonical T&M ticket/pack schema", "acl_strategy": "Per-section parser translates external format to canonical schema", "failure_strategy": "Retry then manual fallback", "audit_need": "Every external call logged with timestamp and payload hash" } ], "event_storm": [ { "seq": 1, "command": "SubmitCORSet", "event": "SubmissionReceived", "actor": "Customer", "context": "Intake context", "aggregate": "Submission", "policy": "Start SLA clock on complete intake", "downstream": "Normalize documents", "risk": "Incomplete intake starts a false clock" }, { "seq": 2, "command": "NormalizeDocuments", "event": "DocumentsNormalized", "actor": "Intake bot", "context": "Intake context", "aggregate": "Document", "policy": "Classify every page", "downstream": "Extract evidence", "risk": "Illegible handwriting misclassified" }, { "seq": 3, "command": "ExtractEvidence", "event": "EvidenceExtracted", "actor": "AI workbench", "context": "Evidence context", "aggregate": "EvidenceMatrix", "policy": "Never infer a rate or quantity", "downstream": "Crosswalk exhibits", "risk": "Hallucinated line without a source page" }, { "seq": 4, "command": "CrosswalkExhibits", "event": "MatrixCrosswalked", "actor": "AI workbench", "context": "Evidence context", "aggregate": "EvidenceMatrix", "policy": "Flag any line with no supporting exhibit as a gap", "downstream": "Run completeness rules", "risk": "Ambiguous exhibit link accepted silently" }, { "seq": 5, "command": "RunCompletenessRules", "event": "CompletenessScored", "actor": "Rules engine", "context": "Completeness context", "aggregate": "CompletenessScore", "policy": "Block on any open hard fail", "downstream": "Specialist QA", "risk": "Soft flag treated as hard fail or vice versa" }, { "seq": 6, "command": "AttestAndDeliver", "event": "PackDelivered", "actor": "Customer + Specialist", "context": "Review & Fulfillment context", "aggregate": "CORPackage", "policy": "No delivery without QA sign-off and attestation", "downstream": "Rejection learning on GC comment", "risk": "Delivery before attestation captured" } ], "critical_path": [ "T&M ticket.received -> T&M ticket.normalized -> pack_cycle.crosswalk_completed -> Gap.reviewer_approved -> COR_Pack.signed -> pack.delivered" ], "exception_flows": [ "A T&M ticket line below the matching-confidence threshold -> routed to reviewer exception queue, blocks pack_cycle.crosswalk_completed until resolved", "A Gap classification needs-reviewer-judgment -> held for reviewer, never auto-approved" ], "escalation_flows": [ "A Gap over $2,500 -> second reviewer pass before Chase list approval", "A manufacturer disputes an chase email beyond a routine response -> referred to the subcontractor's own counsel" ], "retry_flows": [ "Vendor chase email unacknowledged after 60 days -> automated reminder, then reviewer-judged escalation at 90 days" ], "manual_override_flows": [ "Founder/senior reviewer can force-hold any COR Pack pre-release regardless of automated source-page check pass, if a data-integrity issue is suspected" ], "commands": [ { "name": "SubmitCORSet", "issued_by": "Customer", "preconditions": [ "COR id or unnumbered flag", "at least one T&M ticket" ], "aggregate": "Submission", "success_event": "SubmissionReceived", "failure_event": "IntakeRejected", "authorization": "Customer", "validation": "Files readable; scope stated", "audit": "Intake log" }, { "name": "NormalizeDocuments", "issued_by": "Intake bot", "preconditions": [ "SubmissionReceived" ], "aggregate": "Document", "success_event": "DocumentsNormalized", "failure_event": "NormalizationFailed", "authorization": "System", "validation": "OCR confidence recorded per page", "audit": "Page-class version" }, { "name": "ExtractEvidence", "issued_by": "AI workbench", "preconditions": [ "DocumentsNormalized" ], "aggregate": "EvidenceMatrix", "success_event": "EvidenceExtracted", "failure_event": "ExtractionEscalated", "authorization": "System + Specialist", "validation": "No inferred rates or quantities", "audit": "Matrix version" }, { "name": "RunCompletenessRules", "issued_by": "Rules engine", "preconditions": [ "MatrixCrosswalked" ], "aggregate": "CompletenessScore", "success_event": "CompletenessScored", "failure_event": "HardFailRaised", "authorization": "System", "validation": "Deterministic rule functions", "audit": "Rule result set" }, { "name": "CaptureAttestation", "issued_by": "Customer", "preconditions": [ "SpecialistQAPassed" ], "aggregate": "AttestationRecord", "success_event": "AttestationCaptured", "failure_event": "AttestationMissing", "authorization": "Customer", "validation": "Attestor identity + attested scope", "audit": "Attestation record" }, { "name": "AttestAndDeliver", "issued_by": "Specialist", "preconditions": [ "AttestationCaptured", "zero open hard fails" ], "aggregate": "CORPackage", "success_event": "PackDelivered", "failure_event": "DeliveryBlocked", "authorization": "Specialist", "validation": "QA checklist 100%", "audit": "Delivery record" } ], "policies": [ { "name": "Start SLA on complete intake", "trigger": "SubmissionReceived", "condition": "Intake checklist complete or deferral recorded", "action": "Start the delivery SLA clock", "context": "Intake context", "ai_involvement": "Checklist bot verifies completeness", "human_approval": false }, { "name": "Never invent a rate", "trigger": "EvidenceExtracted", "condition": "A rate or quantity is not written on a source page", "action": "Mark the line a gap and cite the missing rate-sheet page", "context": "Evidence context", "ai_involvement": "Extraction prompt forbids inference", "human_approval": true }, { "name": "Block on hard fail", "trigger": "CompletenessScored", "condition": "Any hard fail is open", "action": "Prevent the pack from advancing until cleared or deferred by the customer", "context": "Completeness context", "ai_involvement": "None — deterministic rules", "human_approval": true }, { "name": "Code every rejection", "trigger": "GCCommentReceived", "condition": "GC returns a comment", "action": "Tag root cause (our miss / GC preference / contractor change) and update playbooks", "context": "Evidence context", "ai_involvement": "Taxonomy classifier suggests a tag", "human_approval": true } ], "aggregates": [ { "name": "CORPackage", "root": "CORPackage", "context": "Review & Fulfillment context", "purpose": "The assembled, submission-ready pack for one COR / T&M set.", "entities": [ "CORPackage" ], "value_objects": [ "CompletenessScore", "AttestationRecord" ], "invariants": [ "Cannot reach Delivered with an open hard fail or missing attestation" ], "commands": [ "AttestAndDeliver", "RequestResubmittal" ], "events": [ "PackDelivered", "GCCommentReceived" ], "repository": "CORPackageRepository", "transaction_boundary": "One CORPackage per transaction" }, { "name": "EvidenceMatrix", "root": "EvidenceMatrix", "context": "Evidence context", "purpose": "Crosswalk of each labor/material claim to supporting exhibits.", "entities": [ "MatrixLine" ], "value_objects": [ "Exhibit", "CoverageStatus" ], "invariants": [ "Every claim line has a coverage status of covered, gap, or ambiguous" ], "commands": [ "ExtractEvidence", "CrosswalkExhibits" ], "events": [ "EvidenceExtracted", "MatrixCrosswalked" ], "repository": "EvidenceMatrixRepository", "transaction_boundary": "One EvidenceMatrix per transaction" }, { "name": "Submission", "root": "Submission", "context": "Intake context", "purpose": "The customer's uploaded COR set and its normalization.", "entities": [ "Document", "Page" ], "value_objects": [ "PageClass", "CORHeader" ], "invariants": [ "A submission has a COR id or an explicit unnumbered flag" ], "commands": [ "SubmitCORSet", "NormalizeDocuments" ], "events": [ "SubmissionReceived", "DocumentsNormalized" ], "repository": "SubmissionRepository", "transaction_boundary": "One Submission per transaction" }, { "name": "CompletenessScore", "root": "CompletenessScore", "context": "Completeness context", "purpose": "The deterministic completeness read on a pack.", "entities": [ "RuleResult" ], "value_objects": [ "HardFail", "SoftFlag" ], "invariants": [ "Score cannot be 'ready' while any hard fail is open" ], "commands": [ "RunCompletenessRules" ], "events": [ "CompletenessScored", "HardFailRaised" ], "repository": "CompletenessScoreRepository", "transaction_boundary": "One CompletenessScore per transaction" }, { "name": "AttestationRecord", "root": "AttestationRecord", "context": "Review & Fulfillment context", "purpose": "The contractor's sign-off on rates, quantities, and entitlement.", "entities": [ "AttestationRecord" ], "value_objects": [ "Attestor", "AttestedScope" ], "invariants": [ "Attestation is captured before PackDelivered" ], "commands": [ "CaptureAttestation" ], "events": [ "AttestationCaptured" ], "repository": "AttestationRecordRepository", "transaction_boundary": "One AttestationRecord per transaction" }, { "name": "GCPlaybook", "root": "GCPlaybook", "context": "Evidence context", "purpose": "GC- and trade-specific packaging preferences and rejection memory.", "entities": [ "PlaybookRule" ], "value_objects": [ "GCFirm", "Trade" ], "invariants": [ "A coded rejection maps to exactly one root-cause tag" ], "commands": [ "CodeRejection" ], "events": [ "RejectionCoded" ], "repository": "GCPlaybookRepository", "transaction_boundary": "One GCPlaybook per transaction" }, { "name": "GapChase", "root": "GapChase", "context": "Evidence context", "purpose": "The outstanding missing items and their draft chase communications.", "entities": [ "GapItem" ], "value_objects": [ "GapReason", "ChaseDraft" ], "invariants": [ "Every gap item names a concrete missing artifact" ], "commands": [ "DraftChase" ], "events": [ "ChaseDrafted" ], "repository": "GapChaseRepository", "transaction_boundary": "One GapChase per transaction" } ], "invariants": [ { "invariant": "Cannot reach Delivered with an open hard fail", "context": "Review & Fulfillment context", "aggregate": "CORPackage", "why": "A pack that ships with a missing signature or unlinked photo defeats the completeness promise.", "enforcement": "Delivery command checks zero open hard fails." }, { "invariant": "Attestation captured before delivery", "context": "Review & Fulfillment context", "aggregate": "AttestationRecord", "why": "The contractor, not CORReady Clear, owns rates, quantities, and entitlement.", "enforcement": "AttestAndDeliver requires AttestationCaptured." }, { "invariant": "Every claim line has a coverage status", "context": "Evidence context", "aggregate": "EvidenceMatrix", "why": "An unclassified line hides a gap from the reviewer.", "enforcement": "Matrix validation rejects null coverage." }, { "invariant": "No invented rate reaches the pricing worksheet", "context": "Evidence context", "aggregate": "EvidenceMatrix", "why": "Presenting an inferred rate as contract fact is a hallucination and a compliance risk.", "enforcement": "Rates cite a rate-sheet page or are marked deferred." } ], "ai_agents": [ { "name": "Extraction Agent", "context": "Intake & Normalization", "responsibility": "Extract and normalize structured fields from manufacturer COR T&M tickets (PDF, portal CSV, scanned paper) into the canonical schema.", "inputs": [ "Uploaded/forwarded T&M tickets" ], "outputs": [ "Structured line items with per-field confidence score" ], "tools": [ "OCR", "per-section parser library" ], "forbidden_actions": [ "Guessing a requirement id fragment not present in the source text" ], "memory_scope": "Single T&M ticket extraction run", "retrieval_sources": [ "Per-section parser fixture library" ], "validations": [ "Confidence score attached to every field" ], "confidence_scoring": "0-100 per field, threshold 85", "escalation_triggers": [ "Any required field below 85% confidence" ], "human_approval": "Reviewer confirms during exception review", "failure_modes": [ "Misread scanned/paper T&M ticket", "Wrong manufacturer-format classification" ], "audit_logs": [ "Every extraction run logged with document hash and confidence scores" ], "metrics": [ "Extraction accuracy vs. reviewer-corrected value" ], "versioning": "Prompt versioned independently of the underlying model" }, { "name": "Matching Agent", "context": "Completeness & Matching", "responsibility": "Match normalized T&M ticket lines to spec policies (exact -> fuzzy -> reviewer-adjudicated) and compute expected COR from the schedule.", "inputs": [ "Normalized T&M ticket lines", "Spec basis-of-design set", "COR schedules" ], "outputs": [ "Match candidates with confidence score", "Expected-COR computation" ], "tools": [ "Fuzzy entity matcher", "COR-schedule lookup" ], "forbidden_actions": [ "Auto-accepting a match below the confidence threshold" ], "memory_scope": "Single pack cycle", "retrieval_sources": [ "Subcontractor's Spec basis-of-design set (tenant-scoped)" ], "validations": [ "Every match below threshold routed to reviewer with reasoning" ], "confidence_scoring": "0-100 per match, auto-accept ≥95, reviewer queue below", "escalation_triggers": [ "No candidate match found", "Ambiguous multi-candidate match" ], "human_approval": "Reviewer adjudicates all sub-threshold matches", "failure_modes": [ "Wrong fuzzy match on a common project owner name", "Stale spec requirement Procore" ], "audit_logs": [ "Every match decision logged with confidence and reasoning" ], "metrics": [ "Auto-match rate", "Match-reversal rate on reviewer audit" ], "versioning": "Prompt versioned independently of the underlying model" }, { "name": "Gap Drafter Agent", "context": "Completeness & Matching", "responsibility": "Classify each line's Gap type and draft a plain-language explanation citing the source T&M ticket and policy.", "inputs": [ "Matched/unmatched T&M ticket lines", "Spec requirement", "Spec-quirk notes", "Prior payment history" ], "outputs": [ "Gap classification", "Draft explanation with citations" ], "tools": [ "Spec-quirk knowledge base lookup" ], "forbidden_actions": [ "Stating a Gap is confirmed before reviewer approval", "Estimating a dollar gap the schedule doesn't cover" ], "memory_scope": "Single pack cycle", "retrieval_sources": [ "Spec-quirk knowledge base" ], "validations": [ "Output must cite a source T&M ticket line and spec requirement reference" ], "confidence_scoring": "Qualitative (missing / rejected / late / resubmittal / rate-mismatch / unearned / needs-reviewer-judgment)", "escalation_triggers": [ "Schedule doesn't cover the case" ], "human_approval": "Reviewer approves every classification before it appears in the Chase list", "failure_modes": [ "Misclassifying a legitimate resubmittal as a short-pay" ], "audit_logs": [ "Every classification logged with citation and confidence" ], "metrics": [ "Gap-classification accuracy vs. reviewer-corrected value" ], "versioning": "Prompt versioned independently of the underlying model" }, { "name": "ChaseItem Drafter Agent", "context": "Delivery", "responsibility": "Draft a professional, chase email-toned (never demand-toned) email to a manufacturer's COR department for an approved Gap.", "inputs": [ "Approved Gap", "Subcontractor identity", "Spec requirement reference" ], "outputs": [ "Drafted vendor chase email email" ], "tools": [ "Demand-language deterministic filter" ], "forbidden_actions": [ "Using demand, collection, or legal-threat language", "Sending without reviewer approval" ], "memory_scope": "Single Gap chase email", "retrieval_sources": [ "Spec-quirk knowledge base", "Manufacturer contact map" ], "validations": [ "Draft passes the demand-language filter before reaching the reviewer" ], "confidence_scoring": "N/A (deterministic filter gate, not a confidence score)", "escalation_triggers": [ "Filter rejects a draft twice in a row for the same Gap" ], "human_approval": "Reviewer approves every draft before send", "failure_modes": [ "Draft reads as aggressive despite passing the filter" ], "audit_logs": [ "Every draft + approval + send logged" ], "metrics": [ "Manufacturer response rate", "Reviewer edit rate on drafts" ], "versioning": "Prompt versioned independently of the underlying model" } ], "prompt_chain_map": [ "Intake -> Extraction Agent (extract + score) -> Matching Agent (match + compute expected) -> Gap Drafter Agent (classify + cite) -> OutputValidator -> Reviewer (approve or escalate)", "Approved Gap -> ChaseItem Drafter Agent (draft) -> demand-language filter -> Reviewer (approve or edit) -> send" ], "rag_map": [ "Per-Subcontractor Spec basis-of-design set (tenant-scoped) -> retrieval router -> Subcontractor-scoped hits -> Matching Agent", "Versioned per-section parser fixture + quirk knowledge base -> shared retrieval -> Extraction Agent and Gap Drafter Agent (cited)" ], "ai_evaluation": [ "Golden dataset of past reviewer-accepted matches and Gap classifications, per manufacturer", "Regression requirements on auto-match rate + Gap-citation coverage", "Every prompt release requires a passing evaluator run against the fixture library" ], "hallucination_controls": [ "Retrieval-first (no free-form Gap generation without a cited T&M ticket line and requirement reference)", "Structured-output validator enforces citation-per-claim", "Confidence-scored escalation on extraction and matching", "Reviewer gate on every Gap and every outbound vendor chase email", "Deterministic filter blocks any demand/collection-style or coverage-determination language before it reaches the reviewer" ], "human_in_the_loop_plan": [ "Reviewer signoff on every COR Pack before delivery", "Reviewer approval on every Gap before it appears in a Chase list or goes to a manufacturer", "Senior-reviewer co-sign on cover narratives", "Owner approval on public-release readiness" ], "ai_audit_plan": [ "Every AgentRun logged with prompt version, retrieval hit ids, cost, latency, validator verdict", "13-month rolling retention on run logs", "Financial/PII data scrubbed from log payloads" ], "prompt_versioning": "Prompt versions immutable once published; rolled out via feature flag; every rollout paired with an evaluator run against the fixture library.", "human_roles": [ { "role": "Subcontractor principal", "responsibilities": [ "Supply Spec section and T&M tickets", "Sign vendor-communication authorization", "Approve trade scope split" ], "contexts": [ "Intake & Normalization" ], "decisions_owned": [ "Whether to engage", "Which records to supply", "Whether to authorize the rush rider" ], "ai_support": [ "[PLACEHOLDER] owner to complete" ], "approval_authority": "Authorizes the engagement and vendor-communication authorization", "escalation_authority": "None (escalates to CORReady Clear, not from it)", "quality_metrics": [ "Intake completeness" ], "workload_risks": [ "Month-end time scarcity" ] }, { "role": "Trade-specialist QA reviewer", "responsibilities": [ "Review AI-drafted matches and gaps", "Verify evidence sufficiency", "Sign off before delivery or manufacturer send" ], "contexts": [ "Completeness & Matching", "Quality Assurance" ], "decisions_owned": [ "Approve, escalate, or reject a Gap or match" ], "ai_support": "Extraction, matching, Gap-classification, and chase email-drafting agents", "approval_authority": "Sole authority to sign a COR Pack or approve a vendor chase email", "escalation_authority": "Escalates coverage/claims questions to the subcontractor's own licensed staff; disputes beyond routine chase email to the subcontractor's counsel", "quality_metrics": [ "Client-caught material error rate", "Review cycle time" ], "workload_risks": [ "Volume spike during month-end delivery window" ] }, { "role": "Senior Reviewer", "responsibilities": [ "Second-pass sampling on auto-matched lines", "Co-sign cover narratives", "Second review on high-value chase lists" ], "contexts": [ "Quality Assurance" ], "decisions_owned": [ "Cover narrative approval" ], "ai_support": "None (human-only by design)", "approval_authority": "Cover narrative co-signature authority", "escalation_authority": "Escalates to founder/owner", "quality_metrics": [ "Cover narrative rate" ], "workload_risks": [ "Contractor-bench availability at scale" ] } ], "human_review_checkpoints": [ "AI draft -> Reviewer approval", "Public release -> owner acceptance", "Cover narrative -> senior-reviewer co-sign", "Prompt rollout -> ops + evaluator" ], "escalation_matrix": [ "AI -> Reviewer -> Senior Reviewer -> Owner -> Subcontractor's own counsel", "Coverage/claims dispute -> Reviewer -> Subcontractor's own licensed staff" ], "manual_override_rules": [ "Any manual override captured as an explicit override event with actor + reason", "No override may bypass the reviewer-signoff or manufacturer-authorization invariant" ], "separation_of_duties": [ "Extraction/Matching/Drafter Agents cannot sign; Reviewer cannot draft on behalf of AI without an override event; Senior Reviewer cannot silently retract" ], "quality_control_workflow": [ "Weekly reviewer calibration meeting", "Monthly evaluator regression report", "Quarterly spec-quirk library re-verification review with owner + compliance" ], "data_objects": [ { "name": "CORReady", "meaning": "One manufacturer's T&M ticket for one period", "owner_context": "Intake & Normalization", "writers": [ "Extraction Agent", "Subcontractor principal" ], "readers": [ "Trade-specialist QA reviewer", "Completeness & Matching" ], "source_of_truth": "Intake & Normalization context", "retention": "7 years (mirrors standard financial-record retention practice)", "privacy": "Sensitive business/financial data, Subcontractor-isolated", "audit": "Every field change logged" }, { "name": "Pack", "meaning": "One pack cycle's signed source-page check record", "owner_context": "Completeness & Matching", "writers": [ "Matching Agent", "Trade-specialist QA reviewer" ], "readers": [ "Subcontractor principal", "Quality Assurance" ], "source_of_truth": "Completeness & Matching context", "retention": "7 years", "privacy": "Sensitive", "audit": "Full version history retained" }, { "name": "ComplianceMatrix", "meaning": "One cycle's list of classified, evidenced gaps", "owner_context": "Completeness & Matching", "writers": [ "Gap Drafter Agent", "Trade-specialist QA reviewer" ], "readers": [ "Subcontractor principal", "Delivery" ], "source_of_truth": "Completeness & Matching context", "retention": "7 years", "privacy": "Sensitive", "audit": "Reviewer approval logged per line" } ], "read_models": [ "OperatorDashboard read model (per tenant): open cycles, in-review, delivered this week", "ReviewerQueue read model: T&M tickets/gaps awaiting review with confidence + escalation reason", "CompliancePack read model: open owner actions + release-decision", "AnalyticsRollup read model: metric definitions rolled up daily" ], "reporting_models": [ "Outcome report per client: packs delivered, cycle time, client-caught error status, cleared sections", "Ops report: AI cost per cycle, escalation rate, reviewer load" ], "data_duplication_notes": [ "Reviewer identity is stored in Onboarding, referenced by Quality Assurance — QA does not own it", "OwnerActionPack duplicates minimal facts into read models for Completeness & Matching consumption" ], "data_retention": [ "COR Packs + Gap ComplianceMatrixs + signoffs: 7 years (standard financial-record retention)", "AgentRun logs: 13 months rolling", "Users + sessions: life of account + 2 years" ], "data_quality_risks": [ "Silent schema drift from a a manufacturer changing its T&M ticket layout", "Stale COR-schedule version Procore after a rate change (mitigated by quarterly re-verification)", "Missing cover narrative cross-links after a legacy client-history import" ], "use_cases": [ { "name": "Run a Gap Scan", "actor": "Subcontractor principal", "context": "Intake & Normalization", "goal": "Get a matched-percentage and estimated-dollar-value finding within 10 business days", "preconditions": [ "Spec section and 3 months of T&M tickets supplied" ], "main_flow": [ "Intake checklist completed", "CORReadys normalized and source-checked", "Matching engine runs", "Reviewer approves gaps", "Scan report delivered" ], "alternative_flows": [ "No material finding -> report says so explicitly, no fee retained beyond the flat scan price" ], "business_rules": [ "No Gap ships without reviewer approval" ], "ai_role": "Extraction, matching, classification, drafting", "human_role": "Reviewer approves and signs", "commands": [ "ReceiveCORReady", "NormalizeCORReady", "RunMatching", "ApproveGap" ], "events": [ "T&M ticket.normalized", "pack_cycle.crosswalk_completed", "Gap.reviewer_approved" ], "aggregates": [ "CORReadyAggregate", "SectionAggregate", "ComplianceMatrixAggregate" ], "success": "Scan report delivered within SLA with reviewer signature", "failure_handling": "Missing inputs trigger an automated nag; cycle does not start until complete", "audit": "Full audit trail from T&M ticket receipt to report delivery" }, { "name": "Deliver a monthly Completeness Desk pack", "actor": "Trade-specialist QA reviewer", "context": "Delivery", "goal": "Ship a signed Monthly Completeness Pack by the 5th business day", "preconditions": [ "Client on an active Completeness Desk tier", "Prior cycle's vendor chase emails tracked" ], "main_flow": [ "CORReadys collected and normalized", "Matching completed", "Gaps approved", "Vendor chase emails drafted and sent", "Pack signed", "Pack delivered" ], "alternative_flows": [ "High-value Chase list (>$2,500) routed to second reviewer before finalization" ], "business_rules": [ "Source-page completeness required before signature" ], "ai_role": "Extraction, matching, classification, chase email drafting", "human_role": "Reviewer signs; second reviewer on high-value chase lists", "commands": [ "RunMatching", "ApproveGap", "SendChaseItem", "SignPack" ], "events": [ "COR_Pack.signed", "manufacturer_chase email.sent", "pack.delivered" ], "aggregates": [ "PackAggregate", "ChaseItemAggregate" ], "success": "Pack delivered on time with a signed pack", "failure_handling": "Missed SLA triggers the error-SLA acknowledgment process", "audit": "Full cycle audit trail retained" } ], "architecture": { "style": "Modular monolith with edge functions for bursty T&M ticket-extraction workloads", "why": "One audit boundary, low ops burden for a founder-operated business, easy per-context ownership as the team grows past founder-only.", "rejected_alternatives": [ "Microservices per bounded context (premature at this scale)", "No-code workflow tool (can't enforce the source-page-complete deterministic gate reliably)" ], "backend_modules": [ "intake-normalization", "Completeness-matching", "Resubmittal-delivery", "quality-assurance" ], "frontend_modules": [ "reviewer-console (internal only at launch)", "marketing microsite (public)" ], "api_boundaries": [ "Internal reviewer console API (authenticated)", "No public API at launch — intake is upload-link/email only" ], "database_strategy": "Single Postgres instance, tenant_id row-level security on every table", "event_bus": "In-process event dispatch at launch; durable queue (e.g. a managed message queue) once cycle volume requires async fan-out", "queue": "Background job queue for T&M ticket extraction and matching (bursty, month-end-weighted load)", "workflow_engine": "None at launch — explicit state machine per aggregate in code", "ai_orchestration": "Scripted pipeline calling a single frontier-model provider, prompts + fixtures versioned in the repo", "rag_layer": "Per-Subcontractor book-of-business retrieval + shared per-section parser/quirk knowledge base", "file_storage": "Encrypted object storage, per-Subcontractor prefix isolation", "authn_authz": "SSO with MFA for reviewers; row-level tenant auth for Subcontractor-facing surfaces (year-1 client portal)", "admin_dashboard": "Internal only at launch (founder + reviewer)", "client_portal": "None at launch (email/upload-link delivery); read-only pack-status portal planned year 1", "operator_dashboard": "ReviewerQueue read model surfaced in the internal console", "observability": "Structured logs + RED metrics + model-call cost/latency spans", "audit_logging": "Append-only, hash-chained per pack cycle", "deployment": "Single production region, multi-AZ; preview environment per PR" }, "module_structure": { "tree": "src/{intake-normalization,Completeness-matching,Resubmittal-delivery,quality-assurance}/{domain,application,infra}", "modules": [ { "name": "intake-normalization", "purpose": "CORReady receipt, extraction, and source-page check.", "owned_domain": [ "CORReady" ], "application_services": [ "ReceiveCORReady", "NormalizeCORReady" ], "infra_adapters": [ "Mailbox listener", "Object storage adapter", "Extraction-model client" ], "public_interfaces": [ "T&M ticket.normalized event" ], "forbidden_deps": [ "Cannot call Completeness-matching internals directly — event only" ] }, { "name": "Completeness-matching", "purpose": "Matching, Gap classification, Pack source-page check.", "owned_domain": [ "Section", "ComplianceMatrix", "Pack" ], "application_services": [ "RunMatching", "ApproveGap", "SignPack" ], "infra_adapters": [ "spec-export parser", "COR-schedule store" ], "public_interfaces": [ "Gap.reviewer_approved event", "COR_Pack.signed event" ], "forbidden_deps": [ "Cannot call Resubmittal-delivery internals directly — event only" ] }, { "name": "Resubmittal-delivery", "purpose": "Vendor-chase drafting/sending, aging, pack assembly.", "owned_domain": [ "ChaseItem", "AECommentRecord", "MonthlyCompletenessPack" ], "application_services": [ "SendChaseItem", "AssemblePack", "DeliverPack" ], "infra_adapters": [ "Email-send adapter", "Posting-file generator" ], "public_interfaces": [ "pack.delivered event" ], "forbidden_deps": [ "Cannot bypass quality-assurance signoff gate" ] }, { "name": "quality-assurance", "purpose": "Signoff and cover narrative lifecycle.", "owned_domain": [ "Signoff", "Cover narrative" ], "application_services": [ "ApproveArtifact", "RetractArtifact" ], "infra_adapters": [ "Signature-binding session store" ], "public_interfaces": [ "ArtifactSigned event" ], "forbidden_deps": [ "Cannot draft on behalf of any other module" ] } ], "dependency_rules": [ "Modules communicate only via domain events or explicit application-service calls, never shared database tables", "quality-assurance has no outbound dependency on any other module" ] }, "security_governance": { "controls": [ { "risk": "Cross-tenant data leak", "context": "Completeness & Matching", "impact": "severe", "control": "Row-level security on every tenant-scoped table; retrieval indices partitioned per Subcontractor", "audit": "Access logged with tenant_id + session_id" }, { "risk": "Reviewer identity spoofing", "context": "Quality Assurance", "impact": "severe", "control": "SSO + MFA; signature bound to authenticated session, not a form field", "audit": "Signature manifest logged per artifact" }, { "risk": "Demand-language vendor chase email sent", "context": "Delivery", "impact": "high", "control": "Deterministic filter blocks demand/collection/legal-threat patterns before reviewer sees the draft", "audit": "Every blocked draft logged with the trigger phrase" } ], "ai_governance": [ "Every prompt version checked into the repo", "Every AgentRun logged with prompt version + validator verdict", "No fine-tuning on client data" ], "prompt_injection_defense": [ "Uploaded T&M ticket content treated as untrusted input, never as instructions", "Extraction output schema-validated before use downstream" ], "sensitive_data_handling": [ "Financial/PII scrubbed from logs", "Per-Subcontractor object-storage prefix isolation", "Encryption at rest and in transit" ], "access_control_matrix": [ { "role": "Subcontractor principal", "context": "Intake & Normalization", "capabilities": [ "Upload T&M tickets", "View own subcontractor's cycle status" ] }, { "role": "Trade-specialist QA reviewer", "context": "Completeness & Matching, Quality Assurance", "capabilities": [ "Approve gaps", "Sign Packs", "Approve vendor chase emails" ] }, { "role": "Senior Reviewer", "context": "Quality Assurance", "capabilities": [ "Co-sign cover narratives", "Second-review high-value chase lists" ] } ], "audit_log_requirements": [ "Every command + payload hash logged with actor identity", "13-month rolling retention on AgentRun logs; 7-year retention on signed Packs" ] }, "observability": { "metrics": [ { "metric": "Auto-match rate", "type": "leading", "context": "Completeness & Matching", "why": "Directly drives reviewer minutes per cycle", "target": "≥90%", "alert_threshold": "<80%" }, { "metric": "Reviewer minutes per client per cycle", "type": "leading", "context": "Completeness & Matching", "why": "Core unit-economics driver", "target": "≤115 min by day 90", "alert_threshold": ">180 min" }, { "metric": "Client-caught material error rate", "type": "lagging", "context": "Quality Assurance", "why": "Trust and retention driver", "target": "<0.5%", "alert_threshold": ">1%" } ], "dashboards": [ "Ops dashboard: cycles in flight, reviewer queue depth", "Economics dashboard: COGS/client, gross margin trend" ], "audit_reports": [ "Monthly signed-Pack audit export per client" ], "quality_review_reports": [ "Weekly red-team seeded-error catch rate" ], "ai_evaluation_reports": [ "Monthly evaluator regression report per manufacturer parser" ], "client_outcome_reports": [ "Cleared-first report per client per quarter" ] }, "testing_strategy": { "tests": [ { "type": "unit", "validates": "Source-page check math and materiality thresholds", "context": "Completeness & Matching", "example": "Pack total must equal sum of matched + exception-coded lines" }, { "type": "contract", "validates": "Per-section parser output schema", "context": "Intake & Normalization", "example": "Gold-standard fixture T&M ticket per manufacturer re-run on every prompt change" }, { "type": "e2e", "validates": "Full intake -> match -> reviewer signoff -> delivery path", "context": "cross-context", "example": "Smoke test against 5 sample T&M ticket formats" } ], "critical_domain_rules": [ "Source-page completeness before signature", "No Gap without a cited source and requirement reference", "No vendor chase email without authorization on file" ], "ai_eval_dataset": [ "Gold-standard fixture T&M tickets per manufacturer", "Reviewer-corrected historical matches and classifications" ], "regression_plan": "Every parser/prompt/model change re-runs the full fixture suite before touching a live client T&M ticket.", "contract_testing_plan": "Per-T&M ticket schema contract tests run in CI on every parser change.", "manual_qa_checklist": [ "10% second-pass sample of auto-matched lines", "Monthly red-team seeded-error check", "Every Chase list over $2,500 second-reviewed" ] }, "mvp_roadmap": [ { "phase": "Thin slice", "goal": "One end-to-end Gap Scan delivered and reviewer-signed", "features": [ "CORReady intake", "Single-manufacturer-format extraction", "Manual-assisted matching" ], "contexts": [ "Intake & Normalization", "Completeness & Matching" ], "ai_needs": [ "Extraction Agent v1" ], "human_workflows": [ "Founder-run reviewer role" ], "data_needs": [ "Fixture T&M tickets for 5 formats" ], "integrations": [ "None — manual Spec section upload" ], "risks": [ "Reviewer cycle time far above target at pilot 1" ], "exit_criteria": [ "1 scan delivered within 10 business days, reviewer-signed" ] } ], "scaling_roadmap": [ { "stage": "Pilot (1-10 clients)", "trigger": "First 10 pilot Subcontractors onboarded", "architecture_change": "None — single monolith suffices", "operational_change": "Founder is the sole reviewer", "risk": "Reviewer bottleneck at any volume spike" }, { "stage": "Early scale (10-50 clients)", "trigger": "Day-90 checkpoint targets met", "architecture_change": "Background job queue for T&M ticket extraction", "operational_change": "Contract a second trade-specialist QA reviewer", "risk": "Parser library coverage gaps on new manufacturers slow onboarding" } ], "risk_register": [ { "risk": "GC-portal vendor bundles Completeness 'free' with a chase workflow", "likelihood": "medium-high", "impact": "high", "signal": "Autodesk Build (ACC) or a competing GC-portal module adds chase/Resubmittal features", "mitigation": "Portal-agnostic positioning; resubmittal/chase as the human moat", "owner": "owner", "context": "Delivery" }, { "risk": "Scan-to-desk conversion underperforms", "likelihood": "medium", "impact": "severe", "signal": "Pilot cohort conversion below 25%", "mitigation": "Pilot gate at 25%; alternative packaging tested in cohort 2", "owner": "owner", "context": "product" }, { "risk": "False-positive Gap sent to a manufacturer", "likelihood": "medium", "impact": "high", "signal": "Manufacturer disputes an chase email as unfounded", "mitigation": "100% reviewer approval; evidence-link requirement; chase email-not-demand language", "owner": "legal", "context": "Delivery" } ], "adrs": [ { "id": "ADR-001", "decision": "Adopt a modular monolith, not microservices, at launch", "status": "accepted", "context": "Founder-operated team; low ops burden required", "options": [ "Modular monolith", "Microservices per bounded context", "No-code workflow tool" ], "chosen": "Modular monolith", "business_reason": "Fastest path to first paid pilot without a platform team", "technical_reason": "One deploy, one audit boundary, easy to reason about at this scale", "tradeoffs": [ "[PLACEHOLDER] owner to complete" ], "risks": [ "[PLACEHOLDER] owner to complete" ], "revisit_trigger": "Sustained CPU/latency pressure isolated to one module", "why": "One deploy, one audit boundary, easy to reason about at this scale", "consequences": "Will need extraction into services if reviewer-console load grows sharply", "reversal": "Would require a migration of the affected module's data model.", "revisit_when": "Sustained CPU/latency pressure isolated to one module" }, { "id": "ADR-002", "decision": "Deterministic code owns all money math; the model never computes a final dollar figure", "status": "accepted", "context": "Source-page completeness is a hard trust requirement", "options": [ "Model computes totals", "Deterministic code computes totals, model only extracts/classifies" ], "chosen": "Deterministic code computes totals", "business_reason": "A wrong dollar figure from a model is the single fastest way to lose a client's trust", "technical_reason": "Removes an entire class of hallucination risk from the highest-stakes output", "tradeoffs": "Slightly more engineering work per new transaction-type edge case", "risks": "Edge cases not yet coded fall through to reviewer manual calculation", "revisit_trigger": "None — this is a standing invariant, not revisited", "why": "Removes an entire class of hallucination risk from the highest-stakes output", "consequences": "Slightly more engineering work per new transaction-type edge case", "reversal": "Would require a migration of the affected module's data model.", "revisit_when": "None — this is a standing invariant, not revisited" } ], "self_audit": { "scores": [ { "category": "domain_modeling", "score": 4, "weakness": "Spec-quirk knowledge base is described but not yet instantiated with real manufacturer data", "improvement": "Populate from the first 5 pilot Subcontractors' actual manufacturer mixes" }, { "category": "ai_governance", "score": 4, "weakness": "Evaluator regression suite depends on fixture T&M tickets not yet collected at volume", "improvement": "Build the fixture library incrementally from each pilot's real (anonymized) T&M tickets" }, { "category": "compliance_boundary", "score": 3, "weakness": "State-by-state collection-Subcontractor-statute review for the rush rider is not yet complete", "improvement": "Complete counsel review in the first 5 operating states before offering the rider broadly" } ], "weakest_parts": [ "State-by-state licensing review for the rush rider", "Spec-quirk knowledge base population" ], "biggest_assumptions": [ "Scan-to-desk conversion reaches 25-40%", "Reviewer minutes per client fall as projected by day 90" ], "highest_risk_decisions": [ "Offering the rush rider before full state-by-state counsel review", "Relying on a single named reviewer at pilot scale" ], "needs_domain_expert": [ "[PLACEHOLDER] owner to complete" ], "needs_legal": [ "[PLACEHOLDER] owner to complete" ], "needs_prototype": [ "[PLACEHOLDER] owner to complete" ], "validate_before_prod": [ "[PLACEHOLDER] owner to complete" ] }, "final_recommendations": [ "Ship a modular-monolith, evidence-linked, reviewer-gated vertical slice for CORReady Clear. Preserve the invariant that no COR Pack or vendor chase email leaves the system without a signed human release. Do not launch commercially until owner-action facts close and at least one reviewer-released Monthly Completeness Pack has shipped.", "Do NOT default to microservices. Extract a module only when a specific pressure demands it.", "Do NOT allow AI outputs to leave the Completeness & Matching or Delivery contexts without OutputValidator pass and citation coverage.", "Do NOT ship any public claim on the CORReady Clear microsite while owner-action facts (entity, reviewer identity, trademark clearance) remain open.", "Do NOT reuse a competitor/customer pairing or a dollar figure in client-facing copy without a fresh-verification citation — this exact failure mode (a misattributed customer relationship) was found and corrected in this build." ], "extensions": { "service_business_reality_check": { "is_service_business": true, "paid_outcome_clear": true, "workflow_present": true, "ai_native_fit_score": 4.5, "red_flags": [] }, "ai_native_fit": { "score": 4.6, "why": "High-volume, document-heavy, rules-based matching with judgment concentrated in a small exception queue — the exact shape of work current frontier models do well, and margins expand as parsing/matching accuracy improves.", "disqualifiers": [] }, "domain_evidence_register": [ { "claim": "52% of Subcontractors receive direct-bill COR T&M tickets, up from 45% in 2022", "evidence_type": "primary-research summary", "source": "AGC Subcontractor Universe Study (via IA Magazine)", "strength": "high", "gaps": "None — corroborated across two independent trade-press summaries" }, { "claim": "Procore CORs serves large brokers and remains operational as of mid-2026", "evidence_type": "press + legal filing coverage", "source": "Procore CORs/Workday Ventures materials; federal court ruling coverage, Feb 2026", "strength": "high", "gaps": "Exact customer roster not independently verifiable — corrected one misattributed customer pairing this build" } ], "assumption_register": [ { "assumption": "Scan-to-desk conversion reaches 25-40%", "impact_if_wrong": "severe — wedge economics fail", "how_to_validate": "10-Subcontractor pilot cohort with explicit pricing conversation", "blocking": true }, { "assumption": "Reviewer minutes per client fall as parser coverage grows", "impact_if_wrong": "high — margin target missed", "how_to_validate": "Instrument reviewer minutes per cycle from pilot 1 onward", "blocking": false } ], "language_conflict_map": [ { "term": "pack", "meaning_a": "Monthly Completeness Pack (this business's bundled deliverable: Pack + Chase list + report + furnish decisions + posting file)", "context_a": "CORReady Clear", "meaning_b": "A different bundled-deliverable term used by unrelated businesses elsewhere in the AINBIS portfolio", "context_b": "other portfolio businesses (not this one)", "resolution": "Always qualify as 'Monthly Completeness Pack' in CORReady Clear copy; never bare 'pack' without the qualifier in cross-portfolio contexts" } ], "build_buy_integrate": [ { "subdomain": "Completeness & Matching", "decision": "build", "reason": "Core differentiated IP — the parser/matching engine is the moat" }, { "subdomain": "Referral & Outreach", "decision": "buy", "reason": "Off-the-shelf CRM suffices; not differentiating" } ], "core_protection_strategy": [ "[PLACEHOLDER] owner to complete" ], "boundary_stress_tests": [ { "scenario": "A manufacturer disputes an chase email as a collection demand", "contexts_touched": [ "Delivery" ], "breaks_if": "The demand-language filter has a gap for a novel phrasing", "verdict": "Mitigated by reviewer approval as a second gate" } ], "unresolved_ownership": [ { "concept": "Trade scope split accuracy", "candidates": [ "Subcontractor principal", "Trade-specialist QA reviewer" ], "recommendation": "Subcontractor principal owns and approves the scope split; CORReady Clear only computes from it" } ], "published_language_contracts": [ { "producer": "Intake & Normalization", "consumer": "Completeness & Matching", "contract": "Canonical normalized T&M ticket schema", "versioning": "Schema version pinned per manufacturer parser release" } ], "shared_kernel_warnings": [ "None identified — bounded contexts communicate only via events, no shared kernel" ], "aggregate_stress_tests": [ { "aggregate": "PackAggregate", "scenario": "Concurrent reviewer sign attempts on the same Pack", "invariant_at_risk": "Source-page completeness before signature", "verdict": "Mitigated by optimistic locking on the aggregate root" } ], "agent_stress_tests": [ { "agent": "ChaseItem Drafter Agent", "scenario": "A manufacturer's known aggressive collections department prompts an escalated tone", "failure_mode": "Draft reads as a threat despite passing the deterministic filter", "guardrail": "Reviewer approval catches tone issues the filter misses", "verdict": "Acceptable with reviewer gate" } ], "regulated_domain_handling": [ { "regime": "State engineering-practice statutes", "applies_because": "CORReady Clear performs back-office accounting adjacent to a licensed industry", "controls": [ "No selling/soliciting/negotiating", "No consumer contact" ], "evidence_required": [ "[PLACEHOLDER] owner to complete" ] }, { "regime": "State collection-Subcontractor statutes", "applies_because": "Vendor chase emails could be miscategorized as third-party debt collection", "controls": [ "Chase emails sent under subcontractor's own name", "Administrative-agent authorization", "No demand language" ], "evidence_required": "Per-state counsel review before offering the rush rider" } ], "unit_economics": { "price_model": "Flat monthly desk fee by volume tier + one-time scan + capped rush rider", "unit_of_value": "pack cycle (one client-month)", "gross_margin_pct": 62, "cost_drivers": [ "Model inference (parse/match/draft)", "Reviewer minutes", "QA sampling" ], "breakeven_note": "COGS/client falls from $510 at launch to $245 by year 1 as parser coverage and auto-match rate improve" }, "margin_leakage_map": [ { "leakage": "Reviewer minutes not falling with parser coverage", "cause": "New manufacturer formats not yet in the fixture library", "impact": "Gross margin compression per new client", "mitigation": "Fixture library grows with every pilot; reuse across clients on the same manufacturer" } ], "slop_findings": [ { "pattern": "Generic SaaS marketing phrasing", "status": "checked", "note": "Banned-phrase list enforced on the landing page (no 'leverage AI', 'streamline', etc.)" } ], "drift_checks": [ { "stage": "build", "status": "checked", "findings": [ "[PLACEHOLDER] owner to complete" ] } ], "gates": [ { "id": "G1", "title": "No public claim before owner-action facts close", "passed": false, "checks": [ { "name": "Entity confirmed", "ok": false, "evidence": "Pending owner action" }, { "name": "Reviewer identity confirmed", "ok": false, "evidence": "Pending owner action" }, { "name": "Trademark clearance", "ok": false, "evidence": "Pending owner action" } ] } ], "contradiction_scan": [ { "id": "C1", "severity": "medium", "message": "Blueprint attributed Baldwin Group to Procore CORs; fresh sourcing shows Baldwin Group uses Ascend/ReSource Pro instead", "refs": [ "business-plan.md fresh-verification notes" ] } ], "rubric": { "categories": [ { "category": "domain_modeling", "score": 4, "min": 3, "passed": true }, { "category": "ai_governance", "score": 4, "min": 3, "passed": true }, { "category": "compliance_boundary", "score": 4, "min": 3, "passed": true }, { "category": "unit_economics", "score": 4, "min": 3, "passed": true }, { "category": "gtm_clarity", "score": 4, "min": 3, "passed": true } ], "pass": true, "average": 4.1 }, "foundry_package": { "version": "1.0.0", "checksum": "n/a-generated-locally", "counts": { "subdomains": 4, "bounded_contexts": 4, "aggregates": 7, "events": 6, "commands": 6, "policies": 4, "ai_agents": 4, "invariants": 4, "integrations": 4, "adrs": 2 }, "subset": { "subdomains": [ "Completeness & Matching", "Delivery", "Evidence & Compliance", "Referral & Outreach" ], "bounded_contexts": [ "Intake & Normalization", "Completeness & Matching", "Delivery", "Quality Assurance" ], "aggregates": [ "CORReadyAggregate", "SectionAggregate", "ComplianceMatrixAggregate", "PackAggregate", "ChaseItemAggregate", "AttestationAggregate", "Cover narrativeAggregate" ], "events": [ "T&M ticket.received", "T&M ticket.normalized", "pack_cycle.crosswalk_completed", "Gap.reviewer_approved", "COR_Pack.signed", "manufacturer_chase email.sent" ], "commands": [ "ReceiveCORReady", "NormalizeCORReady", "RunMatching", "ApproveGap", "SignPack", "SendChaseItem" ], "policies": [ "Auto-route low-confidence match to reviewer", "Block demand-language patterns", "Second-reviewer spot check", "Auto-escalate aging chase email" ], "ai_agents": [ "Extraction Agent", "Matching Agent", "Gap Drafter Agent", "ChaseItem Drafter Agent" ], "invariants": [ "A COR Pack cannot be signed without tying to T&M ticket totals to the penny", "A ChaseItem cannot be sent without reviewer approval and Subcontractor authorization on file", "No Gap is published without a cited source-T&M ticket and Spec-requirement reference", "CORReady Clear never issues a coverage or claims-adjustment determination" ], "integrations": [ "Subcontractor management system (spec) export", "T&M ticket portals", "QuickBooks / spec posting-file import", "Manufacturer COR-department mailbox" ], "adrs": [ "ADR-001", "ADR-002" ] } } } }, "ddd_coverage": { "slug": "specialty-trade-cor-tm-completeness-desk", "total": 17, "passed": 17, "pct": 100, "checks": [ { "key": "actors", "label": "Actors", "count": 4, "min": 3, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "subdomains", "label": "Subdomains", "count": 4, "min": 3, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "bounded_contexts", "label": "Bounded Contexts", "count": 4, "min": 3, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "aggregates", "label": "Aggregates", "count": 7, "min": 3, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "events", "label": "Events", "count": 6, "min": 3, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "commands", "label": "Commands", "count": 6, "min": 3, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "policies", "label": "Policies", "count": 4, "min": 2, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "ai_agents", "label": "Ai Agents", "count": 4, "min": 3, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "invariants", "label": "Invariants", "count": 4, "min": 3, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "use_cases", "label": "Use Cases", "count": 2, "min": 2, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "human_roles", "label": "Human Roles", "count": 3, "min": 3, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "data_objects", "label": "Data Objects", "count": 3, "min": 3, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "risk_register", "label": "Risk Register", "count": 3, "min": 3, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "adrs", "label": "Adrs", "count": 2, "min": 2, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "mvp_roadmap", "label": "Mvp Roadmap", "count": 1, "min": 1, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "scaling_roadmap", "label": "Scaling Roadmap", "count": 2, "min": 2, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "context_map", "label": "Context Map", "count": 4, "min": 2, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." } ], "failingGates": [] }, "architecture": { "slug": "specialty-trade-cor-tm-completeness-desk", "archetypes": [ "Completeness-and-Resubmittal workflow application", "back-office document-intelligence service" ], "archetype_impact": "Completeness cycle (client + calendar month) is the global scoping parameter — every read/write is scoped by Subcontractor tenant and cycle, not just tenant alone.", "personality": [ "numerate", "calm", "evidence-first", "no hype" ], "forces_ranked": [ { "force": "Trust/accuracy (source-page completeness)", "why": "A wrong Pack is the single fastest way to lose a client" }, { "force": "Founder-operability (low ops burden)", "why": "Founder-operated launch cannot support a platform team" }, { "force": "Time-to-first-revenue", "why": "Pilot cohort must convert within 90 days to validate the model" }, { "force": "Scalability beyond pilot", "why": "Lowest priority at launch; revisit at 20+ clients" } ], "tradeoffs": [ "Modular monolith trades some future scaling ease for launch speed and audit simplicity", "Manual manufacturer follow-up at launch trades automation for learning real response patterns first" ], "quality_scenarios": [ { "attribute": "accuracy", "assumption": "Every T&M ticket line traces to its source", "target": "Pack source-page check to the penny before signature, 100% of releases" }, { "attribute": "reviewability", "assumption": "A reviewer can reconstruct any evidence chain quickly", "target": "Under 5 minutes to trace any Pack line to its source T&M ticket" } ], "options": [ { "style": "Modular monolith", "complexity": "low", "cost": "low", "ops_burden": "low", "team_fit": "high (founder-operated)", "scaling_path": "Extract modules under pressure", "security_impact": "Single audit boundary", "fits_here": true, "fits_when": "Founder/small-team launch", "wrong_here": false, "recommended": true }, { "style": "Microservices per bounded context", "complexity": "high", "cost": "high", "ops_burden": "high", "team_fit": "low at launch", "scaling_path": "Already decomposed", "security_impact": "More boundaries to secure", "fits_here": false, "fits_when": "Large team, proven scale pressure", "wrong_here": true, "recommended": false }, { "style": "No-code workflow tool", "complexity": "low", "cost": "low", "ops_burden": "low", "team_fit": "medium", "scaling_path": "Poor — hard to enforce deterministic gates", "security_impact": "Vendor-dependent", "fits_here": false, "fits_when": "No hard money-math invariant", "wrong_here": true, "recommended": false } ], "chosen_style": "modular monolith", "chosen_rationale": "Modular monolith with background jobs for bursty T&M ticket-extraction work — one audit boundary, low ops burden, easy per-context ownership as the team grows.", "rejected": [ { "style": "Microservices per bounded context", "why_rejected": "Premature operational complexity for a founder-operated launch" }, { "style": "No-code workflow tool", "why_rejected": "Cannot reliably enforce the deterministic source-page-complete gate" } ], "target": { "overview": "Single-region modular monolith, Postgres primary store, background job queue for extraction/matching, internal reviewer console, public marketing microsite.", "frontend": "Reviewer console (internal, authenticated) + public marketing microsite (static, self-contained)", "backend": "Single deployable service, module boundaries enforced by code convention and event-only cross-module calls", "data": "Postgres with row-level tenant security; object storage for T&M ticket files", "api": "Internal authenticated API for the reviewer console; no public API at launch", "authn_authz": "SSO + MFA for reviewers; row-level auth scaffolding for a future client portal", "integrations": "Spec section file ingestion; T&M ticket mailbox/portal; QuickBooks/spec posting-file export", "background_jobs": "CORReady extraction, matching, aging-escalation checks", "object_storage": "Encrypted, per-Subcontractor-prefix isolated", "notifications": "Email only at launch (client comms + internal escalation alerts)", "search": "None at launch", "analytics": "Internal metrics dashboard only; no third-party analytics on the reviewer console", "ai": "Single frontier-model provider via a scripted extraction/matching/drafting pipeline, prompts + fixtures versioned in-repo", "observability": "Structured logs, RED metrics, model-call cost/latency spans", "deployment": "Single production region, multi-AZ, preview environment per PR", "security": "Row-level tenant isolation, encryption at rest/in transit, least-privilege access", "dr": "Daily backups, tested restore runbook, RPO 24h / RTO 4h at launch scale" }, "modules": [ { "name": "intake-normalization", "purpose": "CORReady receipt, extraction, and source-page check.", "owned_domain": [ "CORReady" ], "application_services": [ "ReceiveCORReady", "NormalizeCORReady" ], "infra_adapters": [ "Mailbox listener", "Object storage adapter", "Extraction-model client" ], "public_interfaces": [ "T&M ticket.normalized event" ], "forbidden_deps": [ "Cannot call Completeness-matching internals directly — event only" ], "responsibility": "CORReady receipt, extraction, and source-page check.", "owned_data": [ "CORReady" ], "events_produced": [ "T&M ticket.normalized event" ], "events_consumed": [], "interfaces": [ "T&M ticket.normalized event" ], "depends_on": [], "entities": [ "CORReady" ], "failure_risks": [ "Module-boundary violation via direct DB access" ], "scaling": "Extract to a service only under sustained isolated load pressure", "future_split_trigger": "Sustained CPU/latency pressure isolated to this module" }, { "name": "Completeness-matching", "purpose": "Matching, Gap classification, Pack source-page check.", "owned_domain": [ "Section", "ComplianceMatrix", "Pack" ], "application_services": [ "RunMatching", "ApproveGap", "SignPack" ], "infra_adapters": [ "spec-export parser", "COR-schedule store" ], "public_interfaces": [ "Gap.reviewer_approved event", "COR_Pack.signed event" ], "forbidden_deps": [ "Cannot call Resubmittal-delivery internals directly — event only" ], "responsibility": "Matching, Gap classification, Pack source-page check.", "owned_data": [ "Section", "ComplianceMatrix", "Pack" ], "events_produced": [ "Gap.reviewer_approved event", "COR_Pack.signed event" ], "events_consumed": [], "interfaces": [ "Gap.reviewer_approved event", "COR_Pack.signed event" ], "depends_on": [], "entities": [ "Section", "ComplianceMatrix", "Pack" ], "failure_risks": [ "Module-boundary violation via direct DB access" ], "scaling": "Extract to a service only under sustained isolated load pressure", "future_split_trigger": "Sustained CPU/latency pressure isolated to this module" }, { "name": "Resubmittal-delivery", "purpose": "Vendor-chase drafting/sending, aging, pack assembly.", "owned_domain": [ "ChaseItem", "AECommentRecord", "MonthlyCompletenessPack" ], "application_services": [ "SendChaseItem", "AssemblePack", "DeliverPack" ], "infra_adapters": [ "Email-send adapter", "Posting-file generator" ], "public_interfaces": [ "pack.delivered event" ], "forbidden_deps": [ "Cannot bypass quality-assurance signoff gate" ], "responsibility": "Vendor-chase drafting/sending, aging, pack assembly.", "owned_data": [ "ChaseItem", "AECommentRecord", "MonthlyCompletenessPack" ], "events_produced": [ "pack.delivered event" ], "events_consumed": [], "interfaces": [ "pack.delivered event" ], "depends_on": [], "entities": [ "ChaseItem", "AECommentRecord", "MonthlyCompletenessPack" ], "failure_risks": [ "Module-boundary violation via direct DB access" ], "scaling": "Extract to a service only under sustained isolated load pressure", "future_split_trigger": "Sustained CPU/latency pressure isolated to this module" }, { "name": "quality-assurance", "purpose": "Signoff and cover narrative lifecycle.", "owned_domain": [ "Signoff", "Cover narrative" ], "application_services": [ "ApproveArtifact", "RetractArtifact" ], "infra_adapters": [ "Signature-binding session store" ], "public_interfaces": [ "ArtifactSigned event" ], "forbidden_deps": [ "Cannot draft on behalf of any other module" ], "responsibility": "Signoff and cover narrative lifecycle.", "owned_data": [ "Signoff", "Cover narrative" ], "events_produced": [ "ArtifactSigned event" ], "events_consumed": [], "interfaces": [ "ArtifactSigned event" ], "depends_on": [], "entities": [ "Signoff", "Cover narrative" ], "failure_risks": [ "Module-boundary violation via direct DB access" ], "scaling": "Extract to a service only under sustained isolated load pressure", "future_split_trigger": "Sustained CPU/latency pressure isolated to this module" } ], "data_architecture": { "primary_db": "Postgres", "secondary": [ "Object storage for T&M ticket files" ], "cache": "None at launch", "search": "None at launch", "vector": "None at launch (retrieval is structured lookup, not embeddings, at this scale)", "object_storage": "Per-Subcontractor-prefix isolated bucket", "schema_strategy": "Migration-gated, reviewed per PR", "migrations": "Forward-only, reviewed", "backups": "Daily automated, tested restore quarterly", "retention": "7 years on signed Packs/chase lists; 13 months on agent-run logs", "audit_logs": "Append-only, hash-chained per pack cycle", "soft_delete": "Used for client offboarding, hard-delete on retention expiry", "privacy": "Per-tenant row-level security", "encryption": "At rest and in transit", "multi_tenancy": "Logical isolation via tenant_id row-level security" }, "api": { "style": "Internal REST", "public_vs_internal": "Internal only at launch", "versioning": "Path-versioned when a client portal ships", "rate_limiting": "Per-tenant budget caps on model-backed endpoints", "idempotency": "Idempotency keys on T&M ticket ingestion", "pagination": "Cursor-based on list endpoints", "error_format": "Structured JSON problem-details", "webhook_security": "N/A at launch", "retries": "Exponential backoff on model-provider calls", "contract_testing": "Per-section parser schema contract tests in CI", "backward_compat": "N/A at launch (no public API)", "contract_testing_plan": "Fixture-based regression suite run on every parser/prompt change" }, "security": { "authn": "SSO + MFA for reviewers", "authz": "Role-based, server-side capability checks", "tenant_isolation": "Row-level security keyed on tenant_id", "secrets": "Managed secrets store, no secrets in code", "encryption": "At rest and in transit", "session": "Server-side session with short-lived tokens", "input_validation": "Schema validation on every ingestion path", "api_protection": "Rate limiting + auth on all internal endpoints", "audit_log": "Append-only, hash-chained", "admin_access": "Break-glass access logged and time-boxed", "supply_chain": "Dependency scanning in CI", "threat_model": [ "Cross-tenant leak", "Reviewer identity spoofing", "Prompt injection via uploaded T&M tickets" ], "abuse_cases": [ "Bulk fraudulent T&M ticket upload attempting to poison the matching engine" ], "zero_trust": "Server-side checks on every capability, never client-only", "asvs_notes": "Aligned to OWASP ASVS L2 controls for a B2B financial-data service" }, "reliability": { "failure_modes": [ "Model-provider outage mid-extraction", "Manufacturer portal credential expiry", "CORReady queue backlog at month-end" ], "graceful_degradation": "Queue and retry rather than fail hard; reviewer notified of delayed cycles", "retry_policy": "Exponential backoff, max 5 attempts on model calls", "timeouts": "30s extraction timeout, background-job fallback beyond that", "circuit_breaker": "Trip on repeated model-provider failures, alert on-call", "queueing": "Background job queue for extraction/matching", "idempotency": "Idempotency keys on T&M ticket ingestion", "dlq": "Dead-letter queue for repeatedly failing extraction jobs", "transactions": "Aggregate-scoped transactions, no cross-aggregate transactions", "dr": "Daily backups, quarterly restore test", "incident_response": "Runbook: detect, contain, notify, root-cause, postmortem", "slos": [ { "name": "p95 T&M ticket extraction latency", "target": "under 30s" }, { "name": "Monthly pack on-time delivery", "target": "≥95% of cycles by the 5th business day" } ] }, "scaling": { "mvp_can_stay_simple": [ "Single Postgres instance", "In-process event dispatch" ], "modular_now": [ "Module boundaries enforced by convention" ], "deferrable": [ "Client-facing portal", "Public API", "Vector search" ], "breaks_first": "Reviewer throughput before infrastructure", "db_path": "Read replicas once reporting load grows", "jobs_path": "Managed queue once in-process dispatch saturates", "cache_path": "Add a cache layer only if read latency becomes a measured problem", "search_path": "Add full-text search only if client-portal search becomes a real need", "files_path": "Object storage scales natively", "api_path": "Add a versioned public API only when a client portal ships", "multi_region": "Not needed at this scale", "cost_control": "Per-tenant model-spend budget caps" }, "ai": { "provider": "Single frontier-model provider (model-agnostic schemas/prompts, swappable within days)", "prompt_mgmt": "Versioned in-repo, immutable once published", "rag": "Structured per-Subcontractor + per-section retrieval, not embeddings-based at this scale", "vector": "Not used at this scale", "embeddings": "Not used at this scale", "eval": "Fixture-based regression suite per manufacturer", "hitl": "Reviewer gate on every Gap and vendor chase email", "guardrails": "Deterministic output filters + structured validation", "prompt_injection": "Uploaded T&M ticket content treated as untrusted data, never instructions", "leakage": "Per-tenant retrieval partitioning", "fallback": "Dual-provider fallback path documented, not yet implemented at pilot scale", "latency_cost": "Tracked per AgentRun", "memory": "Session-scoped only, no persistent cross-client memory", "tool_permissions": "Extraction/matching/drafting agents have read-only access to their own context's data", "auditability": "Every AgentRun logged with prompt version + validator verdict", "citation": "Every Gap and eligibility-adjacent claim must cite a source" }, "devops": { "environments": [ "local", "preview (per-PR)", "staging", "production (single region + multi-AZ)" ], "cicd": "PR -> typecheck + unit + snapshot -> preview deploy -> main auto-deploys", "iac": "Declarative infra config checked into the repo", "secrets": "Managed secrets store", "preview_envs": "Per-PR ephemeral environments", "migrations": "Reviewed, forward-only", "rollback": "Blue/green deploy with fast rollback", "release_style": "Continuous deployment on main, feature-flagged risky changes", "feature_flags": "Used for prompt-version rollouts", "monitoring": "Structured logs + RED metrics", "alerting": "On-call paged on SLO breach", "logs": "Structured, tenant-scoped, PII-scrubbed", "error_tracking": "Source-mapped error tracking", "uptime": "Target 99.5% at pilot scale", "cost_monitoring": "Per-tenant model-spend dashboard" }, "testing": { "unit": "Source-page check math and materiality thresholds", "integration": "Cross-module event contracts", "contract": "Per-section parser schema", "e2e": "Intake to delivery smoke test", "security": "Row-level isolation tests", "a11y": "axe-core on reviewer surfaces", "load": "Month-end volume simulation", "chaos": "Model-provider outage simulation", "migration": "Forward-only migration dry-run in CI", "backup_restore": "Quarterly restore drill", "ai_eval": "Fixture-based regression suite per manufacturer", "test_data": "Anonymized gold-standard T&M ticket fixtures" }, "observability": { "logs": "Structured, tenant-scoped, PII-scrubbed", "metrics": "RED metrics per workflow", "traces": "Model-call spans with cost + latency", "audit_events": "Append-only, hash-chained per cycle", "business_events": "scan_requested, pack_delivered, Gap_approved", "error_tracking": "Source-mapped error tracking", "security_monitoring": "Cross-tenant access-attempt alerting", "cost_monitoring": "Per-tenant model-spend dashboard", "dashboards": [ "Ops dashboard", "Economics dashboard" ], "alert_thresholds": [ "Auto-match rate <80%", "Reviewer minutes >180/cycle" ], "triage": "On-call reviews alert, checks tenant scope, escalates per runbook" }, "cost": { "drivers": [ { "name": "Model inference per T&M ticket", "note": "Scales with T&M ticket volume, falls per-T&M ticket as parser coverage grows" }, { "name": "Reviewer labor minutes", "note": "Falls with auto-match rate improvement" }, { "name": "Object storage", "note": "Linear with client count, low absolute cost" } ], "likely_traps": [ "Over-provisioning background workers before real volume data exists" ], "controls": [ "Per-tenant budget caps", "Monthly cost-per-client dashboard review" ] }, "multi_tenancy": { "model": "Shared infrastructure, logical isolation", "isolation": "Row-level security keyed on tenant_id", "tenant_aware_authz": "Every capability check includes tenant_id", "tenant_config": "Per-Subcontractor section list and COR-schedule config", "branding": "N/A at launch (internal-only console)", "tenant_export": "Full-cycle export available on request", "tenant_deletion": "Soft-delete then hard-delete on retention expiry", "tenant_audit": "Per-tenant audit log export", "noisy_neighbor": "Per-tenant concurrency and budget caps", "tenant_rate_limits": "Per-tenant model-call budget", "billing": "Stripe, flat monthly + one-time scan fee", "why_this_fits": "Small client count at launch makes logical isolation sufficient; a hard single-tenant requirement would trigger a per-client deployment exception." }, "privacy_compliance": { "data_classification": "Financial/PII tiers documented in product.security.data_classifications", "minimization": "Only fields needed for matching/Completeness retained", "consent": "Engagement letter + vendor-communication authorization", "access_logs": "Per-access logged with actor + timestamp", "audit_trails": "Append-only, hash-chained", "retention": "7 years on Packs/chase lists; 13 months on agent logs", "legal_hold": "Manual legal-hold flag overrides retention deletion", "right_to_delete": "Honored post-retention-window or on contract termination per engagement letter", "right_to_export": "Full-cycle export available on request", "sensitive_handling": "Confidential project-data handling program", "boundaries": "No Subcontractor activity; no fund custody; no tax/legal advice", "residency": "US-only at launch", "vendor_risk": "Single model-provider risk documented; dual-provider fallback on the roadmap", "breach_response": "Documented incident-response runbook", "admin_controls": "Break-glass access logged and time-boxed", "evidence_collection": "Audit-log export within 24 hours of a breach or dispute" }, "frontend": { "framework": "React (internal reviewer console)", "rendering": "Client-rendered SPA for the console; static self-contained HTML for the public microsite", "routing": "Client-side router for the console", "state": "Local + server-state cache", "server_state": "Fetched per reviewer session", "forms": "Native form elements with client + server validation", "error_handling": "Structured error boundaries", "components": "Design-token-driven component library", "design_system": "Semantic tokens per DESIGN-STANDARD.md", "auth_ui": "SSO redirect flow", "authz_aware_ui": "Capability-gated UI elements", "a11y": "WCAG 2.2 AA target", "i18n": "en-US only at launch", "performance": "Console not performance-critical (internal); microsite budget ≤120KB, no external requests", "bundling": "Standard bundler, code-split by module", "testing": "Component + e2e tests on reviewer surfaces", "offline": "Not supported at launch", "realtime": "Not needed at launch" }, "backend": { "framework": "Node/TypeScript service", "layering": "domain / application / infra per module", "domain": "Aggregates + value objects per bounded context", "services": "Application services orchestrate domain + infra", "repositories": "One repository per aggregate root", "validation": "Schema validation at every boundary", "authorization": "Server-side capability checks only", "jobs": "Background job queue for extraction/matching", "events": "In-process event dispatch at launch", "files": "Object storage adapter", "email_sms": "Email adapter for client comms and vendor chase emails", "scheduled": "Aging-escalation checks run daily", "errors": "Structured error types per layer", "logging": "Structured, tenant-scoped, PII-scrubbed", "config": "Environment-based config, no secrets in code", "di": "Constructor-based dependency injection", "testing": "Unit + contract + e2e per module" }, "diagrams": { "context_mermaid": "graph TD; Subcontractor-->Intake; Intake-->Completeness; Completeness-->Resubmittal; Resubmittal-->QA", "container_mermaid": "graph TD; Console-->API; API-->Postgres; API-->ObjectStorage; API-->ModelProvider", "data_flow_mermaid": "graph LR; CORReady-->Extraction-->Matching-->ComplianceMatrix-->Pack-->Pack", "auth_flow_mermaid": "graph LR; Reviewer-->SSO-->MFA-->Session", "authz_flow_mermaid": "graph LR; Request-->RoleCheck-->TenantCheck-->Allow", "deployment_mermaid": "graph TD; PR-->Preview-->Main-->Production", "background_job_mermaid": "graph LR; Queue-->Worker-->Retry-->DLQ", "event_flow_mermaid": "graph LR; CORReadyExtracted-->CrosswalkCompleted-->MatrixDrafted-->PackSigned", "failure_flow_mermaid": "graph LR; Failure-->Retry-->CircuitBreaker-->Alert", "multi_tenant_flow_mermaid": "graph LR; Request-->TenantContext-->RowLevelSecurity-->Data", "ai_flow_mermaid": "graph LR; CORReady-->ExtractionAgent-->MatchingAgent-->DrafterAgent-->Reviewer" }, "adrs": [ { "id": "ADR-001", "decision": "Adopt a modular monolith, not microservices, at launch", "status": "accepted", "context": "Founder-operated team; low ops burden required", "options": [ "Modular monolith", "Microservices per bounded context", "No-code workflow tool" ], "chosen": "Modular monolith", "business_reason": "Fastest path to first paid pilot without a platform team", "technical_reason": "One deploy, one audit boundary, easy to reason about at this scale", "tradeoffs": "Will need extraction into services if reviewer-console load grows sharply", "risks": [ "[PLACEHOLDER] owner to complete" ], "revisit_trigger": "Sustained CPU/latency pressure isolated to one module", "why": "One deploy, one audit boundary, easy to reason about at this scale", "consequences": [ "[PLACEHOLDER] owner to complete" ], "reversal": "Would require a migration of the affected module's data model.", "revisit_when": "Sustained CPU/latency pressure isolated to one module" }, { "id": "ADR-002", "decision": "Deterministic code owns all money math; the model never computes a final dollar figure", "status": "accepted", "context": "Source-page completeness is a hard trust requirement", "options": [ "Model computes totals", "Deterministic code computes totals, model only extracts/classifies" ], "chosen": "Deterministic code computes totals", "business_reason": "A wrong dollar figure from a model is the single fastest way to lose a client's trust", "technical_reason": "Removes an entire class of hallucination risk from the highest-stakes output", "tradeoffs": "Slightly more engineering work per new transaction-type edge case", "risks": "Edge cases not yet coded fall through to reviewer manual calculation", "revisit_trigger": "None — this is a standing invariant, not revisited", "why": "Removes an entire class of hallucination risk from the highest-stakes output", "consequences": "Slightly more engineering work per new transaction-type edge case", "reversal": "Would require a migration of the affected module's data model.", "revisit_when": "None — this is a standing invariant, not revisited" } ], "roadmap": [ { "phase": "Phase 0 — Discovery + pilot LOI", "weeks": "Weeks 1-2", "outcomes": [ "3-5 pilot Subcontractor LOIs", "Evidence pack from each pilot Subcontractor", "Written ICP + pricing hypothesis" ], "exit_criteria": [ "≥3 LOIs signed", "Owner-action Pack populated per Subcontractor", "Reviewer identity confirmed" ], "kill_criteria": [ "<2 LOIs after 2 weeks", "No willingness-to-pay signal above pilot price" ], "build": [ "3-5 pilot Subcontractor LOIs", "Evidence pack from each pilot Subcontractor", "Written ICP + pricing hypothesis" ], "defer": [], "monitor": [ "≥3 LOIs signed", "Owner-action Pack populated per Subcontractor", "Reviewer identity confirmed" ], "avoid": [ "<2 LOIs after 2 weeks", "No willingness-to-pay signal above pilot price" ], "acceptable_debt": [ "[PLACEHOLDER] owner to complete" ], "dangerous_debt": [ "[PLACEHOLDER] owner to complete" ], "triggers_to_change": [ "[PLACEHOLDER] owner to complete" ] }, { "phase": "Phase 1 — Thin vertical slice", "weeks": "Weeks 3-4", "outcomes": [ "Intake -> match -> reviewer signoff -> delivery working end-to-end for one spec format", "Audit trail wired", "Instrumentation live" ], "exit_criteria": [ "1 real Gap Scan delivered + reviewer-signed", "p95 workflow latency published" ], "kill_criteria": [ "Reviewer signoff cycle >10 business days", "Evidence bundle cannot be reconstructed on demand" ], "build": [ "Intake -> match -> reviewer signoff -> delivery working end-to-end for one spec format", "Audit trail wired", "Instrumentation live" ], "defer": [], "monitor": [ "1 real Gap Scan delivered + reviewer-signed", "p95 workflow latency published" ], "avoid": [ "Reviewer signoff cycle >10 business days", "Evidence bundle cannot be reconstructed on demand" ], "acceptable_debt": "Manual manufacturer follow-up and onboarding at pilot scale", "dangerous_debt": "Skipping the reviewer-signoff gate under volume pressure", "triggers_to_change": "Kill/pivot criteria met at any phase gate" }, { "phase": "Phase 2 — Pilot cohort", "weeks": "Weeks 3-8", "outcomes": [ "10 pilot Subcontractors scanned", "First standard-price desk conversion", "SOC 2 Type I scoping" ], "exit_criteria": [ "≥1 standard-price contract", "Post-scan debrief trust signal captured", "Postmortem cadence in place" ], "kill_criteria": [ "No standard-price conversion by Day 90", "Scan-to-desk conversion below 25%" ], "build": [ "10 pilot Subcontractors scanned", "First standard-price desk conversion", "SOC 2 Type I scoping" ], "defer": [], "monitor": [ "≥1 standard-price contract", "Post-scan debrief trust signal captured", "Postmortem cadence in place" ], "avoid": [ "No standard-price conversion by Day 90", "Scan-to-desk conversion below 25%" ], "acceptable_debt": "Manual manufacturer follow-up and onboarding at pilot scale", "dangerous_debt": "Skipping the reviewer-signoff gate under volume pressure", "triggers_to_change": "Kill/pivot criteria met at any phase gate" }, { "phase": "Phase 3 — Recurring-desk scale-up", "weeks": "Weeks 9-13 (Day 90 checkpoint)", "outcomes": [ "Public commercial launch of the microsite as 'ready'", "Rush rider and Diligence Source-page check line active", "Owner-action Pack closed for launch" ], "exit_criteria": [ "COGS/rework/cycle-time measured against target", "Expansion beyond the pilot cohort gated on targets, not calendar time" ], "kill_criteria": [ "Rework rate persistently above 3%", "Reviewer minutes per client not falling with volume" ], "build": [ "Public commercial launch of the microsite as 'ready'", "Rush rider and Diligence Source-page check line active", "Owner-action Pack closed for launch" ], "defer": [], "monitor": [ "COGS/rework/cycle-time measured against target", "Expansion beyond the pilot cohort gated on targets, not calendar time" ], "avoid": [ "Rework rate persistently above 3%", "Reviewer minutes per client not falling with volume" ], "acceptable_debt": "Manual manufacturer follow-up and onboarding at pilot scale", "dangerous_debt": "Skipping the reviewer-signoff gate under volume pressure", "triggers_to_change": "Kill/pivot criteria met at any phase gate" } ], "anti_overengineering": { "flagged": [ { "item": "Client-facing portal at launch", "why": "No client has asked for self-serve status; email/upload-link delivery is sufficient at pilot scale.", "simpler": "Defer to year 1, gated on client demand signal." }, { "item": "Vector search / embeddings", "why": "Data volume at launch doesn't justify it; structured retrieval suffices.", "simpler": "Structured per-Subcontractor and per-section lookup." }, { "item": "Microservices per bounded context", "why": "Premature operational complexity for a founder-operated launch.", "simpler": "Modular monolith with enforced module boundaries." } ] }, "risks": [ { "risk": "GC-portal vendor bundles Completeness 'free' with a chase workflow", "likelihood": "medium-high", "impact": "high", "mitigation": "Portal-agnostic positioning; resubmittal/chase as the human moat", "detection": "Autodesk Build (ACC) or a competing GC-portal module adds chase/Resubmittal features", "owner": "owner", "escalation": "Reviewer -> Senior Reviewer -> Owner -> Counsel", "fallback": "Portal-agnostic positioning; resubmittal/chase as the human moat", "category": "business" }, { "risk": "Scan-to-desk conversion underperforms", "likelihood": "medium", "impact": "severe", "mitigation": "Pilot gate at 25%; alternative packaging tested in cohort 2", "detection": "Pilot cohort conversion below 25%", "owner": "owner", "escalation": "Reviewer -> Senior Reviewer -> Owner -> Counsel", "fallback": "Pilot gate at 25%; alternative packaging tested in cohort 2", "category": "business" }, { "risk": "False-positive Gap sent to a manufacturer", "likelihood": "medium", "impact": "high", "mitigation": "100% reviewer approval; evidence-link requirement; chase email-not-demand language", "detection": "Manufacturer disputes an chase email as unfounded", "owner": "legal", "escalation": "Reviewer -> Senior Reviewer -> Owner -> Counsel", "fallback": "100% reviewer approval; evidence-link requirement; chase email-not-demand language", "category": "business" } ], "rules": [ "No cross-module database table sharing", "No model call computes final money math", "No public claim before owner-action facts close" ], "audit": { "product_fit": 4, "simplicity": 4, "security": 4, "reliability": 4, "scalability": 3, "maintainability": 4, "performance": 4, "cost": 4, "compliance": 3, "dx": 4, "ops_burden": 4, "extensibility": 4, "team_suitability": 4, "time_to_market": 4, "recommendation": { "verdict": "conditional-go", "stack": "Node/TypeScript + Postgres + single frontier-model provider", "style": "modular monolith", "database": "Postgres with row-level tenant security", "hosting": "Single-region, multi-AZ", "auth": "SSO + MFA for reviewers", "ai_approach": "Scripted extraction/matching/drafting pipeline with reviewer gates", "integrations": "Spec section ingestion, T&M ticket intake, QuickBooks/spec posting export", "build_first": [ "Intake & Normalization", "Completeness & Matching" ], "revisit_later": [ "Client-facing portal", "Public API" ], "avoid": [ "Microservices", "Vector search at this scale" ], "biggest_risks": [ "Reviewer bottleneck", "A vendor-facing claim proves incorrect" ], "top_10_rules": [ "No cross-module database table sharing", "No model call computes final money math", "No public claim before owner-action facts close", "Deterministic code owns all money math", "Reviewer gate on every client- or vendor-facing output" ], "first_10_steps": [ "Confirm the named trade-specialist QA reviewer + engagement letter on file", "Populate owner-action Pack with entity, jurisdiction, contact inbox, privacy inbox", "Open pilot-cohort intake (cap 10) with explicit pricing conversation", "Write ICP + kill/pivot criteria in the plan file", "Stand up the evidence-linked intake -> match -> reviewer signoff loop", "Wire append-only audit log + hash-chained snapshots", "Add row-level auth + tenant-scoped retrieval indices", "Instrument scan-request, pack-delivery, and reviewer-signoff events", "Publish the microsite with FAQPage schema only and noindex until owner-facts close", "Schedule the Day-90 kill/pivot review with executive sponsor" ] } } }, "design": { "slug": "specialty-trade-cor-tm-completeness-desk", "archetypes": [ "Pack / Completeness Desk", "back-office trust interface" ], "user_mindset": { "goals": "Find out fast whether manufacturers are shipping incomplete T&M ticket data, without operating new software", "session_length": "Short, task-focused (scan intake, monthly pack review)", "confidence": "Numerate, skeptical of unproven claims — wants evidence, not a dashboard", "interface_needs": "Clear evidence chain from T&M ticket line to Pack to signature" }, "posture": [ "calm", "numerate", "institutional-but-warm" ], "density": "compact", "trust_level": { "tier": "high", "sensitive_domains": [ "Subcontractor financial data", "GC comment data" ], "implications": [ "Every dollar figure must show its source", "No fabricated proof; honest placeholder slots until real cycles ship" ] }, "differentiation": { "avoid": [ "Insurtech-startup gradient look", "Wheat/tractor-style vertical clip-art equivalents (generic finance-SaaS iconography)", "Alarm-red urgency banners" ], "strategy": "A spec-sheet aesthetic — deep teal/ink against warm parchment, serif numerals — that reads like a specialist's workbook, not a dashboard demo." }, "territories": [ { "name": "Pack Desk", "color_mood": "deep teal + warm parchment + amber accent", "typography": "Serif numerals, sans body", "density": "compact", "component_feel": "workbook-like, artifact-shaped cards", "motion": "minimal, calm", "fits": "Completeness/back-office trust interfaces", "risks": "Could read as too formal for a younger buyer persona (not a concern here — buyer is an subcontractor principal)" }, { "name": "Filing Desk", "color_mood": "similar palette family used elsewhere in the portfolio", "typography": "Serif display", "density": "compact", "component_feel": "filing-tab metaphor", "motion": "minimal", "fits": "Deadline-driven filing businesses", "risks": "Wrong metaphor here — no single filing deadline exists in this business" }, { "name": "Completeness Console", "color_mood": "cooler blue-gray, more software-dashboard feeling", "typography": "Sans-only", "density": "dense", "component_feel": "dashboard-like", "motion": "minimal", "fits": "A future client-facing portal, not the launch microsite", "risks": "Reads too much like software the client has to operate — against the done-for-you positioning" } ], "chosen_territory": "Pack Desk", "chosen_rationale": "The COR Pack is the deliverable; the spec-desk metaphor keeps every screen artifact-shaped, the way a Subcontractor or acquirer would want to see it.", "prioritized_components": [ { "name": "Hero with cycle-status panel", "why": "Core to the conversion path from stat proof to pricing trust to CTA" }, { "name": "Stat strip (real, sourced figures)", "why": "Core to the conversion path from stat proof to pricing trust to CTA" }, { "name": "Deliverable cards", "why": "Core to the conversion path from stat proof to pricing trust to CTA" }, { "name": "Pricing tiers with guarantee callout", "why": "Core to the conversion path from stat proof to pricing trust to CTA" }, { "name": "Honest placeholder proof slots", "why": "Core to the conversion path from stat proof to pricing trust to CTA" }, { "name": "FAQ", "why": "Core to the conversion path from stat proof to pricing trust to CTA" } ], "tokens": { "brand": "191 74% 23%", "brand-fg": "40 31% 94%", "surface": "0 0% 100%", "ink": "197 14% 10%", "muted": "195 10% 32%", "accent": "22 75% 41%" }, "type": { "display": "Iowan Old Style (system serif stack)", "body": "system-ui", "fonts_url": "" }, "signature": { "motif": "An unlinked exhibit page resolving into a linked T&M ticket with a source-cited evidence-matrix row", "render": "CSS-only shapes/borders, no imagery (120KB budget)" }, "patterns": [ { "name": "Card-based deliverable grid", "description": "See site/index.html implementation" }, { "name": "Stepped how-it-works numerals", "description": "See site/index.html implementation" }, { "name": "Dashed placeholder proof slots", "description": "See site/index.html implementation" } ], "states": [ "matched (state-ok)", "at-risk/rejected (state-risk)", "pending manufacturer response (state-pending)", "blocked/needs input (state-blocked)" ], "uniqueness_audit": { "app_specific_decisions": [ "Pack-teal + amber palette distinct from the portfolio's other palettes", "CORReady-to-Pack visual motif specific to this business's workflow" ], "cliches_avoided": [ "No generic insurtech gradient hero", "No stock handshake/office imagery" ], "scale_notes": "Palette and motif chosen to be visually distinct from sibling businesses in the same multi-tenant site." }, "localization": [ "en-US only at launch" ] }, "seo": { "slug": "specialty-trade-cor-tm-completeness-desk", "archetype": "outcome-priced back-office authority site", "archetype_impact": "Search fit is a back-office trust authority site, not a filing-deadline authority site. That means depth on manufacturer-format and Gap-classification specifics, evergreen (not deadline-driven) content cadence.", "authority_dna": { "site_archetype": "outcome-priced back-office authority site", "monetization_model": "B2B lead -> Gap Scan -> paid Completeness Desk engagement (not ad revenue; not affiliate).", "main_search_intents": [ "informational", "commercial" ], "topical_authority_opportunity": "Own the \"Construction COR completeness\" topic cluster by covering direct-bill T&M ticket formats, spec-quirk patterns, Gap classification, and GC-comment disputes better than any single trade-press explainer.", "local_seo_opportunity": "Not justified: buyers search by problem/GC portal, not by city.", "global_national_opportunity": "National (US-first); state Construction regulation varies but the core service is not state-gated.", "easiest_ranking_path": "Long-tail, manufacturer-specific and spec-specific queries (\"Procore Change Events direct bill Completeness\", \"why is my T&M ticket short\") where the SERP is dominated by vendor blog posts, not buyer-first guides.", "hardest_ranking_path": "Head terms like \"Construction COR software\" — dominated by aged SaaS vendor domains (Procore, Clearstory, Core CORs).", "trust_credibility_requirements": [ "Named human reviewer with role + credentials", "Manufacturer/T&M ticket citations on every claim", "Last-reviewed date on regulatory/compliance pages", "Direct links to primary trade-press sources, not aggregators" ], "ymyl": true, "expert_review_needed": true, "site_structure": "Authority hub + narrow high-intent service page + linkable evidence assets. Not a directory. Not a marketplace.", "seo_moat": "Always-current per-spec and per-section how-to pages with real anonymized teardown evidence, refreshed as the parser library grows." }, "search_market": { "primary_markets": [ "Construction COR completeness service", "direct bill COR Resubmittal", "Gap Scan" ], "secondary_markets": [ "GC comment dispute resolution", "Subcontractor M&A COR diligence", "spec COR completeness how-to" ], "low_competition_subtopics": [ "manufacturer-specific T&M ticket quirks", "as-earned vs annualized missing-docs risk", "Procore Change Events/Clearstory direct bill Completeness how-to" ], "high_commercial_intent": [ "done-for-you COR completeness service", "outsource Construction COR completeness", "COR Resubmittal service for Construction Subcontractors" ], "informational": [ "what is direct bill COR completeness", "how to complete Construction COR T&M tickets", "why is my T&M ticket short" ], "local_intent": [], "transactional": [ "Gap Scan pricing", "book a COR completeness consultation" ], "comparison": [ "COR completeness service vs software", "CORReady Clear vs Procore CORs vs ReSource Pro" ], "problem_solution": [ "manufacturer rejected my COR what to do", "GC comment dispute resolution" ], "near_me": [], "long_tail": [ "Procore Change Events direct bill COR completeness", "as-earned COR resubmittal explained", "Procore COR completeness how-to" ], "questions": [ "what records does a COR completeness need?", "who reviews a Gap Scan?", "how long does COR completeness take?" ], "emerging": [ "AI-assisted T&M ticket extraction", "automated vendor chase email drafting" ], "seasonal": [ "tax-season spec set cleanup", "Subcontractor M&A diligence season COR verification" ], "underserved_serps": [ "manufacturer-specific T&M ticket quirks", "GC comment dispute resolution" ], "weak_serps": [ "COR completeness self-check", "COR completeness checklist" ], "forum_dominated_serps": [ "why is my T&M ticket short", "manufacturer resubmittal explained" ], "winnable_authoritative_serps": [ "direct bill COR completeness definitive guide", "Gap Scan evidence requirements" ], "avoid_initially": [ "Construction COR software", "best COR tracking tools" ], "easy_wins": [ "manufacturer-specific T&M ticket quirks", "COR completeness checklist", "GC comment dispute anatomy" ], "moderate": [ "direct bill COR completeness definitive guide", "Subcontractor M&A COR diligence" ], "long_term_plays": [ "Construction COR software comparison", "portfolio-level multi-Subcontractor Completeness" ], "do_not_pursue": [ "generic \"how to start a bookkeeping business\" content", "celebrity or trend-jacking posts", "AI-generated listicles" ] }, "keyword_clusters": [ { "primary": "direct bill COR completeness service", "related": [ "done-for-you COR completeness", "outsource COR completeness" ], "intent": "commercial", "user_problem": "Subcontractor suspects manufacturer rejection and needs a done-for-you fix", "funnel": "BOFU", "business_value": "high", "ranking_difficulty": "medium", "conversion_potential": "high", "content_effort": "medium", "serp_weakness": "Dominated by enterprise SaaS vendor pages, not small-Subcontractor-focused content", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Pillar / service page", "reason": "High buyer intent + weak SERP for our segment", "priority_score": 17, "priority": "P0", "bucket": "easy-win" }, { "primary": "Gap Scan", "related": [ "COR completeness self-check", "how much COR am I missing" ], "intent": "commercial", "user_problem": "Wants a low-commitment diagnostic before a full engagement", "funnel": "TOFU", "business_value": "high", "ranking_difficulty": "low", "conversion_potential": "high", "content_effort": "low", "serp_weakness": "No existing competitor owns this exact term", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Lead-magnet / calculator page", "reason": "Own a branded-term wedge outright", "priority_score": 16, "priority": "P0", "bucket": "easy-win" }, { "primary": "why is my Construction T&M ticket short", "related": [ "manufacturer rejected COR", "GC comment dispute" ], "intent": "informational", "user_problem": "Immediate confusion moment after a light manufacturer T&M ticket", "funnel": "TOFU", "business_value": "medium", "ranking_difficulty": "low", "conversion_potential": "medium", "content_effort": "low", "serp_weakness": "Forum-dominated, thin", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "How-to / FAQ page", "reason": "Easy win + strong lead-magnet fit", "priority_score": 14, "priority": "P0", "bucket": "easy-win" } ], "topical_authority_map": { "core_topics": [ "Direct-bill COR completeness — definitive guide", "Spec-quirk & Gap classification library", "GC comment dispute resolution" ], "pillars": [ { "name": "Direct-bill COR completeness — definitive guide", "core_intent": "informational", "audience": "Subcontractor principals and ops managers", "conversion_goal": "Self-check / scan request", "supporting_pages": [ "What a resubmittal should look like on your Pack", "As-earned vs annualized missing-docs risk", "T&M ticket formats explained" ], "internal_links": [ "/", "/resources/self-check" ], "schema": [ "Article", "BreadcrumbList", "FAQPage (where genuine)" ], "evidence_needed": [ "Named reviewer", "Primary-source citations", "Worked example" ], "local_variants": [], "national_variants": [ "US-national (default)" ] }, { "name": "Gap Scan evidence & trust", "core_intent": "commercial", "audience": "Subcontractor principals", "conversion_goal": "Book a scan", "supporting_pages": [ "Anatomy of a Gap Scan", "One manufacturer, 12 months, $X missing" ], "internal_links": [ "/#diagnostic", "/resources/evidence" ], "schema": [ "Article", "FAQPage", "BreadcrumbList" ], "evidence_needed": [ "Worked evidence artifact", "Reviewer credential" ], "local_variants": [], "national_variants": [ "US-national" ] } ], "supporting_page_types": [ "definition / glossary", "how-to workflow", "edge-case handling", "worked example", "FAQ", "comparison (only when honest)", "evidence artifact / template" ] }, "site_architecture": { "homepage_strategy": "Single-page conversion-focused microsite; deep content lives in a future /resources hub", "main_nav": [ "Pricing", "FAQ", "Operating blueprint" ], "footer_nav": [ "Compliance", "Operating blueprint" ], "hubs": [ { "name": "Resources hub", "purpose": "House long-form authority content", "url": "/resources (future)" } ], "url_patterns": [ "/specialty-trade-cor-tm-completeness-desk/" ], "avoid_url_patterns": [ "Thin per-section programmatic pages with no unique evidence" ] }, "global_national": { "national_clusters": [ "Direct-bill COR completeness" ], "linkable_assets": [ "COR completeness self-check calculator" ], "original_research_ideas": [ "Aggregate pilot-cohort missing-docs risk statistics once cohort completes" ], "international_needed": false, "international_notes": "US-only specialty-trade subcontracting regulation; no international expansion in scope" }, "local_seo": { "justified": false, "reason": "Buyers search by problem/GC portal, not location", "gbp_categories_primary": [], "gbp_categories_secondary": [], "location_page_rules": [], "citations": [], "review_strategy": "No fabricated reviews; real testimonials only after pilot cohort completes with permission", "local_schema": [] }, "programmatic": { "recommended": false, "reason": "No large structured dataset justifies programmatic pages at launch", "rules": [], "per_page_requirements": [], "quality_gates": [] }, "page_templates": [ { "page_type": "Pillar/service page", "purpose": "Convert a qualified visitor into a scan request", "target_intent": "commercial", "url_pattern": "/specialty-trade-cor-tm-completeness-desk/", "title_pattern": "{Brand} — {outcome} for {audience}", "meta_description_pattern": "{Brand} for {audience}. {outcome} — {price/SLA}.", "h1_pattern": "{Outcome-led headline}", "outline": [ "Hero", "Stat strip", "Pain", "Deliverables", "How it works", "Pricing", "Proof", "FAQ", "Compliance" ], "above_the_fold": [ "[PLACEHOLDER] owner to complete" ], "internal_links": [ "Operating blueprint dossier" ], "schema": [ "FAQPage", "Service" ], "cta_strategy": "Single primary CTA (scan request), secondary deep-links only", "conversion_elements": [ "Guarantee beside pricing", "Honest placeholder proof" ], "trust_elements": [ "Compliance section", "Named reviewer (pending owner action)" ], "faq_opportunities": [ "Objection-derived FAQ" ], "media": [ "[PLACEHOLDER] owner to complete" ], "quality_requirements": [ "No banned phrases", "Contrast-checked palette" ], "anti_thin_rules": [ "Every claim sourced or explicitly placeholdered" ] } ], "on_page_rules": { "title_tag": "Primary keyword + brand, under 60 chars", "meta_description": "Under 155 chars, states the outcome", "headings": "One H1, ordered H2/H3", "intro": "Answer the query in the first 2 sentences", "snippet_targeting": "Direct-answer paragraphs above the fold", "tables_lists": "Used for pricing and comparison content only", "images": "None required at launch (text-first authority content)", "internal_links": "Link every supporting page back to the pillar", "external_citations": "Link primary trade-press/vendor sources by name", "author_attribution": "Named reviewer bio on YMYL pages", "freshness": "Quarterly re-verification of dollar figures and vendor claims", "cta_placement": "End of every page + inline after the core answer", "mobile": "Mobile-first responsive layout", "avoid": [ "Keyword stuffing", "Thin AI-generated filler" ] }, "entity_seo": { "main_entities": [ "CORReady Clear", "Completeness Desk", "Gap Scan" ], "related_entities": [ "Procore CORs", "ReSource Pro", "Autodesk Build (ACC)", "AgencyBloc" ], "people": [ "Named trade-specialist QA reviewer" ], "orgs": [ "AGC", "state Construction departments" ], "tools": [ "Clearstory", "Procore Change Events", "Procore", "QQCatalyst", "Procore" ], "regulations": [ "State engineering-practice statutes", "State collection-Subcontractor statutes" ], "problems": [ "COR rejection", "GC comment disputes" ], "solutions": [ "Completeness Desk", "Gap Scan" ], "processes": [ "Intake", "Matching", "Gap review", "Delivery" ], "alternatives": [ "Enterprise SaaS", "BPO services", "Specialist bookkeeping firms" ], "synonyms": [ "COR completeness", "direct-bill Completeness", "COR Resubmittal" ] }, "schema_strategy": [ { "type": "FAQPage", "where": "Homepage FAQ section", "required_fields": [ "mainEntity", "acceptedAnswer" ], "caution": "Only genuine, answered questions — no fabricated Q&A" }, { "type": "Service", "where": "Homepage, with a real-entity Organization provider", "required_fields": [ "provider", "areaServed", "serviceType" ], "caution": "No review/rating/aggregateRating" } ], "internal_linking": { "pillar_to_cluster": "Every pillar links to its supporting pages", "cluster_to_pillar": "Every supporting page links back to its pillar", "cluster_to_cluster": "Cross-linked where the buyer journey naturally continues", "service_to_location": "N/A (no location pages)", "faq_to_commercial": "FAQ answers link to the pricing section", "breadcrumbs": "Present on all supporting content pages", "anchor_text_rules": [ "Descriptive, not \"click here\"" ] }, "technical_seo": { "crawlability": "noindex at launch until owner-action facts close", "indexability": "Enabled post-launch review", "sitemaps": "Generated once indexable", "robots": "noindex,nofollow at launch", "canonicals": "Self-canonical", "pagination": "N/A", "faceted_nav": "N/A", "duplicate_control": "Single canonical URL per page", "redirects": "N/A at launch", "core_web_vitals": "LCP ≤2.5s, INP ≤200ms, CLS ≤0.1 budget enforced", "mobile": "Mobile-first responsive", "accessibility": "WCAG 2.2 AA", "js_seo": "Minimal JS, server-renderable content", "rendering": "Static self-contained HTML", "gsc_setup": "Pending owner action", "analytics_setup": "Pending owner action", "rank_tracking": "Pending owner action" }, "eeat": { "author_bios": "Named reviewer bio pending owner action", "expert_reviewers": "Named trade-specialist QA reviewer", "editorial_policy": "Facts cited to primary/trade-press sources; vendor-sponsored claims labeled", "fact_checking": "Quarterly re-verification cadence", "credentials": [ "Trade-specialist QA reviewer credentials — pending owner action" ], "citations": "Every load-bearing statistic cited by source name", "first_hand_proof": [ "Anonymized pilot-cohort teardowns once available" ], "update_cadence": "Quarterly", "monetization_disclosure": "Service pricing disclosed on the pricing section itself", "ymyl_notes": "Treated as YMYL due to financial-advice-adjacent content; no coverage/legal/tax advice given" }, "ai_search": { "principles": [ "Answer the exact question asked, directly and first", "Cite named sources, not vague claims" ], "tactics": [ "FAQ schema on genuine FAQs", "Definitive per-topic guides answer engines can cite" ], "do_not": [ "Fabricate statistics", "Claim certifications not held" ] }, "conversion": { "primary_cta": "Start a free Gap Scan", "secondary_cta": "See what's in a pack", "lead_magnets": [ "15-Point change order documentation Rejection Checklist", "Spec-to-T&M ticket Crosswalk Template (MEP trades)" ], "trust_elements": [ "Guarantee + out-clause beside pricing", "Compliance section with licensing boundary" ], "per_page_paths": [ { "path": "Homepage -> scan request", "page_type": "pillar" } ], "tracking": "data-event taxonomy per DESIGN-STANDARD §4" }, "link_earning": { "digital_pr_ideas": [ "Aggregate anonymized pilot-cohort missing-docs risk statistics as original research" ], "original_research": [ "Average missing-docs risk by trade/section mix (post-pilot)" ], "directories": [ "State AGC/ABC association vendor resource pages" ], "expert_contributions": [ "Guest posts on Trade user-community blogs" ], "partnerships": [ "CPA/bookkeeper referral partners" ], "avoid": [ "Paid link schemes", "Low-quality directory submissions" ] }, "roadmap_90d": [ { "phase": "Launch", "goal": "Publish core microsite", "pages": [ "Homepage" ], "keywords_targeted": [ "direct bill COR completeness service" ], "required_assets": [ "Self-check lead magnet" ], "internal_links": [], "difficulty": "low", "business_value": "high", "conversion_goal": "Scan requests", "why_first": "Foundation for every other page" } ], "roadmap_12m": [ { "phase": "Authority hub", "goal": "Build /resources content cluster", "pages": [ "Definitive guide", "Per-spec how-tos" ], "keywords_targeted": [ "manufacturer-specific T&M ticket quirks" ], "required_assets": [ "Anonymized pilot-cohort statistics" ], "internal_links": [ "Homepage" ], "difficulty": "medium", "business_value": "medium", "conversion_goal": "Organic scan requests", "why_first": "Compounding organic channel per the GTM kit" } ], "priority_pages": [ { "rank": 1, "page_title": "CORReady Clear homepage", "slug": "/specialty-trade-cor-tm-completeness-desk/", "page_type": "pillar/service", "primary_keyword": "direct bill COR completeness service", "secondary_keywords": [ "Gap Scan" ], "intent": "commercial", "funnel": "BOFU", "business_value": "high", "difficulty": "medium", "conversion_potential": "high", "cta": "Start a free Gap Scan", "schema": [ "FAQPage", "Service" ], "internal_links": [ "/resources (future)" ], "required_proof": [ "[PLACEHOLDER] owner to complete" ], "why_opportunity": "Owns the branded wedge term outright", "production_priority": "P0", "scope": "Launch" } ], "competitor_gaps": { "typical_competitor_types": [ "Enterprise SaaS vendor blogs", "BPO service pages", "Generic bookkeeping content" ], "common_weaknesses": [ "Written for large brokers, not the $500K-$5M Subcontractor", "No manufacturer-specific evidence" ], "how_to_beat_them": [ "Publish small-Subcontractor-specific, manufacturer-specific, evidence-first content" ] }, "metrics": { "weekly": [ "Scan requests", "Self-check completions" ], "monthly": [ "Organic scan requests", "Keyword ranking movement on P0 terms" ], "quarterly": [ "Fresh-verification pass on all cited statistics" ], "annual": [ "Full content-cluster audit" ] }, "risks": [ { "risk": "YMYL scrutiny on financial-outcome claims without named-reviewer attribution", "applies": true, "mitigation": "Named reviewer attribution and quarterly re-verification" }, { "risk": "Competitor content targeting the same small-Subcontractor segment", "applies": true, "mitigation": "Named reviewer attribution and quarterly re-verification" } ], "first_20_pages": [ "Homepage", "COR completeness self-check", "Manufacturer CORReady Survival Kit", "Direct-bill Completeness definitive guide" ], "first_10_tech_fixes": [ "Confirm noindex removed only after owner-action facts close", "Verify FAQ schema validates" ], "first_10_authority_actions": [ "Publish first 3 educational posts", "Launch the self-check lead magnet", "Pitch first association webinar" ], "final_recommendation": "Launch noindexed until owner-action facts (entity, reviewer identity, trademark clearance) close; then pursue a narrow, evidence-first authority strategy targeting the $500K-$5M Subcontractor segment the enterprise SEO content ignores.", "disclaimers": [ "Not engineering, architectural, or legal advice; not a engineering or legal opinion", "The contractor selects the product and submits it; the GC issues review actions and approves substitutions", "Fees are flat per COR / T&M set, never hourly; the completeness guarantee is not a guarantee of GC acceptance" ] }, "microsite": { "category": "Construction / specialty-trade subcontracting — COR / T&M change-order completeness", "shortTitle": "CORReady Clear", "audience": "US commercial specialty-trade subcontractors (electrical, mechanical/HVAC, plumbing, fire protection), 5-100 employees, submitting CORs and T&M tickets through GC portals without a dedicated change-order administrator", "problem": "A specialty-trade subcontractor performs extra work and must turn field tickets into a priced Change Order Request (COR) before the GC will pay — but with no change-order administrator, the work lands on a project engineer already running jobs. 57% of delayed or rejected CORs cite missing documentation: an unsigned T&M ticket, a photo not linked to a ticket line, no email authorizing the extra work, or a material claim with no cost backup. The COR bounces, runs two to three revision rounds, and the cash slips from the 8-14 day window into 15-30 days.", "offer": "With CORReady Clear, subs stop guessing and get a First-Pass COR Completeness Pack for one COR / T&M set — evidence matrix, indexed exhibits, gap chase list, completeness-risk score, and a draft cover narrative, with a change-order specialist's QA signature — delivered before the COR due date. Beachhead $249 per COR, never hourly.", "faq": [ { "q": "Do you guarantee the GC approves the change order?", "a": "No. We guarantee completeness — that your pack has the tickets, signatures, photos, authorization trail, and cost backups a reviewer needs. Whether the work is entitled extra work is a contract question you and, if needed, your counsel decide." }, { "q": "We already pay for Clearstory or Procore. Isn't this the same thing?", "a": "Those are tools your team operates; they track and sometimes price tickets, but someone still assembles the complete first-pass evidence pack — the 6-10 hours a week your project engineer is losing. CORReady Clear is the done-for-you desk that produces the finished pack. We complement your software; we don't replace your seat." }, { "q": "Our T&M tickets are handwritten paper. Can you use them?", "a": "That's the normal case — 97% of specialty contractors still run paper T&M tickets. We OCR handwriting and classify pages, then a specialist QAs the extraction. When a ticket is illegible we flag it and ask for a re-photo or typed clarification rather than guessing. We never invent a number." }, { "q": "How is this priced, and how fast is it?", "a": "Per COR, never hourly. The beachhead price is $249 for a typical MEP T&M-to-COR set; complex multi-ticket or multi-trade sets run $299-$349. Standard delivery is 5 business days from complete intake; rush under 48 hours adds $99-$149. The Gap Scan is free." }, { "q": "Who attests the rates and quantities?", "a": "You do, always. We package your rates from your rate sheet and cite the page; you attest the rates, quantities, and entitlement before anything goes to the GC. We are a documentation-preparation vendor, not a party to your contract." }, { "q": "Does CORReady Clear submit to the GC on our behalf?", "a": "No. We deliver the pack with an upload checklist; you upload to the GC portal under your own name and attest the rates, quantities, and entitlement. Submission and accountability stay with you." }, { "q": "Is this legal or engineering work?", "a": "No. We do not practice law, prosecute claims, take a recovery percentage, stamp drawings, or offer professional-engineering entitlement opinions. Design entitlement and legal disputes stay with your design team and counsel." }, { "q": "What if the pack still bounces?", "a": "If it comes back solely for a completeness item we marked as clear, we rebuild the resubmittal once at no additional pack fee. If the GC returns it for pricing or entitlement, that's outside completeness and stays yours to resolve — we'll still help you assemble the resubmittal." }, { "q": "What trades do you serve?", "a": "Beachhead trades are electrical, mechanical/HVAC, plumbing, and fire protection (10-60 employees). We expand to wall & ceiling, glazing, and specialty interiors as the playbooks harden." } ], "process": [ { "title": "Send the COR that bounced", "body": "Upload your tickets, photos, authorizing emails, rate sheet, and any prior GC comments. Free Gap Scan returns a gap map in 24 hours." }, { "title": "We build the pack", "body": "AI OCR and crosswalk, then deterministic completeness gates, then a change-order specialist QA." }, { "title": "You attest", "body": "Attest the rates, quantities, and entitlement on the pack we deliver." }, { "title": "You submit", "body": "Upload the finished pack to your GC portal under your own name, using our upload checklist." }, { "title": "We learn from the outcome", "body": "Any GC comment is coded into the playbook so the next pack starts closer to clear." } ], "northStarCta": { "label": "Start a free Gap Scan", "href": "#gapscan", "secondary_label": "See how it works", "secondary_href": "#how" }, "trust": { "standards": [ "Documentation-preparation service — not a law firm, engineering firm, or claims-recovery agent.", "The contractor selects what to claim, attests the rates, quantities, and entitlement, and submits to the GC.", "Deterministic completeness rules plus a change-order specialist QA signature on every pack; a complete pack does not guarantee GC approval." ], "response_time": "5 business days per pack from complete intake (48-hour rush available); delivered before your COR due date.", "data_handling": "T&M tickets, photos, contracts, and bid documents treated as confidential; least-privilege access; no training on customer documents without written consent; retention limits per the engagement letter." }, "hook": "A free Gap Scan tells you exactly where a COR would bounce for completeness — before your resubmittal date.", "sub_headline": "You send your T&M tickets, field photos, authorizing emails and RFIs, and rate-sheet exhibits. You get back a GC-ready First-Pass COR Completeness Pack — evidence matrix, exhibit index, gap chase list, draft narrative — with a change-order specialist's QA signature, before your due date.", "dream_outcome": "A change order package that comes back clear the first time, gets the extra work priced and paid on schedule, and never costs you a revision round for completeness.", "specific_pains": [ "An unsigned T&M ticket or daily report turns a real day of work into an unpayable line.", "Photos that aren't tied to a ticket line or work day, so the GC can't trace the labor or material.", "No RFI or email authorizing the extra work — entitlement questions swallow the whole COR.", "Labor hours without cost codes and materials without invoices or packing slips.", "A cover narrative that doesn't match the exhibit index, or a COR log out of sync with what was submitted." ], "cost_of_inaction": "Every bounced COR runs two to three revision rounds and pushes the priced change from the 8-14 day window into 15-30 days; on a $50M contractor a 5% change-order loss is an illustrative $2.5M at risk (AWCI, 2026).", "mechanism": { "name": "The CORReady Clear pack-cycle engine", "steps": [ { "title": "Intake: send the COR set", "body": "Send your T&M tickets and daily reports, field photos, authorizing emails and RFIs, contract rate exhibits, and any prior GC rejection comments. Tell us the COR number, the claimed scope, and the due date." }, { "title": "Extract & crosswalk", "body": "The engine runs OCR on tickets and handwriting, classifies each page, and builds a draft evidence matrix that links every ticket line to its supporting exhibits and flags what is missing." }, { "title": "Gate on deterministic rules", "body": "Hard fails on an unsigned ticket, a photo with no ticket or day link, a missing authorization trail, or a material line with a blank cost backup. The pack cannot proceed until each hard fail is cleared or you defer it." }, { "title": "Specialist QA", "body": "A change-order-aware specialist reviews the evidence match, resolves ambiguous exhibit links, applies the GC's packaging preferences, and sets the completeness-risk score. Nothing ships on the AI's word alone." }, { "title": "Attest & deliver", "body": "You attest the rates, quantities, and entitlement; we deliver the pack plus an upload checklist. You submit to Procore, Clearstory, or the GC's email under your own name." } ] }, "offer_stack": [ { "item": "Evidence matrix", "note": "Every labor and material claim crosswalked to its ticket, photo, authorization, and cost backup, with gaps flagged." }, { "item": "Exhibit index", "note": "Tickets, photos, emails/RFIs, invoices, and rate-sheet excerpts, indexed the way GC reviewers read them." }, { "item": "Gap chase list", "note": "Exactly what signatures, photos, or backups are still missing, with draft chase emails for the field." }, { "item": "Completeness-risk score", "note": "A plain read on whether the pack is submission-ready — not a prediction of GC approval." }, { "item": "Draft cover narrative + specialist QA signature", "note": "A narrative that matches the exhibits, signed off by a change-order specialist." } ], "guarantee": "If a pack comes back solely for completeness items we marked as clear, we rebuild the resubmittal at no additional pack fee, once. It is not a guarantee of GC approval, and we never claim a change order was approved.", "urgency": "There is no single filing deadline — the cost compounds: every bounced COR adds weeks of slipped cash, and 60% of firms write down or write off change-order revenue at least occasionally.", "objections": [ { "q": "We can't share bid and contract docs with an outside vendor.", "a": "Your documents are handled under a data-processing agreement with retention limits and are never used to train models without your consent. Access is least-privilege and deliverables go through access-controlled links." }, { "q": "Our COR volume is seasonal — we don't need this every month.", "a": "That's exactly why it's priced per COR, not as a seat or a salary. Use it on the CORs that matter; add a Continuity Desk only when an active project has steady volume." }, { "q": "How do we know a pack is actually complete?", "a": "Every pack clears deterministic hard-fail rules and a specialist checklist before delivery, and carries a completeness-risk score. If our completeness call is wrong, the rebuild is free once." }, { "q": "Isn't this just ChatGPT with a markup?", "a": "Generic AI owns no deadline, remembers no GC's preferences, chases no field signature, and signs no QA checklist. We sell the manufactured pack and the accountability loop, not raw model access." } ], "who_this_is_not_for": [ "Subcontractors wanting legal claims prosecution or a contingency/recovery-percentage arrangement — a different scope we refuse and refer.", "Anyone wanting a PE stamp, engineering entitlement opinion, or design judgment — outside our lane.", "Shops wanting us to build a Clearstory-style COR software platform — we produce packs, not seats." ], "proof_pillars": [ { "title": "Deterministic completeness gates", "body": "Hard fails on unsigned tickets, unlinked photos, missing authorization trails, and blank cost backups — rules the AI cannot overrule." }, { "title": "A specialist signs every pack", "body": "A change-order-aware specialist QAs the evidence match and signs the checklist before the pack reaches you. No pack ships on the model's word." }, { "title": "Rejection memory by GC and trade", "body": "Every GC comment is coded into the playbook, so the next pack for that trade and that GC starts closer to clear." } ], "stakes_line": "Incomplete means returned: the GC does not fix your COR, and a completeness bounce keeps the cash on your extra work unpaid for weeks.", "deliverable": "First-Pass COR Completeness Pack", "unit_of_work": "COR / T&M set", "lexicon": { "regulator": "The general contractor (GC)", "regulator_full": "The general contractor (GC) reviewing the COR under the contract's change and notice provisions", "statute": "the contract change and notice provisions", "statute_frame": "the intake-to-delivery workflow where an incomplete pack is a self-inflicted missing-docs rejection risk", "persona": "Subcontractor Principal", "persona_moment": "You're the principal of a 20-person specialty-trade sub with a COR for added scope coming due. A prior COR bounced for missing docs — an unsigned T&M ticket and no email authorizing the work — and the cash on the extra work has been stuck for three weeks.", "trigger_moment": "a bounced COR, a change order coming due before the resubmittal date, or a T&M backlog you must price", "enforcement_stakes": "the COR is returned for missing documentation, the priced change slips from days into weeks, and the cash on the extra work sits unpaid", "retention": "the full record of every pack, evidence-matrix line, gap-chase item, and specialist QA signature", "cta_verb": "Start a free Gap Scan", "intake_checklist": [ "The T&M tickets and daily reports for the work days claimed", "Field photos and the authorizing emails or RFIs for the extra work", "Your contract rate exhibit (or explicitly defer it)", "Prior GC rejection comments, if the COR already bounced" ], "regulator_faqs": [ { "q": "Does CORReady Clear submit to the GC on our behalf?", "a": "No. We deliver the pack with upload instructions; you upload to the GC portal under your own name and attest the rates, quantities, and entitlement. The GC issues the review action." }, { "q": "Does a complete pack mean the GC will approve the COR?", "a": "No. Completeness removes the missing-docs reason for rejection; approval of entitlement and pricing is the GC's decision and, where disputed, a matter for you and your counsel." } ], "trust_standards_specific": [ "The contractor attests all rates, quantities, and entitlement before submission.", "CORReady Clear never invents a rate or an entitlement position and never auto-submits to a GC portal." ] }, "proof_angle": { "id": "resubmittal-readiness", "headline": "The next GC review lands on a complete, source-cited COR pack — not a scramble — so your cash doesn't stall.", "lever": "CORReady Clear stores every required item, matrix line, exhibit, gap-chase item, and specialist QA signature in a pack record you can reproduce for the next COR.", "outcome_verb": "clears", "outcome_frame": "the COR comes back clear for completeness the first time", "proof_promise": "First-pass completeness acceptance and median cycle time will be published here from real pilot packs — no fabricated numbers." }, "indexable": true, "ubiquitousLanguage": { "audience": "US commercial specialty-trade subcontractors (electrical, mechanical/HVAC, plumbing, fire protection), 5-100 employees, submitting CORs and T&M tickets through GC portals without a dedicated change-order administrator", "domain": "commercial specialty-trade COR / T&M change-order completeness", "deliverable": "First-Pass COR Completeness Pack + specialist QA signature", "reviewer": "change-order specialist QA reviewer", "record": "pack record register", "unit_of_work": "COR / T&M set", "cta_primary": "Start a free Gap Scan", "cta_secondary": "See how it works", "regulator": "The general contractor (GC)", "regulator_full": "The general contractor (GC), under the contract's change and notice provisions", "statute": "the contract change and notice provisions", "trigger_moment": "a bounced COR, a change order coming due, or a T&M backlog to price", "event_intake_started": "domain.diagnostic_requested", "event_conversation_requested": "domain.diagnostic_requested" } }, "evidence": [ { "id": "specialty-trade-cor-tm-completeness-desk-e1", "business_slug": "specialty-trade-cor-tm-completeness-desk", "area": "Identity", "claim_or_finding": "Operating entity declared: Your Deputy, Obuke LLC, 924 W 23rd St., Erie, PA 16502, support@yourdeputy.com; CORReady Clear is a service of Your Deputy, Obuke LLC.", "status": "verified", "evidence": "Owner-supplied entity and support address; reflected in the landing-page footer and disclaimers.", "verification_command": "Owner submits entity + jurisdiction pack.", "fix_owner": "owner", "remediation": "Confirm entity, registered address, and support channel before first paid pack.", "severity": "low" }, { "id": "specialty-trade-cor-tm-completeness-desk-e2", "business_slug": "specialty-trade-cor-tm-completeness-desk", "area": "Market", "claim_or_finding": "57% of delayed or rejected CORs cite missing documentation; CORs/T&M are 10-30% of specialty-contractor revenue; 97% of T&M tickets are paper.", "status": "verified", "evidence": "Clearstory 2025 Specialty Contractor Change Order Report and 'Why CORs Get Delayed' (2025), re-verified 2026-07-15; 2026 report restates 53% insufficient backup docs.", "verification_command": "Web re-verification of Clearstory 2025/2026 reports.", "fix_owner": "owner", "remediation": "Keep landing-page stats aligned to the cited 2025 figures; note 2026 update in evidence.", "severity": "low" }, { "id": "specialty-trade-cor-tm-completeness-desk-e3", "business_slug": "specialty-trade-cor-tm-completeness-desk", "area": "Market", "claim_or_finding": "AWCI 2026 reports up to 36% ticket loss and 38% rejected for missing docs; Rhumbix cites 15-25% T&M leakage under manual processes.", "status": "verified", "evidence": "AWCI 'Change Orders Under Pressure' (2026) and Rhumbix T&M benchmark content confirmed 2026-07-15.", "verification_command": "Web search of AWCI and Rhumbix sources.", "fix_owner": "owner", "remediation": "Cite source names beside each figure; refresh annually.", "severity": "low" }, { "id": "specialty-trade-cor-tm-completeness-desk-e4", "business_slug": "specialty-trade-cor-tm-completeness-desk", "area": "Pricing", "claim_or_finding": "Beachhead $249 per COR; range $199-$349; Resubmittal $129-$199; Continuity Desk $299-$599/project/mo; never hourly.", "status": "verified", "evidence": "Anchored to Clearstory SaaS + project-engineer COR time + write-down exposure; consistent with the blueprint.", "verification_command": "Owner confirms price list in offer-and-pricing.md.", "fix_owner": "owner", "remediation": "Hold beachhead price through pilot; revisit after 20 packs.", "severity": "low" }, { "id": "specialty-trade-cor-tm-completeness-desk-e5", "business_slug": "specialty-trade-cor-tm-completeness-desk", "area": "Compliance", "claim_or_finding": "Documentation-preparation service only; no UPL, no PE opinions, no contingency/recovery fees; contractor attests and submits.", "status": "verified", "evidence": "Licensing boundary operationalized in compliance-checklist.md with verbatim disclaimers and banned-phrase list.", "verification_command": "Counsel reviews site copy and engagement letter.", "fix_owner": "owner", "remediation": "Complete the pre-launch compliance gate before first paid pack.", "severity": "medium" }, { "id": "specialty-trade-cor-tm-completeness-desk-e6", "business_slug": "specialty-trade-cor-tm-completeness-desk", "area": "Proof", "claim_or_finding": "No testimonials, client names, win rates, or case results are published; proof slots are honest placeholders keyed to real future pilot data.", "status": "placeholder", "evidence": "Landing page uses dashed placeholder proof slots; DNA proof_promise commits to publishing only real pilot numbers.", "verification_command": "Owner publishes first-pass completeness rate and cycle time after pilot.", "fix_owner": "owner", "remediation": "Fill proof slots only with permissioned, real pilot results.", "severity": "low" } ], "seo_pages": { "id": "seo-specialty-trade-cor-tm-completeness-desk", "business_slug": "specialty-trade-cor-tm-completeness-desk", "route": "/specialty-trade-cor-tm-completeness-desk", "title": "CORReady Clear — first-pass COR / T&M set pack for one COR / T&M set", "description": "CORReady Clear for commercial specialty-trade subcontractors. A GC-ready First-Pass COR Completeness Pack for one COR / T&M set — evidence matrix, linked T&M tickets, chase list, cover narrative — with specialist QA, before your due date. $249 per COR, never hourly.", "canonical": "/specialty-trade-cor-tm-completeness-desk", "og_title": "CORReady Clear — First-Pass COR Completeness Pack for one COR / T&M set", "og_description": "CORReady Clear for commercial specialty-trade subcontractors. A GC-ready First-Pass COR Completeness Pack for one COR / T&M set — evidence matrix, linked T&M tickets, chase list, cover narrative — with specialist QA, before your due date. $249 per COR, never hourly.", "schema_type": "FAQPage", "schema_status": "pending-owner-facts", "sitemap_include": false, "noindex": true }, "vertical_style": { "accent": "spec-teal", "signature": "Spec-desk tabs with a rejection-risk-score chip and Approved/returned for missing docs status", "layout": "change order documentation completeness desk index", "anti": "Insurtech/construction-tech gradient hero, stock hardhat handshake imagery, and alarm-red urgency banners" }, "canva": { "slug": "specialty-trade-cor-tm-completeness-desk", "territory": "Spec Desk", "family": { "id": "construction-COR-desk", "name": "Construction / specialty-trade CORs and T&M tickets", "motion": "calm" }, "tokens": { "brand": "191 74% 23%", "brand-fg": "40 31% 94%", "surface": "0 0% 100%", "ink": "197 14% 10%", "muted": "195 10% 32%", "accent": "22 75% 41%" }, "type": { "display": "Iowan Old Style", "body": "system-ui", "fonts_url": "" }, "scale": { "h1": "clamp(2.5rem, 5.5vw, 4.25rem)", "h2": "clamp(1.75rem, 3vw, 2.5rem)", "h3": "clamp(1.25rem, 2vw, 1.5rem)", "body": "clamp(1rem, 1.1vw, 1.125rem)", "small": "0.8125rem", "tracking_display": "-0.02em", "tracking_body": "-0.005em", "weight_display": 700, "weight_body": 450 }, "spacing": { "card_padding": "1.75rem", "card_radius": "0.35rem", "card_shadow": "0 0 0 1px hsl(var(--ink) / 0.08)", "section_gap": "clamp(3.5rem, 8vw, 6.5rem)", "hero_gap": "clamp(1.25rem, 2vw, 2rem)" }, "layout": { "hero": "split-primary", "card": "elevated-soft", "cta": "solid-brand", "archetype": "Pack", "card_silhouette": "flat-outline", "button_geometry": "rounded" }, "background": { "hero_gradient": "radial-gradient(1100px 600px at 8% -10%, hsl(191 74% 23% / 0.14), transparent 60%), radial-gradient(900px 500px at 100% 0%, hsl(22 75% 41% / 0.10), transparent 60%)", "cta_gradient": "linear-gradient(135deg, hsl(191 74% 23%), hsl(22 75% 41%))", "section_wash": "linear-gradient(180deg, hsl(0 0% 100%) 0%, hsl(191 74% 23% / 0.04) 100%)" }, "motif": "Catalog-page-to-linked-T&M ticket cover art" }, "capabilities": { "marketing": true, "portal": false, "ops": true, "chatbot": false, "payments": false }, "generated_at": "2026-07-15T00:00:00Z", "checksum": "8d99e99587e9d600" }