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

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 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 – The human-readable specification defining the three operating modes (A, B, C) and the seven-step analysis workflow.
• 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 – The prompt wrapper enabling invocation from the Codex prompt system.
• 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, 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 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.

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

For example, to compare quarterly snapshots for Pinduoduo:

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

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

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

已找到：
- 当前报告：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. While these calls happen automatically during drift detection, you can invoke the validator directly for ad-hoc verification:

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.
• 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 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 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. The Codex-compatible interface used by the command system is generated in 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.

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