mariourquia/cre-skills-plugin/acquisition-handoff

Acquisition Handoff

Workflow purpose

Turn a closed Dealpath deal into a fully-operational asset with auditable handoff completion across AppFolio (operating), Intacct (financial), master data crosswalks (data platform), and the vendor master. The workflow does not itself execute setup steps in vendor systems; it composes the handoff checklist, validates each item's completion against the source-of-truth matrix, and routes gated items through workflows/owner_approval_routing. Handoff is not complete until every item is within the tolerance band on reconciliation_tolerance_band.yaml and the asset_mgmt_director has signed off.

Trigger conditions

• Explicit: "acquisition handoff for {deal}", "open operating handoff package", "close the handoff for {property}", "handoff status for {deal}".
• Implicit: Dealpath deal.stage transitions to closed AND deal_close_date_actual is non-null for an acquisition deal type (Handoff 1 in reference/connectors/_core/stack_wave4/lifecycle_handoffs.md). Downstream post_ic_property_setup emits a handoff_baton_pass event at close.
• Recurring: none. Strictly event-driven.

Inputs (required / optional)

Outputs

Required context

asset_class, segment, form_factor, lifecycle_stage, management_mode, market, deal_id, property_id (or placeholder), org_id. jurisdiction conditionally required for legal-entity setup and lender registration.

Process

1. Receive close event. Consume the Dealpath close trigger (Handoff 1 in lifecycle_handoffs.md). Confirm deal.stage = closed and deal_close_date_actual present. If absent, refuse.
2. Load baseline. Pull canonical deal, asset, placeholder property, IC approval_request, and the baton-pass payload from post_ic_property_setup.
3. AppFolio property setup. Confirm property record promoted from pre_acquisition to the target lifecycle_stage per source_of_truth_matrix.md (property primary = AppFolio). Verify unit_count_total, unit_count_rentable, nrsf_total, address, market, submarket, form_factor all populated. Any missing field is a blocker.
4. Intacct legal entity dim. Confirm legal_entity_id recorded in Intacct dimension structure (source_of_truth_matrix.md row property: secondary = intacct for legal_entity_id). Confirm project/property dimension created in Intacct.
5. Vendor master rationalization. For each inherited + new vendor: run identity resolution per master_data/identity_resolution_framework.md; de-duplicate against existing vendor_master_crosswalk.yaml; emit proposed additions or merges. Count goes to vendor_rationalization_count (proposed).
6. Opening rent roll load. Reconcile the pre-close rent roll to the AppFolio first-load rent roll within tolerance band (opening_rent_roll_reconciliation_variance, proposed). Outside-band variance blocks the handoff until explained.
7. PMA execution (if TPM). Verify the PMA has been executed if management_mode=third_party_managed. Lag computed as pma_execution_lag_days (proposed) from close date. Late PMA opens an exception row.
8. Lender reporting registration. Confirm lender-facing package submitted and acknowledgment received. Registration status becomes a checklist item; lack of acknowledgment > band triggers row 14 escalation via workflows/owner_approval_routing.
9. Data-platform crosswalk row creation. Propose new property_master_crosswalk.yaml row, asset_crosswalk.yaml row, and vendor_master_crosswalk.yaml additions per master_data/crosswalk.schema.yaml. Proposed rows are written to a staging area and only merged after approval; see survivorship_rules.md.
10. Handoff-lag screen. Compute handoff_lag_days (proposed) per workstream against handoff_lag_threshold_days from reconciliation_tolerance_band.yaml. Any breach routes to workflows/owner_approval_routing row 7.
11. Completeness score. Compose handoff_completeness_score (proposed) as weighted completion of the checklist (weights per overlay).
12. Sign-off packet. Assemble the asset_mgmt_director sign-off packet with the checklist, scorecard, blocker memo, and crosswalk drafts. Route via workflows/owner_approval_routing row 7.
13. Confidence banner. Surface as_of_date and status tags for every reference file and crosswalk referenced; cite the lifecycle_handoffs.md handoff id (h_dp_int_to_af_setup_...).

Metrics used

