Create Bot

# Create & Validate a New Thesis Bot

Autonomously create a new thesis-driven trading bot and progressively validate it through 3 backtest stages. Do NOT ask for help — make all decisions yourself.

## Stage Ladder

Stage 1: 7-day backtest → beats SPY? → Stage 2 Stage 2: 1-month backtest → beats SPY? → Stage 3 Stage 3: 1-year backtest → beats SPY? → DONE ✅

Each stage: max **3 cycles**. Each cycle: run backtest → **validate DB** → analyze → tweak prompt → retry.
If 3 cycles fail a stage: **STOP** and write the final report anyway.
**Validation is mandatory every cycle** — never advance a stage or count a cycle as complete until the DB checks pass.

---

## Step 1 — Invent a Thesis

Design a bot that is **completely different** from the three existing bots:
- `trump-bot` — trades Trump Truth Social posts
- `datacenter-bot` — long data center infrastructure secular thesis
- `claude-bot` — macro regime rotation (TQQQ/QQQ vs SH based on VIX + SPY trend)

Good thesis ideas (pick one or invent your own):
- **Earnings momentum** — buy stocks with recent earnings beats, short misses
- **Options flow** — trade direction implied by unusual options activity (via web search)
- **Sector rotation** — rotate between XLF/XLE/XLK/XLV based on macro signal
- **Small cap momentum** — IWM/TNA when Russell diverges from S&P
- **Credit spread canary** — HYG/JNK spread as risk-on/off signal; rotate into TLT or equities
- **Dollar carry** — UUP (dollar ETF) inverse correlation with commodities/EM
- **Volatility crush** — trade around VIX term structure; buy SVXY after vol spikes

Keep the thesis **mechanistic and signal-driven** — not opinion. The bot needs observable data it can pull via `web_search` and `get_market_snapshot`.

---

## Step 2 — Create the Bot File

### File location
`runner/src/bots/<bot-id>.ts`

### Template
```typescript
import type { ScheduledBotConfig } from "../bots.js"
import { webSearchMcp, alpacaTradeMcp } from "./mcps.js"

export const myBot: ScheduledBotConfig = {
  id: "<bot-id>",          // kebab-case, unique
  name: "<Human Name>",
  description: "<one-line thesis>",
  enabled: false,          // keep false — backtest only, not live scheduled

  cron: "30 9 * * 1-5",   // 9:30 AM ET weekdays

  model: "google/gemini-3-flash-preview",

  alpacaKeyEnv: "ALPACA_TRUMP_BOT_KEY",
  alpacaSecretEnv: "ALPACA_TRUMP_BOT_SECRET",
  alpacaEndpointEnv: "ALPACA_TRUMP_BOT_ENDPOINT",

  system_prompt: `...`,

  mcps: [webSearchMcp, alpacaTradeMcp],
}

System prompt guidelines

• State the thesis clearly upfront
• List exact tools the bot should call and in what order
• Define entry/exit rules as concrete conditions, not vibes
• Specify position sizing (% of $100k portfolio)
• Define what "do_nothing" means for this strategy (patience is a valid call)
• Remind the bot: buy_stock for inverse ETFs (SH, SDS, SQQQ) — never short_stock on ETFs

Register in bots.ts

Add to runner/src/bots.ts:

export { myBot } from "./bots/<bot-id>.js"
import { myBot } from "./bots/<bot-id>.js"
// add myBot to the bots array

Run bun run typecheck after changes.

---

Step 3 — Compute Date Ranges

Run these to get current dates (macOS):

END=$(date -v-1d +%Y-%m-%d)          # yesterday (backtest cap)
START_7D=$(date -v-10d +%Y-%m-%d)    # ~7 trading days
START_1M=$(date -v-32d +%Y-%m-%d)    # ~1 month
START_1Y=$(date -v-368d +%Y-%m-%d)   # ~1 year

---

Step 4 — Run a Backtest

# Always run from repo root
cd /Users/panda/dev/trading-bots
bun run runner/src/index.ts --backtest=<bot-id> --start=<START> --end=<END>

The backtest automatically uses data/dev.db. It will print EOD results per day.

---

Step 5 — Read Results

TRADING_ENV=dev bun -e "
process.env.TRADING_ENV = 'dev'
process.env.TRADING_BOTS_DATA_DIR = new URL('./data', import.meta.url).pathname
const { getDb } = await import('./runner/src/db.ts')
const db = getDb()

const run = db.prepare('SELECT * FROM backtest_runs ORDER BY id DESC LIMIT 1').get()
console.log('Return:', (run.total_return * 100).toFixed(2) + '%')
console.log('SPY:   ', (run.spy_return * 100).toFixed(2) + '%')
console.log('Beats SPY:', run.beats_spy ? 'YES' : 'NO')
console.log('Max DD:', (run.max_drawdown * 100).toFixed(2) + '%')

const decisions = db.prepare(\`SELECT sim_date, action, symbol, amount, reasoning FROM decisions WHERE backtest_run_id = ? ORDER BY sim_date\`).all(run.id)
for (const d of decisions) {
  console.log(d.sim_date, d.action.padEnd(12), d.symbol ?? '', (d.reasoning ?? '').slice(0, 80))
}
"

---

Step 5b — Validate DB Integrity (MANDATORY every cycle)

Run this after every backtest before doing anything else. Do not count the cycle as complete or advance the stage until all checks pass.

cd /Users/panda/dev/trading-bots && TRADING_ENV=dev bun -e "
process.env.TRADING_ENV = 'dev'
process.env.TRADING_BOTS_DATA_DIR = new URL('./data', import.meta.url).pathname
const { getDb } = await import('./runner/src/db.ts')
const db = getDb()

const run = db.prepare('SELECT * FROM backtest_runs ORDER BY id DESC LIMIT 1').get()
const runId = run.id
let issues = []

// 1. Run completed cleanly
if (run.status !== 'completed') issues.push('FAIL run.status=' + run.status + ' (expected completed)')
else console.log('✅ Run status: completed')

// 2. Decisions exist and count is plausible
const decisions = db.prepare('SELECT * FROM decisions WHERE backtest_run_id = ?').all(runId)
const snaps = db.prepare('SELECT * FROM pnl_snapshots WHERE backtest_run_id = ?').all(runId)
if (decisions.length === 0) issues.push('FAIL no decisions recorded')
else console.log('✅ Decisions recorded:', decisions.length)
if (snaps.length === 0) issues.push('FAIL no pnl_snapshots recorded')
else console.log('✅ PnL snapshots recorded:', snaps.length)

// 3. Decisions count matches snapshots count (one decision per trading day)
if (Math.abs(decisions.length - snaps.length) > 3)
  issues.push('WARN decisions (' + decisi