tac-exp-dev/AGENTS.md

# TradeAC Quant Trading Guide — Agent Working Agreement

You are writing a practitioner's guide to quantitative trading in a way that is **real**: every number, result and claim must be traceable to evidence produced on the TradeAC stack (this repo's lake + R&D server + live execution trail) or to a cited external source. This file is the contract for that work.

## Mission

A book that a quant-desk reader can act on: signal generation → strategy → sizing → execution → risk → reconciliation, grounded in what TradeAC actually ran and actually traded. Where TradeAC has *not* proved something, the book says so and marks it a hypothesis.

## Truth rules (non-negotiable)

1. **Never fabricate.** No invented backtests, metrics, fill prices, papers, or quotes. If we did not run it or cannot cite it, we do not state it.
2. **The clean-lake boundary (2026-08-18, exp 21) is the evidence watermark.** `PROVEN` status is reserved for experiments and live rounds **after** the lake rebuild (exp 21 onward) and post-reset live rounds. Anything before it (exp 8–18 and their backtests, the pre-reset live rounds) is **historical context and idea material only** — it was demonstrably inflated by lake data-quality problems (`EVIDENCE#010 → exp 21`) and may never be cited as fact. Ideas from pre-reset experiments and from all opencode chat transcripts (see `book/data/chat_mining/`) are welcome as hypotheses, labeled as such.
3. **Classify every quantitative claim** with an inline evidence tag:
   - `PROVEN` — reproduced from a recorded experiment run **on the clean lake** or a reconciled post-reset live round. Cite `experiment_id`/`run_id`/branch or `round_id`.
   - `HYPOTHESIS` — plausible but untested (or tested once, un-reproduced), or a pre-reset/chat-derived idea. Always labeled as such; never stated as fact.
   - `REFERENCED` — industry/academic practice. Cite the external source (websearch/HITL), never from memory.
3. **Backtests are historical, not promises.** Anywhere a backtest metric is quoted, say so and note the universe + date window + whether the hypothesis was pre-registered before the run (TradeAC has 31+ experiments — be explicit about post-hoc cherry-picking risk).
4. **Live beats backtest.** A claim about trading performance must trace to the tac-rd-book execution trail (round_id, decisions, fills, reconcile: slippage bps, cost), not just to a backtest.
5. **Every quoted number lands in the evidence ledger** (`book/EVIDENCE.md`) with a link to where it was produced.
6. **The book is a living document.** Sections are updated as new experimental results land; a chapter marked `done` is done for its window, not forever.

## Evidence sources (use in this order of trust)

1. **Traced experiments** — the `experiments/` git repo, per-experiment branches (`exp/7`…`exp/31`), and MLflow runs via `tac-qlib-rd`: `rd_exp_list`, `rd_exp_get_run`, `rd_exp_result`, `rd_exp_model`, `rd_exp_input`, `rd_exp_get_notes`, `rd_exp_lineage`, `rd_trace_search`. Skill: `tradeac-rd-explain` (how to read runs), `tac-qlib-custom` (how experiments are wired).
2. **Live execution trail** — `tac-rd-book`: `round_list`, `round_get`, `round_metrics`, `trail_query`, `book_reconcile`. This is ground truth for execution cost, slippage and whether the funnel (targets → decisions → fills) holds up.
3. **Lake + market data** — `tac-engine`: `get_lake_bars/_coverage/_features`, `get_account`, `list_positions`, `list_orders`, `get_portfolio_history`, `get_news`. Skill: `tradeac-lake`, `tradeac-alpaca`.
4. **Ad-hoc scripting** — a scripted validation is allowed to *confirm or extend* an experiment, but its inputs, code and outputs must be persisted under `book/data/` and referenced from the ledger. It is evidence, not gospel.
5. **External references** — use websearch/HITL for academic foundations, market microstructure facts, regulation, industry practice. Always cite.

## Workflow for each chapter

1. Draft the chapter outline and a **claim inventory** — each claim listed with its expected truth status.
2. Gather evidence claim-by-claim using the MCP tools + experiments repo (parallelize tool calls; read runs, notes, backtest reports, live rounds).
3. Write the chapter; embed evidence tags inline: `(EVIDENCE#012 → exp/19)`.
4. **HITL review gates** before finalizing anything a reader could act on: live performance numbers, cost/slippage figures, risk-limit advice, size/position formulas, drawdown guidance.
5. Update `EVIDENCE.md` and `CLAIMS.md` after each chapter.
6. Commit per chapter with a message that names the chapter and the experiments cited.

## Repository layout (book project)

```
book/
  README.md          # TOC, per-chapter status (drafting/in-review/done), how to read
  EVIDENCE.md        # ledger: id → claim → source (experiment/run/branch, round_id, script, citation) → verified?
  CLAIMS.md          # the proven-vs-hypothesis matrix, updated every chapter
  chapters/
    00-intro.md      # why a real execution trail matters (tradeac-rd-book as the spine)
    ...              # one file per chapter, ordered per README TOC
  data/              # ad-hoc validation scripts + their outputs
  references/        # external citations collected during research
```

## Writing conventions

- **No false precision**: report IC/Rank IC to sensible decimals, always with universe + date window.
- **Separate "what TradeAC observed" from "what practice generally does"** in the text.
- Hedge hypotheses; avoid absolutes; include standard disclaimers wherever returns or risk are discussed.
- Mark open questions as `TODO(evidence-needed: <what would settle this>)`.
- Do not add emojis or filler; keep prose desk-grade and direct.

## Don'ts

- Don't invent a backtest we never ran, or quote one run as a universal rule.
- Don't quote live P&L without a `round_id` + reconcile behind it.
- Don't cite a paper/URL from memory — fetch it or ask the user.
- Don't claim a "fix" worked if it only shows up in one experiment; demand reproduction or label it hypothesis.