# How to Run thesis-drift to Detect Changes in Investment Theses

> Learn how to run thesis-drift to detect changes in investment theses. Compare thesis versions and identify shifts in facts, valuation, management, red-lines, or moats. Get insights from xbtlin/ai-berkshire.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: how-to-guide
- Published: 2026-07-11

---

**`thesis-drift` is a Skill that compares two versions of an investment thesis and identifies whether the underlying facts, valuation, management, red-lines, or moats have actually changed.**

The `ai-berkshire` repository provides a structured framework for value investing analysis, and `thesis-drift` serves as its change-detection engine. This tool decouples superficial wording changes from substantive evidence changes, ensuring every drift claim is backed by verifiable data. Understanding how to run `thesis-drift` correctly allows you to maintain rigorous investment discipline by tracking when your convictions actually shift versus when only your wording does.

## What thesis-drift Actually Does

At its core, `thesis-drift` orchestrates a multi-stage comparison workflow defined in [`skills/thesis-drift.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/thesis-drift.md). The skill expects structured input from the `/thesis-tracker` output format, which includes core-assumption lists, red-line lists, valuation anchors, and tracking tables.

The architecture relies on several key components:

- **Normalization layer** – Extracts standardized dimensions (valuation, assumptions, red-lines, management quality, competitive moat) from both reports and aligns them into a unified comparison table.
- **Financial-rigor toolbox** – Located in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), this module executes exact decimal calculations for numeric changes (e.g., market-cap adjustments, PE ratio shifts) rather than relying on LLM estimation.
- **Decision matrix** – Assigns one of three outcomes to each dimension: **Improved**, **Unchanged**, or **Weakened**, with specific evidence citations.
- **Report generator** – Emits a structured markdown drift report containing the overall conclusion, dimension tables, evidence details, and next-step recommendations.

## Prerequisites for Running thesis-drift

Before invoking the skill, ensure your environment meets these requirements:

1. **Install the AI Berkshire command set** for Claude Code or Codex, following the repository's Quick-Start instructions in [`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md).
2. **Generate a structured thesis baseline** using `/thesis-tracker <Company>`, as `thesis-drift` depends on the standardized sections (core assumptions, red-lines, valuation anchors) that this command produces.
3. **Verify executable permissions** on [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) if running manual verification steps (`chmod +x tools/financial_rigor.py`).

## Three Ways to Run thesis-drift

The skill supports three distinct invocation modes, automatically selected based on your arguments.

### Mode A – Explicit Comparison

Use this mode when you have two specific markdown reports you want to compare directly.

```bash
/thesis-drift <Company> <old-report-path> <new-report-path>

```

**Example:**

```bash
/thesis-drift 拼多多 reports/拼多多-thesis-2025Q4.md reports/拼多多-thesis-2026Q1.md

```

### Mode B – Auto-Snapshot

When you omit the file paths, the skill locates the oldest and newest thesis snapshots automatically under the `reports/` directory.

```bash
/thesis-drift <Company>

```

**Example:**

```bash
/thesis-drift 腾讯

```

### Mode C – Missing Baseline

If only one report exists and you invoke the auto-snapshot command, the skill detects the missing baseline and warns you, suggesting you run `/thesis-tracker` first to establish the required structured sections.

## The Execution Pipeline

When you run `thesis-drift`, the following sequence executes according to the logic in [`skills/thesis-drift.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/thesis-drift.md):

1. **Argument parsing** (§ 27‑33) – Determines which of the three modes applies based on input arguments.
2. **Report loading** (§ 39‑50) – Reads both markdown files and extracts essential sections including dates, core assumptions, red-lines, and valuation anchors.
3. **Evidence normalization** (§ 56‑65) – Constructs a side-by-side table lining up each dimension from both reports.
4. **Numeric verification** (§ 70‑86) – Feeds every numeric difference to [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) using commands like `verify-valuation` or `verify-market-cap` to ensure decimal precision.
5. **Drift assessment** (§ 94‑101) – Applies the decision matrix to determine directionality (Improved/Unchanged/Weakened) for each dimension.
6. **Report rendering** (§ 115‑128) – Generates the final markdown drift report following the standardized template.

## Interpreting the Drift Report

The generated output contains five critical sections:

- **Overall conclusion** – A high-level summary (e.g., "Positive drift (valuation improved)").
- **Dimension drift table** – Rows showing old judgment vs. new judgment, drift direction, triggering evidence, and confidence level.
- **Evidence detail** – Specific financial statements, regulatory filings, or news items that triggered the change.
- **Action recommendation** – Suggested position adjustments (e.g., "Buy → Hold", "Watch → Reduce").
- **Next-step checklist** – Data sources to gather before the next drift check.

## Code Examples

### Running Explicit Comparison

```bash

# Compare two specific thesis files for PDD

/thesis-drift 拼多多 reports/拼多多-thesis-2025Q4.md reports/拼多多-thesis-2026Q1.md

```

### Auto-Detecting Snapshots

```text
使用 thesis-drift 对比 腾讯

```

### Manual Verification of Valuation Changes

When you need to verify calculations independently of the skill:

```bash
python3 tools/financial_rigor.py verify-valuation \
  --price 68.5 --eps 5.12 --bvps 45.7 --fcf-per-share 3.4

```

### Sample Drift Table Output

```markdown
| 维度 | 旧判断 | 新判断 | 漂移方向 | 触发证据 | 置信度 |
|------|--------|--------|----------|----------|--------|
| 估值锚点 | 55×PE | 48×PE | Improved | 市盈率下降 7×, 目标价上调 5% | 高 |
| 核心假设清单 | 收入+20% | 收入+12% | Weakened | Q4 收入增速放缓, 同业增长率12% | 中 |

```

## Summary

- **`thesis-drift`** compares investment thesis versions to detect substantive changes in facts, not just wording.
- **Three modes** cover explicit comparison, auto-snapshot detection, and missing baseline handling.
- **File locations** to remember: [`skills/thesis-drift.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/thesis-drift.md) (workflow), [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) (calculations), and [`skills/thesis-tracker.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/thesis-tracker.md) (baseline generation).
- **Decision outcomes** are strictly categorized as Improved, Unchanged, or Weakened with verifiable evidence citations.
- **Numeric precision** is guaranteed through [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py), preventing LLM hallucination in financial calculations.

## Frequently Asked Questions

### What happens if I run thesis-drift without a baseline thesis?

The skill enters Mode C and displays a warning that required sections (core assumptions, red-lines, valuation anchors) are missing. It will recommend running `/thesis-tracker <Company>` first to generate the structured baseline before attempting drift detection.

### How does thesis-drift ensure financial calculations are accurate?

Rather than relying on LLM estimation, the skill delegates all numeric verification to [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py). This module performs exact decimal calculations for metrics like market-cap, PE ratios, and target prices, ensuring that drift assessments are based on verified numbers rather than "mental math."

### Can I compare theses from different companies using thesis-drift?

No. The skill is designed to compare temporal versions of the same company's thesis. The normalization layer expects consistent dimensions (valuation anchors, management quality, moats) specific to one company to ensure meaningful comparison across time periods.

### What file format does thesis-drift expect for input reports?

The skill requires markdown files generated by `/thesis-tracker` containing specific sections: date headers, core assumption lists, red-line lists, valuation anchors, and tracking tables. These sections are parsed according to the logic in [`skills/thesis-drift.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/thesis-drift.md) (§ 39‑50).