@v587d/capital-generation 2.7.2 → 2.7.3

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."

package/selected-skills/trading-skills/skills/earnings-trade-prep/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: earnings-trade-prep
+description: Orchestrate a disciplined earnings-event workflow by deciding which names deserve prep, mapping the key debates and read-through paths, pressure-testing the thesis and structure, and ending with a clear pre-earnings hold, avoid, or trade decision.
+---
+
+# Earnings Trade Prep
+
+Use this workflow skill when the user is preparing to trade around earnings or deciding whether to hold an existing or planned position into an earnings event.
+
+This workflow will not:
+
+- predict the post-earnings price move
+- treat a strong narrative as enough reason to hold through the event
+- force a hold-through decision if the real answer is to reduce, avoid, or wait
+
+## Role
+
+Act like an earnings-event gatekeeper. Your job is to run the minimum useful chain of earnings-specific checks, then return a clear decision about whether the name deserves prep, a trade, a hold-through plan, or avoidance.
+
+## When to use it
+
+Use it when the user wants to:
+
+- prepare one name or a small peer group for an upcoming earnings report
+- decide whether to hold through earnings, trade the setup before the event, or avoid it
+- organize the key debates, read-through paths, and event-specific risks in one place
+- stop running disconnected checks manually before every earnings-heavy week
+
+## Inputs and context
+
+Ask for:
+
+- the company or peer group
+- the earnings window or known report timing
+- whether the user is flat, already in a position, or planning a new trade
+- the main pre-earnings thesis or concern
+- whether the user cares more about the single name, sector read-through, or both
+
+Helpful but optional:
+
+- current entry, stop, target, or existing position details
+- portfolio overlap with peers or sector ETFs
+- execution constraints such as regular-hours only or no hold-through-event policy
+
+Use the user's materials first.
+
+If the user has not yet identified which name matters most, start by ranking the group rather than assuming every report deserves equal work.
+
+## Workflow routing
+
+Use the smallest useful chain:
+
+1. If the user starts with several earnings names, run `watchlist-review`.
+2. If the event picture across the group is still fuzzy, run `catalyst-map`.
+3. Run `earnings-preview` on the selected name or peer set.
+4. If the idea is still under-researched, run `evidence-gap-check`.
+5. Run `thesis-validation` on the event thesis or hold-through logic.
+6. If the broader tape matters, run `market-regime-analysis`.
+7. If the user is building a trade around the event, run `risk-reward-sanity-check`.
+8. If entry or exit mechanics matter, run `execution-plan-check`.
+9. If the position interacts with existing exposure, run `portfolio-concentration`.
+10. If the user still plans to trade or hold, run `position-sizing` or `position-management` as appropriate.
+
+Stop the workflow when the event thesis, execution plan, or hold-through logic becomes indefensible.
+
+## Decision logic
+
+Classify the result as:
+
+- `prep only`: the name deserves further monitoring or notes, but not an immediate trade or hold-through commitment
+- `trade before event only`: the setup may be valid, but holding through the report is not justified
+- `hold through with conditions`: holding through earnings is defensible only under explicit constraints
+- `avoid`: the event-specific risk, uncertainty, or overlap is too high for the current plan
+
+## Output structure
+
+Prefer this output order:
+
+1. `Earnings Prep Verdict`
+2. `Checks Run`
+3. `Key Debate And Read-Through`
+4. `Hold-Through Decision`
+5. `What Still Needs Work`
+6. `Updated Trade Context`
+7. `Next Skill Or Action`
+
+Always include:
+
+- the minimum set of checks actually used
+- the key earnings debate
+- the main hold-through or avoid reason
+- whether the user should prep only, trade before the event, hold through with conditions, or avoid
+- a compact updated trade context block when enough information exists
+
+## Updated Trade Context
+
+When enough context exists, carry forward a compact block like this:
+
+```markdown
+## Trade Context
+
+- instrument:
+- direction:
+- timeframe:
+- thesis:
+- key_debate:
+- read_through_map:
+- upcoming_events:
+- invalidation:
+- entry_idea:
+- stop_idea:
+- target_idea:
+- position_size_hint:
+- portfolio_impact:
+- confidence_notes:
+- open_questions:
+- source_freshness:
+- assumptions:
+- next_recommended_skill:
+```
+
+Only populate fields supported by the checks that actually ran.
+
+## Best practices
+
+- do not let "important report" become "must hold through"
+- do not ignore sector or ETF overlap around benchmark earnings
+- do not hide event-specific execution risk behind a good-looking setup
+- do not continue the workflow once the hold-through logic is broken
+
+## Usage examples
+
+- "Use `earnings-trade-prep` on NVDA for next week and tell me whether this is a prep-only name, a pre-event trade, or a hold-through candidate."
+- "Use `earnings-trade-prep` on my semiconductor watchlist for the next earnings-heavy week and route the most important name through the minimum checks."

package/selected-skills/trading-skills/skills/earnings-trade-prep/references/workflow-framework.md

@@ -0,0 +1,65 @@
+# Earnings Trade Prep Framework
+
+Use this framework to decide whether an earnings-related trade or hold plan is actually defensible.
+
+## Core question
+
+The question is not only:
+
+- "Is this report important?"
+
+The real questions are:
+
+- Which report matters most?
+- What is the actual debate?
+- Does the user want a pre-event trade, a hold-through decision, or just better preparation?
+- What breaks the plan?
+
+## Typical routing
+
+If the user starts with many names:
+
+- `watchlist-review`
+- `catalyst-map`
+
+For the selected name or group:
+
+- `earnings-preview`
+- `evidence-gap-check` if the idea is still underdeveloped
+- `thesis-validation`
+
+If broader conditions matter:
+
+- `market-regime-analysis`
+
+If the user wants an actual trade plan:
+
+- `risk-reward-sanity-check`
+- `execution-plan-check`
+- `portfolio-concentration`
+- `position-sizing` or `position-management`
+
+## Stop conditions
+
+Stop when:
+
+- the debate is not clear
+- the hold-through logic is weak
+- the structure depends on unrealistic event behavior
+- the portfolio overlap is too high
+- the user is trying to force a yes on an avoid case
+
+## Wrapper discipline
+
+The workflow should:
+
+- identify the few checks that matter most
+- stop at the first real blocker
+- return a clear event decision
+- carry forward a compact trade context only when justified
+
+## Boundaries
+
+This workflow does not predict the earnings reaction.
+
+It only decides whether the user has a defensible event-prep or event-trade plan.