CLAUDE.md · Lumiwealth/lumibot

Sections

1. Public Repo Secret Hygiene (CRITICAL)
2. BotSpot integration release qualification
3. 🚨🚨🚨 RULE #1 — NEVER FABRICATE BACKTEST DATA 🚨🚨🚨
4. Quick Start
5. Image Generation Rule (CRITICAL)
6. Backtesting Accuracy (Definition)
7. Multi-Agent Collaboration (CRITICAL)
8. Branch Management (CRITICAL - Branches Are Extremely Sensitive)
9. AGENTS.md / CLAUDE.md Best Practices (how we keep instructions useful)
10. Env var documentation (REQUIRED)
11. Changelog Maintenance (MANDATORY)
12. GitHub Release Markers (RECOMMENDED)
13. Documentation Layout
14. Public Documentation Updates (MANDATORY)
15. Project Overview
16. Key Locations
17. Critical Rules
18. Common Tasks
19. Known Issues & Fixes
20. Split Adjustment Testing (Added Dec 11, 2025)

First lines (shown under the repo's GPL-3.0 license)

# Entry-page translation policy

Follow the shared entry-page and translation policy in `AGENTS.md`: README and documentation-homepage changes include every shipped localized counterpart in the same commit. Review meaning, commands, prerequisites and links together; do not update English alone or treat a matching source fingerprint as proof of translation quality.

# Capability first: agents may use undated sources; live trading has no date rules (Rob, 2026-10-22)

- Never make LumiBot agents less capable to look safer. Do not add an instruction, tool filter or gate that blocks ordinary research without a concrete failure behind it.
- Backtests: prefer sources that say when each document became public, and never use anything known to be from after the simulated time (the `document_after_cutoff` refusal and price-data clamping stay). A source with no date at all is still allowed: the agent estimates when it became public, uses it only if that estimate is at or before the simulated time, and says in its answer that the date is an estimate and why. Never invent a date or present an estimate as exact.
- Live trading has no publication-date restrictions. Backtest-only date rules must stay inside the backtest branch of the prompt and tool results.
- Enforced by `tests/test_agent_undated_sources_capability.py` and the evals `web_documents_undated_source_estimated_date`, `web_documents_known_future_document_not_opened` and `web_documents_live_undated_source_used_freely`. Do not loosen them.

# Generic platform behavior and evidence-bound selection (Rob, 2026-10-18, ABSOLUTE)

- LumiBot, BotSpot, BotSpot Agent, Node, Bot Manager and their infrastructure serve every supported strategy, broker, account and customer. Fix generic capabilities at their existing owner. Never add strategy/customer names, IDs, ticker-specific intent branches, private network routes, resource exceptions or hidden defaults to shared runtime, prompts, skills, tools or infrastructure to solve one incident.
- Strategy-specific investment rules and research instructions belong in that strategy's own saved files/prompts. Clearly labeled example strategies may demonstrate generic capabilities; they must never become production defaults or special cases in core.
- Evals reproduce reusable failure modes with neutral, varied synthetic identities and configurations, including multiple live accounts and unrelated strategies. Do not teach a remembered customer strategy as the expected identity. Keep exact incident evidence as provenance, separate from fixtures and behavior rules. A pass tied to one name or configuration does not establish generic correctness.
- Saved memory, prior conversations, sidebar order and example names are clues, not authority to select the current strategy/account. For an unbound new chat saying "this strategy", inspect current owned inventory without silently filtering to a remembered name. If multiple candidates remain, ask the user to select a safe name/account label. Honor an explicitly selected current-chat target and explicit switches; never borrow another account's metrics.
- Before shipping a shared fix, state the generic contract, affected configuration classes, negative controls and source-to-served proof. Do not introduce tool filters, regex intent routing, response rewriting or strategy-specific infrastructure as enforcement shortcuts. Do not alter running customer workloads without their normal exact authorization.

# LumiBot is the platform: never put strategy-specific code in it (Rob, 2026-10-17, ABSOLUTE)

- LumiBot is one generic platform for every strategy. Never add strategy-, person-, company- or website-specific logic, text, tools, skills, prompts, eval fixtures or branches to LumiBot core (for example "House Clerk", "Pelosi", or one site's filing format). Strategy-specific knowledge lives only in that strategy's own prompts.
- Improve LumiBot only with generic capabilities that help every strategy: browser use, file downloads, ZIP, PDF and CSV reading, API calls, and look-ahead safety that works for any source. While fixing a strategy, explain exactly what a proposed LumiBot change does and get Rob's explicit approval before touching LumiBot core. Never release, tag or deploy LumiBot without Rob's explicit approval.
- AI strategy examples (LumiBot `example_strategies` and BotSpot AI strategies) use AI and AI only: exactly one agent dedicated to trading, plus any number of research or planning agents, all called every iteration. The Ray Dalio and Citadel examples are the reference pattern; do not change them. Agents hand work to each other only through their answers, and `self.vars` may carry an agent's last answer forward so it does not redo old work. No Python in between that fetches or parses data, filters filings, computes weights, or skips agents with if statements. The whole point is to show how simple LumiBot makes it: agents research, one agent trades.
- Let the agent find its own way: browse, download, read. A short hint about where to look may go in the prompt. Parsing or availability code may not.
- If a platform behavior blocks a simple example, report the evidence to Rob and propose a generic platform fix. Never work around it with strategy Python or a strategy-specific platform change.
- Why: on 2026-10-17 an agent "fixed" the Pelosi bot with Python that downloaded and filtered House filings and skipped the AI on most days. It then edited LumiBot's shared web-documents skill and evals with House Clerk text on a `pelosi-house-filings` branch. Rob: "LumiBot is not a strategy. LumiBot is the platform. The platform needs to work for all strategies."

# CLAUDE.md - AI Assistant Instructions for LumiBot

## Public Repo Secret Hygiene (CRITICAL)

LumiBot is open source. Never put private, account-specific, or
machine-specific information in this file or any other tracked repo file.

- Do not include usernames, passwords, API keys, tokens, account emails,
  customer identifiers, broker credentials, paid vendor credentials, private
  hostnames, private URLs, cookies, local profile paths, or absolute personal
  filesystem paths.
- Do not document real `.env` locations, credential-file paths, secret store
  values, or commands that write real credentials to disk.
- Use placeholders such as `<your-vendor-username>`,
  `<your-downloader-host>`, `<repo>`, and `$TMPDIR`, and point contributors to
  public environment variable names or their own secret manager.
- If sensitive data is needed for private BotSpot/Lumiwealth operations, keep it
  in private repos/docs/secret stores, not in this public LumiBot checkout.

## BotSpot integration release qualification

- LumiBot has its own package/release cycle. When a BotSpot release explicitly
  includes a changed LumiBot artifact or contract, run the complete locally
  runnable LumiBot gate on that exact package candidate before downstream Dev.
- The consuming BotSpot candidate must pass every Playwright test owned by its
  scope locally before Dev; focused tests never qualify. If Agent is scoped,
  mandatory local eval freshness and required targeted repeats must also pass.
- Hosted qualification reruns the same committed BotSpot inventory against the
  exact Dev tuple. Hosted-only failures block production and return to local
  parity, contention, or nondeterminism diagnosis.

## 🚨🚨🚨 RULE #1 — NEVER FABRICATE BACKTEST DATA 🚨🚨🚨

**Fake / synthesized / default-filled market data is STRICTLY FORBIDDEN.**
**Missing data is fine. Fake data is a lawsuit waiting to happen.**

- If real bars are unavailable for a day / symbol / timeframe, return empty. Do NOT invent a placeholder bar, do NOT carry-forward the last price, do NOT substitute a constant (e.g. `VIX=14.2`), do NOT interpolate.
- This applies to **every provider path** (IBKR, ThetaData, Polygon, Yahoo, DataBento, custom) and **every timestep** (minute, day, tick).
- Placeholder rows used for cache bookkeeping ("we tried this day, nothing was there") must NEVER be returned to a strategy as real bars. Filter them out, and surface the absence to the caller.
- If you find code that fabricates/synthesizes/forward-fills missing market data to keep a strategy alive — **delete it**. The honest outcome (empty frame, explicit warning, strategy skip) is the ONLY correct outcome.
- A backtest that makes decisions on fake data produces fake PnL. Showing fake PnL to customers is a legal and reputational catastrophe.
- Full details and enforcement rules live in `docs/BACKTESTING_ARCHITECTURE.md` under "RULE #1". Read it before touching any data-fetching code.

## Quick Start

**First, read these files:**
1. `docs/BACKTESTING_ARCHITECTURE.md` - Understand the backtesting data flow AND the no-fake-data rule
2. `AGENTS.md` - Critical rules for ThetaData (DO NOT SKIP)

## Image Generation Rule (CRITICAL)

- For any generated or AI-edited image, infographic, diagram, marketing visual, README visual, documentation visual, or repo asset image, use the approved Image Generator only.
- `Nano Banana` is a compatibility phrase for the approved Image Generator. It does not select Google or Gemini unless Rob explicitly insists on that provider after rejecting the approved default result.
- The Image Generator controls provider, model, resolution, and quality. Callers may provide only the prompt, purpose, aspect ratio, approved reference images, and an explicit Rob-requested Medium-quality exception. Never request Pro, High, Auto, an arbitrary resolution, or another model.
- Never use local SVG/HTML/canvas placeholders, Python drawing scripts, Mermaid screenshots, manually assembled box diagrams, or other fallback pipelines for generated documentation/product images.
- For Lumibot, BotSpot, and Lumiwealth visuals, use the canonical Spot mascot reference or the approved brand reference images when a mascot is helpful. Spot should usually be doing something relevant to the concept being explained, such as reviewing filings, managing agents, guarding risk, or filing memories. Do not accept off-brand mascot variants or generic static poses when a topic-specific Spot action would make the visual clearer.
- Every generated image must be visually inspected before it is committed. Reject outputs with broken/missing text, awkward arrows, cluttered layouts, inaccurate product claims, or anything that looks like a placeholder.
- If the Image Generator is unavailable or broken, stop and report that blocker instead of making replacement images another way.

## Backtesting Accuracy (Definition)

Backtesting “accuracy” is measured against live broker behavior when possible (replay a live-traded interval and reproduce fills + PnL within tolerances). Vendor parity (e.g., stored DataBento artifacts) is a regression signal, not absolute truth.

## Multi-Agent Collaboration (CRITICAL)
This repo is often worked on by **multiple AI sessions** at the same time.

- Canonical checkout: normal LumiBot work must happen in this repository
  checkout. Keep that checkout on the active `version/X.Y.Z` branch, clean, and
  ready for release. Do not create sibling
  worktrees like `lumibot-version-X.Y.Z` for normal development. Temporary
  worktrees outside this folder are acceptable only for isolated review of
  unusually large or risky external PRs, and must not become the active release
  workspace.
- Branch etiquette: if a task mandates a specific version branch (e.g., `4.4.25`), treat it as the shared branch—stay on it and do not create new branches/PRs unless explicitly instructed. Otherwise, start new work branches from a stable base branch (e.g., `dev`/`main`/`master`), and avoid chaining feature/WIP branches.
- No “feature branch chaining”: if you’re already on a feature/WIP or version branch (e.g., `feature/*`, `fix/*`, `wip/*`, `version/*`, `release/*`, or a version-named branch like `X.Y.Z`), keep working there; don’t create another feature branch from it unless explicitly instructed.
- Branch naming (LumiBot convention): prefer version-scoped branches so multiple agents can collaborate without “feature branch naming drift”.
  - Default for active release work: the shared version branch (e.g., `4.4.25` or `version/X.Y.Z`).
  - Avoid `feature/*` and `fix/*` here unless explicitly requested.
  - If you truly need isolation and are explicitly instructed to branch, use a scoped suffix (e.g., `4.4.25/<topic>` or `version/X.Y.Z/<topic>`)—but don’t chain off that unless explicitly instructed.
- Never run `git checkout`; avoid destructive commands (`git reset --hard`, `git clean -f`, `git stash`).
- Dirty-tree safety: if you need to branch with uncommitted changes, create the new branch from the current working tree so the changes come with you; avoid `git stash`. Verify with `git status --porcelain=v1`.
- Before committing: `git status` must be clean/understood; read diffs for changes you didn’t personally create.
- Coordinate via `docs/handoffs/` when touching shared areas (CI/baselines/backtest harnesses).
- Any behavioral change must include docs updates + regression tests, with comments explaining “why/invariants”.

## Branch Management (CRITICAL - Branches Are Extremely Sensitive)

**ALWAYS stay on a `version/X.Y.Z` branch.** Never work on `master`, `main`, or `dev` directly. If you find yourself on `master` or `main`, something is wrong. Fix it immediately by switching to the current version branch.

### At session start (MANDATORY every time)
```bash
git branch --show-current  # MUST be version/X.Y.Z
grep ‘version=’ setup.py   # MUST match the branch name
```
If the branch is NOT `version/X.Y.Z`, find the latest version branch and switch to it:
```bash
git fetch origin
git branch -r | grep ‘version/’ | sort -V | tail -1  # Find latest
git switch version/X.Y.Z                               # Switch to it
```

### Before every commit (MANDATORY)
```bash
git branch --show-current  # Verify still on version/X.Y.Z
```

### Deployment procedure (follow `docs/DEPLOYMENT.md` strictly)
1. **All work** happens on `version/X.Y.Z`. Never push directly to `dev`.
2. **Before release**: merge `dev` into `version/X.Y.Z` to pick up other engineers’ changes.
3. **Release**: merge `version/X.Y.Z` into `dev` via PR, tag `vX.Y.Z` on the dev merge commit.
4. **After release (CRITICAL, DO NOT SKIP)**: the release workflow auto-creates `version/X.Y.(Z+1)` on the REMOTE. You must switch your LOCAL checkout to it. Steps:
   - `git status --porcelain=v1` — if non-empty, commit as `wip: carry-over to X.Y.(Z+1)` on the OLD branch first.
   - `git fetch origin && git switch version/X.Y.(Z+1)` (never `git checkout`).
   - If you had local-only commits on `version/X.Y.Z` (including the carry-over above), cherry-pick them onto the new branch.
   - Verify: `git branch --show-current` must print `version/X.Y.(Z+1)`; `grep 'version=' setup.py` must match.
   - Staying on the released branch locally causes every new commit to land on frozen code and uncommitted work to silently belong to the wrong version (the 2026-04-20 4.5.1 incident — WEEX/Coinbase/iter_count work had to be manually cherry-picked to 4.5.2 because the local checkout was never switched).
5. **BotManager deploy**: update `LUMIBOT_VERSION` variable, trigger dev then prod workflows.
6. **Post-deploy**: verify `lumibot_version` in a backtest’s `settings.json` matches (via BotSpot MCP `start_backtest` + `get_backtest_artifact` with `label="settings.json"`).

### What went wrong (2026-04-15 incident)
During the flat-price bug investigation, the local checkout silently switched from `version/4.4.62` to `master`. This was not caught until the user noticed. The deploy itself was correct (all remote artifacts were on the right branch), but the local state was wrong. **Always verify your branch before and after every operation.**

### The `master` branch is NOT used for active work
`master` is a legacy branch used only for GitHub Pages. The active branches are `dev` (source of truth) and `version/X.Y.Z` (active work). If you find yourself on `master`, you are in the wrong place.

## AGENTS.md / CLAUDE.md Best Practices (how we keep instructions useful)
- These instruction files are loaded automatically at session start, so keep guidance here **universal** and avoid dumping long, task-specific walls of text here.
- Prefer **progressive disclosure**:
  - Architecture + runbooks: `docs/` (start with `docs/BACKTESTING_ARCHITECTURE.md`).
  - Investigations and full trade audits: `docs/investigations/`.
  - Cross-session coordination: `docs/handoffs/`.
  - One-off helpers: `scripts/` (safe-timeout friendly).