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.
4. 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).
5. 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.
6. Every quoted number lands in the evidence ledger (book/EVIDENCE.md) with a link to where it was produced.
7. 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.