Best Practices¶

This guide covers proven patterns for using what-if scenarios effectively, from individual analysis to team-wide workflows.

Scenario Templates¶

Create reusable templates for common analysis patterns:

Template: Standard Buy Evaluation¶

Use when evaluating a new loan opportunity:

{
  "name": "Template - Buy Evaluation - [CUSIP]",
  "description": "Standard template for evaluating new loan purchases",
  "trades": [
    {
      "trade_type": "buy",
      "cusip": "[ENTER_CUSIP]",
      "borrower_name": "[ENTER_BORROWER]",
      "par_value": 1000000,
      "price": 99.00,
      "spread": 4.00,
      "rating_moodys": "[ENTER_RATING]",
      "industry": "[ENTER_INDUSTRY]"
    }
  ]
}

Template: Credit Rotation¶

Use for upgrading credit quality:

{
  "name": "Template - Credit Rotation",
  "description": "Sell weak credits, buy stronger replacements",
  "trades": [
    {
      "trade_type": "sell",
      "cusip": "[WEAK_CUSIP]",
      "par_value": 0,
      "rating_moodys": "[CURRENT_RATING]"
    },
    {
      "trade_type": "buy",
      "cusip": "[STRONG_CUSIP]",
      "par_value": 0,
      "rating_moodys": "[BETTER_RATING]"
    }
  ]
}

Template: Industry Rebalance¶

Use for reducing sector concentration:

{
  "name": "Template - Industry Rebalance - [INDUSTRY]",
  "description": "Reduce concentration in [INDUSTRY] sector",
  "trades": [
    {
      "trade_type": "sell",
      "cusip": "[SELL_CUSIP_1]",
      "industry": "[CONCENTRATED_INDUSTRY]",
      "par_value": 0
    },
    {
      "trade_type": "buy",
      "cusip": "[BUY_CUSIP_1]",
      "industry": "[DIVERSIFYING_INDUSTRY]",
      "par_value": 0
    }
  ]
}

Naming Conventions¶

Consistent naming makes scenarios easy to find and understand:

Recommended Format¶

[YYYY-MM-DD] [Type] [Target] - [Detail]

Examples by Use Case¶

Naming Rules¶

1. Start with date for time-sensitive scenarios
2. Include action type: Buy, Sell, Rebalance, Exit, Stress
3. Reference the target: Obligor name, sector, or metric
4. Add distinguishing detail when needed
5. Prefix templates with "Template -"

Workflow Patterns¶

Individual Analyst Workflow¶

For daily trade decisions:

flowchart TD
    A[Trade Opportunity] --> B[Create Scenario]
    B --> C[Add Proposed Trade]
    C --> D[Run Simulation]
    D --> E{Results OK?}

    E -->|Yes| F[Document Approval]
    E -->|No| G{Modify Trade?}

    G -->|Yes| H[Create New Scenario<br/>with Adjustments]
    G -->|No| I[Reject Trade]

    H --> D
    F --> J[Execute Trade]

Team Collaboration Workflow¶

For multi-person trade review:

flowchart TD
    A[Analyst Creates Scenario] --> B[Run Simulation]
    B --> C[Share Results with PM]
    C --> D{PM Review}

    D -->|Approved| E[PM Signs Off]
    D -->|Changes Needed| F[Analyst Revises]
    D -->|Rejected| G[Close Scenario]

    F --> H[New Scenario Version]
    H --> B

    E --> I{Compliance Review<br/>Required?}
    I -->|Yes| J[Compliance Officer Review]
    I -->|No| K[Execute Trade]

    J --> L{Compliance Approved?}
    L -->|Yes| K
    L -->|No| F

Approval Workflow Integration¶

Pre-Trade Approval Process¶

1. Create Scenario: Analyst creates scenario with proposed trades
2. Run Simulation: Execute simulation to get compliance impact
3. Prepare Summary: Document impact summary and any concerns
4. Submit for Review: Share scenario ID with approvers
5. Review Results: Approver views scenario in CalcBridge
6. Decision: Approve, reject, or request modifications
7. Document: Record approval decision with rationale

Approval Documentation Template¶

## Trade Approval Request

**Scenario**: [Scenario Name]
**Scenario ID**: [UUID]
**Date**: [YYYY-MM-DD]
**Analyst**: [Name]

### Proposed Trades
| Type | CUSIP | Par Value | Rating |
|------|-------|-----------|--------|
| Buy | ABC123 | $1,000,000 | B2 |

### Impact Summary
- Improving: 5 tests
- Worsening: 1 test
- Neutral: 9 tests
- New Failures: 0

### Key Impacts
- CCC Bucket: 6.5% -> 5.8% (IMPROVE)
- Single Obligor (ABC Corp): 2.1% -> 3.0% (WORSEN, still within limit)

### Recommendation
APPROVE - Trade improves credit quality with minimal concentration impact.

