lesson-book

Tuition memory for traders. A local-first, deterministic mistake ledger: record what each mistake cost you, tag it, and lb match reminds you of it the next time the same situation shows up — before you act. Python 3.11+, zero dependencies, Windows / Linux / macOS. No LLM, no cloud, no statistics: the reminder is reproducible and auditable.

Status: v0.1 — alpha. The matching logic is distilled from a production trading system's lesson-matching module; this standalone package is new.

Why this exists

Your trading system has a memory problem: it forgets. The mistake you paid 1,200 for last month looks like a fresh opportunity today, because nothing stood between the idea and the order. Trading journals solve the recording half — they are ledgers of what happened. lesson-book solves the retrieval half: it keeps the tuition in a form that can speak up when the same situation appears again.

Two design commitments make it different from journaling apps and LLM "memory" systems:

1. Deterministic, not statistical. Scoring is a fixed weighted formula (code +3, industry +2, market cap +1, volatility proximity bonus, tag overlap bonus). Same situation, same reminder, every time — the opposite of an LLM memory that improvises.
2. Local-first and verifiable. The book is a plain append-only JSONL file in your repo. git log on it is your audit trail; nothing ever leaves your machine.

Philosophy

Tuition is capital — the system does not forget what you paid for, and it reminds you before you pay again.

This is the checklist culture of aviation and medicine, applied to trading: Gawande's The Checklist Manifesto is the canonical argument that simple checklists reduce catastrophic error rates by an order of magnitude. And it is the premortem in reverse: Klein (2007), "Performing a Project Premortem" asks you to imagine, before acting, that you already failed and explain why. lb match is the automated premortem: it surfaces the historical answers to "why will this fail?" without you having to ask.

The IOM (1999), To Err Is Human framing applies directly: errors are a system problem, not a character flaw. The book exists to improve the system — classification, review and retrieval — never to punish the person. That is why records carry cost (a number, not a shame) and why the tool classifies but never enforces: rules, positions and limits stay with you.

Quick start

# install from PyPI (once published)
pip install lesson-book

# or run without installing anything:
#   PYTHONPATH=src python -m lesson_book --help

python examples/demo.py   # record, match, review on a scratch book

Your own book:

# record a mistake — classification happens via the rule table
lb add --book book.jsonl \
  --title "bought into the open gap" \
  --issue execution_failed --error-category price_limit \
  --date 2026-08-01 --code 600000 --industry banking \
  --volatility 0.03 --tags gap,limit-up --cost 1200 \
  --lesson "never chase the open gap; wait for the retest"

# before acting tomorrow: ask the book
lb match --book book.jsonl --industry banking --volatility 0.03 \
  --code 600000 --tags gap
# -> the 2026-08-01 record, score 8.0, lesson: "never chase the open gap..."

# import an existing ##-style markdown knowledge base
lb import-lessons --from LESSONS.md --book book.jsonl

# daily review of what the day cost
lb review --book book.jsonl --day 2026-08-01 --out reviews/

Commands

The book

book.jsonl — append-only, one JSON record per line:

{"schema_version": "lesson_book.lesson.v1", "record_id": "...",
 "title": "bought into the open gap", "date": "2026-08-01",
 "code": "600000", "industry": "banking", "volatility": 0.03,
 "market_cap": "large", "tags": ["gap", "limit-up"],
 "category": "price_limit_rejected", "priority": "P1",
 "cost": 1200.0, "lesson": "never chase the open gap",
 "situation": "", "recorded_at": "..."}

Matching score (deterministic):

A primary match (code / industry / market cap) is required for a non-zero score — the book never speaks up about situations it has no grounds to compare.

Classification rules

add classifies issue + error_category through a plain rule table (category, priority, action), fully overridable in code. Defaults:

Unclassified records are P2 with "review manually and extend the rule table" — the taxonomy grows with you, never silently.

Development

python -m pip install -e . pytest
python -m pytest

CI runs the full test suite on Ubuntu, Windows and macOS with Python 3.11 and 3.12. Issues are handled on weekends; pull requests are welcome.

Related work

• Klein (2007), Performing a Project Premortem (HBR) — imagine the failure before it happens
• Gawande (2009), The Checklist Manifesto — checklists as error-rate reduction
• IOM (1999), To Err Is Human — errors as system problems

License

MIT