@v587d/capital-generation 2.7.2 → 2.7.3

package/selected-skills/trading-skills/skills/portfolio-concentration/references/concentration-framework.md

@@ -0,0 +1,72 @@
+# Concentration Framework
+
+Use this framework to judge whether a portfolio is less diversified than the raw ticker count suggests.
+
+## What concentration risk actually means
+
+Concentration risk is not only "one giant stock position."
+
+It can also come from:
+
+- multiple holdings tied to the same issuer
+- sector overlap
+- thematic overlap
+- benchmark overlap
+- employer stock
+- illiquid positions that cannot be reduced easily
+- partial portfolio views that hide true exposures
+
+## Source-informed heuristics
+
+These are practical review thresholds, not universal laws:
+
+- A single position at roughly `5%` of total portfolio value deserves review.
+- A single issuer above roughly `10%` is often already an elevated concentration case for many investors.
+- Employer stock above roughly `10-20%` is a notable overconcentration risk because income and portfolio value may depend on the same company.
+- Two or three concentrated single-name positions can create concentration risk even if no single holding looks extreme by itself.
+
+These heuristics are informed by retail-investor guidance and portfolio tools from FINRA, Fidelity, and Schwab. Use them as prompts for review, not mechanical rules.
+
+## Direct vs indirect concentration
+
+Direct concentration:
+
+- one stock
+- one bond issuer
+- one narrow ETF
+
+Indirect concentration:
+
+- individual semiconductor names plus a semiconductor ETF
+- multiple AI or cloud names with the same demand driver
+- broad indexes that already have large weights in the same mega-cap holdings
+- company stock plus compensation, restricted stock, or career exposure to the same issuer
+
+## What to look for
+
+Ask:
+
+- What are the top three positions?
+- What are the top three correlated clusters?
+- If one thesis fails, how many holdings fail with it?
+- Could the user reduce the exposure quickly?
+- Is this the full portfolio or just one sleeve?
+
+## Typical caution cases
+
+- employer stock paired with salary dependence
+- narrow sector ETFs layered on top of the same underlying single names
+- thematic baskets that look diversified by label but share the same catalyst chain
+- portfolios tied closely to cap-weighted indexes during periods of heavy mega-cap concentration
+- illiquid or tax-constrained winners that grew into oversized positions
+
+## Boundaries
+
+This framework does not decide:
+
+- whether the thesis is valid
+- where to enter
+- where the stop belongs
+- how large the position should be
+
+It only answers whether the portfolio is already too dependent on a small set of exposures.

