Skip to content

Stabilize review v2 workflow and English contracts #190

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
atomchung wants to merge 1 commit into from
Closed

Stabilize review v2 workflow and English contracts #190

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 23 additions & 25 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,39 +1,37 @@
# AGENTS.md — fomo-kernel

> 給 AI coding agent(**Codex**、Cursor、Claude Code 等)的操作指引。
> 人類使用說明見 [README.md](README.md);**完整流程權威見 [skills/fomo-kernel/SKILL.md](skills/fomo-kernel/SKILL.md)**。
> Thin routing guidance for Codex, Cursor, Claude Code, and other coding agents. Human-facing product documentation lives in [README.md](README.md). The only cross-agent workflow entry point is [skills/fomo-kernel/SKILL.md](skills/fomo-kernel/SKILL.md).

## 這個 repo 是什麼
## When to trigger

一個交易復盤工具:把使用者的交易 CSV 復盤成**一張卡** —— 一個最大的行為漏洞 + 一條下次守則 + 一句大師原則。三層遞進:機械層(Python 確定性精算)→ 鏡片層(大師原則問動機)→ 收斂成一張卡。
Trigger when a user asks for a trade review, transaction postmortem, brokerage-statement review, or provides a trade CSV or position snapshot.

## 何時觸發
## Workflow

使用者說「復盤」「trade review」「檢討交易」「看我的對帳單」,或丟出一份交易 CSV 時。
1. Read `skills/fomo-kernel/SKILL.md` completely.
2. Normalize brokerage data locally. Do not require the user to reformat it.
3. Start from the single orchestration entry point:

## 怎麼做(照這個順序)

1. **先讀完整流程**:`skills/fomo-kernel/SKILL.md` 是四步流程的權威,照它走。
2. **跑 engine(機械層)**:
```bash
cd skills/fomo-kernel
python3 engine/trade_recap.py <使用者的 CSV 路徑>
# 不帶參數 = 引擎跑內建 mock(僅供你自測引擎);使用者沒給資料 → 請他提供,
# 或走 SKILL.md「試駕模式」:mock 走四步,但不落盤 + 標明演練 + 卡標示範,防護缺一不可
python3 engine/review.py prepare <CSV...> --language en
```
依賴:Python 3.11+、`yfinance`、`pandas`、`rich`(見 `requirements.txt`)。沒網路時 engine 會自動退成行為層診斷,不會中斷。
CSV 來自任何券商都行 —— 你負責讀懂、轉成引擎要的欄位(`Symbol / Action(BUY|SELL) / Quantity / Price / TradeDate`,非美股補選填欄 `Market / Currency`,如 `2330.TW / TW / TWD`;不填 = 美股 USD),不必要求使用者手動整理。
3. **出卡前問動機(鏡片層)**:engine 標 `[ASK]` 的標的(金額大 + 虧損中加碼),逐一問使用者「逢低布局還是凹單?」,拿到答案才出定論卡。
4. **出卡(收斂層)**:engine 輸出 + 使用者動機答案 → 收斂成一張卡(版型見 `skills/fomo-kernel/card-template.html`)。

## 鐵律(不可違反;完整版見 SKILL.md)
4. Read the returned `review_plan.flow_path` and shared references. Ask only questions in `question_queue` with `required:true`. Use a native option UI when available; otherwise present the same options in plain text.
5. Produce schema-valid answers and a narrative with no digits, then call `preview`. Fix rejected artifacts instead of bypassing the validator.
6. Show the private preview and ask the user to choose one candidate rule, supply a custom rule, or skip. Write that choice to `answers.commitment` and call `finalize`.
7. Deliver `sessions/<id>/card-private.md`. Deliver `card-public.md` only when the user asks for a shareable version.

After an interruption, use `review.py resume`; do not refetch live prices. If a projection fails, use `review.py repair-projections`. An existing canonical session is not data loss.

## Non-negotiable boundaries

