vertical-professional-services

name	vertical-professional-services
description	Domain-knowledge primer for the professional-services vertical (agencies, consulting firms, creative studios) so architect/pm don't spec naively against PSA incumbents (Scoro, Productive, Accelo, Ruddr, BigTime). Supplies the vocabulary, the non-obvious billing/margin rules, the entities a real proposal/portal/time/profitability product must model, and the per-product wedge. Applied by architect/pm during spec authoring for any of the four products in this vertical — proposals, client-portal, time-invoicing, profitability.
when_to_use	Apply when: - architect is writing ARCH-*.md for a professional-services product (proposals, client-portal, time-invoicing, profitability) - pm is decomposing one of these into tasks and needs to model the domain entities (SOW, retainer, time entry, change order) correctly - any spec touches agency/consulting/studio billing, margin, or scope Do NOT apply for other verticals (home services, restaurants, etc.) — the billing economics here (utilization × realization) are specific.
effort	low
allowed-tools	Read, Write, Grep, Glob
paths	["docs/architecture/**","docs/plans/**","docs/design/**"]

Vertical: professional services — bill time, defend margin, sell the scope

Agencies, consulting firms, and creative studios sell hours and deliverables, not units. Their economics are unintuitive: revenue can rise while margin collapses, and the document that wins the work (the proposal/SOW) is also where margin leaks. Incumbents (Scoro, Productive, Accelo, Ruddr, BigTime — collectively "PSA", professional-services automation) model this correctly; a naive build does not. Spec against the real domain.

1. Domain vocabulary

• SOW (statement of work) — the binding scope: deliverables, timeline, price, terms. It IS the contract and the upsell surface.
• Engagement types: project (fixed scope/price), retainer (recurring fee for a capacity/hours bucket), T&M (time & materials — bill actuals).
• Utilization rate — billable hours ÷ available hours. The first lever of margin.
• Realization rate — billed amount ÷ standard value of hours worked (i.e. how much of what you could bill you actually invoiced and collected). The second lever.
• Billable vs non-billable — every time entry carries this flag; non-billable (admin, sales, rework) is pure cost.
• WIP (work in progress) — unbilled-but-delivered work; revenue earned, not yet invoiced. Agencies carry it for weeks.
• Blended rate — single effective $/hour across a mixed-seniority team on an engagement (vs per-person rate cards).
• Change order — a formal amendment when scope grows; the antidote to scope creep.
• Milestone billing — invoice tied to deliverable acceptance, not the calendar.
• Scope creep — uncompensated work beyond the SOW; the silent margin killer.
• Gross margin per project — (revenue − cost of delivered hours) ÷ revenue, per engagement — not company-wide, not revenue.
• e-signature — legally binding accept on the proposal (ESIGN/UETA, see §6).
• Net-30 terms — payment due 30 days after invoice; drives cash flow and reminders.

2. Non-obvious domain rules

• The proposal/SOW is the contract AND the upsell. It's not a marketing PDF — it's where price, scope, and acceptance live. Optional line items and tiers turn a quote into expansion revenue. Treat it as a revenue surface, not a document export.
• Margin is utilization × realization, not revenue. A firm can grow billings and lose money if people are busy on non-billable work or hours never get invoiced. Profitability must compute , never top-line revenue.