Framework Issue
框架問題的知識載體是 canonical repo（tarrragon/claude）上的 issue，本地 ticket 只記執行。本檔是入口：先定位你在做哪一種事，再依路由表讀對應的一份 reference。
定位：ticket 記執行，issue 記問題
| | ticket | issue | |---|---|---| | 一張對應什麼 | 一個執行單位（本專案這一階段做什麼） | 一個問題領域（問題是什麼、為何這樣解） | | 狀態可逆 | 否 | 是（close 可 reopen，close 只代表當前結論暫時穩定） | | 可見範圍 | 單一 consumer | 所有 consumer | | 增長語意 | 池增長是負債 | open 數增長不是失效，同領域裂成多張才是 |
工作流四階段：發現問題 → 分析票（ticket）；分析與方案 → issue 區段；實作 → 實作票（依階段裁票）；同步 → sync-push。分析 context 留在 ticket 時對其他 consumer 不可見，同一問題會被重複發現、已解的問題後續票不知情。
決策入口
先答這一問：這個問題替換掉本專案名稱與路徑後還成立、且根源在 .claude/ 通用資產嗎？ 兩者皆是才是框架問題；否則走 ticket skill。
| 你要做的事 | 動作 |
|-----------|------|
| 記錄一個新框架問題 | dedup 查重 → 逐一判定命中的關係（重複／切分／引用）→ 依關係處置 |
| 對既有 issue 補實測、反證、疑慮 | observe，任何 session 隨時可加，不需 owner |
| 更新自己擁有的區段 | update <comment-id>，以 comment id 精準編輯 |
| 把一群本地 ticket 的分析收進 issue | 收束流程五步（見下節） |
| 一個壞 change 多個 consumer 各自修 | fix-matrix 命令（fix-status / fix-version / close） |
| ticket 執行中發現框架問題，決定接不接 | 兩條路徑（先記錄不接手 / 當下接手）與關閉協定 |
查重命中不等於重複：全文檢索涵蓋 comment 內文，互相引用的 issue 會同時命中彼此。三種關係的判定與處置見按需讀取表的協定檔。
命令總表
全部命令住在 scripts/，以 python3 .claude/skills/framework-issue/scripts/<檔名> ... 執行。<issue-ref> 支援 owner/repo#N（限框架 repo）、#N、純數字。
| 命令 | 檔名 | 用途 |
|------|------|------|
| dedup | section_comment.py | 唯讀查重，含空白的關鍵字組拆單詞聯集查詢 |
| init | section_comment.py | 查重後建全部區段 comment、與既有索引列合併回填一次 body 索引；issue 已有區段時拒絕（exit 3，--force 可覆蓋並合併） |
| add | section_comment.py | 對已 init 過的 issue 追加單一區段，併入既有索引列 |
| update | section_comment.py | 以 comment id 更新自己擁有的區段 |
| transfer-owner | section_comment.py | PATCH 區段首行標記的 owner 欄，內容不變 |
| observe | section_comment.py | 附加觀測 comment |
| show | section_comment.py | 以 body 索引為入口，區分區段與觀測流 |
| check | section_comment.py | 三項警訊：當前結論落後最新觀測（主）、comment 數、索引一致性 |
| todo | section_comment.py | 唯讀，跨 open issue 聚合「待辦與來源*」表格列；預設本 consumer 擁有的 open issue，--all／--issue N 改範圍，--status／--stage／--priority／--consumer／--json 可用 |
| create | create_issue.py | 建 issue，body 自動附環境資訊 |
| list | list_issues.py | 列 issue，--search 作粗篩 |
| link | link_issue.py | 把 issue ref stamp 進本地 error-pattern 的分類資訊表 |
| fix-status | fix_status.py | 查或標記本 consumer 的修復狀態（body 內 fix-matrix 表） |
| fix-version | fix_version.py | 追加修復版本號（body 內 fix-versions 表），close 前置 |
| close（issue） | close_issue.py | 關 issue，缺版本號註記即拒（exit 3）；與收束流程的 ticket close 是不同對象 |
exit code：0 成功、3 降級（gh 未安裝／未登入／Issues 停用／執行例外，stderr 給提示不拋 traceback）。
收束流程速覽
把一群本地 ticket 壓成 issue 的當前結論，完整配方在 references/ticket-intake.md。五步不可跳：
- 分群：以主題為單位，一主題一 issue；先與並行 session 對齊誰認領哪個主題。
- 查重：
dedup單詞 token；主題已有 open issue 一律附加，不新開。 - 改寫：ticket 是時序累積（後段修正前段），區段是狀態呈現（只含現在成立的）。逐段問「這是現在的結論，還是通往結論的過程？」，被推翻的中間版本刪除、只留一句撤回記錄。
- 建段：「當前結論」（讀者入口）必有；「問題與方案」「待辦與來源」有內容才建，不寫空殼。
- 收票：ANA／DOC／IMP 一律 close，知識住址寫進 reason-note；依賴範圍票的外部票以
set-why補 issue ref。命令、範圍規則與 reason-note 禁詞見references/ticket-intake.md步驟五。
Owner 與派發
區段 owner 是實際執行該工作的 session，他方以 observe 附加或 add 自己的區段。owner 識別固定為 <專案目錄 kebab-case>-<session 序號>（如 flutter-balance-77），CLI 對其他形態 exit 3；理由見協定檔〈區段與觀測標記格式〉。
收束與區段撰寫派 framework-issue-curator（opus、effort medium）；一個主題一個 curator 並行，派發票列明範圍內的 ticket ID，curator 只對這些票 close。純 observe／check 類輕量操作不需派發。
按需讀取
涵蓋章節欄與目標檔的 ## 標題逐字相同、雙向齊全。
| 何時讀 | 檔案 | 涵蓋章節 |
|--------|------|---------|
| 要 init／add／update／transfer-owner／observe／show／check，或判定查重關係、解讀 check 警訊、查 owner 格式 | references/comment-as-section-protocol.md | 〈操作一覽〉〈CLI 語法〉〈區段與觀測標記格式〉〈init 前查重：三種關係處置〉〈check 的三項警訊〉〈增長語意與 close 語意〉〈已知限制〉 |
| 要用 create／list／link／fix-status／fix-version／close | references/fix-matrix-commands.md | 〈create 與 list〉〈link〉〈fix-status〉〈fix-version〉〈close〉〈Graceful Degradation〉 |
| ticket 執行中辨識到框架問題，決定接不接與怎麼關 | references/escalation-flow.md | 〈介入判斷：框架問題 vs 專案問題〉〈兩條路徑〉〈Issue 關閉協定〉〈回報前查重 SOP〉 |
| 要把一群 ticket 收束成 issue，或派 curator 做這件事 | references/ticket-intake.md | 〈前提與分工〉〈步驟一：分群〉〈步驟二：查重與落點〉〈步驟三：時序改狀態〉〈步驟四：區段範本〉〈步驟五：ticket 處置〉〈步驟六：驗證與交接〉〈派發 curator〉 |
| 想看一張 issue 從 dedup 到 check 的完整走查 | references/worked-example.md | 〈情境〉〈查重輸出與關係判定〉〈sections.json〉〈init 與索引〉〈ticket close〉〈check 與 owner 更新〉 |
Testing
uv run --project .claude/hooks pytest .claude/skills/framework-issue/tests/ -v
測試以 mock 攔截 gh subprocess，不真打 GitHub API。
版本紀錄在同目錄的 CHANGELOG.md。