Serenity Bottleneck Hunter: a Codex and Claude skill that reverse-maps a supply chain

The offline demo replays a 2026-06-01 snapshot and touches nothing live

The cheapest way to see what this project produces needs no account, no key and no connectivity. One command runs a bundled historical example on Python 3.10 or newer:

python scripts/run_demo.py

The output is a generated file at reports/demo-report.html. The example works from a 2026-06-01 historical snapshot that was already public in the repository, runs strict numeric reconciliation automatically, and writes its results into a separate demo tracking file so the official history table stays untouched. The repository is explicit that the demo does not represent a current investment judgment. Everything the demo needs sits in examples/: a spec, a scan, a tracking CSV, a blank tracking CSV, a provenance file, the rendered HTML report, and a README with reproduction notes. The root requirements.txt pins only yfinance and python-dotenv, and both are described as optional network-backed tools, because the bundled demo and the tests rely on the standard library alone. That separation is what makes the demo a fair smoke test rather than a marketing screenshot.

Where to get it: a git clone, the release ZIP or the .skill package

There are three routes in, and all of them end at the same entry file. For Codex on macOS or Linux the repository is cloned straight into the skills directory:

git clone https://github.com/Mrjie7205/serenity-bottleneck-hunter.git \
  ~/.codex/skills/serenity-bottleneck-hunter

For Claude Code the target is the personal skills folder instead:

git clone https://github.com/Mrjie7205/serenity-bottleneck-hunter.git ~/.claude/skills/serenity-bottleneck-hunter

Codex needs a restart or a new session afterwards, then reads the workflow from SKILL.md inside that directory and treats scripts/, reference/ and tracking/ as supporting resources. Users on claude.ai or Claude Desktop have no directory to clone into, so the documented options are packaging the repository as a skill and uploading it, or dragging SKILL.md into the conversation so the model follows the instructions. The release page for tag v0.2.0 also ships a ZIP and a .skill archive, and after extraction the entry point is still SKILL.md. The skill is written to be invoked by name or described in plain language, for example asking it to analyse the AI data centre power theme or the humanoid robot chain.

EODHD first, yfinance second, and price guessing by search is forbidden

Every verdict in a report traces back to a price, so the project treats prices as the least trustworthy input. The optional credential lives in an environment file shaped like this:

EODHD_API_KEY=your_eodhd_key_here

The same file documents the fallback order per market. For A-share history it is AKShare in qfq form, then Yahoo adjusted, then EODHD with an explicit adjusted close. For other markets it is EODHD adjusted, then Yahoo adjusted. The comment in that file is blunt about the failure mode: providers can be unavailable. A-share work also needs a second dependency file, requirements-ashare.txt, installed on top of the base requirements. The scripts under scripts/ enforce the order rather than trusting the model to follow it, keep all nine price fields on record for later reconciliation, and forbid a hand-typed price. The rationale is specific: an earlier version of this skill guessed prices from web search results and from memory, and the numbers ended up wrong. Live pricing, valuation and scoring therefore need extra dependencies and can consume data service quota, which is exactly what the offline demo exists to avoid.

Funnel nodes get a gold edge and hub nodes a wine-red edge

The core output is one self-contained HTML file per theme, with a template kept at reference/report_template.html and no runtime dependency in the browser. The map itself is Step 2: five layers of reverse decomposition drawn as an SVG web where the dependency edges are generated. Bottleneck nodes are picked by two rules applied to the same in-degree and out-degree counts. A funnel node, with in-degree of at least two and out-degree of at most one, is drawn with a gold edge. A hub node, with in-degree of at least two and out-degree of at least two, is drawn with a wine-red edge, on the reasoning that a many-to-many position is the hardest for a buyer to route around. Around that map the report fixes a reading order. Step 1 states capex certainty in three or four numbers, naming who is spending, how much and where the certainty comes from. A 30-second overview serves readers outside the industry. An action-point block at the top pins at most two cards, either an alert to set or a condition to act under, so the single next action is visible before any table. Step 7 closes with position thinking and a trigger list, and the footer records the date the prices were taken, their source, a glossary extracted from the body, citation links and a disclaimer.

The second axis splits expensive but right from genuinely at the top

