| name | knowledge-prune |
| description | Prune governance sprawl across CLAUDE.md / specs / skills / hooks / memory / settings. Finds duplicate rules (Rule-of-3), dead hooks (6mo 0 fire via `.claude/logs/hook-fires-per-hook.jsonl`), stale memories, over-concrete bug case studies that should abstract to meta, and contradictions across homes. Enforces per-file budget (CLAUDE.md target ≤ 200 / transition ≤ 400, spec ≤ 300, SKILL ≤ 250, memory ≤ 100) and retire rate ≥ 5% / quarter. Invoke via /knowledge-prune quarterly or when CLAUDE.md > 800 / MEMORY.md > 20 entries / audit Phase F reports sprawl. Auto-chained by /design-system-audit --deep Phase 4.5. |
Knowledge Prune — 治理反膨脹 skill
目的:本 DS governance 自身是活的知識庫,若只 append 會讓 CLAUDE.md 載入成本失控、MEMORY.md 條目爆炸、hook 變殭屍、spec.md 重複。本 skill 掃 8 個 home 找冗贅,提議 retire 候選,加嚴執行 Rule-of-3 SSOT + 行數預算。
🔒 核心前提(每次必遵,不需 user 提醒 — mindset #6「tell me once」):prune 唯一目的是移除噪音以銳化 signal、提升遵循正確率,絕不以犧牲品質換行數 / 條目下降。每次跑同時必滿足:(a) 品質不可因 prune 打折;(b) 以提升品質(清晰度↑ / drift 風險↓ / recall 精度↑)為目標。故:① 只 retire 真冗餘 / stale / 已被上游完整吸收的條目(這類本身是噪音,清掉反提升正確率);② consolidate 重複(同概念多 home → 選 SSOT + pointer);③ 每條真實 invariant / 機械防線必完整保留 — retire 前必 grep 確認保護已被別處覆蓋,否則不動;④ distinct 條目強合成大條目會降 recall 精度 = 反 pattern,不做。retire rate 是結果指標非目標:湊 % 傷品質 = 違本前提;寧可 retire rate < 5% + report 明寫「成熟無冗餘」rationale,也不強刪真保護。本前提 override 下方所有 Phase / Checkpoint 的數值 target。
對齊 CLAUDE.md # 治理 canonical:本 skill 是 L3(Periodic deep)實作。L1(pre-write hook)+ L2(fire log)自動執行,L3 需人決策 canonical retire,走 checkpoint。
對齊 CLAUDE.md # 稽核 canonical「Audit-vs-execute 分權」:動 canonical substantive meaning → STOP 提議;對齊 / 清 duplicate / 回填 pointer → AUTO。
When to run
- CLAUDE.md 超過 800 行(hook 硬 cap 觸發)
- MEMORY.md 超過 20 條 index
- 季度健檢(每 3 個月跑 1 次)
/design-system-audit --deep Phase 4.5 自動 chain- 單一 spec.md 超過 500 行(hook 硬 cap 觸發)
Non-goals
- 不動 code(
.tsx / .css / .ts)— 只動 governance 文件
- 不 retire 被 hook / skill 仍引用的 rule(先改 consumer,再 retire)
- 不刪歷史 commit / git log
- 不 rewrite spec.md 內容(只刪 duplicate / 提議合併,實質改寫走
/design-system-audit)
Workflow(5 phases)
Phase 0 — Baseline scan(AUTO)
掃 8 個 home 建立基準表:
Home Size Over-budget?
─────────────────────────────────────────────
CLAUDE.md N lines [target ≤ 200 / transition ≤ 400 / hard cap 800]
MEMORY.md N entries [≤20]
spec.md total N files per-file ≤300
SKILL.md total N files per-file ≤250
hooks N scripts (count only, Phase 3 看 fire log)
memory files N per-file ≤100
.claude/logs/ parse existing (feed Phase 3)
Output:phase0-baseline.md(session-local,不 commit)
Phase 0.5 — 讀 external signal(AUTO)
讀 .claude/logs/ + .claude/benchmarks/(Commit 5 後):
hook-fires.jsonl — governance-file edits(tool/path per event);用於 hot governance files 分析hook-fires-per-hook.jsonl — per-hook fire count(2026-04-25 起);via shared helper .claude/hooks/_log-fire.sh;啟用 D2 dead-hook detectionskill-invokes.jsonl(若存在)— 過去 3 月每 skill invoke 次數user-corrections.jsonl(若存在)— pending codification 清單benchmarks/claude-code-features.jsonl — 新 CC feature 採用提議benchmarks/external-ds-snapshots/*.md — Polaris / Material / Atlassian 近期更動
Output:外部 signal 摘要(送 Phase 3 judging)
Phase 1 — 4 維 scan(並行 sub-agent)
4 個 sub-agent 並行跑,每個產 finding 清單:
D1 — Duplicate across homes(Rule-of-3)
Scan:同概念(同 keyword / 同 canonical)出現在 ≥ 3 個不同 home 寫完整 rule?
Example violations(historic — 2026-05-22 prune verify 後均已收斂為 pointer 模式,僅留作教學範例):
Portal 逃脫 theme:過去在 hover-card.spec.md / avatar.spec.md / color.spec.md 各重述;現只 M3 SSOT + 各 spec pointer。2026-05-22 audit verify 為已對齊(僅 ui-development.md / meta-patterns.md 2 home 涉及,clean pointer)Inline Action vs Button predicate:過去 CLAUDE.md / item-anatomy.spec.md / button.spec.md 各完整;現 inline-action.spec.md 為 SSOT,其他 cross-link- 新範例(2026-05-22 抓):hook count threshold 在 CLAUDE.md
# 治理 canonical 行數預算表 / meta-patterns M14 / M20 / session_start_governance_check.sh 4 處 drift 3 值(40/35/30)→ M14/M20 strip 數字改 pointer SSOT 修
Output:duplicate cluster 清單 + 建議 SSOT home。
D2 — Dead & stale(fire / edit recency)
- Dead hooks:跑
npm run audit:hook-quality(= scripts/audit-hook-quality.mjs,讀 .claude/logs/hook-fires-per-hook.jsonl 自動產 per-hook signal-to-noise report → .claude/logs/hook-quality-report.json:fire_count_6mo / fire_per_day / hot-warm-cool-dead 分類 / file_exists orphan signal / retire_candidate flag)。6 月 0 fire 的 hook 名 → retire 提名(report 已標 dead)
- Stale memories:
ls -la ~/.claude/.../memory/*.md,6 月無 git log 變動且不在 MEMORY.md index head = stale
- Unused skills:
skill-invokes.jsonl 3 月 0 invoke(除非是 rare-event skill,例 delivery-handoff)
Output:retire 候選 + rationale(fire=0 / last_edit=2025-10 / 被 M14 吸收)
D3 — Over-concrete case studies
Scan:Meta-Pattern / spec / memory 條目是「單次 bug 敘述」而非「meta 抽象」?
Example:
- M-row 是「2026-04-22 Dialog autoFocus tooltip 洩漏 / body 未用 ScrollArea / ... 7 題炸」這種純敘述 → 是否該抽成「凡 overlay + subtree context,必 self-scan N 題」的 meta rule?
- feedback memory 條目:「2026-04-21 User 抓到 applicable-where-meaningful」→ 是否已被 M10 / M14 吸收?
Output:候選 abstract proposal + 被吸收後可刪的下游條目
D4 — Cross-home contradiction
Scan:CLAUDE.md canonical vs spec.md vs skill reference 描述同概念時語義衝突(非表達差異)?
Example:
- CLAUDE.md M3 說「Portal 必繼承 data-theme」;但 avatar.spec.md 說「Portal 必繼承 data-theme + data-density」— 差
data-density,看誰真 SSOT
- CLAUDE.md
# 稽核 canonical 列 D4 UX 同時也談 3-tier scope — 2026-04-24 已合併為一章(原本 2 章重疊)
Output:matrix of 衝突點 + 誰該讓步
D5-D10 — 2026-05-17 加維度(各維 scan + Example + Output 詳 references/prune-dimensions-d5-d10.md)
D5 Canonical drift(spec vs code)/ D6 Hook-fire health / D7 Skill-invoke health / D8 Memory recency-orphan / D9 Benchmark-citation debt(M22)/ D10 Verification artifact rot(M32)。
Phase 2 — Triage + Checkpoint 1(MUST ASK)
Phase 1 findings(D1-D10):
- D1 duplicate: M clusters
- D2 dead/stale: N items
- D3 over-concrete: K items (abstract proposals)
- D4 contradiction: L pairs
- D5-D10(2026-05-17 加,detail 詳 references/prune-dimensions-d5-d10.md): D5 canonical drift / D6 hook-fire health / D7 skill-invoke health / D8 memory recency-orphan / D9 benchmark-citation debt / D10 verification artifact rot — 各 N items
Priority:
- P0 (AUTO): 對齊 SSOT / 補 pointer / 刪 confirmed dead hook / retire unused skill — 表達層調整,不動 canonical 意思
- P1 (AUTO with brief report): 合併 duplicate(保 semantic)/ 刪 6+ 月 stale memory(非 critical)/ 編號 renumber
- P2 (STOP / CHECKPOINT): 抽新 meta / 合併 contradiction 要選哪邊 / 撤 Meta-Pattern / 改 SSOT ownership
Proceed with P0+P1 as atomic commit? Then discuss P2?
Do NOT skip:P2 動 canonical substantive,per # 稽核 vs 執行 分權,必 user sign-off。
Phase 3 — Apply P0 + P1 fixes(分組 commit)
- 每個 cluster 一個 commit(
prune: duplicate X → SSOT owner Y / pointers elsewhere)
- 每次 commit 後
npx tsc -b 驗證(prune 不動 code,但防 spec path 斷)
- 每 commit 後重跑 Phase 0 baseline,確認 size 有下降
Phase 4 — P2 discussion + apply(user sign-off 後)
- 每 P2 item 一個獨立 commit(animation trail 可回溯)
- 新 meta-pattern 加進 CLAUDE.md
# Meta-Pattern 預警 → 同時必檢討哪些下游條目冗餘(上游加 = 下游減)
Phase Z reference — Cross-repo SSOT propagation
詳 references/phase-z-cross-repo-ssot-propagation.md(2026-05-26 retract skill-specific Phase Z;sync trigger = push main 後 SSOT-affecting diff,canonical 在 CLAUDE.md # Git solo-work canonical Step 5.5 + hook check_post_main_ssot_propagate.sh)。
Phase 5 — Final report + quantified retire rate + baseline update
Retire rate 計算公式(從 aspirational 轉 quantified,2026-04-24):
total_governance_items_before =
count(CLAUDE.md 章節)
+ count(Meta-Pattern 條目)
+ count(.claude/skills/)
+ count(.claude/hooks/)
+ count(MEMORY.md entries)
+ count(memory files)
+ count(spec.md SSOT anchors)
retired_this_quarter = items 本次 /knowledge-prune 刪 / 合併 / 撤
retire_rate = retired_this_quarter / total_governance_items_before
Target:≥ 5% / quarter。< 5% 不一定壞(系統已成熟 / 無冗贅),但必在 report 明寫 rationale(「成熟 — 無 retire 候選 / stable ecosystem」),不可空白。
## Prune report(N 日期)
### Metric delta
- CLAUDE.md: B → A(-X 行)
- MEMORY.md: B → A(-Y 條目 / -Z 檔)
- Total spec.md: B → A(-Z 行)
- Hooks: B → A(-N 個 hook retired)
- Skills: B → A(-N 個 skill retired)
- **Retire rate: X% = retired N / total M**(target ≥ 5%)
- 公式套用見本 Phase 頂部
- 若 < 5% 必附 rationale(成熟 / 無冗贅 / deferred 等)
### Retired(實際)
- {list of retired items + why + grep 確認無 reference}
### 未達 retire target rationale(若 < 5%)
- {e.g. "governance ecosystem stable, 上季已大幅 prune,本季無重大冗贅"}
### Still deferred(P2 pending user sign-off)
- {list}
## Self-improvement capture
- 新發現 prune pattern: {...} OR "無"
- 新確立 anti-bloat rule: {...} OR "無"
- 下次 prune trigger 建議: {...}
Update .claude/logs/metric-snapshots.jsonl:
{"ts":"2026-04-24","retire_rate":0.07,"retired":5,"total_before":71,"claude_md_lines":612,"hooks_total":18,"skills_total":13,"memory_entries":29}
**本 snapshot 讓 /governance-health trend 分析:**若 3 季連續 retire rate < 5% 且 governance 行數仍增 → auto-propose「有隱性冗贅未抓,考慮換 /knowledge-prune 掃描策略」。
Checkpoints(禁止跳)
⚠️ Checkpoint 1 — Phase 2 triage(見上)
⚠️ Checkpoint 2 — 動 Meta-Pattern(P2)
提議撤 / 合併 / 改寫 Meta-Pattern 條目前 STOP。Meta-Pattern 是 CLAUDE.md 最上游,動意思必 user 拍板。
⚠️ Checkpoint 3 — 抽新 canonical
Phase 1 D3 發現 5+ 條下游條目可被新 meta 吸收 → 提議新 Meta-Pattern 前走命名三 test + world-class benchmark(對齊 CLAUDE.md M8 / M12)。
⚠️ Checkpoint 4 — Retire 率 < 5%
季度 prune 若 retire 不到 5%,表示:(a) 真沒冗餘(罕見),OR (b) judgment 太保守。STOP 跟 user 確認哪邊。
Retire rules(執行規則)
| 項目 | Retire criteria |
|---|
| Hook | 6 月 hook-fires-per-hook.jsonl 0 fire + 無 future-planned consumer |
| Skill | 3 月 0 invoke + 非 rare-event skill(release-cut 類可例外) |
| Meta-Pattern 條目 | 被新上游 meta 完全吸收 + grep 無引用 |
| Memory file | 6 月未更新 + 現況已不符 + MEMORY.md 無 head pointer |
| Spec 段落 | 被 SSOT pointer 取代 + grep 無外部引用 |
Hard rule:retire 前必 grep 全 repo 無 reference,避免斷鏈。
世界級對照
詳 references/world-class-prune-alignment.md(Elasticsearch ILM / Linux kernel doc policy / Python PEP 387)。
與其他 skill 的分工
| Skill | Scope | 不重疊點 |
|---|
/design-system-audit | full-dim DS code + spec audit(Phase 0 自建 baseline) | 不管治理文件冗贅 — 找 bug / drift,不 prune governance 大小 |
/knowledge-prune | 治理文件冗贅 + 行數 + 矛盾 | 不 audit DS code 本體 — 管 governance 不管 DS |
