governance-health

name	governance-health
description	Monthly metric-driven governance health scan. Reads .claude/logs/{hook-fires,hook-fires-per-hook,skill-invokes,user-corrections}.jsonl → detects dead hooks(6mo 0 fire)/ hot files / Meta-Pattern candidates / stale memories / pending corrections. Auto-proposes retire + rule upgrades. Complement to /knowledge-prune(quarterly deep restructure).

Governance Health — 持續 metric 監控 + auto-propose

目的:從 aspirational「會有大腦」升級到 operational 自我優化。/knowledge-prune 是季度深度重構;本 skill 是月度 metric scan + 自動提議 rule 升級 / retire 候選。

When to run

• 月度 check(預設 cadence)
• CLAUDE.md 行數突增(> 100 行/month)→ trigger
• .claude/logs/hook-fires.jsonl > 5MB → trigger
• audit Phase F 報告 sprawl 時 auto-chain
• user 說「governance 健康嗎」/「有沒有 rule 該 retire」/「哪條 rule 該升級」

Non-goals

• 不改 canonical substantive(只提議,STOP 等 user sign-off)
• 不做深度 prune(那是 /knowledge-prune)
• 不 retire 有 active consumer 的規則(只列候選,不執行)

---

5-Phase Workflow

Phase 0 — Log freshness check

ls -la .claude/logs/*.jsonl

若任一 log > 1MB → 確認已 rotate(*.jsonl.YYYYMM 檔存在)。無 log → Phase 0 回報「instrumentation 未積累資料,需 1-2 個月 baseline」,退出。

Phase 1 — Metric harvest(parallel)

Metric	Source	判斷
Hook fire count(per hook,6 月窗)	hook-fires-per-hook.jsonl(+ .jsonl.YYYYMM rotation 檔)或 npm run audit:hook-quality(產 hook-quality-report.json 含 fire_count_6mo/dead 分類);hook-fires.jsonl 記的是 governance-file 編輯軌跡(hot files 分析用),無 hook 名欄	0 fire = retire 候選;>50 fire = hot rule
Skill invoke count(per skill,3 月窗)	skill-invokes.jsonl(若存在)	0 = dead;< 3 = under-used
User correction signals(per session)	user-corrections.jsonl count + sample	總累積 > 20 = 需 codify
File size trend(weekly snapshot)	metric-snapshots.jsonl(若存在)	CLAUDE.md 增速 > 5 line/week = sprawl alert
Benchmark freshness(external)	.claude/benchmarks/last-fetch.txt	> 30 天 = 過期
Infra-ref integrity(2026-05-30 加,根因防線)	node scripts/check-dangling-infra-ref.mjs + node scripts/check-skill-deadref.mjs(fail-open report)	bucket-B > 0(死 hook ref)OR removed-section/line-number ref > 0 = infra-self drift → 提議 repoint。錨例:2026-05-30 抓 40 處死 hook ref + env-smoke set-e bug
判準化佔比 trend(2026-07-07 加,治理進化方向 1 KPI)	node scripts/audit-coverage-matrix.mjs(PURE-JUDGMENT / HOOK / DETERMINISTIC 三級計數)	PURE-JUDGMENT 佔比應逐月持平或降;連 2 月上升 = deep-audit C.0b 判準化 harvest 沒在跑 → flag。SSOT → .claude/planning/2026-07-07-governance-evolution-roadmap.md

Phase 2 — Analysis(fire-driven auto-propose)

三類 auto-propose:

2a. Hot rule → Meta-Pattern upgrade candidate

規則 fire > 50 次 / 6 月 = 該 rule 反覆觸發 = 問題普遍 = 值得上升 Meta-Pattern layer 收斂(對齊 mindset #6「大原則吸收瑣碎」)。

Output: 「check_item_list_gap.sh 6 月 fired 78 次 → 提議擴充到 CLAUDE.md Meta-Pattern M18?」

2b. Dead rule → retire 候選

Hook 0 fire / 6 月 OR skill 0 invoke / 3 月 = 無 consumer = retire 候選。

Output: 「check_sideoffset_canonical.sh(retired;已移入 hooks/retired/,此為 dead-rule 偵測示例)6 月 0 fire → retire 候選(先 grep 全 repo 確認無 reference 才執行)」

2c. Pending corrections → codify 候選

user-corrections.jsonl > 10 條未 codify = user 反覆糾正類似錯誤,該升級到 canonical。

Output: 「過去 4 週 user 糾正 15 條,sample: ..., 提議:升級 M19「XX pattern」或擴充 # Meta-Pattern 預警」

Phase 3 — Health report(produce report to user)

# Governance Health Report — {YYYY-MM-DD}

## Metrics
| | 本月 | 前月 | Trend |
|--|------|------|-------|
| CLAUDE.md 行數 | N | M | ↑/↓/→ |
| Hook fire total | N | M | ↑/↓/→ |
| Skill invoke total | N | M | ↑/↓/→ |
| Pending corrections | N | — | — |
| Benchmark freshness | X days | — | — |

## Retire 候選(auto-propose,需 user sign-off)
- {hook/skill name} — 0 fire / N mo — rationale
- ...

## Meta-Pattern upgrade 候選(auto-propose)
- {rule name} — {fire count}/6mo — propose: 升級 M{N} 「...」
- ...

## Codify 候選(pending corrections)
- {topic} — {count} user corrections — propose: 擴充 CLAUDE.md {section}
- ...

## 外部 benchmark
- Last fetch: {date} ({days} days ago)
- 若過期 → 提議 run `.claude/benchmarks/fetch.sh`

Phase 4 — Checkpoint 1(MUST ASK)— user sign-off

report 給 user 後 STOP:

• P0 retire(confirmed dead + 無 reference):AUTO OK 可執行
• P1 Meta-Pattern upgrade / codify:STOP,需 user sign-off(動 canonical)
• P2 外部 benchmark 過期:AUTO run fetcher

Phase 5 — Self-improvement capture + snapshot

報告尾加:

## Self-improvement capture
- 新發現 governance pattern: {...} OR "無"
- 新確立 monitoring rule: {...} OR "無"
- 修完的矛盾 / user 糾正: {list}

Snapshot 本次 metric 到 .claude/logs/metric-snapshots.jsonl append:

{"ts":"2026-04-24","claude_md_lines":686,"hook_fires_total":N,"skill_invokes_total":M}

下次 Phase 1 對比 trend。

---

與 /knowledge-prune 分工

Skill	Cadence	Focus	Scope
/governance-health	月度 / auto-triggered	Metric-driven 自動提議(retire / upgrade / codify)	全 governance files(CLAUDE.md / skills / hooks / memory / logs)
/knowledge-prune	季度 / release cut	深度結構重構(duplicate / dead / contradiction / over-concrete abstraction)	同上

Chain 關係:/knowledge-prune --deep 可 auto-chain /governance-health 產 metric baseline,但 health 不自動 chain prune。

Non-goals 重申

• 不改 canonical substantive meaning
• 不刪 memory 檔(只提議)
• 不動元件 / spec
• 不處理 git log / commits

References

• .claude/logs/ — metric source
• .claude/benchmarks/ — external signal
• CLAUDE.md # 治理 canonical — governance rules (本 skill 執行)