package/selected-skills/trading-skills/skills/portfolio-risk-review/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: portfolio-risk-review
+description: Orchestrate a whole-book risk review by checking concentration, correlated exposure, catalyst clustering, market-context sensitivity, and live-position fragility before the user adds, holds, or reduces portfolio risk.
+---
+
+# Portfolio Risk Review
+
+Use this workflow skill when the user wants a portfolio-level answer to the question, "Where is my real risk right now?" rather than a single-position analysis.
+
+This workflow will not:
+
+- build a long-term strategic financial plan
+- replace tax, legal, or retirement-planning advice
+- assume a portfolio is safe just because no single holding looks extreme in isolation
+
+## Role
+
+Act like a portfolio risk reviewer. Your job is to identify where the book is actually exposed, which risks are clustered, and what needs attention before the user adds, holds, or reduces risk.
+
+## When to use it
+
+Use it when the user wants to:
+
+- review portfolio risk before adding a new position
+- understand where concentration or overlap is hiding
+- assess whether upcoming catalysts create too much clustered exposure
+- know whether the current book needs trimming, hedging, smaller adds, or closer monitoring
+
+## Inputs and context
+
+Ask for:
+
+- the portfolio or account snapshot, including approximate weights or position sizes
+- whether the snapshot is the full portfolio, one account, or only the active risk sleeve
+- any planned new add or reduction
+- upcoming catalysts the user already knows about
+- whether the focus is tactical trading capital, swing capital, or longer-term investing capital
+
+Helpful but optional:
+
+- sector, theme, or factor tags
+- current regime view or macro concern
+- which positions are already under pressure or near key catalysts
+- any known liquidity or execution constraints
+
+Use the user's materials first.
+
+If the snapshot is partial, say so clearly and keep the result provisional.
+
+## Workflow routing
+
+Use the smallest useful chain:
+
+1. Run `portfolio-concentration` to identify direct and indirect concentration.
+2. If catalyst clustering matters, run `catalyst-map`.
+3. If broad market context matters, run `market-regime-analysis`.
+4. If a major macro calendar is relevant to the portfolio, run `macro-event-analysis`.
+5. If one or more open positions are under pressure, run `position-management` on the critical positions.
+6. If the user is considering a new add, run `pre-trade-check` or the specific construction skills only after the portfolio-level risk picture is clear.
+
+Stop the workflow when the book is already too concentrated or too catalyst-heavy for the user's stated objective.
+
+## Decision logic
+
+Classify the result as:
+
+- `portfolio risk acceptable`: the book appears aligned with the user's objective and no immediate portfolio-level change is necessary
+- `portfolio risk elevated`: the book is still manageable, but concentration, overlap, or catalyst clustering needs active monitoring or smaller adds
+- `portfolio risk too high`: the book is too dependent on a limited set of exposures, events, or fragile positions to justify adding risk without changes
+
+## Output structure
+
+Prefer this output order:
+
+1. `Portfolio Risk Verdict`
+2. `Checks Run`
+3. `Main Risk Sources`
+4. `Catalyst And Regime Pressure`
+5. `What To Reduce, Watch, Or Avoid Adding`
+6. `Updated Portfolio Context`
+7. `Next Skill Or Action`
+
+Always include:
+
+- whether the snapshot was full or partial
+- the main risk sources in the current book
+- where exposures overlap or cluster
+- whether upcoming catalysts or macro conditions increase portfolio fragility
+- whether the right action is hold, trim, avoid adding, or review specific positions more closely
+- a compact updated portfolio context block when enough information exists
+
+## Updated Portfolio Context
+
+When enough context exists, carry forward a compact block like this:
+
+```markdown
+## Portfolio Context
+
+- objective:
+- snapshot_scope:
+- top_exposures:
+- overlap_clusters:
+- key_catalysts:
+- regime_pressure:
+- fragile_positions:
+- planned_add:
+- portfolio_constraints:
+- risk_summary:
+- open_questions:
+- assumptions:
+- next_recommended_skill:
+```
+
+Only populate the fields supported by the checks that actually ran.
+
+## Best practices
+
+- do not treat issuer count as diversification by itself
+- do not ignore shared catalyst risk across several names
+- do not review a partial snapshot as if it were the whole book
+- do not continue into a new trade workflow before the portfolio-level blocker is explicit
+
+## Usage examples
+
+- "Use `portfolio-risk-review` on my current book before I add more semis."
+- "Use `portfolio-risk-review` on this account for the next two weeks and tell me where the real risk is concentrated."

package/selected-skills/trading-skills/skills/portfolio-risk-review/references/workflow-framework.md

@@ -0,0 +1,57 @@
+# Portfolio Risk Review Framework
+
+Use this framework to decide whether portfolio-level risk is acceptable before adding or maintaining more exposure.
+
+## Core question
+
+The question is not only:
+
+- "What is my biggest position?"
+
+The real questions are:
+
+- Where are my exposures clustered?
+- Which catalysts matter to the portfolio as a whole?
+- Which positions are fragile right now?
+- Is the current book aligned with my objective and timeframe?
+
+## Typical routing
+
+Start with:
+
+- `portfolio-concentration`
+
+Add as needed:
+
+- `catalyst-map` when several positions share event risk
+- `market-regime-analysis` when broad tape conditions matter
+- `macro-event-analysis` when the macro calendar can pressure the whole book
+- `position-management` when one or more live positions are under pressure
+
+If the user still wants a new trade after the review:
+
+- `pre-trade-check`
+
+## Stop conditions
+
+Stop when:
+
+- concentration is already too high
+- several positions share the same catalyst cluster
+- the macro or regime backdrop makes the current book too fragile
+- the portfolio snapshot is too incomplete to review honestly
+
+## Wrapper discipline
+
+The workflow should:
+
+- surface the biggest risk sources fast
+- separate portfolio-level risk from single-name conviction
+- avoid pretending the portfolio is diversified when the drivers are the same
+- return one clear next portfolio action
+
+## Boundaries
+
+This workflow does not perform full financial planning.
+
+It only reviews current portfolio risk and what should happen next.

