# AI Berkshire Bottleneck-Hunter for Supply Chain Physical Bottlenecks: Implementation Guide

> Implement AI Berkshire's Bottleneck-Hunter, an open-source LLM agent, to find physical supply chain bottlenecks and monetize scarcity. This guide details its quantitative scoring and financial validation.

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

---

**AI Berkshire's Bottleneck-Hunter is an open-source LLM agent framework that systematically identifies physical supply-chain constraints and monetizes scarcity through quantitative bottleneck scoring and rigorous financial validation.**

The AI Berkshire bottleneck-hunter for supply chain physical bottlenecks merges Warren Buffett, Charlie Munger, Duan Yong-ping and Li Lu's investment philosophies with modern LLM agents to identify capital-intensive scarcity opportunities. Located in the `xbtlin/ai-berkshire` repository, this framework replaces generic stock-picking prompts with systematic supply-chain decomposition and financial rigor. The system operates through a three-layer architecture—**Skill**, **Agent**, and **Tool**—and can be deployed via Claude Code commands, Codex skills, or direct Python invocation.

## Core Architecture and File Structure

The repository organizes functionality into declarative markdown skills and reproducible Python tooling. The canonical implementation resides in [`skills/bottleneck-hunter.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/bottleneck-hunter.md), which contains the prompt engineering, workflow logic, and output templates for the entire pipeline.

All financial calculations execute through [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), a zero-dependency Python toolkit that uses only the `decimal` module to eliminate floating-point drift. This module exposes sub-commands including `verify-market-cap`, `verify-valuation`, `cross_validate`, and `three_scenario_valuation` for precise financial validation.

The architecture diagram at `assets/architecture.png` visualizes the Skill→Agent→Tool data flow, while [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) generates Codex-compatible packages from the markdown skill definitions.

## The Six-Step Bottleneck Identification Pipeline

### Step 1 – Trend Confirmation and Physical Decomposition

The pipeline begins by validating "super-trends" against four mandatory criteria embedded in [`skills/bottleneck-hunter.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/bottleneck-hunter.md):

- **Continuity**: ≥3 years of sustained growth
- **Physicality**: Hardware or materials-based constraints (not software)
- **Scale**: >USD 500 billion in projected capex
- **Acceleration**: Demand growth outpacing supply expansion

Once validated, the agent performs a **Layer 0-4 decomposition** to map the physical supply chain:

1. **Layer 0**: Terminal product
2. **Layer 1**: Core components
3. **Layer 2**: Sub-components and materials
4. **Layer 3**: Upstream equipment and raw materials
5. **Layer 4**: Infrastructure (energy, logistics, facilities)

### Step 2 – Quantitative Bottleneck Scoring

