Domain knowledge for the construction vertical (contractors, field crews) so architect and pm don't spec construction products naively. Covers the vocabulary (bid vs estimate, takeoff, retainage, change order, AIA G702/G703, lien waiver, draw schedule), the non-obvious money rules that incumbents like Procore price out of reach for small contractors, what a naive build gets wrong (no assemblies, ignored retainage, ungated sub payments), and the entities that must be modelled. Applied by architect when writing ARCH-{slug}.md and by pm when writing PLAN-{slug}.md for any of the four construction products (bid-builder, project-mgmt, subcontractor-portal, field-docs).
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Domain knowledge for the construction vertical (contractors, field crews) so architect and pm don't spec construction products naively. Covers the vocabulary (bid vs estimate, takeoff, retainage, change order, AIA G702/G703, lien waiver, draw schedule), the non-obvious money rules that incumbents like Procore price out of reach for small contractors, what a naive build gets wrong (no assemblies, ignored retainage, ungated sub payments), and the entities that must be modelled. Applied by architect when writing ARCH-{slug}.md and by pm when writing PLAN-{slug}.md for any of the four construction products (bid-builder, project-mgmt, subcontractor-portal, field-docs).
when_to_use
Apply when:
- architect writes ARCH-{slug}.md for a construction product (bid-builder,
project-mgmt, subcontractor-portal, field-docs)
- pm decomposes a construction feature into PLAN-{slug}.md tasks
- design-advisor wireframes a construction screen (estimate, billing, sub payment, daily log)
- any spec touches money flow (billing, payment, retainage) in the construction vertical
Do NOT apply to non-construction verticals — the money rules (retainage, lien waivers,
AIA pay apps) are construction-specific and will mislead elsewhere.
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:
Product
Archetype
Wedge against
bid-builder
marketplace-lite
Excel (small contractors estimate in spreadsheets)
project-mgmt
crud
Buildertrend, Contractor Foreman
subcontractor-portal
marketplace-lite
Procore, manual COI/payment tracking
field-docs
crud
Procore field tools, paper daily reports
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.
— a contracted change to scope/price after the bid is signed.
Untracked COs are where margin leaks and disputes start.
Change order (CO)
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)
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."
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.
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.
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.
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.
Untracked change orders eat margin and cause disputes. Every CO must adjust the
contract sum and the SOV, with a signature trail.
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).
