Skip to content
HomeStar Docs

Handle a Deal Collapse

The deal fell through. The pipeline has first-class support for this — collapsed deals are analytical signal, not a failure to track. There are two reverse transitions back to QUALIFIED depending on how far the deal had progressed, and both require a reason code.

Pick the right transition

Section titled “Pick the right transition”
The deal collapsed…Use this transitionReason code
Between buyer’s agreement and contract executionCOMMITTED → QUALIFIEDdeal_collapsed
After contract execution, before closingIN_CONTRACT → QUALIFIEDcontract_voided

The two transitions look similar on the board (both demote to QUALIFIED) but the reason codes are different, and the timeline preserves which one fired. That matters when your broker later asks “how many of our IN_CONTRACT deals voided this quarter?”

Steps

Section titled “Steps”
  1. Open the lead’s detail page from the COMMITTED or IN_CONTRACT column.
  2. Fire the state change to QUALIFIED. The state machine recognizes this as a reverse transition.
  3. Select the reason code: deal_collapsed (from COMMITTED) or contract_voided (from IN_CONTRACT).
  4. Add a free-text reason in the payload — financing fell through, inspection killed it, mutual release, cold feet, whatever the truth is. This text is the analytical signal.
  5. Save.

Greg Schultz detail page. The Status dropdown (top right) and Quick Actions panel are where state changes are recorded today, including reverse transitions. The reason_code structured dropdown described in this how-to lives in the data model (crm_state_events.reason_code column) but is not yet exposed as a dedicated UI distinct from forward transitions — the free-text reason goes into payload context.

Be specific in the free-text reason

Section titled “Be specific in the free-text reason”

The reason code (deal_collapsed, contract_voided) is the structured signal. The free-text reason is for the humans reading the timeline three months from now — your broker, the next agent on the lead, you yourself.

Useful:

  • “Buyer’s financing fell through after rate lock expired”
  • “Inspection found foundation issue; seller refused to negotiate”
  • “Mutual release — buyer relocated for a job”

Not useful:

  • “Deal died”
  • “Buyer backed out”
  • “Inspection issue”

The first set tells the next reader what happened. The second tells them only that something happened.

What changes after the transition

Section titled “What changes after the transition”
  • The card moves back to QUALIFIED on the board.
  • The timeline records a Scribe entry with the reverse transition, the reason code, and your free-text payload.
  • The legacy buyer_status projects back to searching (the default QUALIFIED projection).
  • The lead remains assigned to you. They stay in the active pipeline.

What the lead is NOT

Section titled “What the lead is NOT”
  • Not archived. A collapsed deal doesn’t mean the relationship is over. The lead is back in QUALIFIED because they’re still working with you, just on a different property.
  • Not closed-lost. There’s no separate “lost” terminal column. If the relationship ends entirely, the natural transition is QUALIFIED → ARCHIVED via the 180-day timeout, or a manual archive.
  • Not retried automatically. No drips re-fire. You’re back to the searching/touring phase manually.

A worked example

Section titled “A worked example”

Suppose Marcus Williams was in IN_CONTRACT and the inspection found a structural issue the seller wouldn’t address. The contract is voided. Open Marcus’s card, fire the reverse transition with reason code contract_voided and the free text “Inspection: foundation issue, seller declined repair credit, mutual release filed 2026-05-15.”

He goes back to QUALIFIED. His temperature stays whatever it was. His timeline now has a full audit trail of the failed deal, including why. When he finds a different property and signs a new agreement, the transition QUALIFIED → COMMITTED fires fresh — the previous failure is history, not state.

Section titled “Related”