memory-lint

Files (2)

• SKILL.md
• scan.py · scripts/

SKILL.md (first lines)

# memory-lint — Memory 品質健檢

```
Phase 1  唯讀掃描 ──► 報告（預設只做這段，不動任何檔案）
                        │  user 逐條拍板要修哪些
Phase 2  執行修正 ──► commit（開工前先記回退點）
                        │  改完全部提交 = 凍結
Phase 3  獨立複驗 ──► 過 → 收工　／　不過 → 回退到 Phase 2 前
```

🔴 **收到 lint 觸發詞的預設動作是出報告。** user 必須明確點名要修哪幾條
（或明說「全部修掉」）才准進 Phase 2。Phase 1 期間不准順手合併、順手刪、順手歸檔。

**跟 llm-wiki-lint 差異**：本 skill 針對 memory 目錄（prefix-based 平鋪結構）；
`llm-wiki-lint` 針對 Karpathy LLM Wiki repo（`wiki/` + `raw/` + `SCHEMA.md` 三層）。

---

# Phase 1 — 唯讀掃描

## Step 1: 找到 memory 目錄

依序嘗試，命中第一個就用：

| 順序 | 來源 |
|------|------|
| 1 | `$ARGUMENTS` 第一個位置參數 |
| 2 | 環境變數 `$CLAUDE_MEMORY_DIR` |
| 3 | `settings.json` 的 `autoMemoryDirectory` |
| 4 | `~/.claude/memory/` |
| 5 | 都找不到 → **停止**，告訴 user「偵測不到 memory 目錄」，不要瞎猜 |

第 3 條要看**當前設定目錄**（多帳號並存時 `$CLAUDE_CONFIG_DIR` 會指到別處）：

```bash
CFG="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
MEMORY_PATH=$(jq -r '.autoMemoryDirectory // empty' "$CFG/settings.json" | envsubst)
```

## Step 2: 跑機械掃描

```bash
# <skill_dir> = 本 SKILL.md 所在的目錄；掃描標的由參數帶入，
# 所以在哪個工作目錄呼叫都不影響結果
python3 <skill_dir>/scripts/scan.py "$MEMORY_PATH"
```

只用標準函式庫、唯讀、輸出 JSON。**目標目錄由參數帶入**，所以在哪個工作目錄呼叫都一樣。
沒有 `MEMORY.md` 會回 `{"fatal": ...}` 並以 exit 1 結束。

腳本已經處理掉幾個會讓檢查靜默失效的坑，**不要自己在對話裡改寫成 shell 一行流**：

- 不用 shell glob（zsh 未匹配 glob 會在指令執行前中止，而且 `2>/dev/null` 擋不住）
- 不用固定路徑暫存檔（並行執行會互相覆蓋、失敗留髒資料）
- 不 import 第三方套件（唯讀階段不該動 user 的 Python 環境；離線環境也裝不了）
- `[[...]]` 掃描先剝掉 fenced 與行內 code，且**檔名與 frontmatter `name` 兩種都算解析成功**
- 索引目標的 `./` 前綴會正規化

輸出欄位：

| 欄位 | 意義 |
|---|---|
| `layout` | 單層（只有 `MEMORY.md`）／兩層（`MEMORY.md` 只留路由、細目在 `index_*.md`） |
| `index_declared_missing` | `MEMORY.md` 指到但磁碟上沒有的子索引 |
| `index_orphaned` | 磁碟上有、但沒人指向的孤立子索引 |
| `orphan` / `missing` | 有檔沒被索引／索引指向不存在的檔 |
| `frontmatter` | 缺 `name`／`description`（只認頂層）或 `type`（頂層或 `metadata.type`）|
| `wiki_broken` / `wiki_external` | `[[...]]` 解析不到的／指向子目錄或外部的 |
| `oversize` | 超過 300 行的檔（行數語意同 `wc -l`）|
| `prefixes` / `no_prefix` | 命名前綴分布與例外 |

🔴 **兩層結構下若只拿 `MEMORY.md` 當索引來源，會把整庫誤判成 orphan。** 腳本已處理，
但若你另外手寫檢查，這是最容易踩的一個。

