| name | bug-fix-rhythm |
| description | Batch-end-verify rhythm + parallel tool batch + user-listed N-rule MUST-ALL + claim runtime verify. Invoke when entering multi-fix session 或 user 列 numbered rules. Replaces M32(c)(d)(h1)(h2) sub-invariants(2026-05-12 split per Knowledge-Prune Checkpoint 2)。 |
⚠️ 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 跑。
/bug-fix-rhythm — 多 fix session 的 rhythm canonical
目的:當 session 有 ≥ 2 fixes(常見 visual bug session / user 列 N 條 numbered 規則),走 batch-end-verify rhythm,而非 per-fix verify cycle waste。M32 split 後 (c)(d)(h1)(h2) 的 home。
對齊:
- CLAUDE.md mindset #6「大原則吸收瑣碎」+ M14「對話結論 AUTO integrate」
- Bazel incremental-build / GitHub Actions matrix-batch idiom(per-step incremental = waste,batch-end = canonical)
- Anthropic Claude Code prompt engineering「single-message multi-tool-call」canonical
- Toyota TPS jidoka(per-station per-item verify,不可 skip 任何 item)
When to invoke
強制 auto-chain:
- multi-issue session 內 ≥ 2 fix 待處理(visual / behavior / code 任 mix)
- user 列 numbered N 條規則(「規則 1...規則 N」/「Q1...QN」/ image 標 1234)→ 視作 MUST-ALL checklist
手動 invoke:user 明言「批 fix」「一次做完」「跑完再驗」「列規則」
不 invoke(對齊 Anthropic Best Practice 小修 skip):
- 單一 surgical fix(無 numbered rule + 無 cross-component)— per-fix verify 即可
- pure refactor / typo / import cleanup
- spec.md docs only
Non-goals
- 不擴展到「audit full-dim」(那是
/design-system-audit)
- 不取代
/scan-similar-bugs(那是 fix 後 root-pattern scan;本 skill 是 fix-過程 rhythm)
- 不動 canonical 語意(走 audit-vs-execute STOP 提議)
Workflow(4 phases)
Phase 0 — Intake & MUST-ALL checklist 化(原 M32(h1))
讀 user message:
If user 列 numbered rules(「規則 1: X / 規則 2: Y / ...」/「Q1 / Q2 / ...」/ image 標號 / bulleted list)→ 抽出 MUST-ALL checklist:
## MUST-ALL checklist(per-rule 不可下放)
- [ ] 規則 1: <verbatim user wording> — 對應 fix: <target>
- [ ] 規則 2: <verbatim user wording> — 對應 fix: <target>
- ...
- [ ] 規則 N: <verbatim user wording> — 對應 fix: <target>
禁止:
- 把 N 條視作 ranked-priority(「先修 1-3,4 之後再說」)
- 漏 N 條中第 K 條當「做完」report
- 改寫 user wording 為自己 paraphrase(verbatim 保留)
Sweep-first, edit-second(2026-07-07 治理進化軌道 2 codify):任一 fix 屬「跨切面決策」
(改名 / 詞彙統一 / 規則性改動,可寫成 grep 謂詞者)→ 先跑謂詞產出「sweep manifest」
(grep 指令 + 全庫命中清單,artifact 化),照清單做完、驗證清單歸零,才算該 fix 完成。
禁「先改直覺想到的檔、稽核抓漏再補」(anchor:2026-07-07 meta 詞彙統一三波 11→16→9 檔,
規則在散文裡 → 三輪才收斂;寫成謂詞後一個 grep 掃平)。
Phase 1 — Parallel tool batch(原 M32(d))
Read / Grep / Glob 多檔需求 → single message multi-tool-call:
✓ Good: 1 message with [Read A, Read B, Read C, Grep D, Grep E] (~2s)
✗ Bad : 5 messages sequential (~10s)
Heuristic:任何 tool call 之間無 dependency(後一個不需前一個結果) → 必 parallel。
對齊 Anthropic Claude Code best practice:「Maximize use of parallel tool calls where possible」。
Phase 2 — Batch fix(原 M32(c))
每 fix 用 Edit(不 Write,降風險)。禁止 per-fix tsc / audit cycle:
✓ Good: [Edit A] [Edit B] [Edit C] [Edit D] → final tsc + audit + visual (once)
✗ Bad : [Edit A → tsc → audit → visual] [Edit B → tsc → audit → visual] ... (5× waste)
例外:某 fix 確實依賴前一 fix 的 type 結果 → sequential 必要時可,但 verify cycle 仍 batch-end-only。
⚠️ Checkpoint 1 — Substantive vs surgical 分流
每 fix 落地前 inline 判斷:
- Surgical(CLAUDE.md「Scope classifier — Surgical visual bug」):pixel / token / class adjustment, no new SSOT / API / cross-component → AUTO ship 此 fix
- Substantive(audit-vs-execute 分權):新 SSOT / 新 prop / 新 canonical meaning / cross-component semantic → STOP propose,等 user verbatim 拍板才 ship
混合 batch:surgical 部分 ship,substantive 部分 propose。禁止:substantive 偷渡進 surgical batch。
Phase 3 — Final batch-end verify(原 M32(c)(h2))
全 fix 完成後一次性驗證:
npx tsc -b
npm run hooks:test
node scripts/visual-audit.mjs --scope=changed
MUST-ALL re-check(per Phase 0 checklist):
## MUST-ALL verify report
- [x] 規則 1: ✓ verified via <tsc | audit script | pixel measurement | playwright>
- [x] 規則 2: ✓ verified via ...
- ...
- [x] 規則 N: ✓ verified via ...
禁止(原 M32(h2) claim runtime verify):
- 寫「不會有問題」「無 side-effect」「verified」「都實作完了」沒對應 verify trace
- code-reading 推論當「verified」
- ranked-priority 漏 N 條中第 K 條當「做完」
若某條無法 runtime verify → 明撤回 「規則 K:未驗證,推論而已,user 真機 verify needed」,不可假宣告。
對齊 M20 claim-verify gap(M20 是 stop-hook 機制;本 skill Phase 3 是 active workflow side)。
⚠️ Checkpoints(禁止跳)
Checkpoint 1 — Phase 2 surgical vs substantive(見上)
Checkpoint 2 — Phase 3 verify trace 缺漏
若 MUST-ALL N 條有 K 條無 verify trace → STOP report,先補 verify 再報 user。
Checkpoint 3 — User-listed rule wording 改寫
若 Phase 0 抽 checklist 時改了 user wording → STOP,重抓 verbatim。
與其他 skill / hook 的關係
| Tool | Scope | 跟本 skill 關係 |
|---|
/scan-similar-bugs | fix 後 DS-wide root-pattern scan | 本 skill batch-end-verify 後才 chain /scan-similar-bugs |
/visual-audit | 單次視覺對齊 | Phase 3 sub-step,本 skill 包它 |
/component-quality-gate | stakeholder gate | 不重疊(stakeholder vs daily bug fix) |
stop_self_audit.sh(hook) | claim-verify gap 攔 | 本 skill Phase 3 是 active side;hook 是 passive trip-wire |
check_pixel_quantified_audit.sh(hook) | M32(a) audit script(scripts/visual-audit*.mjs,canonical = visual-audit.mjs)必 pixel | 本 skill Phase 3 跑該 audit |
3 層 防線:
- 本 skill(active workflow):MUST-ALL checklist + batch-end-verify rhythm
- stop_self_audit.sh(passive hook,claim-verify gap,BLOCKER)+ check_codex_collab_5step.sh(passive hook,codex-collab commit 缺 cite+verify+verdict marker,P1 soft stderr 不 block)
- M20 / M32(a)(meta-rule):上游 invariant
世界級對照
- Bazel
bazel test //...:全 target 並行 + final report,而非 per-target sequential
- GitHub Actions matrix:N 個 job 並行,final aggregate verdict
- Toyota TPS jidoka:每 station per-item verify,但 verify 是 station-end 而非 in-progress checkpoint
- Anthropic Claude Code prompt eng:「Maximize use of parallel tool calls」
- Stripe / Linear engineering blog:「batch deploy + single canary verify」over「per-PR canary」
Self-improvement capture
每次 invoke 完寫:
- (a) Phase 0 抽 MUST-ALL 時 user wording 是否變形?
- (b) Phase 2 surgical/substantive 分流是否準確?(false-positive 偷渡記錄)
- (c) Phase 3 verify trace 有沒有「runtime verify needed」的條目漏標?
- (d) 新發現 numbered-rule pattern → 加進 Phase 0 抽取 heuristic
回填本 SKILL.md 或 references/。
歷史 absorbed failures(M32 split 來源)
2026-05-12 4 prior failures absorbed by M32 → split 後本 skill 承接 (c)(d)(h1)(h2):
- cell-align audit「Δ=0 ALL PASS」但 user 抓 SKU/Qty 視覺垂直置中於 88px 高 row(audit 沒驗 Field collapse)
- divider 2px audit「ALL PASS」但 pinned panel 邊仍 2px(audit 沒驗 pixel overlap)
- breadcrumb tooltip audit「ALL PASS」但 user 連抓 hover 不 fire(audit 沒驗 Portal DOM bounding rect)
- row-alignment audit「Δ=0 ALL PASS」(attr 對齊,Field collapse 沒抓)
具體 M32(a) pixel-quantified rule 仍在 meta-patterns.md,本 skill 是其 workflow side。
