# Strategies AGENTS

## Purpose

This folder holds strategy modules and their adjacent contract notes.

The code in `strategies/*.py` should stay focused on strategy behavior. Shared mechanics belong in `src/trader_mcp/`.

---

## Shared Rules

- Keep strategy modules narrow: strategy logic, state transitions, and placement decisions.
- Put shared sizing, balance, fee, and venue-awareness logic in `src/trader_mcp/strategy_context.py` and `src/trader_mcp/strategy_sizing.py`.
- Treat `StrategyContext` as the authoritative place for venue/account-aware order sizing and balance access.
- Do not duplicate dust handling, minimum-order checks, or fee math inside a strategy unless there is a strategy-specific reason that cannot live in shared helpers.
- Keep adjacent `strategies/*.md` files aligned with what the code actually does.
- Preserve uncertainty in docs when behavior is still provisional. Use `TODO` instead of guessing.

---

## Shared Helper Map

- `StrategyContext.suggest_order_amount()` is the venue/account-aware sizing primitive.
- `src/trader_mcp/strategy_sizing.py` is the policy layer for quote-sized helpers and balance-target helpers.
- `StrategyContext.get_account_info()` and `StrategyContext.get_open_orders()` are the primary live inputs for balance and order-shape decisions.
- `StrategyContext.cancel_all_orders_confirmed()` is the preferred cancel contract when a strategy needs authoritative cleanup semantics.

---

## Grid Trader

### Grid Shape

- `grid_trader` must compare the active order shape against the best possible funded grid.
- The best possible grid includes both free balances and funds already locked in active orders.
- The shape check must use the same side-aware funded capacity that seeding uses.
- A mismatch between the best possible shape and the actual active orders should trigger a full rebuild.
- Do not treat the grid as paired buy/sell levels. Each side is filled independently.

### Seeding And Rebuilds

- Seeding should place as many levels as are actually fundable on each side.
- Rebuilds should remain full-grid rebuilds, not partial top-ups.
- Restart should not suppress mismatch-driven reseed checks.
- Track and log rebuild reasons clearly in the strategy debug log.

### Sizing Boundary

- `grid_trader` should not implement its own dust or fee policy.
- If sizing behavior changes, update the shared helpers first and keep the strategy thin.
- The strategy may ask for a size and may compare funded capacity, but it should not re-encode venue rules.

### Live Trace

- `state["debug_log"]` is the live trace for the strategy.
- The DB snapshot stores the current state, not a separate event log table.

---

## Wiki References

- [Grid Trader](/home/lucky/wiki/entities/grid-trader.md) for the implementation page.
- [Mean Reversion](/home/lucky/wiki/concepts/mean-reversion.md) and [Grid Trading](/home/lucky/wiki/concepts/grid-trading.md) for the strategy concepts.
- [Inventory Rebalancing](/home/lucky/wiki/concepts/inventory-rebalancing.md) for the inventory-bias concept.
- [Dumb Trader](/home/lucky/wiki/entities/dumb-trader.md) and [Side-Only Execution](/home/lucky/wiki/concepts/side-only-execution.md) for the side-only execution contract.
- [Exposure Protector](/home/lucky/wiki/entities/exposure-protector.md) for the companion defensive strategy.

---

## Future Strategy Sections

- `dumb_trader`: TODO
- `trend_follower`: TODO
- `exposure_protector`: TODO
- any new strategy: document its own shape, sizing, and restart invariants here