1. **數字全部來自 engine,一個都不准自己算或編。** 你的工作是解讀 + 追問動機,不是當計算機。engine 沒輸出的數字 → 不要寫。
2. **不給投資建議。** 不 recommend 買賣標的;只復盤「行為」、問「動機」、給「下次守則」。
3. **動機問句必出。** engine 標 `[ASK]` 的標的,出卡前必問,不可跳過。
4. **一次只逼一件事。** 卡上「下次只改」永遠只有一條,不給清單。
5. **隱私不外傳。** 使用者交易資料只在本機跑,不上傳、不外傳、不寫進任何雲端記憶。
1. Numbers, rankings, cycle IDs, metrics, and ETF exemptions come from code. The agent must not calculate, invent, or alter them.
2. Do not provide buy or sell recommendations. Review behavior, motives, thesis evolution, and the next process rule.
3. Required motive questions cannot be skipped. A `new_evidence` decision requires both a claim and a source.
4. Each card has at most one final rule, chosen by the user. Skipping is valid.
5. Keep trade data local and out of cloud memory. Never mix private-card content into a public card.

## 為什麼有這個檔
## Why this bridge stays thin

`SKILL.md` 是 Claude Code 的 skill 格式,**會被 Claude Code 自動偵測載入**。其他 agent(如 Codex)沒有「自動載入 skill」機制,但**能照常把 SKILL.md 當指令讀 + 跑 engine** —— 本檔就是給這些 agent 的指路牌。核心引擎是純 Python,**與工具無關**:Codex / Claude Code / 甚至使用者自己在終端,都跑得出同一份診斷。
Claude, Codex, and Cursor perform the same small set of high-value judgments. Mode flows, schemas, validators, session commits, and renderers are shared repository code. A thin bridge prevents each agent from maintaining a separate long prompt that drifts over time.
130 changes: 65 additions & 65 deletions BACKLOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,93 +1,93 @@
# fomo-kernel · Backlog
# fomo-kernel backlog

> 從 2026-06-14 的 user-story × engine review 拍出來的待辦。
> 背景脈絡：受眾已收窄為「會用 AI 工具的人（含交易上仍憑感覺的散戶）」；skill 是第一期本體（資料留本機解隱私），不是探針。卡的唯一賣點 = 用你自己的數字，誠實說出你「知道卻沒做到」的事。
Last refreshed: 2026-07-14. The target is a promotion-ready release on 2026-07-19.

> ⚠️ **兩條線同步註記（2026-06-14）**：本檔的「願景層 + ISSUE-1」來自下午的 user-story / 願景 review session；另有一條「engine 實作線」今早 10:34–11:53 並行推進（commit c6cb138→dccf9c4），已 pivot 到 `behavior-diagnosis.md`（對事不對人、行為多標籤）並實作標的層診斷。動 engine 前先跟那條線對齊，別重工。
## P0 for the promotion release

---
### Stable workflow and card production

## ISSUE-1 ·〔小–中〕α 雙閘門：資料不夠厚時，不准用「真本事」語氣出 alpha
Status: implemented, pending manual release gates.

**問題**
`engine/trade_recap.py` 的 alpha 在樣本不足時，仍以「真本事 α」的*能力*語氣輸出 → 會在看得懂統計的受眾面前砸掉第一張卡的信任。
- Keep `SKILL.md` as a thin entry point.
- Use the fixed `prepare -> preview -> finalize` lifecycle.
- Resume interrupted sessions without refetching live data.
- Commit one canonical immutable session and rebuild projections from it.
- Render private and public cards deterministically.
- Keep required questions and evidence completeness as code gates.

- `_regress()` (trade_recap.py:231)：門檻只有 `len(df) < 60`（≈3 個月）就吐 α 數字。
- overview (trade_recap.py:634-636)：措辭「真本事 α 年化 X%」，<252 天只加一句小警語，**數字照印**。
- 統計真相：α 作為「能力證據」的顯著性 ≈ Information Ratio × √年數；散戶尺度（1–2 年、幾十筆）**結構上到不了顯著**。而 mock 失真的真因*不是*天數（有 605 天），是**橫截面太窄**（4 檔、98% 同一 driver）→ 算出的是賽道不是選股。
> 行號已更新至 721 行版 engine（dccf9c4 後）。那批 commit 動的是攤平/出場，**α 邏輯未被動，本 issue 仍有效**。
Release evidence: `docs/release-2026-07-19.md`, `tests/test_review_v2.py`, and the complete offline suite.

