drawdown-circuit-breaker

Q: How do I install drawdown-circuit-breaker?

Run npx skills add https://github.com/tradermonty/claude-trading-skills --skill drawdown-circuit-breaker in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/drawdown-circuit-breaker/ (personal) or .claude/skills/drawdown-circuit-breaker/ (project).

by tradermontyBackend & APIs

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.

Installs: 2.7K
Last 24h: +22
Trending rank: #5508
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/tradermonty/claude-trading-skills --skill drawdown-circuit-breaker

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads drawdown-circuit-breaker automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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 an ISO 8601 active_until. The non-time-based incomplete_state_data rule uses active_until: null; its Markdown report says the halt lasts until the state is repaired and the decision is rerun.

Output Format

The script writes circuit_breaker_decision_YYYY-MM-DD_HHMMSS.json and, unless --json-only is set, a matching markdown report.

{
  "schema_version": "1.0",
  "generated_at": "2026-07-02T16:00:00+00:00",
  "as_of_date": "2026-07-02",
  "recommendation": "COOLDOWN",
  "triggered_rules": [
    {
      "rule": "losing_streak_cooldown",
      "threshold": 2,
      "observed": 2,
      "active_until": "2026-07-02T15:30:00-04:00",
      "detail": "2 consecutive losing closes; last loss exit 2026-07-01T15:30:00-04:00."
    }
  ],
  "metrics": {
    "realized_pnl_today": 0.0,
    "realized_pnl_wtd": -250.0,
    "realized_pnl_mtd": -250.0,
    "consecutive_losses": 2,
    "last_loss_exit_at": "2026-07-01T15:30:00-04:00",
    "theses_scanned": 12
  },
  "account_size": 100000.0,
  "config": {
    "max_daily_loss_pct": 2.0,
    "losing_streak_n": 2,
    "cooldown_hours": 24.0,
    "weekly_drawdown_pct": 5.0,
    "monthly_drawdown_pct": 8.0
  },
  "data_quality": "OK",
  "warnings": [],
  "rationale": "Recent losing closes triggered a cooldown. Avoid new entries until the cooldown expires."
}

Exchange Calendar Contract

Install requirements.txt before running the checker. Daily, weekly, and monthly halt dates use actual XNYS sessions. active_until remains compatible: the halt ends at 00:00 America/New_York on the next eligible session date, not at that session's opening bell. Use --as-of for deterministic evaluation.

Resources

scripts/check_circuit_breaker.py - Main CLI and rule engine
references/circuit_breaker_framework.md - Rule definitions, defaults, and data-source notes
skills/trader-memory-core/schemas/thesis.schema.json - Source schema for thesis state

Key Principles

Realized damage only - Use recorded realized P&L, not unrealized P&L or thesis-level cumulative fields for daily calculations.
Survival first - A circuit breaker exists to prevent escalation after losses.
Advisory, not automatic execution - The output informs the workflow gate; it does not place, cancel, or block broker orders.
Fail closed on incomplete state - Empty state allows a new user to begin, but malformed, discarded, conflicting, or non-finite risk data returns PARTIAL + HALTED without crashing. A finite legacy outcome fallback is reported as recoverable PARTIAL and remains non-blocking.

FAQ

What does the drawdown-circuit-breaker skill do?

How do I install drawdown-circuit-breaker?

Run npx skills add https://github.com/tradermonty/claude-trading-skills --skill drawdown-circuit-breaker in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/drawdown-circuit-breaker/ (personal) or .claude/skills/drawdown-circuit-breaker/ (project).

Which AI agents can use drawdown-circuit-breaker?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is drawdown-circuit-breaker safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains drawdown-circuit-breaker?

It is published by tradermonty in tradermonty/claude-trading-skills. It has 2,721 recorded installs.