InvAssistant

Multi-asset investment portfolio management framework — current version v2.3.18 (2026-09-20). Core philosophy: portfolio before stock-picking, discipline before inspiration. Rules are guardrails, not cages.

⚠️ Risk Warning: This is a decision-support framework, not financial advice. AI guidance is probabilistic; all action triggers — including rule-based alerts and entry thresholds — require human review before any execution. Author assumes no liability for trading losses.

Framework Scope and Bundled Scripts

This is a documentation-driven framework: SKILL.md and the references define the rules. The bundled Python scripts under scripts/ are optional decision-support helpers, not autonomous agents — they never place orders and hold no broker credentials.

Data transmission notice: only two components transmit data off-machine. The three send_*.py helpers stay disabled until you provide a webhook URL and send nothing beyond the report you choose to push; data_fetcher.py only sends GET requests to the public Yahoo Finance quote endpoint. Review the endpoint config before enabling either.

Language policy: documentation is English with Chinese summaries; runtime report language follows the user's request — no language is forced.

1. Asset Classification (Three Tiers)

This is the foundation of v2.1+. Different assets use different exit logic.

Key insight: A-class price drawdowns ≠ sell signals. Using trailing stops on A-class washes out long-term compounders.

2. Portfolio Risk Controls: 7 Red Lines (Non-Overridable)

3. US Stock Strategy

Entry Modes

Mode D: A-Class Candidate Zone Entry (v2.1.1)

Applied to new A-class candidates before they join the core portfolio. Designed to solve the "observation delay misses entry window" problem.

Principle: No observation delay. A -10% pullback from 20D high on an A-class candidate is itself a complete entry signal — the underlying moat business doesn't change with share price.

Constraints: total ≤2% portfolio; some candidates carry an additional valuation gate (e.g. an entry PE-percentile cap); no chasing after rebound.

Anchor discipline: the anchor is the 20-day high, frozen at position open. Do not substitute a 12-month or 52-week range high — that belongs to the range-position rule (§13 D1). A level computed off the wrong window is arithmetically correct and semantically wrong.

Why Different from Panic-Entry Mode A

Narrative-driven, high-beta satellites need bottom confirmation — the drop might be fundamentally justified. A-class candidates (moat compounders) only need price confirmation — a -10% discount on a quality business is self-evidently an opportunity.

4. A-Share Strategy (3-Condition Engine)

All three conditions must pass for entry:

Flex window: 2/3 conditions met + 3rd deviation ≤10% → half-position trial. Time stop: 6 months max in selection pool without entry → forced review.

5. HK Stock Strategy

Warning line (not hard stop): Triggers 48h review upon breach. Time limit: 18 months post-vesting with remaining position → unconditional full exit.

6. QMS Scoring (4-Factor)

QMS = 0.35 × Earnings Trend
    + 0.25 × Sector Relative Strength
    + 0.25 × EPS Revision
    + 0.15 × Price Structure

Boundary: QMS is entry reference for A-Class, NOT an exit trigger. Only B-Class uses QMS <40 as reduction signal.

7. Monthly KPIs

8. Hard Rules Summary

1. Asset classification determines action semantics: A-Class no trailing stop, B-Class uses trailing stop
2. Held vs. watchlist semantics must not be mixed
3. A-share 3-condition is a filter: all pass → entry (flex window = 2/3 + deviation + half-size)
4. US B-Class dual-mode: Mode A (3 red lines all pass) / Mode B (4 conditions all pass)
5. Unfilled ≠ holding: portfolio data must reflect actual positions
6. Never fabricate data: all indicators must come from live data sources
7. A-Class only sells on 3 fundamental reasons (never price)
8. 7 Red Lines triggered = must follow, no override
9. Allocation/incentive positions do not use standard stops
10. Every override must be logged
11. Max 2 overrides per ticker per quarter; 3rd is void
12. Daily self-check: 5 questions, all "no" = no trade today

9. Output Format

Portfolio reviews and risk checks produce:

• Structured review report — A/B/C classification table, red-line pass/fail flags, position-sizing check, QMS scores for candidates
• Action list — framework-compliant observations (never directives): what to watch, what violates a rule, what needs human decision
• Data-source annotations — each number carries its source and timestamp; unsourced values are marked