**要改**
1. 新增 `alpha_credible(ab, held, rts)` 雙閘門：(a) 天數夠（建議 ≥252，且仍標「個人 α 偏 noisy」）**AND** (b) 橫截面夠寬（持倉檔數 ≥ N 且最大單一 driver 暴險 < ~50%，否則 α = 賽道紅利非選股）。
2. overview α 印法 (:634-636)：credible 才出「α 年化」；否則只出 β + 「贏大盤 +Xpp（拆帳見下）」，**拿掉「真本事」**。
3. `print_alpha_beta()` (約 :264-289)：不 credible 時整段降級成「報酬拆帳」語氣，不出 `alpha_ann` 數字，只留「贏大盤多少 / 多少來自賽道」的描述性分解（這層不需顯著性、誠實）。
4. lens 同步：`rubric/vincent-yu.lens.json` 的 `dims."alpha/beta".motive_q` + SKILL.md，不 credible 時不要問「這報酬算你選股本事還是敢押高波動」（前提已不成立）。
### Thesis evolution and add evidence

**驗收**：跑 mock（4 檔 / 98% AI）→ 不再出現「真本事 α +33%」大字，改為「樣本/持倉不足以判定選股能力，先看行為層」之類。
**範圍**：單檔 ~30–50 行，3 處輸出 gate + 1 判斷函式 + 1 處 lens/SKILL 同步。低風險（純輸出層）。約半天。
**原則來源**：跟 `behavior-diagnosis.md` 同向——`prescribe()`（:525-527）對「選股 edge」已經誠實標「資料還判不出、別急著外包也別自滿」；α overview 還沒跟上這個誠實標準，本 issue 就是讓它跟上。
Status: implemented in the v2 lifecycle.

---
- Classify losing-position adds as planned tranche, new evidence, valuation change, price only, or skip.
- Require a claim and source for `new_evidence`.
- Store append-only thesis decision events tied to active cycle IDs.
- Reconcile the evidence in future reviews rather than asking a generic averaging-down question again.

## ISSUE-2 ·〔已作廢校正〕原「落地分型」→ 改為「補 behavior-diagnosis 還缺的純損耗標籤」
### ETF policy

**校正記錄（2026-06-14）**
本 issue 原寫「落地 trader-types.md 先判型再評分」。**作廢**——`trader-types.md` 已於今早 10:34（c6cb138）被否決移除，正解是 `behavior-diagnosis.md`（對事不對人 · 行為多標籤）。理由比分型強：散戶是風格縫合怪、硬分型會錯判；整個開發照出的真洞全是「對事」算的，分型是多餘中間層；「同訊號不同風格意義相反」用「標的層脈絡」就能解、無單點誤判風險。engine 的 `ticker_diagnosis()`（標的層多標籤）已實作此方向。
Status: implemented with conservative fallback.

**真正還缺的（= behavior-diagnosis.md §下一步2 的 ⏳）**
第一層「跨型純損耗」還差兩個標籤未落到 engine：
- `revenge_trade`：連敗後 / 短時間內報復性加碼同標的 → 處方「連敗 N 次強制冷靜期」。
- `overtrading` 強化：高頻進出且淨輸大盤（Barber-Odean），目前只有頻率 + α/β 部分覆蓋。
- Exempt only broad-market, regional, bond, and commodity allocation ETFs from single-name concentration.
- Keep sector, thematic, and leveraged ETFs in concentration and stress diagnostics.
- Give unknown instruments no exemption.
- Disclose missing expense ratio and tracking error rather than assuming zero.
- Add a live metadata source later without changing the policy contract.

**範圍**：engine 內加 2 個偵測 + 對應可驗處方。中等。跟 ISSUE-1 獨立。
**注意**：這條屬「engine 實作線」，動工前先跟該線對齊，別重工。
### English implementation and bilingual GTM

---
Status: implemented in this change, pending full verification.

## ISSUE-3 ·〔小〕Step 2 從「自我定性」改「證據門檻」：堵住 thesis 洗白器
- Keep developer documentation and skill instructions in English.
- Keep English and Traditional Chinese GTM artifacts synchronized as separate files.
- Keep user-visible localized product copy in separate locale resources.
- Prevent mixed-language implementation docs with a deterministic regression test.