package/selected-skills/trading-skills/skills/position-management/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: position-management
+description: Review an open position and decide whether to hold, trim, tighten risk, close, or wait by comparing current behavior against the original thesis, invalidation logic, catalyst calendar, and execution constraints.
+---
+
+# Position Management
+
+Use this skill after a position is open when the user needs a disciplined decision about holding, trimming, tightening risk, or exiting without drifting into improvisation.
+
+This skill will not:
+
+- justify staying in a broken trade because the user wants it to work
+- replace pre-trade sizing or portfolio-concentration review
+- guarantee that stop adjustments or trailing logic will lock in a specific outcome
+
+## Role
+
+Act like a disciplined live-risk manager. Your job is to compare the open position against the original plan, current market behavior, and upcoming catalysts, then recommend the next management decision clearly.
+
+## When to use it
+
+Use it when the user wants to:
+
+- decide whether to hold, trim, tighten risk, or exit an open position
+- manage a winner without turning it into a round trip
+- handle a loser without widening risk impulsively
+- decide whether holding through earnings, macro releases, or other catalysts still makes sense
+
+## Inputs and context
+
+Ask for:
+
+- instrument and direction
+- original thesis, timeframe, entry, stop, target, and size
+- current price behavior or status: near target, stalling, breaking down, gapping, and so on
+- current stop logic or trailing logic
+- any upcoming catalyst or event risk
+- whether the user is trying to protect gains, reduce loss, hold through a catalyst, or simply avoid emotional decision-making
+
+Helpful but optional:
+
+- unrealized PnL or R multiple
+- partial exits already taken
+- whether the position sits in a concentrated portfolio or highly correlated cluster
+- order or liquidity constraints that affect exits
+
+Use the user's materials first.
+
+If the original plan is missing, say that clearly and manage the position provisionally rather than inventing a clean prior plan.
+
+Do not fetch live data unless the user explicitly asks to pair this skill with another market-context or event-risk skill.
+
+## Analysis process
+
+1. Reconstruct the original plan and the current position status.
+2. Compare current behavior against the thesis and invalidation logic.
+3. Separate normal noise from evidence that the trade or investment is weakening.
+4. Evaluate whether an upcoming catalyst changes the holding decision materially.
+5. Check whether the current stop, trailing logic, or target handling is still coherent.
+6. Distinguish between thesis-based management and emotion-based improvisation.
+7. End with one clear next action: hold, trim, tighten risk, close, or wait for a defined condition.
+
+Use [references/management-framework.md](references/management-framework.md) when you need the default checklist for open-risk decisions, trailing logic, and catalyst-aware management.
+
+## Core Assessment Framework
+
+Assess the open position on five anchors before recommending a change:
+
+- `Thesis Integrity`: whether the original reason for holding still looks intact. Example: a breakout that loses leadership and closes back into the prior range has weaker thesis integrity than one consolidating above the breakout area.
+- `Reward Realization`: whether the trade has already traveled enough that the management problem changes from "is the idea valid?" to "how do I avoid giving too much back?" Example: a position near target may justify different management than a new entry still proving itself.
+- `Risk Drift`: whether the user has widened risk, delayed exits, or let the position drift away from the original plan. Example: moving the stop wider after entry without a new thesis is usually risk drift, not strategy.
+- `Catalyst Exposure`: whether earnings, macro releases, or other scheduled events make the current holding plan materially more fragile. Example: a swing long near target ahead of earnings may deserve a different decision than the same setup in a quiet calendar.
+- `Exit Practicality`: whether liquidity, spread, session timing, or order constraints affect the ability to trim or exit cleanly. Example: a thin option or extended-hours position may require more conservative management.
+
+Use the anchors to classify:
+
+- `hold with plan intact`: the position still fits the original logic and current management rules
+- `manage actively`: the thesis may still be alive, but trimming, tightening risk, or updating the hold plan is warranted
+- `exit or reduce decisively`: the thesis, catalyst profile, or risk discipline has degraded enough that passive holding is no longer defensible
+
+## Evidence That Would Invalidate This Analysis
+
+- the original plan was remembered incorrectly or new plan details appear
+- the catalyst timing changes materially
+- the user's timeframe changes from tactical trade to longer-term hold, or the reverse
+- the current position size or partial exits differ from what was described
+- the session, liquidity, or execution conditions change enough to alter the practicality of the suggested action
+
+## Output structure
+
+Prefer this output order:
+
+1. `Management Summary`
+2. `Original Plan Versus Now`
+3. `Thesis And Risk Review`
+4. `Catalyst Decision`
+5. `Best Next Action`
+6. `What Would Change That Decision`
+7. `Next Skill`
+
+Always include:
+
+- whether the original thesis still looks intact
+- whether the current stop or trailing logic is coherent
+- whether upcoming catalysts change the hold decision
+- the clearest next action: hold, trim, tighten risk, close, or wait
+- what specific condition would change that action
+- whether the next step is `post-trade-review`, `macro-event-analysis`, `earnings-preview`, or no additional skill yet
+
+## Best practices
+
+- do not widen risk casually after entry
+- do not manage only from unrealized PnL
+- do not hold through a catalyst by inertia
+- do not tighten stops so aggressively that the plan stops matching the thesis
+
+## Usage examples
+
+- "Use `position-management` on this NVDA swing long. I am up about 1.8R, earnings are next week, and I need to decide whether to trim or hold."
+- "Use `position-management` on this losing EURUSD short. The thesis is not fully broken, but price is stalling and I do not want to widen the stop emotionally."

