Vertical: construction — don't spec it naive

Construction has its own money physics. A spec that treats a contractor's billing like a SaaS invoice will ship something no contractor can use, because the cash flow it ignores (retainage held back, draws against a schedule of values, subs gated on lien waivers) is the thing the contractor is trying to manage. This skill gives architect and pm the vocabulary and the non-obvious rules so the four construction products are specced from domain reality, not intuition.

The four products and their incumbents:

Incumbents: Procore (enterprise, ~$375+/mo minimum — too expensive and heavy for small contractors; do not fight it head-on), Buildertrend (residential-focused), Contractor Foreman, Autodesk Construction Cloud (enterprise). The opening is small contractors priced and complexity'd out of these.

Domain vocabulary (use these terms exactly in specs)

• Estimate — internal cost calculation (what the job will cost the contractor). Bid — the priced number submitted to win the job (estimate + markup). Proposal — the customer-facing document wrapping the bid with scope, terms, exclusions. Estimate → bid → proposal are three artifacts, not synonyms.
• Takeoff (quantity takeoff) — counting/measuring quantities from plans (sq ft of drywall, linear ft of pipe) that feed the estimate. Garbage takeoff = garbage bid.
• Unit cost + assembly — an estimate is built from line items priced per unit (e.g. $/sq ft). An assembly bundles several unit-cost items into one (a "door assembly" = door + frame + hardware + labor). Real estimating is assemblies, not freehand numbers.
• Markup vs margin — markup is added on top of cost (cost × 1.20). Margin is the cut of the bid price (price − cost) / price. 20% markup ≠ 20% margin. Mixing them mis-prices the job. Spec which one a field means.
• Change order (CO) — a contracted change to scope/price after the bid is signed. Untracked COs are where margin leaks and disputes start.
• RFI (request for information) — formal question to the architect/owner about ambiguous plans; the answer can change scope (→ change order).
• Submittal — contractor's proposed material/product samples sent for approval before install.
• Draw schedule + progress billing — payment isn't lump-sum. The contractor bills in draws as work completes, against a schedule of values (the job broken into line items each with a contract value); each billing claims a % complete per line.
• Retainage / retention — the owner withholds a slice (typically 5–10%) of each payment until the job is complete/accepted. It is owed money the contractor can't touch yet — a first-class concept, not a discount.
• Lien / lien waiver — a mechanic's lien is a legal claim against the property for unpaid work; a lien waiver is the sub/supplier signing away that right in exchange for payment. Conditional (on payment clearing) vs unconditional (already paid).
• AIA G702/G703 — the industry-standard pay-application forms. G702 is the summary (application + certificate for payment); G703 is the continuation sheet (the schedule of values with this-period / to-date / retainage columns). Many owners require these exact forms.
• 1099 subcontractor — subs are typically 1099 contractors, not employees; the GC must collect a W-9 and issue a 1099 for tax reporting.
• COI (certificate of insurance) — proof a sub carries required insurance; must be current (not expired) before the sub works or gets paid.
• Daily log — the dated field record (crew on site, work done, weather, deliveries, delays). It is legal/dispute evidence, not a status update.
• Punch list — the end-of-job list of defects/incomplete items to fix before final payment / retainage release.
• Schedule of values (SOV) — the contract sum allocated across work items; the backbone of progress billing and G703.

Non-obvious domain rules (the ones that trip a naive spec)

