weekly-audit

name

weekly-audit

description

每週一次的專案健康度巡檢，產出 docs/audit/weekly/YYYY-Www.md 報告。當用戶說「週巡檢」「每週檢查」「weekly audit」「幫專案做大整理」「這週新增的圖層有沒有資料」「Supabase 長多大了」「S3/R2 花多少錢」「有沒有圖層掛掉」「文件是不是過時了」「README 數字對不對」「專案結構有沒有跑掉」時觸發。查的是「上線之後過了一段時間，東西還健康嗎」——資料活性、儲存成本、效能退化、文件時效、repo hygiene、跨 repo 契約六組。**唯讀巡檢 + 產報告；只有白名單四類整潔問題會自動修**（各自獨立 commit，可單獨 revert）。不做單一 layer 的上線驗收（→ layer-onboarding）、不做 session 收尾（→ wrap-up）、不 deploy、不 push、不寫 DB。主動更新時機：新增檢查項、收集器誤報漏報、某項連續 3 週無變化該降頻、白名單自動修出過事時。

Weekly Audit — 每週巡檢

目的：專案每週都在長（新圖層、新資料源、新疊圖），但所有守門機制都是事件觸發的—— CI 在 PR 時跑、layer-onboarding 在接線時跑、wrap-up 在 session 結束時跑。 沒有人回答「上線三週後這東西還健康嗎」。這個 skill 就是回答這句話的。

設計依據與完整檢查項清單：docs/proposal/weekly-audit-2026-08-21/README.md

何時觸發 / 何時不要

觸發	不要觸發（該用別的）
「跑一下週巡檢」「這週的檢查」	新 layer 剛接好要驗收 → layer-onboarding
「幫專案做大整理」	session 要收尾、整理記憶 → wrap-up
「Supabase／S3 現在多大」「花多少錢」	某個 RPC 慢要優化 → /check-rpc + supabase-optimize
「有沒有圖層掛掉／沒資料」	某個 feature 的跨 repo commit 對照 → /handoff
「README／文件過時了嗎」	一次性的專題稽核 → 直接做，別套週巡檢格式

硬約束（違反即中止）

1. 正式 DB 唯讀：只能 SELECT／describe，查詢帶 LIMIT。 每個 session 開頭下 SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY; （⚠️ 連線字串的 default_transaction_read_only 對 Supabase pooler 無效，實測過）。 禁止任何寫入——包含為了「測試唯讀鎖有沒有效」而試寫。 特別是 pg_stat_statements_reset()：它會清空 C1 的差分基準且不可逆 （2026-08-21 真的被誤觸過一次，8/11~8/21 的統計因此永久遺失）。 要驗證唯讀鎖，用 SHOW transaction_read_only; 讀狀態，不要真的送 DML。
2. 執行時段無限制：這是個人 GIS 專案的 DB。最重的兩支是 probe_upstream（~70s） 與 collect_supabase（~64s，A7 亂碼掃描佔其中約 60s；不含 A7 只要 3.8s）。 想什麼時候跑就什麼時候跑。 ⚠️ A7 預設是抽樣（小表全掃、大表抽樣），能可靠抓到「系統性解碼壞掉」， 但抓不到「大表裡孤零零幾筆壞」。要窮盡檢查跑 AUDIT_MOJIBAKE_DEEP=1（實測 5 分鐘以上）。
3. 報告不得含密鑰：收集器讀 env 但永不 echo 值。產報告前掃一次， 出現疑似 secret 一律 <REDACTED>。
4. 大檔一律 HEAD 不 GET：站上有 46MB 級的 geojson。
5. 不碰平行 session 的髒檔：本 repo 長期有平行 session。dirty 檔只列不動、 不代為 commit、不 revert。
6. 收集器失敗就標 blocked，不因為沒收到資料就寫「無異常」。 _all.json 的 failed[] 必須反映到報告裡。
7. 必須在主工作樹跑，不要在 git worktree 裡跑（2026-08-21 實測）。 worktree 只有 git 追蹤的檔案——public/ 的 1125 個檔在 worktree 裡只剩 156 個 （PMTiles／大 GeoJSON 全被 gitignore 走 S3），且 ../data-collectors 等 sibling repo 的相對路徑會失效。結果是 A3／A5／D5 給出嚴重偏低的假數字、上游探測整組失效， 而且不會報錯——它會安靜地告訴你「只有 18 個 PMTiles」。 主樹被平行 session 佔用時，寧可等，不要改在 worktree 跑。

流程

Step 0 — 前置