The candidate table gives each name a verdict of candidate, watch or exclude, and attaches a ruler to it. The ruler marks the level as pinned to the top, high, middle, low or pinned to the bottom, gives the distance from the high in percent, and adds one-month and three-month momentum in plain language, with the ruler ends labelled by the June low and high and a cursor at the current price. Qualitative and quantitative reading sit on the same object. The correction the project cares about is the second axis, which sits alongside the ruler and exists because a single water-level axis misjudges a leader: mean reversion then masquerades as momentum, and a genuine breakout gets demoted to watch. So a high reading on its own never produces a downgrade. Instead forward P/E trajectory, PEG, earnings growth and relative strength inside the sector decide whether a high name is expensive but correct, earnings carrying a leader, or actually pinned to the top on pure re-rating. Valuation is sourced from more than one place, AKShare for A-shares and yfinance for US names, with a sanity layer to catch outliers, and the project names its own misfire: a wrong forward P/E from yfinance marked an A-share name as exclude, and adding akshare corrected it to watch.

Three gates and a pre-commit hook that has already caught four wrong tickers

The input side is defended by three gates whose names in the report are A, A+ and A++, and each exists because of a recorded failure. Gate A is exhaustiveness: listing candidates from memory misses things, including positions of the size of PANW or CRWD, so the workflow requires an audit of the full known-player set with each entry marked covered, private or acquired. Gate A+ pulls theme ETF holdings through scripts/theme_etf_coverage.py to cover the model's bias toward whatever is famous. Gate A++ is two-way ticker verification, and it is the most concrete of the three: an LLM once treated ticker 603297, Yongxin Optics, as Leader Harmonious Drive, inverting both the price and the verdict, so scripts/ticker_truth.py holds a ground-truth library and verify_tickers.py runs as a git pre-commit hook. That combination has caught four genuine misalignments. Alongside them sits a company status check for the stale-prior problem in both directions: a report still labelled a company private on the day it listed, and another described a listed company after it had been acquired. Any status claim must carry a date, and every verdict in the report is written into tracking/forward_picks.csv with a date lock so it can be checked forward.

Every candidate verdict needs a line that says what would prove it wrong

The judgment side is built to make a call answerable later. Each candidate gets a red-team pass with four forced questions plus the largest thing that could kill the thesis, and the question of whether the story is already priced in has to be answered against real numbers from the price script rather than in prose. A candidate verdict in particular is not allowed to exist on a bullish story alone, so it must carry at least one machine-readable falsification condition, which is written into the invalidation column of forward_picks.csv. Performance is measured against a benchmark rather than in isolation: scripts/score_tracker.py computes Alpha as the stock minus its theme ETF instead of raw return, and the hardest control compares the candidate basket against the excluded basket so that theme beta cancels out. Rows tagged as historical seeds are dropped from every statistic, a rule added after backfilled known winners had inflated average alpha to plus ninety percent when the real figure was negative. Delivery is gated too. scripts/verify_report.py runs a contract check before a report leaves the repository, covering required blocks, the section requirements per candidate, the three prices on each ruler, field-by-field price reconciliation against the scan, presence in forward_picks.csv, dated status assertions, leftover placeholders and balanced disclosure blocks. A report with a blocking finding is fixed before it ships.

The cockpit-r2 package replaced the files under the same v0.2.0 tag

Release v0.2.0 was published on 2026-09-29, and the same day the project reissued the contents of that tag. The current package is marked cockpit-r2 and replaces the earlier v0.2.0 files, which contained only the core tools. Anyone who downloaded the first build is told to download again and check SHA256SUMS.txt, which is the only way to tell the two apart. The cockpit itself is optional: a theme map, a tracking filter, report reading, candlestick and verdict history, manual alerts, snapshots and scorecards, served on 127.0.0.1:8000 after two commands in a project virtual environment.

python -m pip install -r cockpit/requirements.txt
python cockpit/run.py

Python 3.12 is recommended for the cockpit. The ZIP and .skill archives ship the frontend pages, so Node.js is not needed, while anyone who cloned the source has to build the frontend first. It opens in a read-only historical demo and only enables manual price fetching once a personal directory is attached, and it never searches or uploads a private library on its own. Two smaller facts matter for expectations. The public history sample holds 418 records with the latest dated 2026-06-12, and older scorecards and scans are kept as dated archives rather than as current results. The last push was on 2026-09-29, and the licence is MIT. The structure listing in the README breaks off partway through the reference file names, so the full file inventory needs to be read from the repository itself.

Editorial conclusion

Serenity Bottleneck Hunter fits an investor who wants a written chain of reasoning per theme and who is willing to police a model rather than trust it. It does not fit someone who wants a data licence, a broker integration or an unattended signal, because every number comes from a provider you supply and every gate is a local script you must run. Before adopting it, re-download the release package, compare its SHA256SUMS.txt against the cockpit-r2 build, and run the offline demo to see whether the report format is one you would actually read. The project states plainly that its output is not financial advice, and the demo it ships runs on a June 2026 snapshot rather than on live prices.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Mrjie7205/serenity-bottleneck-hunter on GitHub
4. README
5. Releases