@qijenchen/design-system 0.1.0-beta.72 → 0.1.0-beta.74

package/ds-canonical/fork/skills/product-ui-audit/references/common-misuses.md

@@ -0,0 +1,329 @@
+# Common Misuses — 元件誤用 negative example 庫
+
+針對本 DS 常見的元件誤用 pattern。每筆:**誤用 → 正解 → 理由**。
+
+---
+
+## Button 誤用
+
+### ❌ 多個 primary Button 並列
+
+```tsx
+<div className="flex gap-2">
+  <Button variant="primary">儲存</Button>
+  <Button variant="primary">下載</Button>
+  <Button variant="primary">分享</Button>
+</div>
+```
+
+**正解**:一個 row 一個 primary,其他降階。
+
+```tsx
+<div className="flex gap-2">
+  <Button variant="primary">儲存</Button>
+  <Button variant="tertiary">下載</Button>
+  <Button variant="tertiary">分享</Button>
+</div>
+```
+
+**理由**:primary 是「這個流程的主 CTA」,多個 primary 會讓使用者不知該點哪個。
+
+### ❌ icon-only 無 aria-label
+
+```tsx
+<Button iconOnly startIcon={Trash} />  // ❌
+```
+
+**正解**:`aria-label="刪除"`。screen reader 必要。
+
+### ❌ Button 巢狀
+
+```tsx
+<Button onClick={outer}>
+  外層
+  <Button>內層</Button>  {/* ❌ 巢狀 button invalid HTML */}
+</Button>
+```
+
+**正解**:拆成兩個 sibling Button 或 inline ItemInlineAction。
+
+---
+
+## Field / Input 誤用
+
+### ❌ 裸 `<input>` 未包 Field wrapper
+
+```tsx
+<input type="text" className="border rounded p-2" />  {/* ❌ */}
+```
+
+**正解**:用 `<Input>` 元件或包 Field wrapper。
+
+**理由**:DS `<Input>` 已帶 fieldWrapperStyles(hover / focus / error / disabled 狀態全套),自 roll `<input>` 失去一致性。
+
+### ❌ Input 外層自訂 border / padding
+
+```tsx
+<div className="border-2 border-primary p-3 rounded-xl">
+  <Input />
+</div>
+```
+
+**正解**:用 Input 的 `error` prop 或 cva variant,不自套 wrapper。
+
+---
+
+## Dialog / Popover / Sheet 誤用
+
+### ❌ Dialog 內放 Popover(巢狀浮層)
+
+```tsx
+<Dialog>
+  <DialogContent>
+    <Popover>...</Popover>  {/* ❌ 浮層巢狀不推薦 */}
+  </DialogContent>
+</Dialog>
+```
+
+**正解**:改用 Dialog 內 Tabs / Accordion / SelectMenu 等 inline 結構。
+
+### ❌ Dialog 無 DialogTitle
+
+```tsx
+<DialogContent>
+  <p>確定刪除?</p>
+  <Button>確定</Button>
+</DialogContent>
+```
+
+**正解**:必有 DialogTitle + DialogDescription(a11y 必要)。
+
+```tsx
+<DialogContent>
+  <DialogHeader><DialogTitle>刪除專案?</DialogTitle></DialogHeader>
+  <DialogBody><p>此動作無法復原</p></DialogBody>
+  <DialogFooter>
+    <Button variant="tertiary">取消</Button>
+    <Button variant="primary">確定刪除</Button>
+  </DialogFooter>
+</DialogContent>
+```
+
+### ❌ Popover 當 Tooltip 用
+
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <button>hover me</button>
+  </PopoverTrigger>
+  <PopoverContent>提示文字</PopoverContent>
+</Popover>
+```
+
+**正解**:Tooltip 元件。Popover 是 click 觸發互動面板,Tooltip 是 hover 觸發純文字提示。
+
+---
+
+## Empty / 空狀態誤用
+
+### ❌ 自寫 flex+icon+title+desc 垂直居中
+
+```tsx
+<div className="flex flex-col items-center text-center gap-2 py-12">
+  <FileSearch size={48} className="text-fg-muted" />
+  <div className="text-body-lg font-medium">沒有符合的結果</div>
+  <div className="text-body text-fg-secondary">請調整篩選條件</div>
+  <Button>重設篩選</Button>
+</div>
+```
+
+**正解**:
+
+```tsx
+<Empty
+  icon={FileSearch}
+  title="沒有符合的結果"
+  description="請調整篩選條件"
+  action={<Button>重設篩選</Button>}
+/>
+```
+
+**理由**:Empty 元件 own icon size(Avatar 48px)/ typography tier / gap token。自寫 drift 風險。
+
+---
+
+## Skeleton / CircularProgress / Empty 混用
+
+### ❌ Loading 狀態用 Empty
+
+```tsx
+{isLoading && <Empty description="Loading..." />}  {/* ❌ */}
+```
+
+**正解**:Skeleton(骨架)或 CircularProgress(不知時長,indeterminate)。Empty 是「確認無資料」。全頁 loading 可 `<Empty icon={<CircularProgress size={48}/>} title="載入中" />`。
+
+### ❌ Error 狀態用 Empty
+
+```tsx
+{error && <Empty description="載入失敗" />}  {/* ❌ */}
+```
+
+**正解**:`<Alert variant="error">`。Empty 是中性空(可能有操作解除),Error 是需處理的問題。
+
+---
+
+## ProgressBar / CircularProgress 混用
+
+### ❌ 不知進度硬套 ProgressBar(value=0 / 亂跳)
+
+```tsx
+<ProgressBar value={isLoading ? 30 : 100} />  // ❌ 進度無法量化
+```
+
+**正解**:`<CircularProgress>`(不傳 value)做 indeterminate。ProgressBar 是 determinate。
+
+### ❌ 已知百分比的大區塊進度用 CircularProgress indeterminate
+
+```tsx
+<CircularProgress />  {/* 明明已知 45% */}
+```
+
+**正解**:大區塊 / 頁面級用 `<ProgressBar value={45} affix="value" />`;inline 小空間用 `<CircularProgress value={45} affix="value" />`。
+
+---
+
+## Tabs / Accordion / Carousel 誤用
+
+### ❌ Tabs 切換「獨立功能」而非平行視圖
+
+```tsx
+<Tabs>
+  <TabsTrigger value="settings">設定</TabsTrigger>
+  <TabsTrigger value="logout">登出</TabsTrigger>  {/* ❌ 登出是 action 不是 tab */}
+</Tabs>
+```
+
+**正解**:登出走 DropdownMenu 或獨立 Button。Tabs 是「切平行內容視圖」。
+
+### ❌ Accordion 內巢狀 Accordion
+
+```tsx
+<Accordion>
+  <AccordionItem>
+    <AccordionContent>
+      <Accordion>...</Accordion>  {/* ❌ */}
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+**正解**:改用 TreeView(有階層語意)或 flatten。
+
+### ❌ Carousel 當資料切換器用
+
+```tsx
+<Carousel>
+  <CarouselItem>總覽</CarouselItem>
+  <CarouselItem>成員</CarouselItem>
+  <CarouselItem>設定</CarouselItem>
+</Carousel>
+```
+
+**正解**:`<Tabs>`。Carousel 是輪播同類內容(圖片組 / testimonial),不是命名視圖切換。
+
+---
+
+## Coachmark / Dialog / Popover 用錯場景
+
+### ❌ 確認破壞性 action 用 Coachmark
+
+```tsx
+<Coachmark title="確定刪除?" onNext={del}>
+  <Button variant="primary" danger>刪除</Button>
+</Coachmark>
+```
+
+**正解**:`<Dialog>`。Coachmark 是 non-modal onboarding(使用者可忽略),Dialog 是 modal 阻斷(必須處理)。
+
+### ❌ 錯誤訊息用 Coachmark
+
+```tsx
+<Coachmark title="載入失敗" description="網路異常" />
+```
+
+**正解**:`<Alert variant="error">` 或 `<Notice>` (非浮層)/ Toast(非阻斷)。Coachmark 是主動推送功能介紹,不是錯誤回報。
+
+---
+
+## ScrollArea / Native overflow 混用
+
+### ❌ Consumer 內 DataTable 水平捲動用 native overflow-x-auto
+
+```tsx
+<div className="overflow-x-auto">
+  <DataTable columns={...} data={...} />
+</div>
+```
+
+**正解**:`<ScrollArea orientation="horizontal">` 包(跨 OS 一致)。
+
+```tsx
+<ScrollArea>
+  <DataTable columns={...} data={...} />
+  <ScrollBar orientation="horizontal" />
+</ScrollArea>
+```
+
+---
+
+## AspectRatio / 硬寫 aspect-* 混用
+
+### ❌ media 容器硬寫 `aspect-video`
+
+```tsx
+<div className="aspect-video bg-muted">
+  <img src={url} />
+</div>
+```
+
+**正解**:
+
+```tsx
+<AspectRatio ratio={16 / 9} className="bg-muted">
+  <img src={url} className="w-full h-full object-cover" />
+</AspectRatio>
+```
+
+**理由**:`AspectRatio` 是 SSR-safe padding-bottom 方案,跨 OS / 未載入時穩定。硬寫 class 在某些邊緣瀏覽器失效。
+
+---
+
+## 色彩誤用
+
+### ❌ primary 當狀態色用(Mindset #1 違反)
+
+```tsx
+<ProgressBar className="bg-primary" value={60} />  {/* ❌ 除非就是進度 */}
+<Tag className="bg-primary">進行中</Tag>            {/* ❌ 應用 info */}
+```
+
+**正解**:進行中用 info,操作入口用 primary。
+
+```tsx
+<Tag className="bg-info-subtle text-info-text">進行中</Tag>
+<Button variant="primary">開始</Button>
+```
+
+### ❌ 硬寫 Tailwind 預設色
+
+```tsx
+<div className="text-red-500 bg-blue-100">  // ❌
+```
+
+**正解**:改 semantic token(text-error / bg-info-subtle)。
+
+---
+
+## 此清單如何擴充
+
+每次 audit 發現新 misuse pattern,append 到本檔。保留 negative example + 正解 + 理由 3 段格式。

