Playbook: Stuck Investment

An investment has been sitting in "committed" or "pending" status for longer than expected. This playbook helps you diagnose why, fix the underlying issue, and get the investment moving again.

Diagnostic Flowchart

Step-by-Step Guide

Step 1: Open the Investment

1. Go to the investment in admin
2. Look at the Lifecycle Tracker panel at the top -- it shows you exactly where the investment is in its lifecycle and what's blocked

Step 2: Identify the Blocker

The Lifecycle Tracker shows each step with a color-coded status:

• Green (completed): This step is done
• Blue (active/in-progress): This step is currently being processed
• Red (failed): This step failed and needs attention
• Amber (blocked): This step is blocked by an issue
• Gray (pending): This step hasn't been reached yet

The summary bar at the bottom tells you the current readiness decision in plain English.

Step 3: Fix the Underlying Issue

Step 4: Use "Re-evaluate & Dispatch"

This is your primary recovery tool for stuck investments:

1. On the investment page, click the "Re-evaluate & Dispatch" button (teal button in the action bar)
2. A dialog shows the current readiness status and what action will be taken
3. Click "Re-evaluate & Dispatch" to confirm
4. The system will:
   • Check all prerequisites (SPV status, verification, bank registration)
   • Take the appropriate next action (dispatch payment, submit verification, etc.)
   • Show you a flash message with the result

Step 5: Check the Audit Trail

The Audit Trail panel at the bottom of the investment page shows all activity in chronological order. Use it to:

• Understand what the system has already tried
• See if there were previous failures
• Confirm that your "Re-evaluate & Dispatch" action was successful
• Filter by category (Investments, Payments, Compliance) to focus on specific areas

Common Scenarios

Scenario: Bank registration fixed but payment never dispatched

This happens when bank registration fails, an admin manually retries and it succeeds, but the system didn't advance the investment. Click "Re-evaluate & Dispatch" -- it will see the bank is now registered and dispatch the payment.

Scenario: KYC approved but investment still committed

The KYC approval event may not have triggered the dispatch. Click "Re-evaluate & Dispatch" to check readiness and dispatch if everything is in order.

Scenario: SPV opened but investments didn't advance

If multiple investments were waiting for an SPV to open and some didn't advance, use "Re-evaluate & Dispatch" on each stuck investment.

Flow Diagnostics and Health Monitoring

The platform includes automated monitoring for onboarding flows that can help identify issues before they become visible as stuck investments.

Automated Health Checks

A scheduled job runs hourly and detects three categories of unhealthy onboarding flows:

All health check events are recorded in the audit trail, so you can see exactly what the system did and when.

Flow Transition Events

Every significant action in an onboarding flow is recorded as a transition event. These events track:

• Step advances and reversals -- when the investor moves forward or navigates back
• Postcondition failures -- when a step's completion criteria are not met (e.g. identity data is missing)
• Auto-repairs -- when the system automatically fixes a known data inconsistency (e.g. a stale tax status after a back-navigation)
• Health check detections -- stuck, corrupted, or abandoned flow notifications
• Errors -- unexpected failures during flow progression

Flow Diagnostics Endpoint

For super admins, a diagnostics endpoint provides a comprehensive snapshot of any onboarding flow. This is useful when investigating why a new investor appears to be stuck before they reach the investment stage. The diagnostic includes:

• Current step and whether it can advance
• Completed steps and remaining requirements
• Postcondition status and any violations
• The 10 most recent transition events
• Identity verification status summary

Auto-Repair

The system automatically attempts to fix known postcondition violations that can occur when an investor navigates back and changes their tax status. For example, if an investor changes from US to international after already completing a profile step, the system detects the inconsistency and repairs the affected data. Auto-repairs are non-blocking -- if a repair cannot be performed automatically, it is logged for manual investigation.

When to Escalate

• If "Re-evaluate & Dispatch" returns "Blocked" with a reason you can't resolve
• If the same investment keeps getting stuck after fixes
• If you see patterns of multiple investments stuck at the same step
• If the health check is flagging a high volume of stuck or corrupted flows