| 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.