package/selected-skills/trading-skills/skills/position-management/references/management-framework.md

@@ -0,0 +1,70 @@
+# Position Management Framework
+
+Use this framework to manage an open position without drifting into improvisation.
+
+## Core question
+
+The question is not only:
+
+- "Am I up or down?"
+
+The real questions are:
+
+- Is the thesis still intact?
+- Has the risk profile changed?
+- Does a catalyst change the holding decision?
+- What is the next clean action?
+
+## Common management actions
+
+- `hold`: thesis and management plan still fit
+- `trim`: realize part of the gain or reduce event exposure
+- `tighten risk`: reduce giveback or adapt to weakening conditions
+- `close`: thesis broken, catalyst risk too high, or discipline deteriorating
+- `wait for condition`: no change yet, but only if the condition is explicit
+
+## Typical mistakes
+
+- widening stops after entry without a new thesis
+- refusing to trim because of fear of missing out
+- tightening stops purely because unrealized PnL feels uncomfortable
+- holding through earnings or macro catalysts by default
+- treating a temporary bounce as proof the thesis is restored
+
+## Winners versus losers
+
+For winners:
+
+- ask whether the position has already delivered enough to justify different management
+- protect against turning a good trade into a round trip
+- avoid trimming only because of emotion if the thesis and trend are still strong
+
+For losers:
+
+- check whether the invalidation condition is already near or already hit
+- do not widen risk casually
+- separate temporary noise from genuine thesis deterioration
+
+## Catalyst-aware management
+
+Upcoming catalysts can change the right action even if price has not moved much yet.
+
+Review:
+
+- earnings dates
+- macro releases
+- central-bank events
+- policy decisions
+- company-specific milestones
+
+If the event can materially compress the decision window, management should become more explicit, not less.
+
+## Boundaries
+
+This framework does not decide:
+
+- whether the original entry was good
+- how much size should have been taken initially
+- whether the portfolio was too concentrated before entry
+
+It only helps manage the position that already exists.

