scan-similar-bugs

name	scan-similar-bugs
description	Auto-invoke after fix commits — extracts root-cause anti-pattern, greps DS-wide for same pattern, runs visual verify, batches related fixes. Closes M10 mechanical gap. Invoke via /scan-similar-bugs.

⚠️ Fork 工具註記(build 自動加):本 skill 提到的 scripts/*.mjs 或非標準 npm run <audit> 是 DS-author repo 的機械工具,未隨 fork 套件附帶(Claude Code 不掃 node_modules,fork 也無這些 executor + dep)。你的 product fork 用本 skill 的方法論(human / AI judgment)+ 既有 committed governance hook 的機械強制即可;要 mechanical 腳本層(截圖 / CI gate)請自行設置對應工具,或把該檢查 PR 回 DS repo 跑。

/scan-similar-bugs — Fix-time DS-wide Exhaustive Scan

目的:任何 bug fix 提交後,機械化掃 DS-wide 找同 pattern,而非靠 model 記得 M10。

對齊:

• CLAUDE.md M10 「Proactive exhaustive scan」mechanical 落地
• mindset #1「不取巧」+ #2「優先消費既有」+ #6「meta 抽象」
• 對齊 IDE「find similar / find references」+ Chrome DevTools「find usages」+ GitHub Copilot「related code」3+ 家世界級 idiom

對位其他 skill:

• /design-system-audit 是定期 batch full-dim audit
• /visual-audit 是單次視覺對齊 check
• 本 skill 是 batch-end-only root-pattern scan(2026-05-12 codex 抓 infra conflict 重構:per-fix → batch-end,對齊 /bug-fix-rhythm Phase 2-3 batch fix + single end-verify canonical;M32 split 後 batch-end home 移至 bug-fix-rhythm skill)

When to invoke

強制(auto-chain)— batch-end only(2026-05-12 重構,per codex):

• multi-issue session 結束後一次(不是每 fix 一次)
• session 內 ≥ 2 fix commit 觸發批次 root-pattern scan
• session_start_governance_check.sh Check 6 偵測 24h 內 ≥1 fix commit 且 skill-invokes log 24h 無 scan-similar-bugs invoke → soft 提醒

手動 invoke:

• user 明言「掃同類 bug / 看其他元件有沒有 / 全 DS scan」
• multi-issue batch session 結束想驗 root-pattern DS-wide

不 invoke(對齊 Anthropic Best Practice 小修 skip plan):

• Surgical visual bug(user 列 N 個 visual defects + 無 canonical / API / cross-component → 批 fix + final verify only,不必 scan-similar)
• pure refactor(無 bug 修復語義)
• spec.md / docs only commit
• 純 typo / import cleanup

Non-goals

• 不擴展 scope 到「audit full-dim品質」(那是 /design-system-audit)
• 不做視覺 regression baseline diff(那是 /visual-audit)
• 不改 canonical(找到 pattern 後修是 surgical fix,動 canonical 走 audit / Checkpoint)

---

Workflow(5 phases)

Phase 0 — 抓 root-cause anti-pattern

# 讀 last fix commit message + diff
git log -1 --format='%s%n%n%b'
git show HEAD --stat

從 commit message + diff 抽出 grep-able pattern。常見類型:

Bug 類型	Anti-pattern grep target
Padding / sizing 公式錯	calc((var(--field-height-X) - <num>px) / 2) etc
Token leak / shadcn alias	bg-popover / text-muted-foreground / bg-accent
硬寫 magic number	text-[14px] / shadow-[0_2px_8px_...]
API mis-use(prop combo)	iconOnly + endIcon / loading + disabled
a11y missing	<button> 無 aria-label 又無 children
Symbol mis-import	from 'shadcn/ui/X'
CSS w/h asymmetric	SVG 量測 width !== height

Output: ANTI_PATTERN(grep regex / Playwright assertion)。

Phase 1 — DS-wide grep / visual scan

選最適合的 detection:

Static grep(快,適合 token / class / API mis-use):

grep -rnE "$ANTI_PATTERN" node_modules/@qijenchen/design-system/src/ --include="*.tsx" \
  | grep -v "test_\|stories\|node_modules"

Playwright visual scan(慢,適合 geometry / a11y / interaction):

node scripts/scan-asymmetric-icons.mjs   # 已存在,iconOnly visual scan template
# 或 base 同 pattern 自寫 dim-specific scan

Output:候選清單(file:line + 樣本)。

⚠️ Checkpoint 1 — Triage

向 user present:

Phase 1 found N candidates of same anti-pattern:
- node_modules/@qijenchen/design-system/src/components/A/a.tsx:42  > grep match
- node_modules/@qijenchen/design-system/src/components/B/b.tsx:18  > grep match
- node_modules/@qijenchen/design-system/src/components/C/c.tsx:55  > 視覺 14×16

Proceed?
- (a) Auto-fix all N(若修法 deterministic 例 token rename)
- (b) Review per-file(若 fix 需個別判斷)
- (c) 留 N 個 tech debt 後續處理(寫 memory + 不修)

不可 silent 跳過 user — fix scope 影響 N 元件,M10 + 稽核 vs 執行 分權要求 user 拍板。

Phase 2 — 批量 / 個別 fix

按 Checkpoint 1 user 選的路執行。每修一檔:

• 用 Edit(不 Write,降風險)
• 修完 grep 該 anti-pattern 應 0 match
• npx tsc --noEmit 必過

Phase 3 — Visual / unit verify

• Visual:跑 npm run icons:scan 或 dim-specific scan
• Unit:跑 npm run hooks:test
• TSC:npx tsc -b
• 全綠才繼續

Phase 4 — Final report + memory + new defense

## Scan-similar-bugs report

### Root cause(來自 last fix commit `<hash>`)
- Pattern:{ANTI_PATTERN}
- Origin file:{first detected location}

### DS-wide impact
- {N} candidates found
- {M} fixed this run
- {K} deferred(spec rationale 已記)

### New defense layer(防 future regression)
- 加 hook:`.claude/hooks/check_<pattern>.sh`(若 pattern 易 grep)
- 加 visual test:`scripts/scan-<pattern>.mjs`(若需 Playwright)
- 加 spec rule:{spec.md anchor}

## Self-improvement capture
- 新 anti-pattern 加進本 skill 的 Phase 0 「Bug 類型 → grep target」表
- M10 fire 紀錄(commit 後本 skill invoke vs not)

寫進:

• 對應 commit message
• memory/ 若是 cross-session pattern
• 本 skill references/ 若是 reusable detection 公式

---

⚠️ Checkpoints(禁止跳)

Checkpoint 1 — Phase 1 後 Triage

N 個 candidate 的修法 scope。禁止 auto-fix 超過 5 檔不 ask user。

Checkpoint 2 — 動 canonical

若 N candidates 都 violate 同 canonical,但 canonical 本身可能 outdated → 走 audit 重訂(不在本 skill scope)。

Checkpoint 3 — Defer 的 tech debt

若 user 選 (c) 留 tech debt → 必寫 memory + 標明「deferred at ,reason: 」。/codify-corrections 季度會 review。

---

對位其他 skill / hook

Tool	scope	跟本 skill 關係
/design-system-audit	full-dim batch audit	本 skill 抓不到的 architectural pattern audit 補位
/visual-audit	單次視覺對齊	Phase 3 verify 用
/scan-similar-bugs(本)	immediate-after-fix grep + verify	M10 mechanical 落地
/knowledge-prune	季度 governance prune	不重複
check_canonical_propagation.sh E.2(hook;原 check_l3_primitive_import.sh folded 折入,P0 BLOCK)	L3 primitive import 違規	即時 detect,本 skill 是 batch retro scan
pre_write_subsumption_check.sh(retired 2026-06 → .claude/hooks/retired/;新 file / M-row 治理由 session_start_governance_check.sh + enforce_home_charter.sh 現役防線接手)	新 file / M-row	不重複

3 層 防線:

• Hook(pre/post tool):寫的瞬間 detect
• 本 skill(fix-time):修完瞬間 scan DS-wide
• /design-system-audit(periodic):季度 full-dim sweep

---

世界級對照

• Chrome DevTools "find references":單元件變更後找其他 consumers
• VS Code "find similar code":AI-powered same-pattern scan
• GitHub Copilot Workspace:fix 後自動 propose related changes
• WebStorm "Inspect Code → Similar Patterns":同 pattern detect

我們對齊 4 家但加 DS-domain-specific anti-pattern table(Phase 0 列表),是 generic IDE 沒做到的。

---

Self-improvement capture

每次 invoke 完寫:

• (a) 新發現 anti-pattern → 加到 Phase 0 表(grep target template 更新)
• (b) Detection false positive → 修 grep regex 或加 allowlist 註解 pattern
• (c) Phase 1 漏掃 location → 補 grep scope(extend 到 hooks/ / scripts/ etc)

回填 SKILL.md 或 references/ 形成累積資產。