停止。在呼叫任何端點前，請先完整閱讀此 SKILL.MD 檔案。
assess 是做什麼的？
退一步，以批判性視角重新評估專案狀態。提供互動式引導（人機協作）與程式化分析（自動化流水線）。專門用於文件精簡與文件-程式碼一致性分析。
CLI 使用方式
# 用於流水線的結構化 JSON 評估
.pi/skills/assess/assess.py run . --output assessment.json
# 從評估結果中產生所有圖表
create-figure from-assess --input assessment.json --output-dir ./figures/
評估流程
1. 界定評估範圍
明確範圍（「評估 auth 模組」）→ 直接進行。 開放式範圍（「退一步看看」）→ 詢問：有哪些疑慮？程式碼品質還是文件？有已知問題需要跳過嗎？ 文件精簡（「精簡文件」）→ 詢問：有已廢棄的功能嗎？缺少文件嗎？文件與程式碼一致嗎？
2. 尋找專案根目錄並偵測生態系統
透過標記檔案（pyproject.toml、package.json、Cargo.toml、go.mod）進行偵測。 讀取生態系統特定的中繼資料，然後讀取通用文件（README.md、CONTEXT.md、AGENTS.md）。
3. 載入技能清單（路由控管）
對於可能導致「我們應該建置 X」建議的評估，載入 .pi/skills-manifest.json。對於狀態檢查和僅限文件的審查則跳過。
cat .pi/skills-manifest.json | python3 -c "
import json, sys
data = json.load(sys.stdin)
print(f'技能數量: {data[\"skill_count\"]} (產生時間: {data[\"generated\"]})')
"
如果清單超過 7 天未更新，則發出警告。備用方案：ls .pi/skills/ | wc -l。
4. 快速掃描 → 確認 → 深入分析
- 讀取專案中繼資料、README，使用 glob 獲取結構概覽
- 記錄 2-3 個初步觀察結果，並與使用者確認
- 根據使用者指引進行深入分析 — 針對每個發現：是否造成阻塞？是否已知？修復複雜度？
5. 協作式報告
呈現發現結果，並詢問哪些需要修復。提供 /create-figure 以進行視覺化。
評估類別
1. 文件-程式碼一致性
- README 中的宣稱與實際實作
- 交叉引用驗證（內部連結、程式碼範例）
- 佔位符標記與過時資訊
- 廢棄標記：已移除功能的文件
2. 理想 vs 實作
- 樁程式碼（
pass、raise NotImplementedError）、佔位符註解 - 程式碼結構中存在但無實際邏輯的功能、未使用的相依套件
3. 脆弱的程式碼
- 硬編碼的值、缺少錯誤處理、脆弱的正規表達式/解析
4. 無法運作的程式碼
- 死路徑、沉默地吞掉例外、損壞的整合
5. 過度設計的程式碼
- 只有單一實作的抽象層、為假想的靈活性準備的設定
6. 測試覆蓋率（無可協商）
檢查每個功能/模組是否有測試檔案、測試是否通過、是否涵蓋邊界情況。
標記不帶理由的 pytest.mark.skip、「0 tests collected」、沒有斷言的測試。
任務檔案稽核： 確認每個任務都有包含特定測試/斷言的「完成定義」。 如果實作任務缺少「完成定義」，則阻止執行。
7. 運作良好的部分
肯定穩固的程式碼，以校準評估的客觀性。
輸出格式
# 評估：<專案名稱>
## 摘要
<2-3 句話：整體健康狀況、主要發現>
## 發現
### 文件-程式碼一致性
| 宣稱 | 實際情況 | 行動？ |
### 發現的問題
1. **file.py:123** - [問題] — 嚴重性：高/中/低 — 建議修復：[簡短說明]
### 測試覆蓋率
| 功能 | 測試狀態 | 需要採取的行動 |
### 運作良好的部分
- [值得肯定的穩固程式碼]
## 建議後續步驟
1-4 個優先處理的行動。詢問從哪個開始。
政策
- 預設唯讀 — 未經明確同意，絕不寫入檔案
- 先顯示，經同意再寫入 — 先展示建議內容，再提供寫入選項
- 協作 — 評估是對話，而非獨白
- 執行前先詢問 — 在執行測試、建置或付費服務前取得許可
- 明智地升級 — 對複雜/關鍵問題建議使用
/review-code - 具體明確 — 提供檔案路徑與行號
- 可採取行動 — 每個發現都要提出後續步驟
- 測試覆蓋率無可協商 — 將缺少測試標記為阻礙因素
外部研究
需要時可使用（使用前先詢問付費服務）：
/context7— 函式庫文件（免費）/brave-search— 一般網路搜尋（免費）/perplexity— 深度研究（付費）
常見錯誤
# 錯誤：將所有評估發現都視為阻礙問題
# → 代理自動為 12 個私有輔助函式加入 docstring。不必要的膨脹。
# 正確做法：與使用者一起審查發現。將複雜問題升級到 /review-code。
# 錯誤：重大變更後跳過 /assess
# → README 範例使用舊的函式簽章。使用者遇到錯誤。
# 正確做法：編輯核心 API 後，執行 assess --focus "doc-code-alignment"
# 錯誤：執行 /assess 並根據陳舊結果採取行動
# → 評估是 3 天前做的。程式碼庫已經變更。
# 正確做法：始終重新執行 assess；絕不跨階段快取結果。