# Revenue workflow spec: <company> (<CRM and edition>)

- Version: <0.1>, status: <draft | approved>, effective date: <YYYY-MM-DD>
- Accountable owner: <RevOps role>
- Approvers: <marketing lead>, <sales lead>, <customer success lead>, <CRM admin>, <finance for billing state>, <privacy owner for consent rules>
- Mode this spec came from: <design | audit, with the audit file and date>
- Nothing in the CRM changes from this document alone. Changes leave as a change list.

## 1. Scope and motions

- Motions in scope: <inbound request | trial or product-qualified | outbound | partner | expansion | renewal>
- Out of scope: <motions, regions, products>
- The decision each handoff serves, one sentence each:
  - Marketing to sales: <an SDR decides within one business day whether to work this request>
  - SDR to AE: <...>
  - Sales to customer success: <...>
  - Renewal: <...>
- Stages nobody acts on were cut: <list, or none>

## 2. Units and episodes

- Unit per transition: <person | request | account | opportunity | renewal cycle>
- Roll-up rules where the unit changes: <an account is SQL on the first date any of its contacts enters SQL>
- Request episode record: <HubSpot leads object | Salesforce Lead per request | request object | Attio list entry | warehouse ledger>
- Repeat requests are counted on: <the episode record>, never by moving lifecycle back
- One record per buyer action: <which workflow or automation creates each record; an MQL reached through a hand-raise is decided on the hand-raise's record; automations that would create a second record are off>

## 3. State fields

```yaml
relationship:
  field: <lifecyclestage>
  values: [<subscriber>, <lead>, <marketingqualifiedlead>, <salesqualifiedlead>, <opportunity>, <customer>, <evangelist>]
  moves: forward only, except through the correction path
follow_up:
  field: <hs_lead_status | lead stage | Lead Status>
  values: [<NEW>, <ATTEMPTED_TO_CONTACT>, <CONNECTED>, <ACCEPTED>, <UNQUALIFIED>, <BAD_TIMING>]
  decision: <the accept or reject field, and the disposition_at it stamps (HubSpot lead stages have no accept step)>
opportunity:
  field: <dealstage per pipeline>
  pipelines:
    <new_business>: [<stage IDs in order>]
  lost_reasons: <closed_lost_reason, at most 12 values>
customer_state:
  fields: [<subscription_status>, <latest_invoice_status>, <collection_method>]
  writer: <billing integration>
  paid: <latest invoice status paid, read from the invoice; never subscription status alone>
  renewal_record: <renewal pipeline deal | custom object>, one per negotiated or annual cycle
  self_serve: <exception owner and queue for failed payments, scheduled cancellations, downgrades>
```

## 4. Transitions

One block per transition. No placeholder may remain, and no evidence may be an activity proxy (open, page view, meeting booked).

```yaml
- id: <T-MQL>
  from: <lead>
  to: <marketingqualifiedlead>
  unit: <person>
  evidence: <fit gate AND (engagement threshold OR hand-raise)>
  exclusions: <existing customer, open opportunity, partner, competitor, test, spam>
  field: <lifecyclestage>
  value: <marketingqualifiedlead>
  writer: <WORKFLOW:mql-scoring> (only)
  entry_timestamp: <CRM-maintained date entered property>
  exits:
    advance: <...>
    recycle: <follow-up status, reason, recycle date; lifecycle unchanged>
    disqualify: <follow-up status, reason; lifecycle unchanged>
  correction: <correction workflow, reason property, approver>
- id: <D-PROPOSAL>
  from: <evaluation>
  to: <proposal>
  unit: opportunity
  evidence: <what the buyer confirmed, recorded on the deal; buying contact associated or added as a contact role>
  field: <dealstage>
  writer: <the AE in the UI>
  entry_timestamp: <Date entered for the stage>
  exits:
    advance: <next stage, with its gate>
    lost: <closedlost with closed_lost_reason>
  correction: <who moves a deal back, with a reason>
```

## 5. Exclusions and hand-raise rules

- Hand-raise classes that skip the score: <demo request, pricing question, sales callback>
- Exclusions and their paths: <existing customer to account owner>, <open opportunity to opportunity owner>, <partner to partner manager>, <competitor disqualified>, <test and spam excluded with reason>
- Rejection reasons (at most 12): <list>. Closed-lost reasons (at most 12): <list>. Review a list when "other" exceeds 10% of its rejections or losses in a month.
- Self-booked meetings: <class booked_at_submit and its stop event>

## 6. Routing summary

- Precedence: <repeat delivery, support or billing intent, open opportunity owner, account owner, eligibility, segment pool, distribution, monitored fallback>
- Distribution method and pool: <...>; detail lives in <lead-routing-and-speed-to-lead output or references/clocks-and-slas.md>
- Fallback owner and unowned view: <role>, checked <hourly during coverage>
- Every outcome writes: request ID, received_at, matched account and basis, rule ID and version, pool, owner, assigned_at, retry count, exception reason

## 7. Clocks and coverage

- Clock fields: received_at (source system), crm_seen_at, assigned_at (first person or staffed queue), last_assigned_at, first_response_at (occurrence time of a relevant human attempt), disposition_at, first_connected_at, meeting_booked_at
- Buyer clock = SLA; owner clock = coaching metric, labelled as such
- Calendars: <team, IANA time zone, hours, holidays, who maintains Away status>; each request class names the calendar of the team that owns it

## 8. SLA register

- File: <sla-register.yaml path>. Each target names its baseline (median over due requests, unanswered ones at their age, with n) or is marked proposal while fewer than 30 requests are due.

## 9. Handoff contracts

- Packets and gates: <handoff-packet-checklist path>
- Acceptance and rejection per handoff: <who, field, reasons, SLA>

## 10. Scoring inputs and limits

- Fit inputs (source, writer, freshness): <...>. Unknown is not poor fit.
- Engagement inputs (source, window): <...>. Email opens are not evidence.
- A score may set: MQL (with the fit gate) and queue priority. It never changes an existing owner, sets Customer or moves a stage backward.
- Weights and validation: <lead-scoring-model output, version>

## 11. Field ownership

- Register: <field-ownership-register.csv path>. One automated writer per workflow field, per value where restricted.

## 12. Report pack

- Reports R01 to R10 with unit, cohort timestamp, numerator, denominator, maturity and owner: <path>
- Shared exclusion rule: <test, internal, spam definition>

## 13. Correction path

- Who may move a value backward: <correction workflow and named role>
- Required: reason property, before-export of the cohort, approver, review of tasks, emails and reports that already reacted

## 14. Open decisions

- <question>: <owner>, needed by <date>

## 15. Approvals and change log

- <YYYY-MM-DD> <version> <change> approved by <roles>