> 來源：2026-06-19 三方 revisit（Claude 初評 + gemini 3.5 Flash + codex，各自獨立跑，簡報 `/tmp/fomo-kernel-userstory-review.md`）。gemini 與 codex **未互看卻收斂到同一刀**，信號強。
## Manual release gates

**問題**
`SKILL.md` Step 2(a)（約 :52-55）把「動機定性權」整個交給用戶的嘴：「答『逢低/計劃內』→ 移除警告、標逢低……**你的答案定性**」。對「不是不知道在凹單、是不想承認」的目標用戶，這內建一個**洗白器**：
- Outcome Bias——凹單剛好漲回的標的（如 mock 的 PLTR/NVDA），用戶被二選一問時會選保全面子的「計劃內」，診斷在**最該硬的那一筆**軟掉。
- Claude 初評把 Step 2 當「最不可替代的分水嶺」；gemini（Outcome Bias）+ codex（「把定性權交還給最會合理化的人」）**各自獨立判它是最大盲點**。2:1，且兩個外部模型獨立撞同一點。
- Complete one full Traditional Chinese run with an anonymized publishable CSV.
- Complete the same flow in English.
- Inspect the public card manually for amounts, dates, tickers, exact weights, session IDs, evidence text, and free-form narrative.
- Demonstrate evidence-gate rejection and recovery.
- Demonstrate broad ETF exemption versus thematic ETF concentration.

**要改**（純 prompt 層，engine 不動）
1. Step 2 問法：從「你覺得逢低還是凹單?」→「**寫出你加碼當下知道、但進場時不知道的新證據；寫不出 → 標凹單/待確認**」。關鍵：AI 不必判證據真假，**逼用戶舉證這個動作本身就分流**——真逢低寫得出，凹單寫不出。
2. Step 3 卡標籤定性規則：舉不出新證據 → **不准標逢低**（現行「答計劃內就移除警告」改成「舉得出證據才移除警告」）。
3. 動機單元表（約 :59-68）同步：把「自我定性」式問句換成「舉證」式。
## P1

**守住既有鐵律（別被當成走回頭路）**
- **不違反** `behavior-diagnosis.md` 的「不做進場每筆標」（owner 2026-06-14 駁回）：這是**事後、只對 engine 挑出的可疑標的、逼一次舉證**，不是進場每筆標。和該檔「三層降本」第 2 層（只對待確認少數問）完全相容——只是把那一問從「定性」升級成「舉證」。
- 守低摩擦：可疑標的通常 1–2 檔（mock 只 PLTR），不是每筆。
### Multi-lens selection and comparison

**與閉環的關係**：這是「候選 · thesis 對帳」+ 願景 v1「pre-trade gate / 守則檔」的 **MVP**。先用「事後逼舉證」驗方向（今天能改），再長成「事前存進場 thesis 原文、復盤拿原文對帳」的 `~/.trade-coach/` 版——codex 版（事後）是 gemini 版（事前）的最小落地。
- Select from a small verified lens set.
- Apply style-specific divergence only where mechanical evidence supports a style axis.
- Keep universal risk failures outside the lens override.
- Do not duplicate lifecycle, state, schemas, or renderers.
- Verify every public quotation against a primary source before promotion.

**驗收**：對 mock 跑 Step 2，用戶對 PLTR 答「逢低」但寫不出新證據 → 卡仍標「待確認/凹單」，不被洗成逢低。
**範圍**：`SKILL.md` Step 2 + Step 3 標籤規則 + 動機單元表，3 處 prompt 文字，engine 零改動。低風險。約 1–2 小時。
**與 ISSUE-1 同向**：都是「資料/嘴不夠硬時，不准出能力語氣 / 逢低定論」的誠實閘門；兩者獨立可分別做。
### Complete snapshot adapter

---
- Accept a position table or screenshot directly.
- Normalize into the snapshot review card/state contract.
- Limit conclusions to facts supported by a snapshot.
- Allow later transaction history to unlock behavioral dimensions.