package/selected-skills/trading-skills/skills/position-sizing/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: position-sizing
+description: Use when the user needs a conservative position size from account equity, risk budget, entry, stop, and trading friction before entering a trade.
+---
+
+# Position Sizing
+
+Use this skill before entering a trade when you need a defensible size instead of a gut-feel size.
+
+This skill will not:
+
+- tell the user whether the trade thesis is good
+- override liquidity, gap, or event-risk judgment with a formula
+- turn an aggressive stop or oversized conviction into a safe trade
+
+## Role
+
+Act like a conservative risk manager. Survival comes before conviction.
+
+## When to use it
+
+Use it when the user has a trade idea and needs to know:
+
+- how many shares, units, or contracts fit the risk budget
+- how slippage, fees, or contract multipliers change the math
+- whether the planned stop makes the size impractical
+- whether the trade is arithmetically small enough before asking whether it is strategically worth taking
+
+## Inputs and context
+
+Ask for:
+
+- account size or equity
+- max risk as percent or cash amount
+- entry price
+- stop price
+- instrument type if it affects contract value
+- optional slippage, commission, or "extra buffer" assumptions
+
+If any key input is missing, state what is missing and stop rather than invent it.
+
+## Analysis process
+
+1. Compute the per-unit risk from entry to stop.
+2. Add user-provided friction assumptions if they materially increase realized risk.
+3. Compute the maximum position size that stays inside the risk budget.
+4. Report the rounded-down size, estimated total risk, and any caveats.
+5. Flag cases where the stop is too tight, too wide, or structurally unclear.
+
+Use [references/methodology.md](references/methodology.md) for sizing conventions and caveats. Use [assets/trade-plan-template.md](assets/trade-plan-template.md) when the user wants a reusable planning format.
+
+For agents that support code execution, use [references/calculation-helpers.md](references/calculation-helpers.md) for the shared helper functions that cover fixed-fractional sizing, volatility-adjusted sizing, Kelly fraction context, and futures contract math.
+
+## Output structure
+
+Prefer this output order:
+
+1. `Inputs Used`
+2. `Sizing Method`
+3. `Sizing Math`
+4. `Position Recommendation`
+5. `Risk Caveats`
+
+Always include:
+
+- position size
+- total dollar risk
+- percent of account at risk
+- assumptions used
+- caveats about slippage, gaps, leverage, or contract multipliers
+
+Do not imply the size is "safe" just because it fits the arithmetic.
+
+## Best practices
+
+- do not promise that a mathematically valid size is strategically appropriate
+- do not ignore contract multipliers or event risk when they materially change exposure
+- do not replace the need for liquidation planning in fast or illiquid markets
+
+## Usage examples
+
+- "Use `position-sizing` for a $150,000 account risking 0.4% on a long entry at 84.20 with a stop at 81.90 and 0.10 slippage."
+- "Use `position-sizing` on ES futures with account size $80,000, max loss $500, long entry 5210.25, and stop 5199.75."

package/selected-skills/trading-skills/skills/position-sizing/assets/trade-plan-template.md

@@ -0,0 +1,15 @@
+# Trade Plan Template
+
+- Instrument:
+- Direction:
+- Account size:
+- Max risk (% or cash):
+- Entry:
+- Stop:
+- Profit target:
+- Expected slippage:
+- Commission or fees:
+- Event risk notes:
+- Final size:
+- Total planned risk:
+- Reasons to reduce size further:

package/selected-skills/trading-skills/skills/position-sizing/references/calculation-helpers.md

@@ -0,0 +1,13 @@
+# Calculation Helpers
+
+For code-execution environments, reuse the shared repo helper at `skills/_lib/calculations.py`.
+
+Relevant functions for this skill:
+
+- `fixed_fractional_position_size`
+- `volatility_adjusted_position_size`
+- `kelly_fraction`
+- `futures_contract_risk`
+- `price_risk_per_unit`
+
+Keep the skill output grounded in the user's stated risk budget, friction assumptions, and contract details rather than defaulting missing values.

package/selected-skills/trading-skills/skills/position-sizing/references/methodology.md

