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

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. 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, 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.
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 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.

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

Example:

/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.

/thesis-drift <Company>

Example:

/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:

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 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

# Compare two specific thesis files for PDD

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

Auto-Detecting Snapshots

使用 thesis-drift 对比 腾讯

Manual Verification of Valuation Changes

When you need to verify calculations independently of the skill:

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

| 维度 | 旧判断 | 新判断 | 漂移方向 | 触发证据 | 置信度 |
|------|--------|--------|----------|----------|--------|
| 估值锚点 | 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 (workflow), tools/financial_rigor.py (calculations), and 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, 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. 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 (§ 39‑50).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}