Portfolio Risk Assessment Skill

Safety-critical skill for managing trading risk and preventing catastrophic losses.

Overview

This skill provides:

• Real-time portfolio health assessment
• Circuit breaker monitoring and enforcement
• Pre-trade validation
• Post-trade result recording
• Risk metrics calculation

Circuit Breakers (Automatic Trading Halt)

The system implements multiple circuit breakers:

1. Daily Loss Limit: Halt trading if daily loss exceeds 2% of account value
2. Maximum Drawdown: Halt if total drawdown exceeds 10%
3. Consecutive Losses: Halt after 3 consecutive losing trades
4. Volatility Spike: Halt if market volatility exceeds 3x normal
5. Anomaly Score: Halt if trading anomalies detected

Tools

1. assess_portfolio_health

Comprehensive health check of current portfolio.

Parameters:

• None (uses current account state)

Returns:

{
  "success": true,
  "data": {
    "overall_status": "HEALTHY",
    "account_equity": 100000.50,
    "total_pl": 150.25,
    "total_pl_pct": 0.15,
    "daily_pl": 25.50,
    "daily_pl_pct": 0.03,
    "max_drawdown": 2.5,
    "current_drawdown": 0.5,
    "position_count": 3,
    "cash_percentage": 85.0,
    "buying_power": 199500.00,
    "risk_score": 2.5,
    "warnings": []
  }
}

Health Status Levels:

• HEALTHY: All metrics within safe ranges
• CAUTION: Approaching risk limits (yellow flag)
• WARNING: Risk limits being tested (orange flag)
• CRITICAL: Circuit breakers may trigger (red flag)
• HALTED: Trading automatically stopped

2. check_circuit_breakers

Checks if any circuit breakers should trigger.

Parameters:

• force_check (optional): Force re-evaluation even if recently checked

Returns:

{
  "success": true,
  "data": {
    "should_halt_trading": false,
    "active_breakers": [],
    "warning_breakers": ["daily_loss_approaching"],
    "breaker_status": {
      "daily_loss": {
        "triggered": false,
        "current_value": -1.5,
        "threshold": -2.0,
        "pct_to_threshold": 75.0
      },
      "max_drawdown": {
        "triggered": false,
        "current_value": 3.5,
        "threshold": 10.0,
        "pct_to_threshold": 35.0
      },
      "consecutive_losses": {
        "triggered": false,
        "current_value": 1,
        "threshold": 3,
        "pct_to_threshold": 33.3
      }
    }
  }
}

3. validate_trade

Validates a proposed trade against risk management rules.

Parameters:

• symbol (required): Ticker symbol
• side (required): "buy" or "sell"
• quantity (required): Number of shares (can be fractional)
• order_type (required): "market", "limit", "stop", "stop_limit"
• limit_price (optional): Limit price for limit orders
• stop_price (optional): Stop price for stop orders

Returns:

{
  "success": true,
  "data": {
    "is_valid": true,
    "trade_approved": true,
    "estimated_cost": 150.25,
    "estimated_risk": 3.50,
    "position_size_pct": 0.15,
    "warnings": [],
    "recommendations": [
      "Consider reducing position size to 0.10% of portfolio"
    ],
    "validation_checks": {
      "sufficient_buying_power": true,
      "within_position_limits": true,
      "within_daily_trade_limit": true,
      "passes_risk_limits": true,
      "no_active_circuit_breakers": true
    }
  }
}

Validation Failures:

{
  "success": true,
  "data": {
    "is_valid": false,
    "trade_approved": false,
    "rejection_reasons": [
      "Circuit breaker active: daily_loss_limit",
      "Insufficient buying power: need $1000, have $500"
    ]
  }
}

4. record_trade_result

Records the outcome of a completed trade for risk tracking.

Parameters:

• trade_id (required): Unique trade identifier
• symbol (required): Ticker symbol
• side (required): "buy" or "sell"
• quantity (required): Shares traded
• entry_price (required): Fill price
• exit_price (optional): Exit price if closed
• profit_loss (optional): Realized P/L
• status (required): "filled", "partial", "cancelled", "rejected"

Returns:

{
  "success": true,
  "data": {
    "recorded": true,
    "trade_id": "abc123",
    "consecutive_wins": 2,
    "consecutive_losses": 0,
    "updated_metrics": {
      "total_trades": 45,
      "winning_trades": 28,
      "win_rate": 62.2
    }
  }
}

Integration with Risk Manager

This skill wraps and extends the existing src/core/risk_manager.py:

from claude_skills import load_skill

risk_skill = load_skill("portfolio_risk_assessment")

# Check health before trading
health = risk_skill.assess_portfolio_health()
if health["data"]["overall_status"] != "HEALTHY":
    print(f"Warning: Portfolio status is {health['data']['overall_status']}")

# Validate trade
validation = risk_skill.validate_trade(
    symbol="AAPL",
    side="buy",
    quantity=0.5,
    order_type="market"
)

if validation["data"]["trade_approved"]:
    # Execute trade
    pass
else:
    print("Trade rejected:", validation["data"]["rejection_reasons"])

Safety Features

1. Automatic Halting: System automatically stops trading when circuit breakers trigger
2. Pre-Trade Validation: Every trade validated before execution
3. Real-Time Monitoring: Continuous health assessment
4. Audit Trail: All decisions logged for compliance
5. Fail-Safe Defaults: System errs on the side of caution

Alert Thresholds

Usage in Trading Loop

# Daily trading routine
while market_open:
    # 1. Check circuit breakers
    breakers = risk_skill.check_circuit_breakers()
    if breakers["data"]["should_halt_trading"]:
        print("Trading halted by circuit breakers")
        break

    # 2. Assess portfolio health
    health = risk_skill.assess_portfolio_health()
    print(f"Portfolio status: {health['data']['overall_status']}")

    # 3. Generate signals (from RL agent)
    signal = rl_agent.get_signal()

    # 4. Validate trade
    validation = risk_skill.validate_trade(**signal)

    # 5. Execute if approved
    if validation["data"]["trade_approved"]:
        result = execute_trade(signal)

        # 6. Record result
        risk_skill.record_trade_result(**result)

CLI Usage

# Check portfolio health
python scripts/risk_assessment.py assess_portfolio_health

# Check circuit breakers
python scripts/risk_assessment.py check_circuit_breakers

# Validate a trade
python scripts/risk_assessment.py validate_trade \
    --symbol AAPL \
    --side buy \
    --quantity 0.5 \
    --order-type market