The framework applies six quantitative criteria to identify constraints (implemented in the skill's pseudo-code block):

- **Supplier concentration**: Market share of top 3 producers
- **Expansion lead-time**: Years required to add meaningful capacity
- **Substitutability**: Availability of alternative materials or technologies
- **Utilisation**: Current capacity utilization rates
- **Demand-growth**: Projected CAGR vs. supply response
- **Client-validation**: Commitment from end-users to long-term contracts

Each criterion generates a red/amber/green flag. Accumulating **≥4 red flags** triggers an **S-level** bottleneck rating (highest scarcity), while fewer flags yield **A** or **B** ratings. The agent outputs this as a markdown matrix defined in lines 118-132 of the skill file.

### Step 3 – Company Screening and Valuation

The system searches for listed firms owning the identified bottleneck segment using queries like `"{bottleneck} supplier listed company"`, then applies strict filters:

- Market capitalization <$10 billion (small-cap focus)
- >30% revenue exposure to the bottleneck segment
- Liquidity and valuation thresholds (PE/PS limits)

The **Financial-Rigor Toolkit** ([`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)) performs **three-scenario pricing** and calculates TAM-ratio metrics. The `verify_valuation` function checks price-to-earnings, price-to-sales, and book value against sector norms, flagging deviations >5%.

### Step 4 – Cross-Validation and Anti-Bias Controls

Every data point requires **≥2 independent sources** before inclusion. The `cross_validate` function in [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py) enforces this while applying three specific bias-mitigation filters:

- **Small-cap bias**: Overweighting illiquid securities
- **Language bias**: Over-reliance on English-language sources
- **Narrative bias**: Confirmation of pre-existing investment theses

### Step 5 – Dynamic Report Generation

Completed analyses generate markdown "bottleneck maps" stored in `reports/bottleneck-map/`. The report template (defined in lines 340-382 of the skill file) includes S/A/B ratings, company snapshots, valuation flags, and risk checklists. The system performs hourly scans with automatic version control and repository storage.

## Practical Usage Examples

### Claude Code Implementation

Install the commands once, then execute the skill:

```bash

# Install Claude Code commands

./scripts/install-claude-commands.sh

# Run Bottleneck-Hunter for AI infrastructure

/bottleneck-hunter AI基础设施

```

This triggers the four-step workflow and writes the report to `reports/bottleneck-map/AI基础设施-bottleneck-YYYYMMDD.md`.

### Codex Implementation

Synchronize skills after editing markdown files:

```bash

# Sync Codex skills

python3 scripts/sync-codex-skills.py

# Execute via Codex CLI

codex run bottleneck-hunter "AI基础设施"

```

### Direct Python Invocation

For advanced users, call the financial validation tools directly:

```bash

# Verify market capitalization with precision

python3 tools/financial_rigor.py verify-market-cap \
    --price 510 --shares 9.11e9 --reported 4.65e12 --currency HKD

# Run full valuation check

python3 tools/financial_rigor.py verify-valuation \
    --price 120 --eps 5.2 --bvps 45 --fcf-per-share 4.1 --dividend 2.5

```

These commands output decimal-precise calculations and highlight red-flag metrics automatically.

## Summary

- **AI Berkshire** combines value investing principles with LLM agents to identify physical supply-chain bottlenecks rather than guessing stock prices.
- The **six-criteria scoring system** (supplier concentration, lead-time, substitutability, utilisation, demand-growth, validation) assigns S/A/B ratings to scarcity opportunities.
- **Financial rigor** is enforced through [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), which uses Python's `decimal` module for zero-drift calculations of market-cap, PE/PS ratios, and three-scenario valuations.
- **Anti-bias safeguards** require dual-source verification and filter small-cap, language, and narrative biases.
- **Multi-interface support** allows execution via Claude Code (`/bottleneck-hunter`), Codex (`codex run`), or direct Python CLI invocation.

## Frequently Asked Questions

### What distinguishes AI Berkshire's Bottleneck-Hunter from traditional stock screeners?

Traditional screeners filter by financial metrics alone, while the Bottleneck-Hunter starts with physical supply-chain decomposition to identify where capacity constraints will create pricing power. As implemented in [`skills/bottleneck-hunter.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/bottleneck-hunter.md), the framework asks "where will capacity be tight?" rather than "which stock should I buy?", then validates scarcity through six quantitative criteria before screening for listed beneficiaries.

### How does the S/A/B bottleneck rating system work?

The rating system evaluates six criteria (supplier concentration, expansion lead-time, substitutability, utilisation, demand-growth, and client-validation) with red/amber/green flags. An **S-level** bottleneck requires ≥4 red flags indicating extreme scarcity, while **A** and **B** ratings indicate moderate or mild constraints. This scoring logic is embedded in the skill file's pseudo-code and rendered as a markdown matrix in the final report.

### What financial validation safeguards prevent valuation errors?

The [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) module performs all calculations using Python's `decimal` module to avoid floating-point drift. The `verify-market-cap` function flags discrepancies >5% between calculated and reported market capitalizations, while `verify-valuation` checks PE/PS thresholds against sector norms. Additionally, the `cross_validate` function enforces dual-source verification for every data point to prevent single-source errors.

### Can I deploy the Bottleneck-Hunter without Claude Code or Codex?

Yes. While the framework provides optimized interfaces for Claude Code and Codex via [`skills/bottleneck-hunter.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/bottleneck-hunter.md) and [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py), you can invoke the underlying Python tools directly. Use `python3 tools/financial_rigor.py` with sub-commands like `verify-valuation`, `three_scenario_valuation`, or `verify-market-cap` to perform rigorous financial analysis independently of the LLM agent layer.