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

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, which contains the prompt engineering, workflow logic, and output templates for the entire pipeline.

All financial calculations execute through 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 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:

• 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) 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 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:

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

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

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

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