1. Procore is enterprise and expensive. Don't out-feature it for small contractors — undercut on price and simplicity. The wedge is "good enough, cheap, no onboarding consultant."
2. Small contractors estimate in Excel. bid-builder's wedge is replacing the spreadsheet with real estimate math (unit costs + assemblies + markup). It's revenue-adjacent and low-switching — the easiest first sale.
3. Retainage is core, not an edge case. 5–10% withheld until completion changes every billing number. A billing model that doesn't carry a retainage column is wrong.
4. Progress billing runs through the schedule of values. You bill % complete per SOV line, not a flat invoice. Model the SOV first; billing falls out of it.
5. Subs are gated on documents before payment. A sub can't be paid until COI is current and the lien waiver for the period is signed. Payment without that gate is a real-money liability for the GC.
6. Untracked change orders eat margin and cause disputes. Every CO must adjust the contract sum and the SOV, with a signature trail.
7. Daily logs are dispute evidence. Photo + timestamp + weather + crew make them hold up; a free-text note that "we worked today" does not.

What a naive build gets wrong

• Estimating as a flat list of typed-in dollar amounts — no unit costs, no assemblies, no markup/margin distinction. Result: numbers nobody can defend or reuse.
• Billing that ignores retainage — invoices the full amount, so the contractor's books don't match what the owner actually pays.
• project-mgmt that ignores the draw schedule / progress billing — a generic task board that never connects to how money actually arrives.
• Subcontractor payment with no lien-waiver / COI gate — pays subs without the documents that protect the GC from liens and uninsured-work liability.
• No change-order flow — scope changes live in email; margin leaks; disputes have no paper trail.
• Daily logs without photo + timestamp + weather — useless as evidence when a delay or defect claim arrives.

Must-model entities

Hand these to the data model in ARCH (and apply [[migration-ready-schema]] — contractors bring their job list and customer list from the incumbent).

• Estimate — line items with unit_cost, quantity, and assemblies; carries a markup (and derived margin) → produces a Bid.
• Bid / Proposal — the priced submission; references the Estimate it came from.
• ChangeOrder — adjusts contract sum + SOV; has status + signature trail; linked to the Project.
• Subcontractor — its own entity (not an inline field) with COI status + expiry, lien-waiver status (the payment gate), and 1099 / W-9 info.
• Project — carries a Schedule of Values, a draw schedule, and a retainage percentage/balance.
• DailyLog — photos, weather, crew, timestamp; append-only enough to serve as evidence.

Money in integer minor units (*_cents); retainage and SOV math must not float-drift.

Per-product notes

• bid-builder (marketplace-lite) — Wedge: revenue-adjacent, low-switching replacement for the estimating spreadsheet. The one domain thing: real estimate math — unit costs + assemblies + the markup/margin distinction producing a defensible bid. Get this wrong and it's just a worse Excel.
• project-mgmt (crud) — Wedge: lightweight project + daily-log tool vs heavy Buildertrend/Contractor Foreman. The one domain thing: draw schedule / progress billing off the schedule of values — don't ship a generic task board disconnected from billing.
• subcontractor-portal (marketplace-lite) — Wedge: manage subs, docs, and payments without Procore. The one domain thing: lien-waiver + COI gating before payment — the portal's whole value is that a sub can't be paid until the documents are clean.
• field-docs (crud) — Wedge: photo/daily-report/inspection capture vs paper and Procore's field module. The one domain thing: photo + timestamp + weather + crew on every entry so the record is dispute-grade evidence.

Compliance (light — flag, don't gold-plate)

• Lien law is state-specific — preliminary notice deadlines and lien-waiver forms vary by state; treat waiver forms as state-configurable, not hardcoded.
• Retainage law — many states cap the retainage % and regulate timing of release; surface it as a setting.
• 1099 for subs — collect W-9, track payments, support 1099 reporting.
• Prevailing wage — on public/government projects (Davis-Bacon), wage rates are mandated and certified payroll is required; flag if the product targets public work.
• COI verification — verify current (non-expired) coverage before sub work/payment.
• OSHA — relevant to field-docs (safety inspections, incident records) but keep light.

These pair with [[vertical-onboarding]] (importing the contractor's existing jobs, subs, and customers as the low-switching wedge) and [[lifecycle-messaging]] (COI-expiry reminders, lien-waiver requests, draw/payment notifications — the messages that make the money flow run).