llm-wiki-lint

Files (1)

• SKILL.md

SKILL.md (first lines)

# llm-wiki-lint — Karpathy LLM Wiki 三層健檢

You are a documentation auditor for repos following the [Karpathy LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). Scan the three layers (`raw/` + `wiki/` + `SCHEMA.md` / `index.md` / `log.md`), surface drift and gaps, report — then fix **only with explicit user approval**.

**CRITICAL — 兩段式契約**：
- **Phase 1（report）純 read-only**。掃描期間任何「順手補一下 frontmatter」「順手更新 index」都是違規。
- **Phase 2（fix）必須等 user 對報告明確點頭**（「修」「fix」「都修掉」）才啟動。User 只說「跑 lint」= 只做 Phase 1。

**跟 memory-lint 差異**：
- `memory-lint` → Claude memory 目錄（feedback / user profile / project，prefix-based）
- `llm-wiki-lint` → LLM Wiki repo（wiki/ 主題頁 + frontmatter + raw source traceability + index 一致性）

---

## Step 1: Detect wiki repo path

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

| 順序 | 來源 | 條件 |
|------|------|------|
| 1 | `$ARGUMENTS` 第一個位置參數 | 使用者明確傳入，最優先 |
| 2 | 環境變數 `$WIKI_REPO_DIR` | export 過 |
| 3 | 當前工作目錄 `$PWD` | 含 `SCHEMA.md` + `wiki/` 子目錄 |
| 4 | — | 都找不到 → 停止，告訴 user「偵測不到 wiki repo」，**不要瞎猜** |

決定路徑後，先驗證結構：

```bash
ls "$WIKI_PATH/SCHEMA.md" "$WIKI_PATH/wiki/" 2>/dev/null
ls "$WIKI_PATH/index.md" 2>/dev/null || echo "WARN: index.md 不存在"
ls "$WIKI_PATH/log.md" 2>/dev/null   || echo "WARN: log.md 不存在"
```

- `SCHEMA.md` 或 `wiki/` 任一缺 → **fatal**，停止 lint
- `index.md` / `log.md` 缺 → warning，繼續 lint 並在報告建議新建

### Step 1b: 載入 repo 自有規約（lint 的 source of truth）

**不要硬編碼 Karpathy 預設值 — 以目標 repo 自己的宣告為準**：

| 規約 | 來源 | fallback |
|------|------|----------|
| type allow-list | `SCHEMA.md` §Type 分類（含本地擴充） | Karpathy 5 類（overview/entity/concept/comparison/synthesis）+ 報告註明 SCHEMA 未宣告 |
| frontmatter 必備欄位 | `SCHEMA.md` §Frontmatter 欄位 | title / type / last_updated / sources |
| lint 後是否 append log.md | `SCHEMA.md` §Lint 節奏 | 不 append |
| 額外文件風格規則（如「body 禁 date marker」） | repo 的 `CLAUDE.md` / `docs/` 規則檔（如有） | 跳過此項檢查 |

---

## Step 2: Scan & lint（Phase 1 — read-only）

### Step 2a: 掃描範圍

```bash
find "$WIKI_PATH/wiki" -maxdepth 1 -name '*.md' -type f
find "$WIKI_PATH/wiki" -mindepth 1 -maxdepth 1 -type d   # 子目錄偵測 — 上面那條只看 .md，抓不到目錄
```

**包含**：
- `<path>/wiki/*.md` — 所有主題頁（第二條指令找到子目錄時列出並在報告標註，等 user 決定是否納入）
- `<path>/SCHEMA.md` / `index.md` / `log.md` — schema 層
- `<path>/raw/**` — 存在性檢查（gitignored，本地才看得到）

**跳過**：`<path>/journal/`、`<path>/drafts/`、`<path>/scripts/`（非 wiki 一部分）

**工具紀律**：解析 frontmatter / 比對清單一律用 `python3` stdlib（`re` + `glob`），**不要依賴 `yq` / `jq`**（目標機器不保證裝了）。

### Step 2b: Severity decision

| 嚴重度 | 含義 | 範例 |
|--------|------|------|
| 🔴 Error | 結構壞了或宣告與實況矛盾 | 缺必備 frontmatter 欄位、index 列出檔案不存在、body 連結指向已刪頁、SCHEMA.md 數字錯 |
| 🟡 Warning | 沒壞但有腐臭味，user 應該 review | last_updated 漂移、orphan page、stale claim、index 摘要與頁面內容矛盾 |
| 🔵 Info | 啟發式提示，可選處理 | 缺 cross-ref、可能的 missing topic |

不確定時就降一級（warning → info）。**禁止把推測寫成 error**。

### Step 2c: Frontmatter 完整性

每個 `wiki/*.md` 開頭應有 YAML frontmatter，必備欄位以 Step 1b 載入的清單為準：

| 欄位 | 規則 | 缺失等級 |
|------|------|----------|
| `title` | 主題名（string） | 🔴 Error |
| `type` | **在 Step 1b 載入的 allow-list 內** | 🔴 Error（缺欄位 / 不在 allow-list） |
| `last_updated` | YYYY-MM-DD | 🔴 Error（缺）/ 🟡 Warning（格式錯） |
| `sources` | list，指向 `raw/` 或外部來源 | 🔴 Error（缺欄位）/ 🟡 Warning（空 list — 見 Step 2i） |

```bash
python3 - <<'EOF'
import re, glob
for f in sorted(glob.glob("wiki/*.md")):
    s = open(f, encoding="utf-8-sig").read()   # utf-8-sig 吃掉 BOM；\r?\n 容忍 CRLF（Windows 編輯過的檔）
    m = re.match(r"^---\r?\n(.*?)\r?\n---\r?\n", s, re.S)
    if not m: print(f"NO-FRONTMATTER {f}"); continue
    fm = m.group(1)
    for field in ("title", "type", "last_updated", "sources"):
        if not re.search(rf"^{field}:", fm, re.M): print(f"MISSING {field} {f}")
EOF
```

### Step 2d: Index 一致性

| 情況 | 等級 |
|------|------|
| `index.md` 列出但 `wiki/` 下檔案不存在 | 🔴 Error（missing file） |
| `wiki/` 下檔案存在但 `index.md` 沒列 | 🔴 Error（orphan file） |
| `index.md` 的 `last_updated` / `type` 跟檔案 frontmatter 不一致 | 🟡 Warning（drift） |
| `index.md` 標頭宣稱頁數 ≠ 實際頁數 | 🔴 Error |

### Step 2e: Index 摘要 vs 頁面內容矛盾

index 每列通常帶「一句話」摘要。**逐列對照該頁當前核心結論** — 摘要還在講已被頁面推翻的舊事實（例：摘要說「服務 X 運行中、不能停」，頁面已改寫成「服務 X 已停用」）→ 🟡 Warning。這是日期 drift 抓不到的：日期可能同步了、摘要忘了改。

### Step 2f: Body 連結完整性（in-body link integrity）

掃每頁 body 的兩種站內連結，目標不存在 → 🔴 Error：

- markdown link：`[...](some_page.md)` → `wiki/some_page.md` 必須存在（含連字號 / 大寫 / `./` 前綴 / `#anchor` 變體）

From KerberosClaw/kc_ai_skills, MIT.

More from KerberosClaw/kc_ai_skills