# How bottleneck-hunter Identifies Supply Chain Bottlenecks from Super-Trends in AI Berkshire

> Discover how bottleneck-hunter from ai-berkshire maps super-trends to supply chain bottlenecks. It analyzes market data and scores constraints to provide actionable alerts.

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

---

**The `bottleneck-hunter` skill in the xbtlin/ai-berkshire repository transforms macro-level super-trends into actionable supply chain bottleneck alerts by mapping trends to industries, retrieving quantitative market data, and scoring constraints across physical scarcity, structural capacity, and arbitrage potential dimensions.**

The `bottleneck-hunter` skill is a specialized AI agent within the AI Berkshire ecosystem designed to systematically detect supply chain constraints. According to the source code in [`skills/bottleneck-hunter.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/bottleneck-hunter.md), the implementation follows a deterministic pipeline that converts high-level "super-trends" (such as "AI Infrastructure" or "Electric Vehicle Batteries") into ranked bottleneck reports with concrete trading implications.

## The Super-Trend to Bottleneck Pipeline

The skill operates on a six-stage architecture defined in the canonical skill definition file. Unlike generic trend analysis, this workflow specifically targets supply chain fragility by combining sector mapping with quantitative scarcity metrics.

The pipeline executes sequentially:
1. **Ingests** a user-defined super-trend or extracts one from trend-analysis feeds
2. **Maps** the trend to relevant industry sectors using the `industry-research` skill
3. **Retrieves** supply chain data through specialized Python modules in the `tools/` directory
4. **Scores** potential bottlenecks across three quantitative dimensions
5. **Generates** arbitrage opportunities linking to `portfolio-review` and `earnings-review` skills
6. **Renders** a markdown-formatted actionable report

## Step-by-Step Bottleneck Detection

### Super-Trend Ingestion and Industry Mapping

The process begins in [`skills/bottleneck-hunter.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/bottleneck-hunter.md) where the skill accepts a natural language super-trend (e.g., "AI Infrastructure") via the slash-command interface. The skill immediately invokes the `industry-research` skill to decompose the trend into concrete sectors and key market participants.

This mapping is critical because supply chain bottlenecks are industry-specific. The skill maintains internal logic to translate abstract trends into ticker symbols and commodity categories that the data retrieval layer can process.

### Supply Chain Data Retrieval via Python Tools

Once sectors are identified, the skill calls quantitative data modules from the `tools/` package. According to the repository structure, three primary modules feed the scoring algorithm:

- **[`tools/twstock_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/twstock_data.py)**: Retrieves Taiwanese stock exchange data including inventory levels, price movements, and capacity utilization metrics for semiconductor and hardware manufacturers
- **[`tools/ashare_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/ashare_data.py)**: Fetches mainland Chinese equity data for upstream raw material suppliers and downstream manufacturers
- **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)**: Performs rigorous financial calculations including spread analysis and correlation metrics essential for arbitrage detection

These modules supply time-series data that the skill uses to detect abnormal price action or inventory drawdowns indicative of physical scarcity.

### The Three-Dimensional Bottleneck Scoring Algorithm

The core intelligence resides in a custom scoring algorithm implemented within the skill's markdown logic. For each sector mapped from the super-trend, the algorithm evaluates:

**Physical Scarcity**
- Abnormal price volatility exceeding historical baselines
- Inventory-to-sales ratios below critical thresholds
- Extended order-backlog durations

**Structural Constraints**
- Single-supplier dependency concentrations
- Production capacity utilization above 90%
- Geographic concentration risk in manufacturing bases

**Arbitrage Potential**
- Price spreads between upstream raw materials and downstream finished goods
- Temporal mispricing between spot and futures markets
- Cross-border valuation gaps detected via [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py)

Scores are normalized across sectors and ranked to surface the top-N bottlenecks based on severity and profit potential.

### Arbitrage Opportunity Generation

For each high-scoring bottleneck (typically those exceeding a configurable threshold), the skill generates specific arbitrage actions. These recommendations include:
- Long-short equity positions between constrained suppliers and dependent manufacturers
- Contract-forward purchase suggestions for physical commodities
- Calendar spread trades exploiting temporal supply gaps