• 確認在 repo root、.env 可讀（不讀內容，只確認存在）。
• 看一眼現在幾點：落在 10:00–20:00 就提醒用戶這會打到正式 DB。
• 讀上一份報告 docs/audit/weekly/（最新的那份）——趨勢比較的基準來自報告本身， 不是 .claude/.cache/（cache 不進版控，換機器就沒了）。

Step 1 — 收集（確定性，不動腦）

bash scripts/audit/weekly/run_all.sh

六支收集器依序跑，任一支失敗不中斷其他支，結果彙整到 .claude/.cache/weekly-audit/_all.json。

收集器	蓋到的檢查項
collect_supabase.sh	B1 儲存量／B2 retention 缺口／B3 pg_cron 健康／C1 慢查詢 snapshot／C3 孤兒 RPC／A7 文字欄位亂碼掃描
probe_upstream.sh	A1 動態表斷更／F2 next_refresh 到期／上游 repo 狀態
probe_layers.ts	A2 RPC 死鏈／A3 A4 線上資產活性／A5 孤兒資產
probe_runtime.ts	A6 圖層執行期建置（真的開瀏覽器跑正式站，比對 registry 期望的 sourceId 與實際建起來的）
probe_production.sh	C4 正式站回應／B6 CDN 快取有效性
check_docs.ts	D1 README 數字對帳（14 項：layer 數／dataClass／features 夾／主題數／主題表逐列／上游 dataset／Loader 數／collector 數／nginx location／Three.js Scene）／D2 文件齊全／D3 落後／D4 散檔／D5 狀態檔／D7 params 漂移／D8 頻率覆蓋
check_hygiene.sh	E1 未 push／E2 dirty／E3 大檔誤入 git／E4 public 用量

參數：--skip-network（離線只跑 docs／hygiene）、--only <name>（只跑一支）。

Step 2 — 對帳與趨勢

拿本週 metrics 對上週報告的趨勢表做差分。要自己算變化量，不要只報當下值。

首跑無基準時：docs/audit/weekly/ 找不到上一份報告 → 趨勢表所有「上週」欄一律標 —（無基準，本份即基準）。不得推測、不得回填、不得拿 proposal §3 的實測數字冒充上週值。

• Supabase 週增量（>3GB／週 → 🟡，異常跳升 → 🔴）
• 慢 RPC 數量變化。⚠️ pg_stat_statements 是自上次 reset 起的累計視圖， 當下均值會混入舊時代 → 用本週 snapshot 減上週 snapshot 的 calls／total_exec_time 求本週真實均值。
• 斷更表數、線上 404 數、孤兒資產總量的增減。

Step 3 — 判讀（LLM 的活）

收集器只給初判，這步要覆寫成有根據的判斷：

1. 慢查詢必附「誰在打」——pg_stat_statements 只給數字不給呼叫者。 逐一 grep -r "<rpc_name>" src/、查 cron.job.command、必要時查上游 repo。 前端在打 vs 背景 job 在打，嚴重度完全不同。 （實例：health_snapshot 均值 23 秒看似重大效能債，查完發現前端根本沒呼叫， 是 data-collectors/tasks/monitoring.py 的背景監控——從 🔴 降為 🟡。）
2. 孤兒判定要收斂口徑——「DB 有 1023 個 function」是含 extension 的毛數， 排除 extension-owned、pg_cron 呼叫的、前端用到的之後才是候選（實際約 86 個，不是 800 多）。
3. 散檔歸檔看連結不看檔名——water-resources-status.md 看起來像一次性 status， 實際是全域 MEMORY.md 指定的現行狀態檔。
4. 本週新增圖層專章：先 git log --since="7 days ago" --stat src/data/layerManifest.ts 看範圍， 要看內容用 -U0（不要用 -p，這是萬行登記簿，完整 diff 會灌爆 context）抓新 entry， 逐一過 A1~A4（有沒有資料、線上檔在不在、UX 四鐵則有沒有漏）。

Step 4 — 產報告

寫 docs/audit/weekly/YYYY-Www.md（ISO 週編號，date +%G-W%V）。結構：

# Weekly Audit YYYY-Www (YYYY-MM-DD ~ MM-DD)

## 摘要
🔴 N · 🟡 N · 🟢 N ｜ 上週：🔴 N · 🟡 N
（收集器失敗時在這裡標明哪幾項是 blocked）

## 趨勢
| 指標 | 本週 | 上週 | 變化 |

## 🔴 需拍板
- [代號] 標題 → 證據 → 建議動作

## 🟡 已列入 backlog
## 🟢 已自動處理
## 本週新增圖層驗收
## 本次巡檢的盲區
（沒跑到的、被 timeout 的、上游 repo 不在的，據實列出）