## 願景層（2026-06-14 下午 session 拍板）
### ETF metadata enrichment

**終局形態 = 投資教練 agent（process coach，不是 stock advisor）。** 從「事後一張卡」進化成「事前承諾 → 事後對帳」的閉環。四條紅線必守：
1. **過程教練 ≠ 選股顧問**：教怎麼決策（紀律/守則/對帳動機），絕不碰買哪支（IP/法規/北極星）。
2. **會拒絕 ≠ 有求必應**：有求必應的投資 agent = 「焦慮買答案」的溫床 = 產品要解的病本身。克制是 feature。
3. **有哲學但不寫死**：哲學寫死=拿錯尺、無哲學=yes-man。靠 behavior-diagnosis 的「風格當脈絡」解。
4. **記得你 → skill 要長出本機狀態**（`~/.trade-coach/`）才成 agent；Claude Code/Agent SDK 已是 runtime，不必從零造。
- Add a maintained instrument source for classification, expense ratio, and tracking error.
- Preserve the local override and conservative unknown fallback.
- Cache data for offline and repeatable reviews.

**6 步課程弧線**（每步都有現成零件）：初診(卡) → 訂計畫(守則檔) → 賽前提醒(pre-trade gate) → 賽後對帳(驗規矩) → 升級畢業(守則清單) → 哲學演進(behavior-diagnosis 風格脈絡)。
**演進路徑**：v0 無狀態卡 → v1 守則檔+gate+對帳 → v2 風格脈絡+多鏡片 → v3 全 context 對帳。
**守北極星**：vision 是 agent，但 next action 仍是「那張卡戳中一個真人」。**約束在卡的品質（夠不夠好用、到不到能發的水準），不在分發找人**（owner 2026-07-05 糾偏，見 #112：卡一直在測、也一直在給人看，真卡點是卡不夠好用）。別讓大願景偷走當下該驗的小東西。
## Later candidates

---
- Event-driven pre-trade check against the active process rule.
- Personal lens distilled from repeated confirmed review patterns.
- Richer source attribution for owner-only research workflows.
- Automated GTM asset generation and publishing.
- More behavior detectors only when they are measurable and bind to a testable rule.

## 候選（未拍板）
## Product boundaries

- **pre-trade gate**：把「下次只改一件」沉澱成本機 `my-rules.md`，下單前 `/fomo-kernel check <ticker>` 攔一次。市場空白（無人把復盤回灌下一筆）+ 解 Epic D 留存 + 正中北極星。守則檔就是 skill 的「狀態/記憶」。
- **thesis 對帳**：⭐ engine 已起頭（`4599f4f` infer-thesis-from-behavior）。可升級成「拿用戶*寫過的*進場 thesis 原文對帳」——從推斷動機 → 核對原文。skill 能吃用戶全 context，SaaS 結構上做不到。→ **其 MVP 已拆成 ISSUE-3**（先做「事後逼舉證」的證據門檻，再長成「事前存原文對帳」）。
- **行為 counterfactual 重放**：「賣太早那批多抱 30 天會怎樣」——`fwd_from_px` 已有資料，低成本高回報。
- **多哲學對照**：部分已被 behavior-diagnosis「風格當脈絡」吸收；若要做成「多鏡片顯示分歧」，守住收斂——只呈現分歧最大那一點，別變第二份報告。
- **lens 迭代回 kol（2026-06-14,VY 已降為可換鏡片、demo 已去名後）**：把 `lens.json` 的可換架構連回母專案 `kol_collector` / `kol_collect` 的多 KOL 蒸餾——那邊已沉澱 12+ 追蹤 KOL，各可蒸一面鏡片讓用戶選大師；fomo-kernel 的 lens 是這個 distill-KOL→lens 的第一個落地（VY = 第一面，現已通用化呈現、demo 不掛名）。owner 標「之後再迭代」。背景見記憶 `project-kol-collect-vs-collector-overlap`。
- Process coaching is not security selection.
- One card converges on one behavioral leak and at most one rule.
- Trade data remains local.
- A clean strengths card is valid when no costly leak is supported.
- Real-user usefulness remains the final validation layer; passing automated tests is necessary but not sufficient.
Loading
Loading