book: scaffold + ch00 (execution trail as spine) — evidence exp 8-31, round 3
This commit is contained in:
TradeAC Book Agent
@@ -0,0 +1,64 @@
|
||||
# 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. **Classify every quantitative claim** with an inline evidence tag:
|
||||
- `PROVEN` — reproduced from a recorded experiment run or a reconciled live round. Cite `experiment_id`/`run_id`/branch or `round_id`.
|
||||
- `HYPOTHESIS` — plausible but untested (or tested once, un-reproduced). 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.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user