Step 5 — 自動修（白名單，逐類分開 commit）

先開分支 chore/weekly-audit-YYYY-Www（不要直接 commit 到當前分支——這個 repo 有 39 個 branch、15 個無 upstream、長期有平行 session，整潔 commit 混進別人的 feature 分支會很難拆）。 只有這四類能自動動手，每類一個 commit，方便單獨 revert：

動作	commit 前綴
補 .gitignore（大檔誤入版控）	chore(audit):
更新 README 中與 manifest 對不上的數字	docs(audit):
補 docs/features/*/ 缺的檔案骨架（照 _TEMPLATE）	docs(audit):
更新過期的狀態檔數字（如 PMTILES_STATUS.md）	memory:

不在白名單 = 列進報告等拍板：搬移／刪除文件、改程式碼、改 migration、 動 pg_cron、動 S3／R2 物件、push、deploy、git add -A。

Step 6 — 收尾

• 更新 docs/audit/weekly/README.md 的趨勢表（追加一列）。
• 🔴🟡 條目 append 到 .claude/memory/BACKLOG.md，避免報告寫完就沉底。
• 回報用戶：先講 🔴，再講變化最大的趨勢，最後才是清單。

本 skill 不做

• 不做真 render 驗收（圖層畫面是不是空白）——需要 agent-browser，v2 再加。 v1 只驗「資料源活著」，這個界線要在報告裡講清楚。
• 不做單層上線驗收、不做 session 收尾、不做 feature 開發。
• 不重跑 tsc -b / npm test——CI 每個 PR 已經在守，重跑是浪費。
• 不 deploy、不 push、不寫 DB、不動雲端物件。

已知盲區（每份報告都要誠實標示）

本 repo 內查不到「上游資料多久沒更新」。src/data/upstreamRegistry.ts 只做 layer_key ↔ catalog dataset_id 的橋接，沒有頻率／最後更新時間欄位； 頻率目前散在各 handoff.md 的自由文字（44 份中 23 份有寫），無法機器巡檢。 A1 能抓到動態表斷更，半動態／靜態資料的過期只能靠 F2 跨 repo 讀 catalog frontmatter。 長期解是把更新頻率結構化——這是本 skill 之外的獨立工作。

腳本實作陷阱（改收集器前必讀）

1. src/data/layerParamsSpec.ts 含非文字位元組，BSD grep 會判成 binary 並靜默回空（不報錯）。 用 import 讀，或 grep -a。
2. 資料夾層級 git log -1 會被批次 commit 洗掉（一個 docs(backlog): reorganize… 摸過幾乎每個 feature 夾）。staleness 要看單檔，或排除 docs:／memory: 前綴的 commit。
3. .claude/.cache/weekly-audit/ 不進版控——所以趨勢比較的基準是報告本身， 報告的趨勢表必須自帶關鍵數字。
4. 判定不要拿「結構上本來就會不等」的兩個數字當紅線（2026-08-21 教訓）。 原本 Three.js 檢查用 目錄總項目數 !== *Scene.ts 數 判歧義，但 src/three/ 本來就有支援檔與 shaders/ 子目錄——這種判準會永遠亮黃，變成每週噪音。 正確做法是比對「README 宣稱的數」與「該敘述真正對應的實際數」。
5. 「30+」「約 N」這種開放式寫法不能當精確值比。collector 差 2 倍才報、 nginx location 差 30% 才報，否則每週都在報一個作者本來就沒打算寫精確的數字。

主動更新時機

• 新增檢查項 → 改對應收集器 + 本檔 Step 1 的表 + proposal 的 §2 總表 + 本檔 frontmatter 的 description， 四處同步（description 若寫死項目數就會 drift，所以它現在只寫「六組」不寫總項數）。
• 收集器誤報／漏報 → 先改腳本，並把踩到的坑寫進上面「腳本實作陷阱」。
• 連續 3 週某項都是 🟢 且沒變化 → 考慮降頻或移除，別讓報告變成噪音。
• 白名單自動修出過事 → 立刻把那類移出白名單，並在此註明原因。
• v2 接上 agent-browser 真 render 驗收後 → 改寫「本 skill 不做」第一條。

Related

• 設計提案：docs/proposal/weekly-audit-2026-08-21/README.md
• 報告索引：docs/audit/weekly/README.md
• 上層生態的跨 repo drift check：../.gis-agent-system/schedule/
• 相鄰 skill：layer-onboarding（單層上線驗收）、wrap-up（session 收尾）、 supabase-optimize + /check-rpc（慢 RPC 的處置）