## Step 3: 判讀（這段才是本 skill 的價值）

腳本只給事實，**嚴重度與去留由你判斷**。判斷前先讀 `MEMORY.md` 與相關索引的說明文字，
很多「異常」其實是既定決策。

| 嚴重度 | 收什麼 |
|--------|--------|
| 🔴 Error | 結構壞了：`index_declared_missing`、`orphan`、`missing`、`frontmatter` 缺漏、真正的斷鏈、兩條規則直接互打 |
| 🟡 Warning | 沒壞但該看：`index_orphaned`、過期 dashboard、`oversize`、命名例外、疑似結束未歸檔 |
| 🔵 Info | 啟發式：語意相近可能重複、description 與索引描述不符、同一計數寫在多處 |

不確定就降一級。**推測與語意相似一律不得標 Error。**

### 這些不是缺陷，別報

- **`wiki_external` 多半是刻意的** —— 指向 `archive/` 的歸檔檔案，或指向另一台機器上的
  外部知識庫。報之前先看那個目標像不像檔案路徑，並問 user 一次就好，不要每次重報。
  ⚠️ **`wiki_broken` 裡也可能混著刻意的外部連結。** 腳本靠「目標裡有沒有路徑分隔符」分類，
  所以像 `[[某個外部條目]]` 這種沒有路徑特徵的外部參照會落到 `wiki_broken`。
  **這無法自動判斷**，一律當成「需要人確認」，確認過就記進已接受例外清單，別每輪重報。
- **超過 300 行有時是刻意的** —— 若某份 canonical 規則檔明文要求「使用前必須完整讀完」，
  拆開就破壞用途。標成「刻意例外」並寫明理由。
- **語意相近的一組規則可能是刻意不合併的** —— 為了精準 recall 而把同一原則拆成多個觸發點
  是常見設計，索引裡通常有明文宣告。看到就標明是既定決策，**不要建議合併**。
- **子目錄不在掃描範圍** —— 腳本只掃根層。`archive/` 是歸檔；其他子目錄可能是某則 memory
  的附屬資料（例如一份 memory 指向 `ref/` 底下的參考檔）。**它們沒被索引是正常的。**
  自己補查時記得也要限制在根層，別寫成遞迴：

  ```bash
  find "$MEMORY_PATH" -maxdepth 1 -name '*.md' -type f     # ✅
  rg --files -g '*.md' "$MEMORY_PATH"                       # ❌ 會遞迴讀到 archive/ 與其他子目錄
  ```

### 這些要另外用眼睛看（腳本測不出來）

- **過時狀態**：`project_*` 超過 30 天沒動、dashboard 超過 7 天沒更新、內文寫「進行中」
  但檔案很久沒改。🔴 **先確認時間來源可不可信**：檔案的 mtime 一經複製、還原、
  重新 clone 就會全部變成當下時間。是 git repo 就改用 `git -C "$MEMORY_PATH" log -1 --format=%ad -- <file>`；
  不是 git 又剛搬過家，就**明講這項檢查在本次環境不可靠**，不要拿一批假的日期去下判斷。⚠️ **這是低訊號檢查** —— 黑名單、已完工的側專案、機器後路天生就不會動。
  而且「進行中」命中的可能只是待辦清單裡一個帶日期的項目，不是整個專案的狀態。
  **報告要引出命中的那一行原文**，讓 user 看得出是哪一種。
- **規則直接衝突**：🔴 **不要對全部檔案兩兩比對。** 規則檔一多（例如 80 份以上），
  輸出會直接撐爆而被截斷 —— 那時你既審不完、也不知道漏了什麼，卻很容易誤以為審過了。
  **改成兩段**：先用 description 的字元 bigram 做 Jaccard 粗篩（門檻約 0.16）取出候選配對，
  **只對候選配對讀原文**；一輪最多看 10 對，超過就明講「本輪只看了前 N 對、其餘未檢查」。

From KerberosClaw/kc_ai_skills, MIT.

More from KerberosClaw/kc_ai_skills