ensure-canonical

name

ensure-canonical

description

User 說「確保 X 一定要 / 不可繞過 / 永不漂移 / ensure X always」trigger phrase → 自動規劃完整 defense-in-depth pipeline(M14 5-layer + M8 benchmark + M17 SSOT + M10 下游),至少 3 層落地。對應 CLAUDE.md M19。Invoke via /ensure-canonical OR auto-recognize trigger keywords(確保 / 一定 / 不可繞過 / 不准 silent / 永不漂移 / ensure / always / never bypass / never silent)。本 skill 把 reactive「user 講 N 次才完整落地」改 proactive「trigger phrase auto plan 5-layer」。

Ensure Canonical — User Trigger Phrase → Auto Defense-in-Depth

目的: User 提出「某事 X 一定要照規矩發生」類 request → 自動套 5-layer defense-in-depth(canonical / hook / skill / audit / verify),不靠 AI 自律,不靠多次糾正,不留 silent bypass。

對應: CLAUDE.md # Meta-Pattern 預警 M19。世界級對照 Spotify Backstage / Polaris / Material / Carbon 4 家「rule + lint + test + doc」共識。

When to run

自動 trigger keywords(英中):

• 「確保 X / 確保所有 / 一定要 / 一律 / 永不漂移 / 不可繞過 / 不准 silent」
• 「ensure X always / X must / X required / never bypass / no silent X」
• 「規矩」+「發生 / 觸發 / enforce」
• 「自動 X / X must auto」

手動 invoke:/ensure-canonical 後接規則描述。

When NOT to run

• 純資訊請求(「告訴我 X 是什麼」)
• 一次性 ad-hoc 操作(「修這 1 個 bug」)
• 已 codified rule 的 enforcement(走 audit 不走本 skill)

Preconditions

• 讀 CLAUDE.md M14 / M19(本 skill SSOT 上游)
• 讀 # 治理 canonical(8 home)
• 該 rule 的 substantive meaning 還沒 finalize → 必走 Phase 5 user sign-off

Workflow(8 phases)

Phase 0 — Parse user rule(必跑)

從 user prompt 抽出:

• Subject: 「什麼事」(e.g. story splitting principle)
• Constraint: 「必 X」「禁 Y」(e.g. start+end icon 必合 WithIcon,不准拆兩 story)
• Scope: 全 DS / 特定元件 / 特定情境
• Existing state: 已有相關 canonical 嗎?(grep CLAUDE.md / spec.md)

Output:1 句結構化 rule。

Phase 1 — M8 World-class benchmark(必跑)

≥ 3 家 world-class DS / engineering org 對照:

• Polaris / Material / Atlassian / Ant / Carbon / Apple HIG / VS Code / Figma / Storybook 官方 / Spotify Backstage
• 每家寫具體實作名 + URL or source(closed source 標 closed)

通過條件:3 家 verified + AI 不假裝對齊不存在的 source(對齊 M8 「無對照 = 未成熟」)。

Phase 2 — M17 SSOT 識別(必跑)

問 4 題:

• 此 rule 屬哪 home?(CLAUDE.md / spec.md / token / hook / skill / memory)
• 該 rule 是 SSOT 本身還是 pointer?
• 是否 token / primitive / utility class 三擇一可程式化(M17)?
• 若仍 markdown-only canonical → flag 為「假 SSOT」風險

Phase 3 — Rule-of-3 + M10 下游檢查(必跑)

• grep 既有 canonical(CLAUDE.md / specs / skills)有無相同概念
• 若 ≥ 3 處出現 → 選 SSOT owner,其他 pointer only(避免 drift)
• 新 rule 落地後,既有哪些 spec / memory / bug case 變冗餘?明寫「可刪 X」或「無下游」

Phase 4 — 5-Layer enforcement plan(必跑)

對應 M14 pipeline,plan 對齊以下 5+1 層,至少 3 層真落地:

Layer	用途	範例
1 CLAUDE.md / spec.md	Canonical SSOT,文字規則	加段、加 row,定義 rule + rationale
2 Hook	Write-time mechanical block	exit 2 + 訊息 + allowlist
3 Hook test	Regression 防護	8+ scenario test_*.sh
4 Skill workflow	invoke 時 phase gate	/story-writing Phase 0 mapping
5 Audit dim	Periodic mechanical batch verify	/design-system-audit Group X
6 Memory / verify	Cross-session state + 每次 verify	tsc / build / visual / hook test

選擇邏輯:

• 機械可判斷 + 高頻寫 → 必加 Hook
• 多步驟 + 需 user 介入 → 必加 Skill
• 既有元件需驗 → 必加 Audit dim
• 規則本身 → 必加 CLAUDE.md / spec.md
• 無 user-reported pain 的層 → 跳過(M6 反 vanity)