package/ds-canonical/fork/skills/product-ui-audit/references/report-template.md

@@ -0,0 +1,159 @@
+# Report Template — P0/P1/P2 分類 + 報告格式
+
+---
+
+## Severity 分類
+
+### P0 — 必修(無爭議 bug)
+
+自動 bug / 違反明確 DS 規則 / a11y 必要項缺失:
+
+- Token 硬寫 hex / rgb / shadcn alias
+- Tailwind default shadow(shadow-sm / md / lg)
+- Tailwind v4 `[--foo]` shorthand
+- icon-only 無 aria-label
+- Dialog / Modal 無 DialogTitle
+- 非 button 綁 onClick(a11y 破壞)
+- 巢狀浮層 / 巢狀 Modal(HTML invalid 或 UX 破壞)
+- node_modules/@qijenchen/design-system/ds-canonical/references/ui-dev-rules.md「同 flex 列互動 slot 幾何鐵律」違反
+
+**處理**: AI 可直接修(surgical fix),commit 時 user 一併 review。
+
+### P1 — 批次修 + review
+
+設計原則違反 / 元件誤用 / 可改善但無立即 bug:
+
+- Layout primitive 未消費(自 roll Empty / item-layout 等)
+- 硬寫 px 值當應用 token
+- placeholder 文案(Option A/B/C / Lorem ipsum)
+- Primary Button 堆疊
+- 巢狀 Accordion / Tabs / Carousel
+- native overflow 未用 ScrollArea(跨 OS 跑版潛在風險)
+- 硬寫 aspect-* class 未用 AspectRatio
+
+**處理**: 批次 fix,每 Dim 一個 commit,由 user review。
+
+### P2 — 需討論
+
+scope / 設計決策 / 業務判斷:
+
+- cva defaultVariants 三方漂移(可能 intent)
+- Rule B 邊界案例覆蓋不足(scope 決策)
+- 新元件 promotion 判斷
+- 歷史 code 風格差異(rename / refactor 決策)
+- TODO 留白(規格未定)
+
+**處理**: 不自動修,由 user 逐項決策。
+
+---
+
+## Report 格式範本
+
+```markdown
+# Product UI Audit Report
+
+**Scope**: `src/app/features/checkout/` (23 files)
+**Date**: 2026-04-19
+**Dimensions audited**: 6 (Token / Layout primitive / Component / Mindset / Geometry / A11y)
+
+## Summary
+
+| Dim | Total findings | P0 | P1 | P2 |
+|-----|---------------|-----|-----|-----|
+| 1 Token | 3 | 2 | 1 | 0 |
+| 2 Layout primitive | 5 | 0 | 4 | 1 |
+| 3 Component | 2 | 1 | 1 | 0 |
+| 4 Mindset | 4 | 0 | 3 | 1 |
+| 5 Geometry | 1 | 1 | 0 | 0 |
+| 6 A11y | 2 | 2 | 0 | 0 |
+| **Total** | **17** | **6** | **9** | **2** |
+
+## Findings Detail
+
+### P0(必修 6 項)
+
+| # | Dim | File:Line | Finding | Fix |
+|---|-----|-----------|---------|-----|
+| 1 | 1 Token | src/app/checkout/PaymentForm.tsx:87 | 硬寫 `#3b82f6` | 改 `var(--primary)` |
+| 2 | 1 Token | src/app/checkout/Summary.tsx:42 | `shadow-md` | 改 `shadow-[var(--elevation-200)]` |
+| 3 | 3 Component | src/app/checkout/PromoButton.tsx:12 | iconOnly Button 無 aria-label | 加 `aria-label="套用折扣碼"` |
+| 4 | 5 Geometry | src/app/checkout/Actions.tsx:55 | 同 flex 行 Button sm(28)+ICon-only Primary(24)box 不一致 | 統一尺寸,或移 icon 入 Button's startIcon |
+| 5 | 6 A11y | src/app/checkout/ProgressNav.tsx:23 | `<div onClick=...>` | 改 `<button>` 或加 `role="button" tabIndex={0} onKeyDown={...}` |
+| 6 | 6 A11y | src/app/checkout/ConfirmModal.tsx:8 | Dialog 無 DialogTitle | 加 `<DialogTitle>確認結帳</DialogTitle>` |
+
+### P1(批次修 9 項)
+
+{以 Dim 分組,per-Dim table}
+
+### P2(需討論 2 項)
+
+| # | Dim | File:Line | Finding | 為何需討論 |
+|---|-----|-----------|---------|---------|
+| 16 | 2 Layout | src/app/checkout/EmptyCart.tsx:30 | 自 roll icon+title+desc+CTA structure | Consumer 若有品牌化 requirement 可能需 override Empty;需 user 確認 design intent |
+| 17 | 4 Mindset | src/app/checkout/AmountInput.tsx:15 | Input typography 用 `text-[15px]` | 業務要求此欄位字體稍大,需評估 DS 是否加 variant 或 case-by-case 接受 |
+
+## 建議
+
+**先修 P0 6 項**(1 個 commit):無爭議 bug,改完即世界級 baseline。
+**再批次修 P1**(建議按 Dim 分 commit,4 commits):
+1. Token(Dim 1,1 項)
+2. Layout primitive(Dim 2,4 項)— 最大 batch
+3. Component(Dim 3,1 項)
+4. Mindset(Dim 4,3 項)
+
+**最後討論 P2**(stakeholder 共同決策)。
+
+## Next
+
+等待 user Checkpoint 決策:
+- (a) AI 直接修 P0,batch 修 P1,P2 逐項討論
+- (b) 全部 findings 先給 user 自己看,AI 等候指令
+- (c) 只修 P0,其他 park 到下個 sprint
+```
+
+---
+
+## Triage Checkpoint 範本
+
+audit 完,**不可**直接開始修。先 triage 問 user:
+
+```
+🔍 Product UI Audit Report
+
+Scope: {scope}
+Total findings: {N}
+
+P0(必修,無爭議){N0 個} — token 違反 / a11y 必要缺 / 幾何鐵律違反
+P1(批次修 + review){N1 個} — layout primitive 消費 / placeholder 文案 / Button 堆疊
+P2(需討論){N2 個} — scope / 設計決策 / 業務判斷
+
+建議順序:
+1. 先修 P0(1 commit,surgical fix)
+2. 再批次修 P1(每 Dim 一個 commit,共 {N_dims} commits)
+3. P2 逐項討論
+
+你要:
+(a) 按建議順序執行(我開始修 P0)
+(b) 先讓我完整看 findings 再決定
+(c) 跳過 P2,只修 P0+P1
+(d) 縮窄 scope 到 {sub-folder}
+```
+
+絕對不可:AI 自行決定修哪些,必過 triage。
+
+---
+
+## 合法例外聲明範本
+
+若 audit hit 被判定為合法例外(per CLAUDE.md 或 spec documented),在 report 中明文標示:
+
+```markdown
+### Documented exceptions(非 findings,供參考)
+
+| File:Line | Pattern | 例外理由 |
+|-----------|---------|---------|
+| Avatar.tsx:46 | `text: '#fff'` | cva 適用範圍例外(style prop 驅動 object map),per CLAUDE.md `cva 適用範圍` |
+| Rating.spec.md:73 | `bg-warning` 黃星 | 世界級 convention(Amazon / Yelp / Google),documented |
+```
+
+讓 user 知道 AI 有注意到但判斷為合法 — 防被誤解為遺漏。

package/ds-canonical/fork/skills/propose-options/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: propose-options
+description: Auto-invoke when listing options / 建議 / 候選方案. Forces inline 7-Q principle check(M8 benchmark / M17 SSOT / Rule-of-3 / M10 subsumption)per option BEFORE listing. Failures filtered or labeled. Codifies「verify before propose」runtime discipline.
+---
+
+# /propose-options — Propose-time 7-Q Gate
+
+**目的**:Claude 對 user 提建議 / 列 option list 時,**先跑 7 題原則自檢**,通過才寫進回覆。Reject 的不列 OR 列出時標 fail 原因。
+
+**對齊**:
+- CLAUDE.md mindset #1(不取巧)+ #2(消費既有)+ #5(猶豫就問)+ #6(meta 抽象)
+- M8 benchmark / M17 SSOT / M12 binary rule / 治理「加規則前 3 題」
+- 本 skill 是上述 meta 的**propose-time 落地** — meta 寫成文字不夠,要 mechanical workflow 釘住
+
+## When to invoke
+
+**強制 invoke** 在以下情境(不靠 user 提醒):
+- 寫「Option A / B / C」「選 A / B」「3 個方向」 類列表
+- 寫「建議做」「該做」「提議」 類 verb
+- 寫「c. d. e.」 候選清單(像本 conv 我給 c hook + d M18 那種)
+- 任何「if you sign-off, I'll do X」 提案
+
+**不 invoke**:
+- User 已明示要做 X(只是 execute,不 propose)
+- 純資訊回答(描述現況,不選擇)
+- Bug fix 的 surgical solution(無 option,直接修)
+
+---
+
+## Workflow(強制 7 題,缺一就 reject 此 option)
+
+每個 candidate option 過以下 7 題,inline 寫進回覆:
+
+### Q0 — **Pre-ASK self-verify problem 真存在**(2026-05-18 加,absorbs Sheet/inline-action/SurfaceBody 三題誤判事件)
+
+**問**:propose 給 user 拍板前,是否已**grep DS-wide + Read 相關 spec.md / tsx + Read consumer usage** 確認 problem **真存在**?
+
+**為何**:M18 / M23 / M29 都管「決策過程紀律」,但**propose 給 user 前的「problem 真存在?」基本判斷**沒 codify。本 session 我 propose 3 題(Sheet 補 / 5 元件 migrate inline-action / 5 元件 migrate SurfaceBody)**全部不是真 problem** — Sheet spec 已完整、inline-action 已全消費、SurfaceBody 有意設計不該動 — 但我 propose 給 user 拍板浪費 user 時間 + 動搖 user 信任。
+
+**強制檢查**:
+1. **grep 既有 code DS-wide** — 「該 migrate 的 X 元件」真沒消費 primitive?(`rg "<primitive>" node_modules/@qijenchen/design-system/src/components/<X>`)
+2. **Read 相關 spec.md** — spec 有沒有明文 codify 該設計是有意 / 例外 / 合法分支?(本 session 例:Tag inline-action colored host 例外是 spec L52-54 明寫的)
+3. **Read consumer usage** — 該 pattern 已在 N 處 work fine?N ≥ 3 → 該 pattern 是 working canonical,不是 problem
+4. **反問**:「如果 user 答 A,我會做什麼?該動 K 個 file?那 K 個 file 真有問題嗎?還是我假設的?」
+
+**Fail criteria**(任一命中 → reject propose,不丟給 user):
+- 沒 grep 既有就斷言「N 元件缺 X」
+- 沒讀 spec 就斷言「現況違反 canonical」
+- 「我推 A 因 X 比較統一」但 X 已是合法分支(spec 明文)
+- propose 是 mass-migration 但沒列具體哪 K file file:line 需動
+
+**Pass criteria**(全過才能 propose):
+- ✅ 列具體 file:line 證據 problem 存在
+- ✅ 列 spec.md 段落 cite 證明「現況違反 spec」
+- ✅ counter-example scan 跑過:DS 其他元件用一樣 pattern → 反證「這不是 problem」
+- ✅ 給 user 的 option list 含「C. 不動(理由)」且 C 經 grep verify 不是 cheap escape
+
+**例**:
+- ✅ "grep 結果 Input/NumberInput/LinkInput 3 file 都未消費 ItemInlineAction(file:line)+ spec.md L60 表格列為 expected consumer → 真 gap"
+- ❌ "5 元件應該 migrate"(沒 grep / 沒 cite spec / 不知道 K 元件已 migrate / 是 colored host 合法例外)
+
+**對應 hook**:`check_propose_pre_grep_verify.sh`(2026-05-18 加,Edit/Write `*.md` 內含「propose」/「請拍板」/「決策」keyword 但近 N turn 無 grep/Read tool call → P1 warn)
+
+### Q1 — M8 World-class benchmark
+**問**:本 option ≥ 3 家 world-class DS / framework / canonical 有對照嗎?
+**列**:具體實作名 / API 指向 / docs URL
+**Fail**:< 3 家對照 → option 未成熟,不該 propose
+**例**:
+- ✅ "Polaris IconButton padding-free / Atlassian button-iconOnly p:0 / Material UI MuiSvgIcon flex-shrink:0"
+- ❌ "感覺合理 / 可能對 / 沒查"
+
+### Q1' — **M23 DS internal canonical 優先 grep**(2026-05-03 加,chevron 事件後)
+**先 grep DS 既有 token / variant / pattern 命中?有 → 必對齊,Q1 外部 benchmark 只是輔證。**
+**問**:propose 的 visual decision(color / size / spacing / typography / state)是否已 grep `node_modules/@qijenchen/design-system/src/tokens/` + 近親 component spec/tsx 確認沒命中既有?
+**Fail**:跳過 grep 直接搬 world-class → M23 違反(本 conv chevron 用 Ant 5 家 muted 覆蓋 DS 內 icon-only Button = neutral-9 canonical → user 4 輪糾正)
+**例**:
+- ✅ "grep `text-foreground` 已是 icon-only Button 預設(neutral-9 / 85%)→ 對齊;Ant cite 為輔證"
+- ❌ "Ant / Material muted → 直接套(沒 grep 內部 canonical)"
+
+### Q2 — M17 SSOT 必可傳播
+**問**:本 option 動到的 canonical 有真正可執行 SSOT 嗎(token / primitive / utility)?還是只在 markdown 文字?
+**Fail**:只增加 markdown 文字、沒提供 mechanical enforcement → 假 SSOT
+**例**:
+- ✅ "新 utility class `ICON_ONLY_BASE` 共用,2 host import"
+- ❌ "spec 寫一行 rule,未來誰記得就好"
+
+### Q3 — Rule-of-3 SSOT placement
+**問**:本概念在現有 home 已 ≥ 3 處出現?該選 SSOT,其他 pointer。新加的話,SSOT 該住哪 home?
+**Fail**:concept 已 ≥ 3 處仍要新增 home / 重複描述 → 違 Rule-of-3
+**例**:
+- ✅ "uiSize.spec.md 是 SSOT,button.spec.md / segmented-control.spec.md 1 行 pointer"
+- ❌ "每個 spec 各自寫一份"
+
+### Q4 — M10 下游吸收
+**問**:本 option 加入後,既有哪些 rule / memory / bug case 被吸收可刪?
+**Fail**:純 append 沒 retire,違反「上游加 = 下游減」 + 治理 anti-bloat
+**例**:
+- ✅ "M18 加,M12 部分 overlap 但 scope 不同共存(說明)"
+- ❌ "新加 M18,既有 M-row 全保留(沒檢查)"
+
+### Q5 — Issue list 100% mapped(2026-05-05 anti-drift,user trigger 第 5 次後新增)
+**問**:plan iteration / option list 改版時,user 提的**所有** raised issue 是否 100% mapped 到本版的 step / option / 評估?**未 mapped 的逐條 explicit 標**:`done` / `folded into Step X` / `informational(無實作)` / `dropped(原因)` / `pending`。
+**Fail**:silent drop / 沒 mapping table / fold 進 step 沒 trace
+**例**:
+- ✅ "Issue 1-14 列 mapping table,Issue 3+13 標 informational,其他 11 條 mapped"
+- ❌ "改版只列新 Step,沒 walk-through user 之前提的 issue list"
+
+---
+
+## Workflow Output Format
+
+對 user 回覆中的 option list 必含 **inline 7-Q 表 + Issue mapping**(plan iteration 場景):
+
+```markdown
+| 選項 | M23 DS grep | M8 benchmark | M17 SSOT | Rule-of-3 | M10 下游 | Issue cover | 結論 |
+|---|---|---|---|---|---|---|---|
+| A | DS 已有 X token,對齊 | Polaris/Atlassian/Material 輔證 | 抽 utility 共用 | 0 處 SSOT 新增 OK | 可刪 X 條冗餘 | covers 8/14 | **PASS,推薦** |
+| B | 沒 grep | 只查 1 家 | 純 markdown rule | 已 3 處,無新 SSOT 動 | 純 append 沒 retire | covers 4/14 | **REJECT(M23+M8 雙 fail + Q5 不全)** |
+```
+
+**Plan iteration 必含 Issue ↔ Step 完整 mapping table**(不可只列新 step 表,user 看不到原 issue trace):
+```markdown
+| # | Issue (按 user 提出順序) | 處理 |
+|---|---|---|
+| 1 | <user 原文 issue> | Step X / informational / dropped(reason) |
+| ... | ... | ... |
+```
+
+**所有 fail 過 7-Q 的 option 必明示 reject + 原因**,不只 list 不過的。User 看見 reject 過程才能信 propose 過原則。
+
+---
+
+## Edge cases
+
+### 緊急 / surgical bug fix
+不需走全 7 題(沒 option list,直接修)。但 commit message 仍應簡述「修法已知 root cause + 不取巧」(對齊 mindset #1)。
+
+### Option 內含 sub-option(nested)
+每層各自跑 7 題。Skill 不限深度但實作上 ≥ 3 層 nested 已是設計問題,user 該停下重整。
+
+### User 已明示要 X(非 propose)
+不跑 skill。直接執行。
+
+---
+
+## 為什麼這 skill 必要(本 session 教訓)
+
+User 已就「為什麼會給錯誤建議」糾正 ≥ 3 次:
+- session 初:G6/G7/G8 推力,我自己沒 dogfood test → 第 3 次問才補
+- 中:c hook + d M18-inner-area propose,**user sign-off 前剛好我自己覺察跑 7-Q 才撤回**
+- 末:user 直接質問「為什麼會給錯誤建議?如果我答應了會直接執行嗎?」(本 skill 的觸發)
+
+**Infra G6/G7/G8 是 post-edit / session-start 防線,沒 propose-time gate**。Claude Code event model 沒 OnAssistantMessage hook,**只能靠 model-runtime 紀律 + skill self-invoke**。本 skill 就是 mechanical 補位 — invoke 時讀本檔,7-Q 表格自然寫進回覆。
+
+---
+
+## Self-improvement capture
+
+每次 invoke 完,session 結束前自問:
+- (a) 是否每個 option 真跑了 7-Q 還是糊弄填表?
+- (b) 是否有 reject option 曾被 list?(reject 不該被列出)
+- (c) 是否 user 仍質疑 propose 品質?(若是 → 7-Q 沒抓到的 gap → 加 Q5)
+
+回填到本 SKILL.md 或 CLAUDE.md M18(若需 escalate)。
+
+---
+
+## 與其他 skill 對位
+
+| Skill | scope |
+|---|---|
+| `pre_write_subsumption_check.sh`(hook)| Edit/Write 已發生時 |
+| `post_edit_canonical_interrogate.sh`(retired/未實作 — mindset enforcement)| 寫完 canonical 後 3 題 |
+| `check_governance_compliance.sh`(retired/未實作 — 靠 `check_propose_pre_grep_verify.sh` + 加 hook 前 3 題)| 寫新 hook 7 題 |
+| **本 skill** `/propose-options` | **propose-time(寫進 user 回覆前)7 題** |
+
+4 個正交 — propose 前 / write 前 / write 中 / write 後 全 cover。