### Approval
- [ ] Portfolio Manager: _________________ Date: _______
- [ ] Compliance (if required): _________________ Date: _______

Iterative Analysis¶

Version Control for Scenarios¶

Track iterations with clear naming:

2026-01-25 Buy ABC Corp v1 - Initial
2026-01-25 Buy ABC Corp v2 - Reduced Size
2026-01-25 Buy ABC Corp v3 - With Sell Offset
2026-01-25 Buy ABC Corp FINAL - Approved

A/B Comparison¶

Compare different approaches:

1. Scenario A: Buy ABC Corp for $2M
2. Scenario B: Buy ABC Corp for $1M + Buy XYZ Corp for $1M

Run both simulations and compare:

Stress Testing¶

Scenario-Based Stress Tests¶

Create scenarios that simulate market stress:

Downturn Stress Test¶

{
  "name": "Stress Test - Sector Downturn",
  "description": "Simulate forced sales in distressed sector",
  "trades": [
    {"trade_type": "sell", "cusip": "SECTOR01", "par_value": 500000},
    {"trade_type": "sell", "cusip": "SECTOR02", "par_value": 750000},
    {"trade_type": "sell", "cusip": "SECTOR03", "par_value": 1000000}
  ]
}

Rating Migration Stress¶

Simulate what happens if credits are downgraded:

{
  "name": "Stress Test - Rating Migration",
  "description": "Simulate B-rated credits falling to CCC",
  "trades": [
    {
      "trade_type": "sell",
      "cusip": "WEAK01",
      "par_value": 1000000,
      "rating_moodys": "B3"
    },
    {
      "trade_type": "buy",
      "cusip": "WEAK01",
      "par_value": 1000000,
      "rating_moodys": "Caa1"
    }
  ]
}

Stress Test Schedule¶

Performance Optimization¶

Large Scenario Tips¶

When working with many trades:

1. Batch creation: Use bulk trade creation in API
2. Limit iterations: Plan trades before creating scenarios
3. Clean up old scenarios: Delete completed scenarios regularly

API Best Practices¶

# GOOD: Bulk creation
scenario = create_scenario({
    "name": "Bulk Analysis",
    "trades": [trade1, trade2, trade3, ...]  # All trades at once
})

# AVOID: Sequential creation
scenario = create_scenario({"name": "Sequential Analysis"})
for trade in trades:
    add_trade(scenario.id, trade)  # N API calls

Data Quality¶

Input Validation Checklist¶

Before creating a scenario:

• CUSIP is valid (9 characters, alphanumeric)
• Par value is accurate and positive
• Rating is current and from reliable source
• Industry classification matches your taxonomy
• Maturity date is correct

Common Data Issues¶

Team Coordination¶

Scenario Ownership¶

• Creator is responsible for accuracy
• Approver validates compliance impact
• Executor confirms trade matches approved scenario

Communication Patterns¶

Daily Standup¶

"I have two scenarios pending review: - 2026-01-25 Buy ABC Corp - awaiting PM approval - 2026-01-25 Sector Rotation - simulation complete, reviewing results"

Weekly Review¶

"This week we simulated 12 scenarios: - 8 approved and executed - 2 rejected due to concentration impact - 2 modified and re-run"

Slack/Teams Integration¶

Set up notifications for scenario events:

#trades-review channel:
- New scenario created (pending simulation)
- Simulation completed (ready for review)
- Scenario approved (ready for execution)

Compliance Documentation¶

Audit Requirements¶

Maintain records of:

1. Scenario creation: Who, when, why
2. Simulation results: Full test results
3. Approval chain: Who approved, when
4. Execution confirmation: Trade matched scenario

Retention Policy¶

Regulatory Reporting¶

Export scenario data for regulatory reporting:

# Export all completed scenarios for a date range
curl -X GET "https://api.calcbridge.io/api/v1/scenarios?status_filter=completed" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.items' > scenarios_export.json

Common Mistakes to Avoid¶

Scenario Mistakes¶

Process Mistakes¶

Summary: The What-If Workflow¶

flowchart LR
    A[Opportunity] --> B[Create Scenario]
    B --> C[Add Trades]
    C --> D[Simulate]
    D --> E{Review}
    E -->|Approve| F[Execute]
    E -->|Modify| C
    E -->|Reject| G[Archive]
    F --> H[Document]
    G --> H
    H --> I[Audit Trail]

Key Takeaways¶

1. Always simulate before executing - Never trade blind
2. Use consistent naming - Makes scenarios findable
3. Follow approval workflows - Protects the organization
4. Document everything - Supports compliance and audits
5. Iterate systematically - Version your analysis
6. Clean up regularly - Keep the system manageable

Related Resources¶

• Creating Scenarios
• Trade Simulation
• Impact Analysis
• Compliance Testing
• Scenarios API Reference