# How to Use the thesis-drift Skill to Detect Changes in Investment Thesis

> Learn how to use the thesis-drift skill to detect significant changes in investment theses. Isolate valuation shifts, risk signals, and fact updates with this AI tool from xbtlin/ai-berkshire.

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

---

**The `thesis-drift` skill compares two versions of an investment thesis to isolate substantive changes—valuation shifts, risk signals, and fact updates—while filtering out cosmetic wording differences.**

The `thesis-drift` skill is a structured workflow in the [xbtlin/ai-berkshire](https://github.com/xbtlin/ai-berkshire) repository designed for financial analysts who need rigorous, evidence-based detection of investment thesis evolution. Unlike simple text diffing, this skill validates every numeric claim through external financial tools and categorizes changes across five fixed dimensions to prevent false positives from rewording or market-price noise.

## Architecture of the thesis-drift Skill

The skill is implemented across four interconnected components that enforce **evidence-first** reasoning.

### Core Components

- **[`skills/thesis-drift.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/thesis-drift.md)** – The human-readable specification defining the three operating modes (A, B, C) and the seven-step analysis workflow.
- **[`codex-skills/thesis-drift/SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/codex-skills/thesis-drift/SKILL.md)** – The machine-readable wrapper used by Codex-compatible agents to parse commands and route to the correct mode.
- **[`codex-prompts/thesis-drift.md`](https://github.com/xbtlin/ai-berkshire/blob/main/codex-prompts/thesis-drift.md)** – The prompt wrapper enabling invocation from the Codex prompt system.
- **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)** – The financial verification utility that validates all numeric calculations (valuation, market-cap, cross-validation) to prevent LLM hallucination in arithmetic.

### Workflow Overview

According to the source code in [`skills/thesis-drift.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/thesis-drift.md), the skill executes seven sequential stages:

1. **Argument parsing** – Detects whether the user provided two file paths, only a company name, or incomplete arguments.
2. **Mode selection** – Routes to Mode A (explicit paths), Mode B (auto-discovery), or Mode C (missing baseline).
3. **Report ingestion** – Extracts structured sections: date, company, stock code, core thesis (5-sentence summary), hypothesis list, red-line list, valuation anchors, tracking table, management-quality assessment, and moat analysis.
4. **Evidence normalization** – Builds a side-by-side comparison table mapping old versus new evidence with source citations.
5. **Numeric verification** – Calls [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py) for every financial figure (EPS, BVPS, FCF) to eliminate calculation errors.
6. **Dimension-level drift assessment** – Evaluates each of the five fixed dimensions, outputting **Improved / Unchanged / Weakened** with concrete triggers.
7. **Report generation** – Produces a markdown drift report with overall conclusion, drift tables, and action migration recommendations.

## Operating Modes

The `thesis-drift` skill supports three distinct invocation patterns based on available data.

### Mode A: Explicit Report Comparison

Use this when you have two specific thesis files to compare. The skill ingests both reports and executes the full seven-stage workflow.

```text
/thesis-drift {company_name} {old_report} {new_report}

```

For example, to compare quarterly snapshots for Pinduoduo:

```text
/thesis-drift Pinduoduo reports/PDD-thesis-2025Q4.md reports/PDD-thesis-2026Q1.md

```

### Mode B: Automatic Snapshot Discovery

When you provide only a company name, the skill automatically locates the oldest and newest snapshots under `reports/` and compares them.

```text
/thesis-drift {company_name}

```

The system searches for `reports/{company_name}-thesis.md` and dated variants, then executes the drift analysis without manual path specification.

### Mode C: Missing Baseline Handling

If the skill detects only one report and no historical baseline exists, it exits gracefully with actionable guidance rather than failing silently.

```text
无法执行论文漂移检测：缺少历史基线。

已找到：
- 当前报告：reports/XYZ-thesis.md
- 历史基线：未找到

建议：
1. 先运行 /thesis-tracker XYZ 建立论文基线
2. 下次有新财报或重大事件后，再运行 /thesis-drift XYZ 旧报告 新报告

```

This prevents erroneous comparisons and prompts the user to initialize tracking via the `/thesis-tracker` command first.

## Running Financial Verification Checks

Under the hood, the skill delegates all numeric validation to [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py). While these calls happen automatically during drift detection, you can invoke the validator directly for ad-hoc verification:

```bash
python3 tools/financial_rigor.py verify-valuation \
  --price 45.2 --eps 3.1 --bvps 20.5 --fcf-per-share 2.8

```

This ensures that any valuation-related drift—such as a changed P/E ratio or revised FCF forecast—is mathematically verified against the underlying financial statements rather than accepted from the LLM's interpretation.

## Interpreting Drift Output

The final report evaluates five fixed dimensions: **valuation anchor**, **hypothesis list**, **red-line list**, **management quality**, and **moat analysis**. Each dimension receives a status of **Improved**, **Unchanged**, or **Weakened**, backed by a specific evidence citation (e.g., financial filing, regulatory disclosure, or validated calculation).

If evidence is insufficient to support a change, the skill marks the dimension **Unchanged** or notes **insufficient data**, preventing false positives from market noise or semantic rephrasing.

## Summary

- The `thesis-drift` skill in `xbtlin/ai-berkshire` detects substantive investment thesis changes through a structured, evidence-first workflow defined in [`skills/thesis-drift.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/thesis-drift.md).
- It operates in three modes: **Mode A** (explicit file comparison), **Mode B** (automatic snapshot discovery), and **Mode C** (graceful handling of missing baselines).
- All financial calculations are validated through [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) to prevent arithmetic hallucination.
- Changes are categorized across five dimensions—valuation, hypotheses, red-lines, management, and moat—each requiring verifiable evidence to trigger a status change from **Unchanged**.
- The skill produces a markdown report with specific citations and recommended action migrations.

## Frequently Asked Questions

### How does the thesis-drift skill distinguish real changes from wording updates?

The skill parses structured sections (hypothesis lists, valuation anchors, red-lines) rather than performing lexical diffing. It requires concrete evidence—such as a revised EPS figure from a 10-K filing or a changed FCF calculation—to mark a dimension as **Improved** or **Weakened**. Mere rephrasing without underlying data changes results in an **Unchanged** classification.

### Can I use the thesis-drift skill if I only have one historical report?

No. The skill requires at least two comparable snapshots to detect drift. If only one report exists, **Mode C** activates and the skill prompts you to run `/thesis-tracker` first to establish a baseline before future drift comparisons.

### What financial metrics does the skill validate automatically?

The skill validates all figures related to valuation anchors—including EPS, BVPS, FCF per share, and market capitalization—by calling [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) during the numeric verification stage. This prevents the LLM from accepting incorrect arithmetic in the thesis text.

### Where is the skill logic defined versus the machine-readable implementation?

The human-readable workflow and analysis steps are defined in [`skills/thesis-drift.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/thesis-drift.md). The Codex-compatible interface used by the command system is generated in [`codex-skills/thesis-drift/SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/codex-skills/thesis-drift/SKILL.md), which mirrors the markdown source but adds the structured metadata required by the Codex prompt wrapper in [`codex-prompts/thesis-drift.md`](https://github.com/xbtlin/ai-berkshire/blob/main/codex-prompts/thesis-drift.md).