Skip to main content

Follow-Up Status Model

This is the locked V1 follow-up status contract for IED.

Use this as the source of truth for:

  • when follow-up begins
  • the V1 follow-up status set
  • what fields belong on a follow-up record
  • how satisfaction and issues are modeled
  • what counts as complete

Follow-Up Entry Rule​

Follow-up is optional and secondary in V1.

If used, it starts only after the lead has already been captured into installer delivery and operations decides a post-delivery customer check is needed.

V1 follow-up is:

  • separate from lead lifecycle
  • separate from routing assignment state
  • a customer satisfaction and quote-check workflow

One installed lead gets one primary follow-up record in V1.

Recurring or long-tail service workflows are outside the core V1 follow-up contract.

V1 Follow-Up Status Model​

V1 uses a small operational follow-up workflow:

  • pending Follow-up record exists and is due or planned, but work has not started
  • in_progress The team is actively working the follow-up
  • completed Follow-up contact happened and the outcome was recorded
  • closed_with_issue Follow-up contact happened, but an issue remains open or requires separate handling

V1 does not turn follow-up into a service-desk workflow.

Do not add support-ticket style statuses such as:

  • waiting_on_installer
  • escalated
  • resolved_ticket

unless a real operating need appears later.

Relationship To Lead Lifecycle​

Follow-up does not change lead lifecycle.

The relationship is:

  • lead assigned may later create a follow-up if operations wants a post-delivery check
  • follow-up completion does not change lead lifecycle
  • follow-up completion does not define billing truth

This means:

  • follow-up is not a lead status
  • follow-up completion is tracked separately from commercial outcome

Customer Contact Visibility​

Follow-up should carry the operational truth of whether someone has actually contacted the customer yet.

This does not belong in lead lifecycle.

Recommended V1 customer-contact fields:

  • contactAttemptCount
  • lastContactedAt
  • lastContactedByEmail
  • lastContactOutcome

Recommended V1 contact outcomes:

  • attempted
  • left_message
  • no_response
  • reached_customer

This lets operators answer:

  • have we tried to contact this customer yet
  • when was the last contact attempt
  • who made the last attempt
  • did we actually reach them

without turning the whole app back into a sales CRM.

Satisfaction And Issue Handling​

Satisfaction must stay separate from the main follow-up status.

Recommended V1 satisfaction outcomes:

  • satisfied
  • mixed
  • unsatisfied

Recommended V1 issue model:

  • hasIssue Explicitly records whether the customer reported a problem
  • issueSummary Captures the issue in plain language
  • issueResolved Tracks whether the problem is resolved

closed_with_issue means:

  • the follow-up workflow itself is operationally closed
  • but an issue still exists or needs separate handling

Do not encode:

  • satisfaction inside the main follow-up status
  • installer escalation flow inside the main follow-up status

Completion And Due-Date Rules​

V1 completion rule:

  • a follow-up becomes completed only after real follow-up activity occurred and the outcome was logged
  • scheduling or assignment alone does not count as completion
  • unresolved issues should use closed_with_issue, not completed

V1 due-date rule:

  • dueAt is required on the record
  • the exact scheduling formula can be defined later
  • the model must support due and overdue filtering in admin

Suggested FollowUp fields:

  • leadId
  • installerId
  • status
  • dueAt
  • startedAt
  • completedAt
  • contactAttemptCount
  • lastContactedAt
  • lastContactedByEmail
  • lastContactOutcome
  • satisfactionOutcome
  • hasIssue
  • issueSummary
  • issueResolved
  • referralOpportunity
  • notes

Contract Boundaries​

These do not belong inside the follow-up status contract:

  • lead lifecycle design belongs in docs/product/lead-lifecycle.md
  • routing assignment states belong in docs/product/routing-assignment-states.md
  • installer support/escalation workflows can be layered later without changing the V1 follow-up status model
  • exact due-date scheduling policy can be defined later without changing the contract

Validation Scenarios​

The model should support these scenarios:

  • a lead does not create a follow-up until operations explicitly needs post-delivery follow-up
  • a delivered lead can create one primary follow-up record
  • a due follow-up can remain pending until action starts
  • once staff begin working it, status moves to in_progress
  • if contact happens and satisfaction is recorded with no open issue, status becomes completed
  • if contact happens but a customer issue remains open, status becomes closed_with_issue
  • follow-up completion does not change the lead lifecycle
  • dashboard and admin views can filter due, in-progress, completed, and issue-bearing follow-ups