⚠️ Phase 5 — Checkpoint:Plan sign-off(必跑)

呈給 user:

Rule: <Phase 0 結構化>
Benchmark: <Phase 1 3 家對照>
SSOT: <Phase 2 home + 是否 SSOT 本身>
下游影響: <Phase 3 retire 候選>
落地 plan(5+1 層,至少 3 落地):
  1. CLAUDE.md: ✓ <加哪段>
  2. Hook: ✓ <檔名 + 抓什麼 pattern>
  3. Hook test: ✓ <case 數>
  4. Skill: ✓ / ✗ <為什麼>
  5. Audit dim: ✓ / ✗
  6. Verify: ✓ <tsc / build / visual>
Substantive 動議: <若有 → STOP wait sign-off>

User 拍板才 Phase 6 起執行。

Phase 6 — Execute(每層 commit / verify)

每層分批 commit(M11 user-perspective walk + governance check):

1. CLAUDE.md edit + 7-Q hook self-check 過
2. Hook write + 8 scenario test + register .claude/settings.json
3. Skill workflow 加 phase
4. Audit dim 加到 /design-system-audit SKILL.md
5. Batch fix 既有違規(grep + perl/sed rename + Visual diff)
6. Commit feat(scope): <rule> + N-layer enforcement(M19)
7. Push + GitHub Pages deploy verify

Phase 7 — Verify

• npx tsc -b 2>&1 | tail -3 → 0 error
• npm run build-storybook 2>&1 | tail -3 → ✓ built
• bash .claude/hooks/tests/run-all.sh → all suites pass
• git status --short → clean
• git log origin/main..HEAD → empty(全 push)

任一 fail → 回 Phase 6 修。

Phase F — Self-improvement capture(必跑)

## Self-improvement capture
- 新發現 trigger pattern: ... OR 「無」
- 新確立 enforce template: ... OR 「無」
- 修完的 trigger 漂移 / user 糾正: ... OR 「無糾正」

回填:

• 新 trigger phrase → 加進 SKILL.md「When to run」
• enforce template 抽象化 → 加進 references/patterns.md(若 ≥ 3 次同 pattern)
• user 糾正 → memory feedback / CLAUDE.md M-row

Checkpoints

⚠️ Checkpoint 1 — Phase 5 plan sign-off(永遠 mandatory)

未 user 拍板不可 start Phase 6。即使 user 已說「全做」「馬不停蹄」,仍要呈 plan(可短),抓「我以為 user 要 X 但其實要 Y」風險。

⚠️ Checkpoint 2 — Substantive 動議遇 STOP

• 動 canonical 既有 substantive meaning(改 rule、刪 rule、改 SSOT 位置)→ STOP
• 對齊 / 表達層調整 / 補 pointer → AUTO

⚠️ Checkpoint 3 — Layer 數不足

至少 3 層落地。若計算只有 2 層(e.g. 只 spec + hook,無 skill / audit / verify)→ 重 Phase 4 plan 補。

⚠️ Checkpoint 4 — User 沒明確 trigger phrase 但 implicit ensure 意圖

例:user 說「為什麼之前都漏這個」「下次怎麼確保不再發生」 → trigger M19 但表達 implicit。主動問 user「要走 /ensure-canonical 規劃完整 5-layer 嗎?」不假裝沒看到。

Non-goals

• 不負責 single-file refactor(走 /design-system-audit)
• 不負責 ad-hoc bug fix(走 /scan-similar-bugs)
• 不替代 propose-options 4-Q gate(M18 不同階段:propose vs ensure)
• 不自動執行 substantive 動議(必 sign-off)

與其他 skill 分工

Skill	Trigger	Scope
/ensure-canonical	「確保 X 一定要」trigger phrase	規劃 N-layer enforcement
/propose-options	列 options 給 user 前	4-Q gate per option
/design-system-audit	已 codified rule batch verify	audit 既有元件
/knowledge-prune	governance bloat	8-home retire
/scan-similar-bugs	修 bug 後	M10 exhaustive scan
/story-writing	寫 / 編 stories	rule-mapping workflow

References

• CLAUDE.md M14(對話結論 → integrate pipeline)
• CLAUDE.md M19(本 skill SSOT 上游)
• CLAUDE.md # 治理 canonical(8 home)
• Story splitting principle(2026-04-26 本 skill template 案例,4-layer 落地)

世界級對照(template 細節)

Org	4-layer pattern
Spotify Backstage	Catalog rules + tech docs + hooks + integration tests
Polaris	Spec.md + storybook tests + lint rules + contribution gate
Material 3	Rule docs + linter + test suite + design token
Carbon	Storybook + a11y test + style lint + contribution check

我們的 5-layer 對齊 + 加 audit dim(periodic verify drift)。