• handoff_completeness_score (proposed: true) — weighted completion of the handoff checklist; grain=deal, time_basis=as_of_date.
• handoff_lag_days (proposed: true) — days between deal_close_date_actual and each handoff workstream's completion; grain=deal, time_basis=event_stamped.
• vendor_rationalization_count (proposed: true) — count of vendor master rows rationalized at handoff; grain=deal.
• opening_rent_roll_reconciliation_variance (proposed: true) — variance between pre-close rent roll and AppFolio first-load; grain=property, unit=percent.
• pma_execution_lag_days (proposed: true) — days between close and executed PMA for TPM assets; grain=deal.
• crosswalk_row_creation_lag_days (proposed: true) — days between close and crosswalk-row approval; grain=deal.

Proposed metrics will be lifted into _core/metrics.md in a dedicated change-log entry before the workflow is promoted beyond draft.

Reference files used

• reference/connectors/_core/stack_wave4/lifecycle_handoffs.md — handoff definitions (Handoff 1 and Handoff 3).
• reference/connectors/_core/stack_wave4/source_of_truth_matrix.md — primacy and effective-dating rules for every canonical object surfaced.
• reference/connectors/adapters/dealpath_deal_pipeline/manifest.yaml and dq_rules.yaml — source shape; blocking rules dp_handoff_lag and dp_one_deal_multiple_projects cited.
• reference/connectors/adapters/appfolio_pms/manifest.yaml — PMS primary for property, unit, lease.
• reference/connectors/adapters/sage_intacct_gl/manifest.yaml — GL primary for legal_entity_id, posted actuals.
• reference/connectors/master_data/property_master_crosswalk.yaml, asset_crosswalk.yaml, vendor_master_crosswalk.yaml — crosswalks the workflow proposes rows for.
• reference/connectors/master_data/identity_resolution_framework.md and survivorship_rules.md — identity and survivorship policy.
• reference/normalized/schemas/reconciliation_tolerance_band.yaml — handoff lag and rent-roll reconciliation bands.
• reference/normalized/approval_threshold_defaults.csv — approval thresholds (rows 7, 14, 17, 19 per approval matrix).

Escalation points

• Handoff lag. Any workstream exceeding handoff_lag_threshold_days escalates to regional_ops_director -> asset_mgmt_director and opens approval_request row 7.
• Missing required approver. If the asset_mgmt_director sign-off cannot be routed (role vacant per approver roster), escalates per row 17.
• Vendor master conflict. Unresolved duplicate or survivorship conflict goes to master_data/unresolved_exceptions_queue.md and routes to row 19.
• Insurance gap during transition. If the acquisition insurance binder expires before the owner's permanent policy is bound, escalates to legal + asset_mgmt_director per row 17.
• Doc package incomplete. Lender reporting or PMA docs below completeness threshold routes to reporting_finance_ops_lead.

Required approvals

• asset_mgmt_director_handoff_signoff — terminal approval that marks handoff complete. Required for every acquisition.
• pma_execution_if_tpm — row 19 (PMA amendment / owner-binding contract) if management_mode=third_party_managed.
• lender_reporting_registration — row 14 (lender-facing submission marked final) when the registration package is transmitted.
• Crosswalk row additions to master_data: routed via workflows/owner_approval_routing per survivorship_rules.md.

Failure modes

1. Silent lifecycle_stage advance. Property flipped to stabilized in AppFolio without AppFolio primary confirmation. Fix: source-of-truth matrix check required before promotion.
2. Vendor master duplication. New vendors added without identity resolution. Fix: identity_resolution_framework.md is a required step.
3. Opening rent roll ignored. Variance > band passed forward. Fix: handoff halts until variance explained or waived with approval.
4. PMA missing for TPM. Handoff marked complete without PMA. Fix: conditional required input; pma_execution_if_tpm approval gate.
5. Crosswalk row approved before handoff completeness verified. Fix: staging area + survivorship rule enforcement.
6. Lender registration drift. Registration acknowledgment not received before close + 10 business days. Fix: escalation via row 14.
7. Multi-asset deal split not propagated. dp_one_deal_multiple_projects warning raised by Dealpath but handoff assumes 1:1. Fix: workflow refuses until mapping is manually resolved.
8. Stale confidence banner. as_of_date references older than the close date without acknowledgement. Fix: banner required per overlay staleness rule.

Edge cases