@@ -0,0 +1,28 @@
+# Position Sizing Methodology
+
+## Base formula
+
+The conservative core formula is:
+
+`position size = allowed trade risk / per-unit realized risk`
+
+Where:
+
+- allowed trade risk is either a cash number or a percentage of equity converted to cash
+- per-unit realized risk is not just entry minus stop if trading friction is meaningful
+
+## Friction matters
+
+When it is realistic, add:
+
+- expected slippage on entry and exit
+- spread cost for illiquid instruments
+- commission if it is large relative to the stop distance
+- a gap-risk buffer when the stop may not fill at the intended level
+
+## Practical cautions
+
+- Tight stops can create oversized positions that are fragile in real execution.
+- Wide stops can produce tiny positions that may not justify the trade.
+- Futures and options require multiplier awareness. Do not reuse equity math blindly.
+- A mathematically valid size can still be inappropriate if event risk is elevated.

package/selected-skills/trading-skills/skills/post-trade-debrief/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: post-trade-debrief
+description: Orchestrate a disciplined post-trade workflow by reconstructing the original plan, reviewing execution and rule adherence, and deciding whether the lesson is trade-specific or part of a larger repeatable pattern.
+---
+
+# Post Trade Debrief
+
+Use this workflow skill when a trade has closed and the user wants one clear learning process instead of manually deciding whether to do a single-trade review, a pattern review, or both.
+
+This workflow will not:
+
+- grade the trade only by PnL
+- skip the original plan reconstruction just because the user remembers the outcome vividly
+- force pattern analysis when the sample is still too small
+
+## Role
+
+Act like a post-trade learning gatekeeper. Your job is to reconstruct what happened, identify the real lesson, and decide whether the issue belongs in a single-trade debrief or a broader journal pattern review.
+
+## When to use it
+
+Use it when the user wants to:
+
+- review a closed trade end to end
+- convert one trade outcome into a concrete lesson
+- decide whether a mistake is isolated or part of a recurring pattern
+- route the result into journal analysis only when the sample supports it
+
+## Inputs and context
+
+Ask for:
+
+- instrument and direction
+- original thesis, entry, stop, target, and size
+- actual entry, exit, and result
+- whether rules were followed
+- what happened around the trade, including catalyst or regime context
+- whether the user suspects this trade reflects a recurring issue
+
+Helpful but optional:
+
+- prior review notes
+- whether similar trades exist in the journal
+- setup tags, timeframe tags, or catalyst tags
+
+Use the user's materials first.
+
+If the original plan is missing, say that clearly and keep the debrief provisional rather than inventing it.
+
+## Workflow routing
+
+Use the smallest useful chain:
+
+1. Run `post-trade-review` on the closed trade.
+2. If the review exposes a recurring-looking mistake and the user has enough history, run `journal-pattern-analyzer`.
+3. If the review shows a structural flaw in the original setup, run `risk-reward-sanity-check` on the original structure.
+4. If the review shows oversizing or poor risk budgeting, run `position-sizing` on what the size should have been.
+
+Stop the workflow once the clearest lesson and next process change are established.
+
+## Decision logic
+
+Classify the result as:
+
+- `single-trade lesson`: the issue is important, but it belongs to this trade only for now
+- `pattern worth tracking`: the issue may recur and should be monitored in future reviews
+- `pattern confirmed`: the issue is strong enough to justify immediate journal-level rule changes
+
+## Output structure
+
+Prefer this output order:
+
+1. `Debrief Verdict`
+2. `Checks Run`
+3. `What Happened`
+4. `Main Lesson`
+5. `Is This A Pattern`
+6. `Process Change`
+7. `Next Skill Or Action`
+
+Always include:
+
+- the minimum set of checks actually used
+- the clearest lesson from the trade
+- whether the issue is isolated or part of a broader pattern
+- the next process change to test
+- whether the user should stop at this debrief or escalate to journal-level analysis
+
+## Best practices
+
+- do not let the workflow jump straight to pattern claims from one trade
+- do not skip reconstructing the original plan
+- do not turn the debrief into a motivational speech
+- do not recommend more than one or two process changes at once
+
+## Usage examples
+
+- "Use `post-trade-debrief` on this closed swing trade and tell me the real lesson."
+- "Use `post-trade-debrief` on this loss and tell me whether it is just one mistake or part of a pattern I need to address."