# https://github.com/ssurmic/claude-investment-skills Project Manual Generated at: 2026-06-20 05:32:00 UTC ## Table of Contents - [Overview, Setup, and Installation](#page-1) - [Analysis Skills Catalog](#page-2) - [Discovery Firehoses and Real-time Channels](#page-3) - [Price Alert System, Architecture, and Operations](#page-4) ## Overview, Setup, and Installation ### Related Pages Related topics: [Analysis Skills Catalog](#page-2), [Discovery Firehoses and Real-time Channels](#page-3), [Price Alert System, Architecture, and Operations](#page-4)
Related Source Files The following source files were used to generate this page: - [strategic-partner-firehose/README.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md) - [price-alert/webhook/package.json](https://github.com/ssurmic/claude-investment-skills/blob/main/price-alert/webhook/package.json)
# Overview, Setup, and Installation ## What this project is `claude-investment-skills` is a collection of **Claude Code skills** designed for retail and semi-professional investors who want algorithmic, source-backed trading signals without paying for Bloomberg or a hedge-fund terminal. Each "skill" is a self-contained bundle of natural-language triggers, Python scripts, configuration files, and GitHub Actions workflows that together implement a specific market-monitoring use case. The flagship skill covered in the documentation is the **Strategic Partner Firehose**, a 30-minute-cadence SEC EDGAR monitor that scans 8-K and SC 13D filings for evidence of Tier-1 strategic investors (NVIDIA, Microsoft, OpenAI, SK Telecom, etc.) taking positions in small/mid-cap US-listed companies. The README frames the use case around the CoreWeave (CRWV) IPO, where a 2025-03-31 8-K disclosing an OpenAI commercial agreement preceded a +367% rally over the following quarter. Source: [strategic-partner-firehose/README.md:11-25]() Companion skills mentioned in the same document form a complete investing toolkit: `insider-firehose` (Form 4 buys), `analyze-stock`, `option-wall-analysis`, `macro-warning`, and `tax-optimize`. A composite signal detector (`scripts/composite.py`) cross-validates alerts from the two firehoses, and a `price-alert` skill integrates a Cloudflare Worker webhook for Telegram delivery. Source: [strategic-partner-firehose/README.md:154-162]() ## High-level architecture The system is fully **self-hosted** on GitHub. No central service, no SaaS dependency, no telemetry. The data flow has four stages: 1. **Cron trigger** — a GitHub Actions workflow fires the entry script (e.g. `scripts/partner_firehose.py`) on a 30-minute schedule during US market hours (weekdays 9 AM – 7:30 PM ET). 2. **EDGAR poll** — the script pulls recent 8-K and SC 13D filings from `sec.gov` and runs regex-based extractors (`scripts/parsers.py`) and filters (`scripts/filters.py`) for market-cap, US-listing, and dollar-amount thresholds. 3. **Scoring** — a 0-10 Partner Score (`scripts/analysis.py`) weights filings by investor tier; a parallel theme classifier (`scripts/classifier.py`, v2.4) catches anonymous-hyperscaler deals like the POWL $400M data-center order. 4. **Alert delivery** — qualifying alerts are pushed to a Telegram chat via bot API, deduplicated against `strategic_state.json` and `recent_alerts.json` ledgers. ```mermaid flowchart LR A[GitHub Actions
cron 30 min] --> B[partner_firehose.py] B --> C[SEC EDGAR
8-K + SC 13D] C --> D[parsers.py
+ filters.py] D --> E{Investor registry
OR theme score >= 6} E -- yes --> F[Partner Score 0-10] E -- no --> G[Skip] F --> H[Telegram
bot API] H --> I[recent_alerts.json] I --> J[composite.py] K[insider-firehose
alert] --> J J --> H ``` ## Repository layout The project follows a per-skill subdirectory convention. Each skill ships with the same five files: `SKILL.md` (natural-language trigger for Claude Code), `SETUP.md` (5-minute installation), `README.md` (long-form with examples), `strategic_config.json` (on/off toggle), and a `scripts/` directory containing the entry point plus helper modules. The firehose skill additionally carries a `tests/` directory with 32 unit tests executed in ~22 ms with no network calls, plus four text fixtures including `peng_sgh_sk_telecom_8k.txt` (score 9/10), `nvidia_partnership_8k.txt`, `sovereign_cluster_8k.txt` (score 10/10), and `noise_5_02_officer_change.txt` (correctly filtered). Source: [strategic-partner-firehose/README.md:21-30]() For the `price-alert` skill, the webhook handler is a Cloudflare Worker written in TypeScript. The `package.json` declares `wrangler` (`^4.0.0`) as a dev dependency, with `dev`, `deploy`, and `tail` scripts for local development and production rollout. Source: [price-alert/webhook/package.json:1-15]() ## Installation steps The README delegates primary installation guidance to each skill's `SETUP.md`, but the canonical 5-minute flow for the firehose family is: | Step | Action | Source | |---|---|---| | 1 | Fork `claude-investment-skills` to your own GitHub account | [README.md:126-128]() | | 2 | Create a Telegram bot via `@BotFather`; record `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` | [README.md:128-130]() | | 3 | Add both values as repository **Secrets** (Settings → Secrets and variables → Actions) | [README.md:130-132]() | | 4 | Open the **Actions** tab, select *Strategic Partner Firehose (8-K + 13D Real-Time)*, and click *Enable* | [README.md:135-137]() | | 5 | Verify the first run from the Actions logs; alerts begin arriving within one cron tick (≤ 30 min) | [README.md:138-141]() | No local Python install is required for end users — the workflow installs dependencies in a fresh `ubuntu-latest` runner. For developers who want to run the script locally, the same `scripts/partner_firehose.py` is executable as a standalone CLI and supports the same environment variables used by the cron. ## Configuration and state The firehose exposes a single on/off toggle in `strategic_config.json` at the skill root; flipping `enabled` to `false` suppresses Telegram delivery without disabling the workflow (the Actions cron keeps running and updating state). Two persistent JSON ledgers track system memory: - `strategic_state.json` — a deduplication ledger of SEC accession numbers already alerted, so a filing is never re-sent even if it appears in multiple poll windows. - `recent_alerts.json` — a 90-day rolling log consumed by `scripts/composite.py` to detect the same ticker appearing in both the partner firehose and the insider firehose within 30 days, which triggers a `MEGA SIGNAL` alert rate-limited to one send per ticker per 24 hours. Source: [strategic-partner-firehose/README.md:170-176]() A third ledger, `composite_state.json`, handles the 24-hour dedup window for composite alerts. None of the three ledgers contain personally identifiable information; they are pure ticker-level caches intended to be checked into the fork. ## What is and is not covered The v2.4 release explicitly excludes **S-1 IPO prospectuses** (which would have caught CoreWeave pre-IPO), **foreign-only listings** (HKEX, LSE, JPX), **SPACs and crypto IPOs**, and **F-1/20-F** filings from foreign private issuers. Form 8-K Item 5.02 (officer/director changes) is parsed but filtered as noise — verified by the `noise_5_02_officer_change.txt` fixture. Source: [strategic-partner-firehose/README.md:108-114]() ## See Also - [Strategic Partner Firehose — Detection Logic and Scoring](strategic-partner-firehose.html) - [Composite Signals — Cross-Firehose Mega-Signal Detection](composite-signals.html) - [Price Alert — Cloudflare Worker Webhook Setup](price-alert-webhook.html) --- ## Analysis Skills Catalog ### Related Pages Related topics: [Overview, Setup, and Installation](#page-1), [Discovery Firehoses and Real-time Channels](#page-3), [Price Alert System, Architecture, and Operations](#page-4)
Related Source Files The following source files were used to generate this page: - [strategic-partner-firehose/README.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md) - [price-alert/webhook/package.json](https://github.com/ssurmic/claude-investment-skills/blob/main/price-alert/webhook/package.json) - [analyze-stock/SKILL.md](https://github.com/ssurmic/claude-investment-skills/blob/main/analyze-stock/SKILL.md) - [macro-risk-check/SKILL.md](https://github.com/ssurmic/claude-investment-skills/blob/main/macro-risk-check/SKILL.md) - [earnings-prep/SKILL.md](https://github.com/ssurmic/claude-investment-skills/blob/main/earnings-prep/SKILL.md) - [leaps-screen/SKILL.md](https://github.com/ssurmic/claude-investment-skills/blob/main/leaps-screen/SKILL.md) - [option-wall-analysis/SKILL.md](https://github.com/ssurmic/claude-investment-skills/blob/main/option-wall-analysis/SKILL.md) - [portfolio-audit/SKILL.md](https://github.com/ssurmic/claude-investment-skills/blob/main/portfolio-audit/SKILL.md)
# Analysis Skills Catalog ## Overview The **Analysis Skills Catalog** is the on-demand, decision-support layer of the `claude-investment-skills` repository. Whereas the firehose skills (e.g., `strategic-partner-firehose`, `insider-firehose`) are cron-driven scanners that push raw signals to Telegram, the analysis skills are invoked by the user (or by a firehose follow-up workflow) to translate a signal into an actionable decision. In the documented triage flow for a freshly-fired firehose alert, the user is explicitly told to "Run `/analyze STOCK` in Telegram → triggers `analyze-stock` skill" and then "Run `/option-wall STOCK` → see option positioning" before sizing the position. Source: [strategic-partner-firehose/README.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md) The catalog is therefore best understood as a **portfolio of single-purpose, triggerable skills** that compose with the firehoses to form a full detect → validate → size → execute pipeline. --- ## Skill Inventory | Skill | Trigger Convention | Primary Purpose | Source Reference | |---|---|---|---| | `analyze-stock` | `/analyze ` | Full-context analysis when a firehose alert names an unknown ticker | [strategic-partner-firehose/README.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md) | | `option-wall-analysis` | `/option-wall ` | Inspect option flow / open-interest before sizing into a name | [strategic-partner-firehose/README.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md) | | `macro-risk-check` | Gates conviction buys | "Gate any conviction buy by current regime" — used as a pre-trade risk filter | [strategic-partner-firehose/README.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md) | | `earnings-prep` | Pre-earnings workflow | Prepares the user for an upcoming earnings event (referenced as a companion skill) | [earnings-prep/SKILL.md](https://github.com/ssurmic/claude-investment-skills/blob/main/earnings-prep/SKILL.md) | | `leaps-screen` | LEAP option screener | Long-dated option screening pass for conviction names | [leaps-screen/SKILL.md](https://github.com/ssurmic/claude-investment-skills/blob/main/leaps-screen/SKILL.md) | | `portfolio-audit` | Periodic audit | Whole-portfolio review (concentration, factor exposure, drawdown) | [portfolio-audit/SKILL.md](https://github.com/ssurmic/claude-investment-skills/blob/main/portfolio-audit/SKILL.md) | The README additionally names a `tax-optimize` skill ("tax math before exit") that is not in the canonical list above but is invoked at the close of a trade. Source: [strategic-partner-firehose/README.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md) --- ## Workflow Integration The analysis skills are **downstream consumers** of firehose output. The README prescribes a six-step triage for every alert that fires: ``` 1. Read the SEC EDGAR link in the alert 2. Run /analyze STOCK in Telegram → triggers analyze-stock 3. Run /option-wall STOCK → triggers option-wall-analysis 4. Cross-check the Partner Score factors 5. Size: ≤ 1% of portfolio per alert 6. Set price-alert if you want to wait for a dip ``` The repository's Telegram webhook handler (the Cloudflare Worker declared in `price-alert/webhook/package.json`) is the dispatch surface that routes `/analyze` and `/option-wall` commands to the appropriate skill. Source: [price-alert/webhook/package.json](https://github.com/ssurmic/claude-investment-skills/blob/main/price-alert/webhook/package.json) ```mermaid flowchart LR A[Firehose Alert
Telegram push] --> B[Read SEC EDGAR link] B --> C[/analyze TICKER
analyze-stock] C --> D[/option-wall TICKER
option-wall-analysis] D --> E{macro-risk-check
regime OK?} E -->|No| F[Pass / reduce size] E -->|Yes| G[Size ≤ 1%
Set price-alert] G --> H[tax-optimize
at exit] ``` --- ## When to Use Each Skill ### `analyze-stock` — The triage primitive This is the first skill called whenever a firehose surfaces a ticker the user does not already know. The README frames it as "when alert fires for unknown ticker, run for full context" — i.e., it produces a multi-factor snapshot (business, financials, recent catalysts) so the user can decide whether the SEC-driven signal is investable. Source: [strategic-partner-firehose/README.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md) ### `option-wall-analysis` — Sizing intelligence Invoked immediately after `analyze-stock`, this skill exposes option-chain positioning (walls of strikes, unusual open interest, dealer gamma) to inform strike selection and timing. The README explicitly recommends "check option flow before sizing in" as a non-optional step. Source: [strategic-partner-firehose/README.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md) ### `macro-risk-check` — The regime gate Unlike the two skills above, `macro-risk-check` is a veto, not an input. It answers "given the current macro regime, should a high-conviction buy be allowed at all?" The README's wording — "gate any conviction buy by current regime" — implies it should be queried for every firehose-derived trade. Source: [strategic-partner-firehose/README.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md) ### `earnings-prep`, `leaps-screen`, `portfolio-audit` These three are scheduled, not alert-driven. `earnings-prep` prepares for an upcoming report; `leaps-screen` runs the long-dated option scan over conviction names; `portfolio-audit` is the periodic whole-book review. They are listed in the `companion skills` section alongside the firehose triggers. Source: [strategic-partner-firehose/README.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md) --- ## Failure Modes and Boundaries Because the analysis skills are on-demand LLM-driven workflows, the principal risks are **hallucination** and **stale data** rather than runtime crashes. The firehose README does not enumerate failure modes for the analysis layer specifically, but its general advice — "if you fork this repo, leaving a star is the single most useful signal to the maintainer that someone is using it" — implies the analysis layer is best-effort and should always be cross-checked against primary sources (SEC filings, broker statements) before any capital is deployed. Source: [strategic-partner-firehose/README.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md) --- ## See Also - [Strategic Partner Firehose](strategic-partner-firehose.md) — the upstream 8-K / SC 13D firehose whose alerts trigger most of these analysis skills - [Insider Firehose](insider-firehose.md) — sibling Form 4 firehose; cross-validates with `strategic-partner-firehose` for MEGA SIGNAL alerts - [Price-Alert Webhook](price-alert-webhook.md) — the Cloudflare Worker that dispatches `/analyze` and `/option-wall` Telegram commands - [Tax-Optimize](tax-optimize.md) — invoked at position exit, per the README's companion-skills list --- ## Discovery Firehoses and Real-time Channels ### Related Pages Related topics: [Overview, Setup, and Installation](#page-1), [Analysis Skills Catalog](#page-2), [Price Alert System, Architecture, and Operations](#page-4)
Related Source Files The following source files were used to generate this page: - [strategic-partner-firehose/README.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md) - [strategic-partner-firehose/SKILL.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/SKILL.md) - [strategic-partner-firehose/SETUP.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/SETUP.md) - [strategic-partner-firehose/strategic_config.json](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/strategic_config.json) - [strategic-partner-firehose/scripts/partner_firehose.py](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/scripts/partner_firehose.py) - [strategic-partner-firehose/scripts/investor_registry.py](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/scripts/investor_registry.py) - [strategic-partner-firehose/scripts/parsers.py](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/scripts/parsers.py) - [strategic-partner-firehose/scripts/filters.py](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/scripts/filters.py) - [strategic-partner-firehose/scripts/composite.py](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/scripts/composite.py) - [strategic-partner-firehose/scripts/classifier.py](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/scripts/classifier.py) - [insider-firehose/SKILL.md](https://github.com/ssurmic/claude-investment-skills/blob/main/insider-firehose/SKILL.md) - [insider-firehose/scripts/form4_firehose.py](https://github.com/ssurmic/claude-investment-skills/blob/main/insider-firehose/scripts/form4_firehose.py) - [price-alert/webhook/package.json](https://github.com/ssurmic/claude-investment-skills/blob/main/price-alert/webhook/package.json)
# Discovery Firehoses and Real-time Channels ## 1. Purpose and Scope The "Discovery Firehoses and Real-time Channels" subsystem is the early-signal layer of the `claude-investment-skills` repository. It continuously polls U.S. SEC EDGAR for new filings and pushes actionable alerts to a Telegram bot, with the goal of surfacing strategic-partnership and insider-buying events before they are absorbed by retail-facing media (Substack, Twitter, financial newsletters). The strategic-partner firehose markets itself with the phrase "Find the next CoreWeave, the next PENG, the next POWL — by reading the same SEC filings hedge funds read, automatically, every 30 minutes" ([strategic-partner-firehose/README.md:1-2](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md)). The subsystem is implemented as two cooperating GitHub-Actions cron jobs (the "firehoses") plus a shared composite detector. Each firehose ingests a different SEC form type, normalizes it into a common alert record, and forwards the result through a Cloudflare Worker webhook to a Telegram chat. The firehoses intentionally do not run LLMs against filings — the design favors deterministic regex extraction plus rule-based scoring, validated by 36 unit tests ([strategic-partner-firehose/README.md:165-170](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md)). ## 2. Two Parallel Detection Paths (v2.4 Dual-Path Architecture) The strategic-partner firehose reads `8-K` and `SC 13D` filings and applies **two independent detection paths** so it catches both named-investor deals (PENG/CRWV) and anonymous-hyperscaler deals (POWL) ([strategic-partner-firehose/README.md:31-36](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md)). | Path | Trigger | Output alert | Implementation file | |---|---|---|---| | **Path A — Registry** | Filing body mentions an entity from `investor_registry.py` (NVIDIA, Microsoft, MGX, etc.) | 🤝 STRATEGIC PARTNER INVESTMENT | `scripts/parsers.py` + `scripts/investor_registry.py` | | **Path B — Theme classifier** | Filing has high density of AI/datacenter/hyperscaler keywords (theme score ≥ 6 / 10) | 🏭 AI INFRASTRUCTURE SIGNAL | `scripts/classifier.py` (added in v2.4) | When both paths fire on the same accession, a bonus theme tag is attached to the alert ([strategic-partner-firehose/README.md:38-46](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md)). ```mermaid flowchart LR A[SEC EDGAR poll
every 30 min] --> B[parsers.py
extract 8-K/13D] B --> C{Path A
investor_registry match?} B --> D{Path B
classifier.py score >= 6?} C -- yes --> E[🤝 PARTNER alert] D -- yes --> F[🏭 AI SIGNAL alert] E --> G[filters.py
mcap + US-listed + amount] F --> G G --> H[composite.py
cross-check insider-firehose] H -- same ticker, 30d --> I[🚨🚨🚨 MEGA SIGNAL] H --> J[Telegram bot
via webhook] I --> J ``` The classifier collapses multi-line whitespace before regex matching, which makes the detector robust to HTML-stripped filings where phrases like "largest order in company history" are broken across lines ([strategic-partner-firehose/README.md:188-190](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md)). ## 3. Filing Coverage and Investor Registry The firehose ingests a deliberately narrow slice of EDGAR to keep the false-positive rate near zero ([strategic-partner-firehose/README.md:53-60](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md)): | Form / Item | Why it matters | Example | |---|---|---| | 8-K Item 1.01 | "Entry into Material Definitive Agreement" — JVs, master supply agreements | OpenAI/CoreWeave 2025-03-31 | | 8-K Item 3.02 | "Unregistered Sales of Equity Securities" — PIPEs | SK Telecom $200M in PENG | | 8-K Item 7.01 | "Reg FD Disclosure" — attached press release | (read as exhibit) | | 8-K Item 8.01 | "Other Events" — material customer wins | POWL $400M data-center order | | SC 13D | Active >5% beneficial ownership | NVIDIA 7% in CRWV | `SC 13G` filings (passive index-fund ownership) are explicitly **downweighted** in the Partner Score by `−1` to avoid mistaking Vanguard/BlackRock holdings for strategic conviction ([strategic-partner-firehose/README.md:99-107](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md)). `investor_registry.py` stores the canonical entity list grouped into four tiers: **Tier-1** (NVIDIA, Microsoft, Alphabet, Amazon, Meta, Apple, Oracle, SK Telecom, SK Hynix, Samsung, LG, TSMC, SoftBank, Sony, ASML, SAP), **Tier-2** (Intel Capital, Qualcomm Ventures, Salesforce Ventures, Dell, HPE, Cisco, IBM, Adobe, ServiceNow, Workday, AMD), **Sovereign** (MGX, Mubadala, ADIA, Saudi PIF, Temasek, GIC, CPPIB), and **Smart-money VC** (a16z, Lux, Sequoia, Founders Fund, Khosla, Coatue, Tiger Global). Each entity carries 2–5 SEC-filing aliases (e.g. "NVIDIA Corporation" / "Nvidia Corp" / "NVentures") and is matched by full regex ([strategic-partner-firehose/README.md:64-69](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md)). ## 4. Composite MEGA SIGNAL and Cross-Firehose Coupling The strategic-partner firehose and the `insider-firehose` (Form 4 monitor) cross-validate each other. When **both** firehoses log an alert for the same ticker within 30 days, `scripts/composite.py` emits a "MEGA SIGNAL" that carries both messages in a single Telegram push ([strategic-partner-firehose/README.md:120-140](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md)). Mechanics ([strategic-partner-firehose/README.md:134-140](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md)): 1. Each firehose appends every alert to its own `recent_alerts.json` (90-day retention). 2. On every new alert, the firehose queries the other firehose's log for the same ticker. 3. If matched within 30 days, a composite alert is emitted. 4. Composite alerts are rate-limited to 1 send per ticker per 24h via `composite_state.json` to prevent spam. The composite detector is invoked by both firehoses and lives in the shared `scripts/composite.py` module; it is the explicit sibling link described in the README's "Companion skills" section ([strategic-partner-firehose/README.md:212-217](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md)). ## 5. Configuration, Scheduling, and Delivery The cron cadence is **every 30 minutes, weekdays 9 AM – 7:30 PM ET** in `strategic-partner-firehose/.github/workflows/`, deliberately aligned with the `insider-firehose` cron so composite alerts can fire on the same tick ([strategic-partner-firehose/README.md:174-178](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md), [strategic-partner-firehose/README.md:191-195](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md)). Toggles and runtime controls live in `strategic_config.json` (on/off for the workflow). Required secrets in the GitHub repository are `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID`, which are also reused by the price-alert bot. The webhook that receives firehose payloads and forwards them to Telegram is a Cloudflare Worker, declared in `price-alert/webhook/package.json` and run with `wrangler dev` / `wrangler deploy` ([price-alert/webhook/package.json:1-15](https://github.com/ssurmic/claude-investment-skills/blob/main/price-alert/webhook/package.json)). ## 6. Known Failure Modes and Out-of-Scope Filings The README is explicit about limitations ([strategic-partner-firehose/README.md:228-240](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md)): - **Conservative amount extraction** — regexes can miss deals where the dollar value is buried in tables or only described generically as "the Investment". - **False positives** — a filing that mentions NVIDIA in passing and also mentions $200M (e.g. a buyback) can be misclassified; the filter pipeline minimizes but does not eliminate these. - **No semantic LLM** — ambiguous cases are not second-passed; a future release may add an LLM layer. - **Out of scope** — S-1 IPO prospectuses (which would have caught CRWV pre-IPO; planned for v2.4+), foreign-only filings (HKEX/LSE/JPX), crypto IPOs/SPACs, and F-1 / 20-F foreign-private-issuer filings. The system is deliberately self-hosted: telemetry is opt-out by construction, with adoption measured only via public GitHub signals (stars, forks, issues, PRs) ([strategic-partner-firehose/README.md:248-273](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md)). ## See Also - [insider-firehose skill](https://github.com/ssurmic/claude-investment-skills/blob/main/insider-firehose/SKILL.md) — Form 4 sibling firehose that participates in composite MEGA SIGNAL detection - [analyze-stock skill](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md) — recommended follow-up workflow when an alert fires for an unknown ticker - [option-wall-analysis skill](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md) — option-flow check before sizing in - [macro-warning skill](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md) — regime gate before any conviction buy - [tax-optimize skill](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md) — tax math before exit --- ## Price Alert System, Architecture, and Operations ### Related Pages Related topics: [Overview, Setup, and Installation](#page-1), [Analysis Skills Catalog](#page-2), [Discovery Firehoses and Real-time Channels](#page-3)
Related Source Files The following source files were used to generate this page: - [price-alert/SKILL.md](https://github.com/ssurmic/claude-investment-skills/blob/main/price-alert/SKILL.md) - [price-alert/SETUP.md](https://github.com/ssurmic/claude-investment-skills/blob/main/price-alert/SETUP.md) - [price-alert/SETUP-zh.md](https://github.com/ssurmic/claude-investment-skills/blob/main/price-alert/SETUP-zh.md) - [price-alert/SETUP-WEBHOOK.md](https://github.com/ssurmic/claude-investment-skills/blob/main/price-alert/SETUP-WEBHOOK.md) - [price-alert/SETUP-WEBHOOK-zh.md](https://github.com/ssurmic/claude-investment-skills/blob/main/price-alert/SETUP-WEBHOOK-zh.md) - [price-alert/EXAMPLES.md](https://github.com/ssurmic/claude-investment-skills/blob/main/price-alert/EXAMPLES.md) - [price-alert/webhook/package.json](https://github.com/ssurmic/claude-investment-skills/blob/main/price-alert/webhook/package.json)
# Price Alert System, Architecture, and Operations ## Purpose and Scope The **Price Alert** skill is the notification and user-interaction surface for the `claude-investment-skills` repository. It is shared infrastructure that multiple upstream skills call into whenever an actionable signal is detected — most notably the `strategic-partner-firehose` and `insider-firehose` skills, but also any of the analysis skills that need to push results to a human operator. The role it plays is narrow but critical: - **Receiving signals** from cron-driven detector scripts that poll public sources (SEC EDGAR 8-K, SC 13D, Form 4, price feeds). - **Normalizing and deduplicating** alerts before they are sent, so a single filing does not page the operator twice. - **Pushing alerts** to a Telegram chat via a Cloudflare-hosted webhook, with credentials supplied through GitHub Secrets. - **Exposing an inbound webhook endpoint** so the user can issue commands back to Claude (`/analyze TICKER`, `/option-wall TICKER`, etc.) and the bot can reply with structured context. This skill is referenced explicitly in the workflow of every other skill in the toolkit. Source: [strategic-partner-firehose/README.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md) describes the workflow ending with *"Set price-alert if you want to wait for a dip"*, confirming the alert mechanism is the entry point for both automated detection and user-initiated analysis. ## Architecture The system is split into two cooperating halves: a **detector side** (Python scripts and GitHub Actions workflows under each upstream skill) and a **delivery side** (the Cloudflare Worker that fronts the Telegram Bot API). ### Detector side Each upstream skill (e.g. `strategic-partner-firehose/scripts/partner_firehose.py`) is invoked on a cron schedule by GitHub Actions. When a signal passes the skill's filters — for the strategic-partner firehose this means a Tier-1/Sovereign/Tier-2 investor in an 8-K Item 1.01/3.02 filing of a US-listed ≥ $50M mcap company, or a theme score ≥ 6 from the theme classifier — the script builds an alert payload and posts it through the shared Price Alert delivery path. Two JSON state files accompany each detector: - `strategic_state.json` — a dedup ledger of accessions already seen, so the same 8-K does not fire twice. - `recent_alerts.json` — a 90-day rolling window used by the composite-signal detector to recognize when two firehoses fire on the same ticker within 30 days and emit a 🚨🚨🚨 MEGA SIGNAL. Source: [strategic-partner-firehose/README.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md) describes *"Both firehoses log every alert to their own `recent_alerts.json` (90-day retention)"* and *"composite is rate-limited to 1 send per ticker per 24h"*. ### Delivery side (Cloudflare Worker) The inbound webhook is implemented as a Cloudflare Worker. The `price-alert/webhook/package.json` declares it explicitly: ```json { "name": "price-alert-webhook", "version": "1.0.0", "private": true, "description": "Cloudflare Worker — Telegram webhook handler for price-alert bot", "scripts": { "dev": "wrangler dev", "deploy": "wrangler deploy", "tail": "wrangler tail" }, "devDependencies": { "@cloudflare/workers-types": "^4.20251201.0", "typescript": "^5.5.0", "wrangler": "^4.0.0" } } ``` Source: [price-alert/webhook/package.json](https://github.com/ssurmic/claude-investment-skills/blob/main/price-alert/webhook/package.json). The presence of `wrangler dev`, `wrangler deploy`, and `wrangler tail` confirms the Worker is a standalone TypeScript service (per the `@cloudflare/workers-types` dependency) deployed to Cloudflare's edge, not a Node.js process or Cloudflare Pages function. ```mermaid flowchart LR EDGAR[SEC EDGAR
8-K / SC 13D / Form 4] -->|cron 30m| Det[Detector Scripts
Python] Det -->|passes filters| Dedup{Dedup ledger
state.json} Dedup -->|new accession| Alert[Build alert payload] Alert -->|HTTP POST| CW[Cloudflare Worker
price-alert-webhook] CW -->|Bot API| TG[Telegram Bot API] TG -->|push| User[Operator chat] User -->|reply /command| CW CW -->|invoke| Claude[Claude Code skills
analyze-stock, option-wall, ...] ``` ## Configuration and Setup Setup is documented across three SETUP files in the `price-alert/` directory, and the same credentials are reused across every skill that emits alerts. From the strategic-partner-firehose setup notes: *"Follow `price-alert/SETUP.md` once. Set `TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID` as GitHub Secrets. That's it — both firehoses + composite detection use the same bot."* Source: [strategic-partner-firehose/README.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md). The setup is split across: | File | Purpose | |---|---| | `price-alert/SETUP.md` | Core one-time setup — Telegram bot token, chat ID, GitHub Secrets | | `price-alert/SETUP-WEBHOOK.md` | Cloudflare Worker deployment for the inbound webhook endpoint | | `price-alert/EXAMPLES.md` | Sample alerts and operator workflow | The Worker has no application-level configuration beyond the standard `wrangler.toml` (not visible in the provided files), and the only declared entry points are `wrangler dev` for local emulation and `wrangler deploy` for production. Source: [price-alert/webhook/package.json](https://github.com/ssurmic/claude-investment-skills/blob/main/price-alert/webhook/package.json). ## Operations and Failure Modes ### When an alert fires The operator workflow, as documented in the strategic-partner-firehose README, is the canonical post-alert procedure reused by every emitting skill: 1. Read the SEC EDGAR link embedded in the alert (≈ 5–10 minutes). 2. Run `/analyze TICKER` in Telegram to trigger the `analyze-stock` skill. 3. Run `/option-wall TICKER` to inspect options positioning. 4. Cross-check the Partner Score factors emitted with the alert. 5. Size the position at ≤ 1% of portfolio per alert; never all-in. 6. Optionally set a price-alert to wait for a dip. Source: [strategic-partner-firehose/README.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md). ### Known gaps and operational risks Because the alert pipeline is regex-driven, three failure modes are documented in the source: - **Missing alerts** — the amount-extraction regex is conservative; filings that bury the dollar value in tables or refer only to "the Investment" generically will be missed. Source: [strategic-partner-firehose/README.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md). - **False positives** — a filing that mentions a Tier-1 name in passing alongside an unrelated $200M figure (e.g. a buyback) may be misclassified; the filter pipeline minimizes but does not eliminate this. - **No semantic understanding** — no LLM is invoked. v2.4 plans an LLM second-pass for ambiguous cases. ### What is *not* covered The skill explicitly does not monitor S-1 IPO prospectuses, foreign-only listings (HKEX, LSE, JPX), crypto IPOs, SPACs, or F-1 / 20-F foreign-private-issuer filings — all by design. Source: [strategic-partner-firehose/README.md](https://github.com/ssurmic/claude-investment-skills/blob/main/strategic-partner-firehose/README.md). ## See Also - [Strategic Partner Firehose](strategic-partner-firehose.md) - [Insider Firehose](insider-firehose.md) - [Analyze Stock](analyze-stock.md) - [Option Wall Analysis](option-wall-analysis.md) - [Macro Warning](macro-warning.md) - [Tax Optimize](tax-optimize.md) --- --- ## Pitfall Log Project: ssurmic/claude-investment-skills Summary: Found 9 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification. ## 1. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: packet_text.keyword_scan | https://github.com/ssurmic/claude-investment-skills ## 2. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.host_targets | https://github.com/ssurmic/claude-investment-skills ## 3. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/ssurmic/claude-investment-skills ## 4. Runtime risk - Runtime risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: packet_text.keyword_scan | https://github.com/ssurmic/claude-investment-skills ## 5. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/ssurmic/claude-investment-skills ## 6. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/ssurmic/claude-investment-skills ## 7. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/ssurmic/claude-investment-skills ## 8. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/ssurmic/claude-investment-skills ## 9. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/ssurmic/claude-investment-skills