The skill automatically links these opportunities to the `portfolio-review` skill for risk assessment and the `earnings-review` skill for fundamental validation, creating a closed-loop research workflow.

## Source Code Architecture and Key Files

The implementation spans several critical files in the xbtlin/ai-berkshire repository:

- **[`skills/bottleneck-hunter.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/bottleneck-hunter.md)**: Contains the canonical skill definition, including the system prompt that instructs the LLM on scoring methodology and sector mapping logic
- **[`codex-skills/bottleneck-hunter/SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/codex-skills/bottleneck-hunter/SKILL.md)**: The generated Codex-compatible artifact that exposes the skill to the AI Berkshire execution environment
- **[`tools/twstock_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/twstock_data.py)**: Implements `fetch_inventory_data()` and `fetch_price_signals()` functions used for physical scarcity detection
- **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)**: Implements `calculate_arbitrage_spread()` and `normalize_scores()` utilities for the scoring algorithm
- **[`tools/ashare_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/ashare_data.py)**: Provides Chinese market data integration for complete upstream coverage

## Practical Usage Examples

Invoke the skill through the AI Berkshire CLI using the `/bottleneck-hunter` slash command:

```bash

# Basic usage: Scan AI infrastructure bottlenecks from the "AI Infra" super-trend

ai-berkshire /bottleneck-hunter --trend "AI Infrastructure"

```

For targeted analysis with output redirection:

```bash

# Advanced usage: Analyze EV battery supply constraints, return top 3 bottlenecks only

ai-berkshire /bottleneck-hunter \
    --trend "Electric Vehicle Battery Supply" \
    --limit 3 \
    --output report.md

```

The commands trigger the full pipeline, automatically calling `industry-research` for sector mapping, executing the Python data retrieval tools, and writing the ranked bottleneck analysis to the specified markdown file.

## Summary

- **`bottleneck-hunter`** converts abstract super-trends into concrete supply chain alerts through a deterministic six-stage pipeline defined in [`skills/bottleneck-hunter.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/bottleneck-hunter.md)
- The scoring algorithm evaluates **physical scarcity**, **structural constraints**, and **arbitrage potential** using data from [`tools/twstock_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/twstock_data.py), [`tools/ashare_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/ashare_data.py), and [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)
- Integration with **`industry-research`**, **`portfolio-review`**, and **`earnings-review`** skills creates a comprehensive research ecosystem
- Results are surfaced via slash commands and output as actionable markdown reports suitable for direct trading desk consumption

## Frequently Asked Questions

### What data sources does bottleneck-hunter use for scarcity detection?

The skill relies on quantitative data modules in the `tools/` directory. Specifically, [`twstock_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/twstock_data.py) provides Taiwanese equity and inventory data for technology hardware analysis, while [`ashare_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/ashare_data.py) covers mainland Chinese suppliers. For financial calculations and spread analysis, the skill calls functions from [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py).

### How does the scoring algorithm differ from traditional supply chain analysis?

Traditional analysis often relies on qualitative surveys or lagging economic indicators. The `bottleneck-hunter` implementation uses real-time quantitative scoring across three dimensions—physical scarcity, structural constraints, and arbitrage potential—normalized via [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py) to surface statistically significant anomalies rather than anecdotal constraints.

### Can bottleneck-hunter integrate with other AI Berkshire skills?

Yes. The skill architecture explicitly supports integration with the `industry-research` skill for sector mapping, `portfolio-review` for risk assessment of generated trades, and `earnings-review` for fundamental validation of companies within identified bottlenecked sectors. These integrations are defined in the skill orchestration layer of [`skills/bottleneck-hunter.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/bottleneck-hunter.md).

### Where is the bottleneck detection logic defined in the repository?

The primary logic resides in **[`skills/bottleneck-hunter.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/bottleneck-hunter.md)**, which contains the system instructions and scoring methodology. The generated execution artifact is located at **[`codex-skills/bottleneck-hunter/SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/codex-skills/bottleneck-hunter/SKILL.md)**. The quantitative data retrieval functions referenced by the skill are implemented in **[`tools/twstock_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/twstock_data.py)** and **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)**.