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 *margin per engagement*, never top-line revenue.
- **Retainers need burn-down tracking.** A retainer is a bucket of hours/fees that
  depletes through the month. Without burn-down you over-deliver (margin loss) or
  under-deliver (churn). Show consumed vs remaining, continuously.
- **Agencies live and die on scope creep + change orders.** The default human behavior
  is to "just do it" rather than raise a change order — which silently converts billable
  work into non-billable. The product must make raising a change order frictionless.
- **Time tracking is hated but is the source of truth for billing.** No time entry → no
  defensible invoice → realization drops. The constraint is *adoption*, not features.

## 3. What a naive build gets wrong

- **Proposal as a static PDF** instead of **accept-to-pay** — losing the e-sign +
  deposit/first-invoice moment where the deal actually closes and cash starts.
- **No change-order flow** — scope creep eats margin invisibly because over-delivery is
  never captured as a billable amendment.
- **Time entry so tedious nobody uses it** — a 12-field modal per entry kills adoption;
  with no entries, billing and profitability are both fiction. Timers + one-tap +
  defaults beat a perfect schema.
- **Profitability that shows revenue, not margin** — a dashboard of billings is
  vanity; the firm needs margin per project/retainer with cost-of-hours subtracted.
- **Ignoring retainer burn-down** — treating a retainer like a flat subscription
  instead of a depleting bucket misses the entire reason retainers are risky.

## 4. Must-model entities

Spec these explicitly; they recur across all four products. Build them
[[migration-ready-schema]] (stable external IDs, soft-delete, audit timestamps) because
agencies switch from incumbents mid-engagement and import open work.

- **SOW / Proposal** — header (client, engagement type, terms, net-N) + **line items**
  (description, qty, rate, optional/tiered flags) + **e-signature** state (sent → viewed
  → signed) + **accept-to-pay** link (deposit or first invoice on acceptance). Status
  machine: draft → sent → signed → active → closed.
- **Retainer** — period, committed hours/fee, **burn-down** (consumed vs remaining),
  rollover policy, renewal date.
- **TimeEntry** — who, project/task, duration, **billable flag**, **rate** (snapshot at
  entry time, not a live lookup), billed/unbilled (WIP) status.
- **Project** — budget (hours and/or fee), engagement type, rate card, computed
  **margin** (revenue − cost-of-delivered-hours), milestones.
- **ChangeOrder** — links to a Project/SOW, delta scope + delta price, its own
  e-sign/acceptance, and a reason — so scope growth becomes captured revenue.

## 5. Per-product notes (wedge vs incumbent + the one thing to nail)

- **proposals** (marketplace-lite) — **the wedge.** Revenue-adjacent and **low switching
  cost**: a firm can adopt it for the *next* proposal without migrating anything, and it
  touches money immediately. Incumbents bury proposals inside a heavy PSA suite. **Must
  nail: accept-to-pay** — e-sign that flows straight into a deposit/first invoice. See
  [[vertical-onboarding]]: first activation = first signed, paid proposal.
- **client-portal** (crud) — wedge: one clean client-facing surface for deliverables,
  approvals, status, and billing, vs incumbents' internal-ops focus. **Must nail:
  approvals as billing triggers** — an approved deliverable should be invoiceable
  (milestone billing), not just a checkbox.
- **time-invoicing** (crud) — wedge: timers → invoices → reminders with **no spreadsheet
  in between**; incumbents make time entry a chore. **Must nail: frictionless capture +
  rate snapshot** — adoption is the product; a wrong/stale rate corrupts every downstream
  invoice and the realization number.
- **profitability** (dashboard) — wedge: **real-time margin**, not month-end revenue
  reporting. **Must nail: margin = utilization × realization per engagement**, with
  cost-of-hours subtracted and retainer burn-down surfaced — not a billings chart.

## 6. Compliance (light)

Keep this proportionate — defer anything money-movement-shaped to the
subscription-billing-engineer.

- **e-signature validity** — ESIGN Act + UETA (US): capture intent-to-sign, consent to
  electronic records, an audit trail (timestamp, IP, signer identity), and a tamper-
  evident copy. For EU clients, eIDAS levels apply. This is what makes accept-to-pay
  legally binding.
- **Invoice / tax basics** — sequential invoice numbers, required fields, sales-tax/VAT
  where applicable. **Defer the engine** (tax calc, payment rails, dunning) to the
  subscription-billing-engineer; the architecture doc only needs the *contract* with it.
- **1099 for contractors** — agencies pay sub-contractors/freelancers; if the product
  touches contractor payouts, track payee tax info for 1099-NEC reporting (US). Note it;
  don't build a payroll system into a proposals tool.

## Output

When applied, contribute a **Domain model** note to the architecture doc capturing: the
engagement types in scope (project/retainer/T&M), the must-model entities above that this
product owns, the margin definition (utilization × realization, per engagement) if
profitability is in scope, and the e-sign/accept-to-pay contract if proposals is in scope.