/drawdown-circuit-breaker

name: drawdown-circuit-breaker
description: Evaluate account-level drawdown circuit breaker rules from trader-memory-core state and decide whether new trade risk is allowed today. Uses realized P&L, losing-streak cooldowns, and weekly/monthly drawdown limits without any external API.

Drawdown Circuit Breaker

Overview

Evaluate whether the trader should take new trade risk today based on account-level realized P&L and recent terminal trade outcomes. This skill reads trader-memory-core thesis YAML files only. It produces a `circuit_breaker_decision` artifact that complements the market-side `exposure_decision` from exposure-coach.

The circuit breaker is a recommendation and recordkeeping tool. It does not replace human judgment, and it does not enforce broker-side blocks or automated order rejection.

When to Use

• Before screening or sizing any new swing trade candidate
• After a losing trade or partial trim to check whether a cooldown is active
• During daily planning when trader-memory-core contains recent closed or partially closed positions
• As a workflow gate before swing-opportunity-daily proceeds to candidate generation
• When reviewing whether daily, weekly, or monthly loss limits have been breached

Prerequisites

• Python 3.9+
• Local trader-memory-core thesis YAML files, usually under `state/theses/`
• Account size in dollars
• No API keys or network access required

Workflow

Step 1: Read Trader Memory State

Point the script at the thesis state directory:

python3 skills/drawdown-circuit-breaker/scripts/check_circuit_breaker.py \
  --state-dir state/theses \
  --account-size 100000 \
  --output-dir reports/

The script scans every `th_*.yaml` file and reads realized P&L from each thesis `status_history[]` ledger entry. It does not use `_index.json` for P&L, because the index is a lightweight lookup file and does not contain the required realized-P&L ledger.

After validating each file, the script groups valid theses by the case-sensitive, whitespace-trimmed `thesis_id`. If two or more valid files share an ID, it excludes the entire duplicate group from P&L and losing-streak calculations, reports every actual source path, and returns `PARTIAL` + `HALTED` until the duplicate state is repaired and the decision is rerun. `metrics.theses_scanned` counts only accepted theses with unique IDs.

If the state directory is missing or is an empty directory, the skill returns `TRADING_ALLOWED` with `data_quality: EMPTY_STATE` so a new user is not blocked by the absence of history. If the configured state path exists but is not a directory, the skill fails closed as incomplete state data.

If state exists but a thesis, ledger event, or terminal result must be skipped or conflicts with another recorded value, the skill fails closed with `data_quality: PARTIAL`, `recommendation: HALTED`, and an `incomplete_state_data` rule. Repair the warnings and rerun before taking new risk. The one recoverable exception is a finite terminal `outcome.pnl_dollars` fallback for a legacy thesis with no realized-P&L ledger entry; it remains visible as `PARTIAL` but does not by itself override the calculated recommendation. For `ACTIVE`, `PARTIALLY_CLOSED`, `CLOSED`, and `INVALIDATED` theses, each history event must be an object with a recognized `status` and parseable `at`, and the last history status must match the thesis status. `ACTIVE` and `PARTIALLY_CLOSED` theses must also carry entry actuals; `PARTIALLY_CLOSED` must carry a position. Malformed, stale, or skeletal lifecycle history disqualifies terminal fallback and halts. Ledger-shaped events whose `realized_pnl` is missing, untyped, or non-finite also halt instead of being coerced.

Step 2: Evaluate Circuit Breaker Rules

The default rules are:

| Rule | Default | Triggered State | Release | |------|---------|-----------------|---------| | Max daily loss | 2.0% of account | HALTED | Next ET weekday | | Losing streak cooldown | 2 terminal losing theses | COOLDOWN | 24 hours after latest loss exit | | Weekly drawdown halt | 5.0% of account | HALTED | Next Monday ET | | Monthly drawdown halt | 8.0% of account | HALTED | First day of next month ET |

Day, week, and month boundaries use `America/New_York`. Date-only producer timestamps from `trader-memory-core` are counted on the named ET date. Set `--as-of` for deterministic evaluation; date-only `--as-of` values cover the full ET day, while timestamp values exclude future events after that time:

python3 skills/drawdown-circuit-breaker/scripts/check_circuit_breaker.py \
  --state-dir state/theses \
  --account-size 100000 \
  --as-of 2026-07-02T12:00:00-04:00 \
  --output-dir reports/

Step 3: Override Thresholds When Needed

Override individual thresholds on the CLI:

python3 skills/drawdown-circuit-breaker/scripts/check_circuit_breaker.py \
  --account-size 100000 \
  --max-daily-loss-pct 1.5 \
  --losing-streak-n 3 \
  --cooldown-hours 48 \
  --weekly-drawdown-pct 4 \
  --monthly-drawdown-pct 6

Or provide a JSON config file:

{
  "max_daily_loss_pct": 1.5,
  "losing_streak_n": 3,
  "cooldown_hours": 48,
  "weekly_drawdown_pct": 4.0,
  "monthly_drawdown_pct": 6.0
}

CLI arguments override config-file values.

Step 4: Interpret the Decision

Use the generated decision as a gate for new trade risk:

| Recommendation | Meaning | |----------------|---------| | TRADING_ALLOWED | No circuit breaker rule is active; new trade risk may proceed through the rest of the workflow | | COOLDOWN | Do not open new positions; continue managing existing positions and review the recent losses | | HALTED | Stop new entries because a drawdown limit is active or account-state data is incomplete; repair/rerun any data warnings before proceeding |

Existing position management remains a human decision. The circuit breaker is designed to prevent new risk escalation after realized damage, not to force liquidation.

Time-based rules carry a