@v587d/capital-generation 2.7.1 → 2.7.3

package/selected-skills/trading-skills/UPSTREAM.md

@@ -0,0 +1,111 @@
+# Upstream Record
+
+- Project: Trading Skills —— 19 颗讲交易过程纪律的 skill：下单前的检查（催化剂排布、自选清单分诊、证据缺口、
+  论点压力测试、盈亏比结构、执行计划可操作性、组合集中度）与下单后的复盘学习（交易日志模式、单笔复盘），
+  外加 4 颗把它们串起来的 workflow、一颗仓位计算与一颗券商 API 执行面。
+- Repository: https://github.com/marian2js/trading-skills
+- Upstream commit: `f1ae7d481154b49192681187cb08d39d7e2d4524`（main，2026-03-16，"Run skill-doctor and improve skill triggers"）
+  - 全仓 31 次提交，全部落在 2026-03-06 至 2026-03-16 这十天里。上游版本文件 `VERSION` = `0.1.0-rc.1`，无 release、无 tag。
+- License: MIT；`LICENSE` 为上游原件、未改写。**注意其 `Copyright (c) 2026` 一行没有署名**（上游就是这么写的），
+  署名按仓库 owner 与 commit author 记为 `marian2js`；catalog 的 `owner` 用同一个值拼仓库链接。
+- Imported content: 该 commit 的完整文件树（`skills/` 下 19 颗 skill + 共享 python 模块 + 仓库级材料），55 个文件 / 约 460 KB。
+  上游带 `.gitignore`（`__pycache__/`、`.env`、`.venv/` 等）——见下面的本地改动 2。
+
+- Local modifications（三类，逐条可复核；口径与理由见 `docs/dev/selected-skills.md` §8.6 的接入必查清单）：
+
+  1. **平铺掉 `<domain>/` 一层。** 上游把 skill 按主题分成两层：`skills/<domain>/<name>/SKILL.md`
+     （`idea-discovery`、`market-context`、`position-oversight`、`review-learning`、`thesis-validation`、
+     `trade-construction`、`live-trade`、`workflows`）。DSH filesystem provider 只枚举 skills 根的**直接子项**，
+     指 `skills` 等于发现 0 颗；而 provider 与 `test/selected-skills-content.test.mjs`、`test/packaging.test.mjs`、
+     `test/persona.test.mjs`、`capital-config` 原文旁路五处都按 `<repo>/<skillsDir>/<name>/SKILL.md` 反查
+     （AGENTS.md §9.7 那一族：漂了不报错，只是"勾了那一格、技能永远不出现"）。所以快照里是
+     `skills/<name>/…`，`SELECTED_SKILL_SKILL_DIRS` 填 `'skills'`。
+     每颗 skill 的 markdown 链接**只指向自己目录内**的 `references/…` 与 `assets/…`（逐颗核过，无 `../`、无跨目录链接），
+     平铺后一条不破。原分组记在这里供核对：
+     `idea-discovery` → catalyst-map、watchlist-review；`market-context` → earnings-preview、macro-event-analysis、
+     market-regime-analysis；`position-oversight` → position-management；`review-learning` → journal-pattern-analyzer、
+     post-trade-review；`thesis-validation` → evidence-gap-check、thesis-validation；`trade-construction` →
+     execution-plan-check、portfolio-concentration、position-sizing、risk-reward-sanity-check；`live-trade` → etoro；
+     `workflows` → earnings-trade-prep、portfolio-risk-review、post-trade-debrief、pre-trade-check。
+     随之变旧的是上游 `catalog.json` 里的 `path` / `docs_path` 字段与 `docs/examples/` 的路径口径——
+     两者都不进 catalog、也不进发布包（见 Packaging），按"不进 catalog 的正文一律不动"原样保留。
+  2. **删除上游的 `.gitignore`。** 被排除的 ignore 规则会在本仓继续生效，并把"按 commit 重导"的快照
+     与所钉 commit 弄成两种样子（InvestSkill 那一轮就是三个文件被静默挡掉）。vendored 快照不把 ignore 规则带进宿主仓库。
+  3. **取数与执行面口径改写**：8 份 `SKILL.md` + 2 份 `references/calculation-helpers.md`，
+     共 17 处句子级改动（+34 / −13 行）。分析结论、判定档位词汇（`must-watch` / `fragile` / `too concentrated` 一类）、
+     输入清单、输出顺序与 `references/` 的框架、阈值文档一字未改。
+     本颗**没有** `web search` 与记忆回填那一族（`web search` 零命中；每颗都写"缺什么就点名缺、别编"，
+     `example-mode` 指使用者自带的示例数据并要求标注，不是逃生口），换的是另外三种形态：
+     - **谁去取数（6 处）**：`catalyst-map`、`watchlist-review`、`evidence-gap-check`、`thesis-validation`、
+       `execution-plan-check`、`portfolio-concentration` 各有一句 `Do not fetch live data unless the user
+       explicitly asks to pair this skill with …`。前半句的意图（别自己去堆一堆数据）保留，
+       后半句改成"确实缺一个日期或一个字段时，把标的、字段、as-of 日期写成 brief 交给宿主取数通道——
+       角色分流的宿主里就是负责检索与行情的角色——用回来的东西继续，剩下的照旧标为未知"。
+       顺带这三句原本点名的 `earnings-preview` / `macro-event-analysis` 不在可选清单里（见下面的收录判断）。
+     - **没有 shell 就算不了（2 + 2 处）**：`journal-pattern-analyzer:49` 与 `risk-reward-sanity-check:52` 的
+       `For agents that support code execution, use [references/calculation-helpers.md] …` 改成
+       "本插件的分析角色没有 shell，也不跑 helper 脚本：统计量交给宿主数据侧（角色分流的宿主里委派做统计与质量校验的角色），
+       三笔以内可以在答复里手算并把算式写出来，缺输入的条目留空不补默认值"；
+       两颗各自的 `references/calculation-helpers.md` 随之从"复用 `skills/_lib/calculations.py` 里的函数"
+       改写成"这些量是什么、怎么取"（公式按上游 `_lib/calculations.py` 的实现核对：
+       `risk_reward_ratio` = |target−entry| / |entry−stop| 每单位、`expectancy` = 胜率×均盈 − 败率×均亏，
+       `kelly_fraction` 只是参照值，不作为交给使用者的仓位）。
+     - **点名的下一步 skill 未必存在（7 处）**：`catalyst-map`、`watchlist-review`、`evidence-gap-check`、
+       `thesis-validation`、`journal-pattern-analyzer`、`execution-plan-check`、`portfolio-concentration` 的
+       `Next Skill` 清单原句保留，各加同一句前置条件与退路（InvestSkill 那轮的改法）：
+       点名的 skill 只有使用者显式开启才存在于会话里，本插件明确不提供的那两类（下单、给仓位）永远不存在，
+       只能说成选项、不能替使用者跑。
+     **没有新增 `Retrieval:` 出处档**：上游根本没有这个枚举（§8.6 第 3 条不适用），
+     不为了套前几颗的改法新造上游没有的模板字段。
+
+- 收录判断（19 颗里 9 颗进 catalog，10 颗留在快照里当可审查材料）：
+  - **进**：`catalyst-map`、`watchlist-review`、`evidence-gap-check`、`thesis-validation`、
+    `risk-reward-sanity-check`、`execution-plan-check`、`portfolio-concentration`、
+    `journal-pattern-analyzer`、`post-trade-review`。
+    `post-trade-review` 一字未动就过闸门（全文无取数、无脚本、无出图，只在 `references/review-rubric.md`
+    里举了一条"高冲击数据日把仓位减 25%"的过程规则例子 → `riskNote` 写明属于过程推演）。
+  - **不进 · 执行面**：`etoro`。它是券商公开 API 的操作手册：`SKILL.md:18` "**Keys (request from the user on install)**"
+    与逐步生成密钥的说明、`x-api-key` / `x-user-key` 请求头、`curl -X POST …/trading/execution/…market-open-orders/by-amount`
+    带 `"IsBuy": true, "Leverage": 1`、"Use **non-demo execution endpoints** for real trading"、按 `positionId` 平仓，
+    末尾还指到一个 MCP server。§8.6 第 4 条（执行面）与第 7 条（真实下单）双重排除；本插件不接券商、不下单、
+    凭据只进 credentials 域（§5）。这颗连发布包都不进（`.npmignore`），全量仍住在 git 里。
+  - **不进 · 仓位与买卖动作**：`position-sizing`（索取 account equity，输出 `Position Recommendation`：
+    股数／合约数／账户风险百分比）、`position-management`（`hold, trim, tighten risk, close, or wait` + `Best Next Action`）。
+    与 `docs/reference/external-skill-scan-2026-10.md` 观察名单里既写的同一口径：
+    「评级、买卖动作和仓位决策属于明确冲突，不能直接集成」。
+  - **不进 · 接管会话路由**：`pre-trade-check`、`earnings-trade-prep`、`portfolio-risk-review`、`post-trade-debrief`
+    四颗 workflow。上游自己的 "Workflow routing" 段按结果分流到 11–12 颗子 skill 并给出
+    `ready` / `reject` / `hold through with conditions` 一类决断，与本插件的角色路由冲突
+    （`china-stock-research-orchestrator` 与 InvestSkill 的 `full-report` 是同一条理由）。
+  - **不进 · 数据层与本插件不兼容**：`earnings-preview`、`macro-event-analysis`、`market-regime-analysis`。
+    上游校验器把这套取数口径写成硬要求（`scripts/validate_repo.py:146` 要求这三颗必须写
+    `ask which supported provider`）：向用户点选 FMP／Polygon／TradingEconomics、在对话里认领"usable access details"、
+    然后 `curl "…apikey=<FMP_API_KEY>"`（三颗共 18 处 curl + 3 份 `data-providers.md`）。本插件没有这些服务商的凭据，
+    也不为它们开第二条取数口子；改写成"委派宿主通道"会让这 10 份 provider 文档变成死路，因此整颗留原文不改。
+    另外 `earnings-preview` 与 catalog 里已收录的 InvestSkill 同名那颗**撞车**——provider 的启用集合只按 `name` 认，
+    `test/persona.test.mjs` 钉住 name 全局唯一，收进来必然出问题。
+  - `test/selected-skills-provider.test.mjs` 用「skills 根目录 − 排除清单」派生本颗的可选清单，
+    `test/persona.test.mjs` 另把 `etoro` / `position-sizing` / `position-management` / `pre-trade-check` 明确断为不进 catalog。
+- 复核方法：`git clone` 所钉 commit 后，把上游 `skills/<domain>/<name>` 与快照 `skills/<name>` 逐颗 `diff -r`——
+  差异只应包含以上三类（10 份文件、17 处句子级改动；其余 11 颗与 `_lib/`、`LICENSE` 逐字节相同）。
+  `test/selected-skills-content.test.mjs` 扫正文**结果**、本文件记**理由**，两边任一漂回去都会红。
+- Packaging: 这颗带 `.npmignore`，挡的是非运行内容：`docs/`（上游文档站与 18 份 walkthrough）、
+  `scripts/`（上游的 catalog 生成与仓库校验 python）、`.github/`、`catalog.json`（上游自己的索引，与本仓
+  `selected-skills/catalog.js` 无关）、`README.md` / `CONTRIBUTING.md` / `CHANGELOG.md` / `VERSION` / `Makefile`、
+  `skills/_lib/`（共享 python 计算模块，本插件没有 shell 可跑它），以及合规口径那条 `skills/etoro/`（券商执行面，见上）。
+  其余不进可选清单的 skill 照 InvestSkill 先例**随包保留**作为可审查材料：provider 的 `list()` / `get()`
+  与 `/capital-skills/<name>.md` 旁路都按 catalog 闭集过滤，运行时读不到它们。
+  `package.json` 的 `files` 已逐仓库登记 `selected-skills/trading-skills`，
+  `test/packaging.test.mjs` 从 catalog 反查发布清单里的真实 `SKILL.md` / `LICENSE` / `UPSTREAM.md`，并反查上面每条目录规则确实生效。
+- Maintenance snapshot (checked 2026-10-11): 31 次提交集中在 2026-03-06 至 2026-03-16，此后 209 天无提交；
+  16 stars、6 forks，`0.1.0-rc.1` 未发 release。因此标 `watchlist`——与 `china-stock-research-skills`、
+  `peter-lynch-skill` 同一口径（内容可用、维护薄，启用前请使用者自行复核来源），不是内容缺陷。
+  See [GitHub commit history](https://github.com/marian2js/trading-skills/commits/main/)。
+- Runtime status: `watchlist` / 默认关闭的显式实验。只有使用者在「插件」→ Capital Generation →「精选 Skills」
+  里逐格打开，它们才对**之后新建**的 Capital 根 Agent 可见；子 Agent 不继承，上游脚本从不执行。
+  能力标签带来的新词是 `trade-discipline`（交易纪律 / Trade discipline），市场口径继续用 `us-stock`；
+  `riskNote` 里逐条写明各颗不做什么（不下单、不改单、不给仓位数字、不预测表现）。
+- Review status: 2026-11-06 复查上游、许可证与维护状态。内容按美股与境外交易习惯写（SPY／QQQ／ES 期货、
+  美股时段与盘前盘后、FINRA／Fidelity／Schwab 口径的集中度阈值、EURUSD 与 CFD／杠杆工具），
+  **不声称适用 A 股**，也不得直接当作 A 股规则；它提供的是过程纪律而不是信号或收益承诺，
+  所有金融主张须回到原始证据核验。本文件与本仓的收录判断不构成对上游观点的背书。

package/selected-skills/trading-skills/skills/catalyst-map/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: catalyst-map
+description: Build a ranked map of the catalysts that could move a watchlist, theme, or portfolio by showing what matters, when it matters, and how those events could transmit across related names or exposures.
+---
+
+# Catalyst Map
+
+Use this skill when the user wants a practical map of what could move a watchlist, sector, theme, or portfolio over a defined window, not just a raw event list.
+
+This skill will not:
+
+- predict the market reaction to a catalyst
+- replace detailed earnings or macro-event analysis for a single event
+- pretend every calendar item deserves equal attention
+
+## Role
+
+Act like a cross-asset catalyst planner. Your job is to identify the few events, milestones, and dependencies that actually matter, then show how they could affect the user's names or exposures.
+
+## When to use it
+
+Use it when the user wants to:
+
+- organize upcoming catalysts for a watchlist or theme
+- understand which events matter most for a sector, basket, or portfolio
+- connect company, macro, policy, product, regulatory, or industry catalysts into one map
+- decide which names need deeper prep and which catalysts only deserve background monitoring
+
+## Inputs and context
+
+Ask for:
+
+- the watchlist, theme, sector, or portfolio slice being mapped
+- the timeframe: next session, next week, next month, next quarter
+- the user's objective: swing prep, event-risk awareness, long-term monitoring, or idea discovery
+- any known catalysts already in view, such as earnings, product launches, CPI, FOMC, OPEC, trial data, policy dates, investor days, or guidance updates
+- which exposures matter most: single names, suppliers, customers, indexes, sectors, or macro-sensitive holdings
+
+Helpful but optional:
+
+- notes on what the user already believes matters most
+- regime or macro context already established elsewhere
+- whether the map is for trading entries, portfolio defense, or investor monitoring
+
+Use the user's materials first.
+
+If the user gives only a vague theme and no timeframe or exposures, say what is missing and keep the map provisional rather than inventing a false catalyst schedule.
+
+The map is built from what the user already has. When a date or a session really is missing, do not go and gather it from here: write the exact brief (event or ticker, the field needed, the as-of date) and hand it to the host's own retrieval path — in a role-split host, the agent that owns web retrieval and market data — then keep mapping from what comes back and leave the rest unknown.
+
+## Analysis process
+
+1. Reconstruct the watchlist, theme, or exposure set and define the time window.
+2. List the catalysts that could realistically move those names in that window.
+3. Rank the catalysts by decision relevance, not by headline count.
+4. Explain the transmission path for each important catalyst: direct issuer effect, peer read-through, supply-chain effect, macro sensitivity, policy channel, or sentiment shift.
+5. Separate high-priority catalysts from background noise.
+6. Flag which names are most exposed to each catalyst and where multiple names depend on the same event.
+7. End with the next research step for the top catalysts: deeper earnings prep, macro analysis, thesis validation, or simple monitoring.
+
+Use [references/catalyst-framework.md](references/catalyst-framework.md) when you need the default checklist for ranking, transmission, and overlap.
+
+## Core Assessment Framework
+
+Assess each catalyst on five anchors before calling it important:
+
+- `Timing Relevance`: whether the catalyst falls inside the user's actual decision window. Example: next week's CPI matters for a near-term rate-sensitive trade; a vague six-month product roadmap may not.
+- `Transmission Strength`: whether the event can directly move the user's names or exposures. Example: a benchmark earnings report may affect suppliers, peers, and sector ETFs, not just the reporting company.
+- `Decision Impact`: whether the event could change position plans, holding periods, or risk tolerance. Example: a catalyst that forces shorter holding periods has more decision impact than a low-signal conference appearance.
+- `Overlap`: whether multiple names or positions depend on the same catalyst chain. Example: owning several semis plus a tech ETF may create more catalyst clustering than the ticker list suggests.
+- `Preparation Need`: whether the catalyst requires deeper work now or only background awareness. Example: an earnings date with a live debate deserves prep; a low-information placeholder date may only deserve a note.
+
+Use the anchors to classify:
+
+- `primary catalyst`: high decision relevance and strong transmission into the user's names or exposures
+- `secondary catalyst`: worth monitoring, but less likely to dominate the plan
+- `background`: context only, unless other conditions make it more important later
+
+## Evidence That Would Invalidate This Analysis
+
+- the timeframe changes enough to reorder catalyst importance
+- a date moves, is canceled, or turns out to be less relevant than assumed
+- the user's watchlist or portfolio exposure changes materially
+- a catalyst's transmission path was overstated or duplicated another event
+- new macro, earnings, or policy information makes a previously secondary catalyst primary
+
+## Output structure
+
+Prefer this output order:
+
+1. `Catalyst Summary`
+2. `Primary Catalysts`
+3. `Secondary Catalysts`
+4. `Transmission Map`
+5. `Crowding Or Overlap Risks`
+6. `Next Skill`
+
+Always include:
+
+- the timeframe and objective used
+- which catalysts matter most and why
+- which names or exposures are linked to each key catalyst
+- where multiple names depend on the same event chain
+- what requires deeper prep now versus background monitoring
+- whether the next step is `earnings-preview`, `macro-event-analysis`, `market-regime-analysis`, `thesis-validation`, or no further action yet
+
+A skill named above is an option for the user, not a step this role can take: only the skills the user switched on exist in this session, and the ones this plugin deliberately does not offer — placing orders, setting position size — are not reachable at all. Say what you would check next and let the user decide.
+
+## Best practices
+
+- do not confuse more calendar entries with better preparation
+- do not list catalysts without explaining why they matter to the user's actual names
+- do not bury shared exposure to the same catalyst chain
+- do not turn a catalyst map into a directional prediction
+
+## Usage examples
+
+- "Use `catalyst-map` on my semis watchlist for the next three weeks and show me the company, macro, and policy events that matter most."
+- "Use `catalyst-map` on this energy portfolio for the next month and tell me which catalysts deserve deep prep versus simple monitoring."

package/selected-skills/trading-skills/skills/catalyst-map/references/catalyst-framework.md

@@ -0,0 +1,68 @@
+# Catalyst Framework
+
+Use this framework to map events and milestones into a smaller set of catalysts that actually deserve attention.
+
+## What counts as a catalyst
+
+A catalyst is not just a calendar event.
+
+It can be:
+
+- earnings
+- macro releases
+- central-bank decisions
+- product launches
+- investor days
+- guidance updates
+- regulatory or legal milestones
+- trial results
+- policy announcements
+- commodity or supply-chain developments
+
+## What makes a catalyst useful
+
+A useful catalyst map answers:
+
+- what matters
+- when it matters
+- who it affects
+- how it transmits
+- what preparation still needs to be done
+
+## Ranking questions
+
+For each catalyst, ask:
+
+- Is it inside the user's real decision window?
+- Can it change the thesis, holding period, or risk budget?
+- Does it affect one name or a whole cluster?
+- Does it overlap with other catalysts?
+- Does it require deeper work now?
+
+## Typical transmission paths
+
+- direct issuer effect
+- peer sympathy or read-through
+- supplier or customer chain
+- sector ETF or index effect
+- rates, FX, energy, or commodity channel
+- sentiment and positioning shift
+
+## Typical mistakes
+
+- listing every event instead of the few that matter
+- ignoring shared dependency on the same catalyst
+- failing to connect macro events to single-name risk
+- treating a catalyst as a forecast
+- forgetting that some catalysts matter only because of timeframe
+
+## Boundaries
+
+This framework does not decide:
+
+- whether a trade should be entered
+- what order type should be used
+- how much size should be allocated
+- whether the portfolio is too concentrated
+
+It only organizes what could move the relevant names or exposures.

package/selected-skills/trading-skills/skills/earnings-preview/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: earnings-preview
+description: Prepare for an upcoming earnings report or earnings week by identifying the reports that matter, framing the key debates, and surfacing the read-through risk that could affect the user's watchlist or positions.
+---
+
+# Earnings Preview
+
+Use this skill when the user needs to prepare before one company reports or before an earnings-heavy week.
+
+This skill will not:
+
+- predict the post-report price move with certainty
+- confuse a benchmark company's importance with a guaranteed read-through
+- replace missing fundamentals with narrative filler
+
+## Role
+
+Act like a skeptical earnings prep analyst. Focus on what matters, what is already priced in, what could surprise, and where the read-through really matters.
+
+## When to use it
+
+Use it when the user wants to:
+
+- prioritize which upcoming reports actually deserve attention
+- prepare for a single company report with peer and sector context
+- identify likely read-through names around a benchmark report
+- decide whether a report is worth holding through, fading, or avoiding
+
+## Inputs and context
+
+Ask for:
+
+- the company, peer group, sector, or watchlist
+- the date window or specific report being discussed
+- the user's thesis, exposure, or planned trade posture
+- what matters most this quarter: growth, margins, guidance, backlog, capex, demand, pricing, AI spend, consumer health, and so on
+- whether the user cares more about the report itself, sector read-through, or index impact
+
+Helpful but optional:
+
+- consensus expectations or prior-quarter context
+- known positioning or sentiment concerns
+- whether the user plans to hold through the event
+
+Use the user's materials first: pasted schedules, watchlists, company notes, guidance excerpts, estimate tables, transcripts, screenshots, or provider details already mentioned in the conversation.
+
+## If critical data is missing
+
+If you already have enough timing and context to do the analysis, do not fetch anything.
+
+If key schedule or estimate context is missing:
+
+- check whether the user already named a supported provider or already shared usable access details in the conversation
+- if they already indicated `FMP`, `TradingEconomics`, or `Polygon`, use [references/providers/fmp.md](references/providers/fmp.md), [references/providers/tradingeconomics.md](references/providers/tradingeconomics.md), or [references/providers/polygon.md](references/providers/polygon.md) directly
+- otherwise consult [references/data-providers.md](references/data-providers.md) and ask which supported provider they want to use
+- once the missing facts are gathered, continue the preview and disclose the source used
+
+## Analysis process
+
+1. Identify the reports that matter most for the user's names or theme.
+2. Explain why each report matters: direct exposure, peer sympathy, benchmark status, or index weight.
+3. Frame the key debates going into the report instead of defaulting to generic "beat or miss" language.
+4. Separate pre-report setup risk from business-quality judgment.
+5. Highlight the likely read-through paths, including supplier, customer, competitor, or sector ETF implications.
+6. State what would actually change the thesis, not just what would create short-term noise.
+7. If provider-based data was needed, use only the minimum missing facts and disclose source, freshness, and any obvious coverage gaps. Otherwise stay fully grounded in the user's material.
+
+Use [references/relevance-ranking.md](references/relevance-ranking.md) when you need a simple way to prioritize reports and explain why they matter.
+
+## Core Assessment Framework
+
+Assess each report on four anchors before ranking it:
+
+- `Benchmark Relevance`: whether the company can move a sector, supplier chain, customer set, or broad index. Example: NVDA is benchmark-relevant for semis and AI infrastructure; a small software name usually is not.
+- `Debate Intensity`: whether the quarter has one or two live disagreements that matter more than the headline beat or miss. Example: gross margin durability or cloud booking reacceleration counts as a real debate; generic "can they beat" does not.
+- `Read-Through Strength`: whether peers or related industries will plausibly react to the same datapoints. Example: capex guidance from a hyperscaler may matter for semis, power, cooling, and networking.
+- `Positioning Risk`: whether sentiment, recent price action, or the user's exposure makes the event more dangerous to hold through.
+
+Use the anchors to classify:
+
+- `must-watch`: benchmark relevance is high and at least one of debate intensity, read-through strength, or positioning risk is also high
+- `watch`: relevant event, but consequences are narrower or easier to absorb
+- `background`: useful context, but low priority unless it directly affects the user's book
+
+## Evidence That Would Invalidate This Analysis
+
+- the report date or session changes enough to alter the planning window
+- the quarter's key debate changes because management, industry data, or a peer report reframes the issue
+- read-through assumptions break because the peer set, supplier chain, or benchmark relationship was overstated
+- the user's exposure or holding plan changes, making the current priority ranking less relevant
+- estimate, guidance, or schedule fields turn out to be stale, incomplete, or sourced from the wrong provider snapshot
+
+## Output structure
+
+Prefer this output order:
+
+1. `Priority List`
+2. `Core Assessment Framework`
+3. `Key Debates`
+4. `Read-Through Map`
+5. `Plan Risk`
+6. `Evidence That Would Invalidate This Analysis`
+7. `Source And Caveats`
+
+Always return:
+
+- a prioritized report list or single-name preview
+- why each report matters in plain language
+- the key debates or watch items going into the print
+- the likely read-through map for peers, suppliers, customers, or sector leadership
+- the main pre-report risk to the user's plan
+- explicit caveats around missing dates, incomplete estimates, stale data, or example-mode data when relevant
+
+## Best practices
+
+- do not turn "important report" into "predictable trade"
+- do not confuse sector importance with a guaranteed stock move
+- distinguish between what matters for fundamentals and what matters for positioning
+- if timing, estimates, or coverage are incomplete, say that early rather than burying it
+
+## Usage examples
+
+- "Use `earnings-preview` for NVDA next week. I care about AI demand, gross margin durability, and read-through for semis."
+- "Use `earnings-preview` for AAPL, AMZN, and COST over the next ten days and tell me which reports matter most for index and sector read-through."

package/selected-skills/trading-skills/skills/earnings-preview/references/data-providers.md

@@ -0,0 +1,26 @@
+# Data Providers
+
+Use this only if the user did not already provide enough schedule or estimate context.
+
+Supported providers:
+
+- `FMP`: best default for forward earnings dates, report timing, and estimate fields through `/stable/earnings-calendar`
+- `TradingEconomics`: useful for earnings dates, release session, forecast fields, and revenue context through `/earnings-revenues`
+- `Polygon`: useful when the user already works in Polygon and needs recent reported financials, but not the best default for forward earnings schedule confirmation
+
+If the user already named one of these providers or already shared usable access details, use that provider path directly.
+
+Otherwise ask: "Which provider do you want to use for the missing earnings context: FMP, TradingEconomics, or Polygon?"
+
+Fallback strategy:
+
+- start with `FMP` when the missing piece is the upcoming earnings date, session, or consensus-style estimate fields
+- use `TradingEconomics` when the user already works there or when revenue forecast context matters
+- use `Polygon` when the user already uses Polygon for fundamentals and the missing piece is prior reported context rather than the upcoming schedule
+- if the user insists on `Polygon` but the exact upcoming date or session still cannot be confirmed, say that clearly and ask whether to supplement with `FMP` or `TradingEconomics`
+
+Provider notes:
+
+- [FMP](providers/fmp.md)
+- [TradingEconomics](providers/tradingeconomics.md)
+- [Polygon](providers/polygon.md)

package/selected-skills/trading-skills/skills/earnings-preview/references/providers/fmp.md

@@ -0,0 +1,49 @@
+# FMP
+
+Use this path only when the user already indicated `FMP` or chose it from the supported provider list.
+
+Use the smallest request that fills the missing earnings facts.
+
+## Best endpoint for a date window
+
+Call the official earnings calendar endpoint:
+
+```bash
+curl "https://financialmodelingprep.com/stable/earnings-calendar?from=2026-03-09&to=2026-03-20&apikey=<FMP_API_KEY>"
+```
+
+Use this when the user gave a date window and you need report timing or estimate context for one or more names.
+
+Pull only the fields you need for the preview:
+
+- `date`
+- `symbol`
+- `name`
+- `time`
+- `epsEstimated`
+- `revenueEstimated`
+- `epsActual`
+- `revenueActual`
+- `lastUpdated`
+
+## Best endpoint for a single company
+
+If the user only cares about one company and you already know the symbol, use:
+
+```bash
+curl "https://financialmodelingprep.com/stable/earnings?symbol=AAPL&apikey=<FMP_API_KEY>"
+```
+
+This is useful when the user wants one-name context rather than a calendar sweep.
+
+## How to use the result
+
+- confirm the report date and timing first
+- use estimate fields only to frame the debate, not to imply direction
+- if `time`, EPS estimates, or revenue estimates are missing, say that explicitly
+- disclose that FMP supplied the missing schedule or estimate data
+
+Official docs:
+
+- [FMP earnings calendar API](https://site.financialmodelingprep.com/developer/docs/stable/earnings-calendar)
+- [FMP earnings report API](https://site.financialmodelingprep.com/developer/docs/earnings-historical-earnings)

package/selected-skills/trading-skills/skills/earnings-preview/references/providers/polygon.md

@@ -0,0 +1,45 @@
+# Polygon
+
+Use this path only when the user already indicated `Polygon` or chose it from the supported provider list.
+
+Polygon is useful here for recent reported fundamentals and prior-quarter anchors. It is not the best default source for exact upcoming earnings date or session confirmation.
+
+## Best endpoint for recent reported financials
+
+Call the official financials endpoint:
+
+```bash
+curl "https://api.polygon.io/vX/reference/financials?ticker=AAPL&timeframe=annual&limit=4&apiKey=<POLYGON_API_KEY>"
+```
+
+Use this when the user already knows the company and you need recent reported revenue, EPS-related fields, margin context, or balance-sheet anchors to frame the debate.
+
+Pull only the fields you need:
+
+- `ticker`
+- `fiscal_period`
+- `fiscal_year`
+- `financials.income_statement`
+- `financials.balance_sheet`
+- `financials.cash_flow_statement`
+- `filing_date`
+
+## Optional market-reaction context
+
+If the user also needs to know how the stock behaved around the last report, pair the fundamentals call with aggregate bars:
+
+```bash
+curl "https://api.polygon.io/v2/aggs/ticker/AAPL/range/1/day/2026-01-15/2026-02-15?adjusted=true&sort=asc&limit=500&apiKey=<POLYGON_API_KEY>"
+```
+
+## How to use the result
+
+- use Polygon to anchor what the company last reported and where the debate may start
+- do not pretend Polygon solved the forward schedule problem if the exact upcoming report date or session is still unclear
+- if the user needs forward timing confirmation and Polygon does not provide it cleanly, say so and ask whether to supplement with `FMP` or `TradingEconomics`
+- disclose that Polygon supplied the historical fundamental context
+
+Official docs:
+
+- [Polygon financials API](https://polygon.io/docs/rest/stocks/fundamentals/financials)
+- [Polygon aggregate bars API](https://polygon.io/docs/rest/stocks/aggregates/custom-bars)

package/selected-skills/trading-skills/skills/earnings-preview/references/providers/tradingeconomics.md

@@ -0,0 +1,49 @@
+# TradingEconomics
+
+Use this path only when the user already indicated `TradingEconomics` or chose it from the supported provider list.
+
+Use the smallest request that fills the missing earnings facts.
+
+## Best endpoint for a date window
+
+Call the official earnings and revenues endpoint:
+
+```bash
+curl "https://api.tradingeconomics.com/earnings-revenues?c=<TE_API_KEY>&d1=2026-03-09&d2=2026-03-20&f=json"
+```
+
+Use this when the user gave a time window and you need the report date, session, or forecast fields for more than one company.
+
+Pull only the fields you need for the preview:
+
+- `Date`
+- `Symbol`
+- `Name`
+- `Forecast`
+- `RevenueForecast`
+- `Previous`
+- `RevenuePrevious`
+- `MarketRelease`
+- `Importance`
+- `LastUpdate`
+
+## Best endpoint for a single company
+
+If the user only cares about one company and you already know the provider symbol, use:
+
+```bash
+curl "https://api.tradingeconomics.com/earnings-revenues/symbol/aapl:us?c=<TE_API_KEY>&d1=2025-01-01&d2=2026-12-31&f=json"
+```
+
+TradingEconomics symbols are provider-specific, such as `aapl:us`.
+
+## How to use the result
+
+- confirm the report date and `MarketRelease` timing
+- use `Forecast` and `RevenueForecast` only as context, not as a prediction signal
+- if the provider lacks a field the analysis needs, say so clearly and continue with the available information
+- disclose that TradingEconomics supplied the missing schedule or estimate data
+
+Official docs:
+
+- [TradingEconomics earnings and revenues docs](https://docs.tradingeconomics.com/financials/earnings_revenues/)

package/selected-skills/trading-skills/skills/earnings-preview/references/relevance-ranking.md

@@ -0,0 +1,24 @@
+# Relevance Ranking
+
+The v1 ranking is deliberately simple and explainable.
+
+## Inputs to the score
+
+- whether the symbol is directly requested
+- market-cap bucket
+- whether the company is a benchmark name in a watched sector
+- whether the report has broad read-through implications
+- whether timing and estimate fields are present
+
+## What the score is not
+
+- a prediction of the stock move
+- a conviction score
+- a measure of trade quality
+
+## Reporting guidance
+
+Always pair the numeric score with a short reason, for example:
+
+- "Mega-cap benchmark with index weight and supplier read-through."
+- "Mid-cap peer read-through is useful, but broad market impact is limited."