10. Data Sources

11. Common Mistakes

12. Capital Plan Consistency Audit

Run these before adopting any multi-sleeve capital plan (account-level targets, DCA schedules, subtype caps). All five caught real defects on first use, and all are arithmetic rather than judgment — detect them by computing, not by reading.

The table above is a digest, re-derived from references/capital_plan_audit.md, which is authoritative. If the two ever diverge, the reference wins and this digest is regenerated from it.

The fixes in one line each: A1 allocate by remaining gap to cap, recomputed monthly — never by fixed amount, since a fixed amount and a percentage cap are mathematically inconsistent whenever prices move. A2 state cash targets in two stages — a transitional range reachable with the sleeves open today, and the strategic range on a stated trigger — because an unreachable target puts the rule in violation from day one. A3 set a look-through industry cap that takes precedence over the subtype label cap and re-test it before every new position. A4 report the breakeven probability, not the drag alone: drag is certain and annual, protection is contingent and pays only on drawdown.

Worked A5 case (four circulating figures for one yield, four calibers, one adoptable), the reconstruct-before-you-trust habit, contractual-payout caveats, and the DCA stop/resume state machine → references/capital_plan_audit.md.

13. Derived Price Level Governance

Every price in this framework that is computed rather than quoted is a derived level: mode-D add lines, mode-B pullback triggers, range-position bands, B-class trailing stops, derived thresholds such as a yield-versus-bond gate. They share one failure mode — none is self-contained. Each is f(anchor), so a level is only as trustworthy as the anchor behind it, and an anchor that is never declared cannot be checked. This section exists because a live portfolio once carried the same add-line at two different values in three different files, with the line within 1% of the price; the cause was a wide-window range high reused as the anchor for a narrow-window rule.

The spine — five steps, run before acting on any level:

1. Declare — name the rule, then take the anchor window and freeze semantics from that rule's definition.
2. Register — the level must sit in the registry with a complete anchor record. An unregistered level is not usable for a decision.
3. Validate — run the validator. Its output is the only accepted evidence.
4. Resolve — a hard failure blocks the action; warnings and open entries are surfaced, never silently absorbed.
5. Trace — an anchor or formula change keeps the previous value, the reason and the date.

What a clean validator run does not tell you. Four distinct gaps, each with its own fix — these are the ones that turn a green run into a wrong action:

Opposing rules on the same instrument need a mutex. An add line below the price and a reduce band above it are both legitimate, but if both can fire in the same period the framework contradicts itself. Resolve by first-trigger-wins on a logged timestamp, freeze the other side for the period, and never allow a same-period add and reduce.

A level near the price is a live commitment, not a monitor. The closer a line sits to the current price, the more it needs a registered anchor, a named owner and an execution plan.

A definition backfill is not a rule change — label it as such. Defining a term the rules lean on changes no threshold and no mode; it only removes the room for two people to compute the same situation differently. Publish it under its own version, call it a backfill, and leave every number untouched.

The numbered rules D1–D10 — per-rule anchor windows, never reverse-engineering an anchor from a target level, registry-versus-mirror topology, the full mechanical check list, resolving every percentage cap against the owning account, dating every balance and reconciling it with a rollforward, keeping author positions out of example configs, the adjudication ledger, and keeping the registry executable with its chronology moved out — are catalogued with their incidents and corollaries in references/derived_price_governance.md, which is authoritative for all ten; the spine above is a digest re-derived from it. Read it before computing, storing, validating or publishing a derived level.

Reference Files

Version History

Full history: CHANGELOG.md — authoritative for every release, moved out of this file at v2.3.17 so the always-read file carries only operative rules.

Current: v2.3.18 (2026-09-20) — frontmatter permissions block + network token added; data-transmission notice corrected.

中文简介：InvAssistant 是一个多市场投资组合管理框架。按资产三层分类（A/B/C）执行差异化规则，7 条组合红线不可覆盖，4 因子 QMS 评分辅助决策。覆盖美股、A 股、港股。核心信念：组合优先于选股，纪律优先于灵感。规则是栏杆，不是牢笼。