docs: simplify spec and task templates for single-project use

.github/spec-template.md

@@ -1,71 +1,87 @@
-# 規格（Spec）模板
+# 規格（Spec）模板 — 單人專案簡化版
 
-> 用途：作為專案的契約與不變條件單一來源（Single Source of Truth）。本模板為領域無關，請依實際專案填寫。
+> 用途：作為專案的契約與不變條件單一來源（Single Source of Truth）。  
+> 注意：本模板為單人小型專案優化版，著重於核心契約與邊界情境；評估必要時補充完整版章節。
 
 ## 1. 概述（Overview）
-- 背景：本專案要解決的問題與目標。
-- 目標（Goals）：可量化或可驗證的目標。
-- 非目標（Non-goals）：此次不處理的事項，避免範圍擴張。
-- 詞彙（Terminology/Glossary）：關鍵名詞定義。
+- **背景與目標**：專案要解決的問題、可量化/驗證的目標。
+- **非目標**：此次不處理的事項（避免範圍擴張）。
+- **主要輸入/輸出**：一句話定義資料流的起點與終點。
 
-## 2. 架構與入口（Architecture & Entry Points）
-- 系統構成：高階元件與資料流示意（可附圖）。
-- 主要入口與執行路徑：CLI/腳本/服務端點等（僅列型態與責任，避免固定檔名）。
-- 模組邊界：各模組職責與相依。
+## 2. 架構與入口（Compact）
+- **主要入口**：CLI/Web/腳本/服務端點（僅列責任，不綁定檔名）。
+- **核心流程**：3–5 步的高層流程圖或敘述。
+- **關鍵相依**：外部服務/檔案/第三方庫。
 
 ## 3. I/O 與資料契約（Data Contracts）
-- 輸入：資料形狀、欄位、必填/選填、預設值、驗證規則。
-- 輸出：資料形狀、欄位、誤差/置信指標（如適用）。
-- 錯誤模型：錯誤碼/訊息格式、可重試性。
-- 相容性：版本欄位或相容策略。
-
-## 4. 限制與不變條件（Invariants & Limits）
-- 時間/長度/頻率/資源上限（用語義而非硬寫數值；具体值置於設定或附錄）。
-- 批次或分段處理策略與上限。
-- 資料完整性與順序保證。
-
-## 5. 外部依賴與設定（Dependencies & Configuration）
-- 外部服務/檔案/模型/金鑰：用途、介面、授權界線。
-- 設定來源：環境變數、設定檔欄位、預設值。
-- 快取策略：命中/失敗行為、TTL。
-
-## 6. 失敗降級與可觀測性（Failure & Observability）
-- 降級矩陣：各失敗點對應的替代行為（阻斷/退回/占位/重試）。
-- Logging：層級、訊息格式、關鍵欄位。
-- Metrics/Tracing：重要指標與取樣策略。
-
-## 7. 使用者介面行為（UI Behavior）
-- 主要互動流程：狀態轉移與可見性規則。
-- 警告/錯誤顯示準則：何時顯示、文案風格。
-- 無障礙與國際化（如適用）。
-
-## 8. 效能與擴展性（Performance & Scalability）
-- 資料量/延遲/吞吐目標。
-- 批次/併發策略與資源界線。
-
-## 9. 測試與驗收（Testing & Acceptance）
-- 最小測試集合：Happy path + 1–2 個邊界案例。
-- 手動冒煙步驟：最短可驗證路徑與預期輸出。
-- 模擬/替身策略（Mock/Fake/Stubs）。
-
-## 10. 相容性、版本與遷移（Compatibility & Migration）
-- 版本策略：如何識別破壞性變更。
-- 遷移與回滾：步驟、風險、時間視窗。
-
-## 11. 安全性與隱私（Security & Privacy）
-- 存取控制、資料保留、最小權限、稽核需求。
-
-## 12. 開放議題（Open Questions）
-- 尚待釐清的需求、依賴或量化門檻。
-
-## 13. 變更記錄（Spec Change Log）
+- **輸入形狀與欄位**：資料形狀、必填欄位、預設值、驗證規則。
+- **輸出形狀與欄位**：預期格式、誤差/置信指標（如適用）。
+- **版本與相容性**：如何識別破壞性變更、遷移策略（若有）。
+
+## 4. 不變條件與限制（Invariants & Limits）
+- **核心規則**：業務邏輯中不可破壞的假設（如取樣率、窗口長度、測站數上限等）。
+- **邊界情境與降級**：資料不足/缺漏/格式錯誤時的行為（退回/佔位/跳過/重試）。
+- **資源上限**：記憶體/時間/API 配額（語義層級，具體值置於設定檔）。
+
+## 5. 外部依賴與設定（Dependencies）
+- **外部服務/檔案/模型**：用途、介面、失敗時的降級方案。
+- **設定來源**：環境變數/設定檔欄位與預設值。
+- **快取與重試**：命中/失敗/TTL 策略。
+
+## 6. 失敗降級與可觀測性（Resilience & Observability）
+- **降級矩陣**：各失敗點 → 替代行為（繼續/佔位/使用預設值）+ Log 等級。
+- **Logging**：關鍵節點需有 INFO/WARNING/ERROR，記錄現象、原因、替代方案。
+- **測試邊界情境**：Happy path + 1–2 個代表邊界案例（如資料缺漏、逾時、格式錯誤）。
+
+## 7. UI/交互行為（若適用）
+- **主要流程**：使用者操作序列與預期結果。
+- **警告/錯誤顯示**：何時顯示、文案風格（應面向終端使用者）。
+- **無障礙/國際化**：如有特殊需求則列出。
+
+## 8. 擴充點（Extensibility）
+- **新增資料來源/目標**：如何添加新資源而不修改核心邏輯。
+- **新增輸入源/功能模組**：預留的設定/表格/介面位置。
+- **版本遷移**：破壞性變更時的因應步驟。
+
+## 9. 最小測試（Testing Checklist）
+- ✅ Happy path：完整流程 1 次（包含所有必填欄位）。
+- ✅ 邊界 1：資料不足/缺漏時能降級並顯示警告。
+- ✅ 邊界 2：外部服務失敗時能使用預設值/佔位。
+- ✅ 邊界 3：異常格式/超限時能記錄並繼續。
+
+## 10. 變更紀錄（Decision Log）
 - YYYY-MM-DD: 條目、影響、相容性、連結（PR/Issue）。
 
 ---
 
-附錄 A：參考設定（可選）
-- 以鍵值方式列出可調參數與預設值（置於設定檔，非硬編於程式）。
+## 附錄 A：常數與參考設定（可選）
 
-附錄 B：資料/結構圖（可選）
-- 圖表或連結。
+| 項目 | 預設值 | 來源 |
+|------|--------|------|
+| 取樣率 | 100 Hz | 硬編 |
+| 窗口長度 | 30 秒 | 模型輸入約束 |
+| 最大測站數 | 25 | 批次上限 |
+| 預設 Vs30 | 600 m/s | 降級用 |
+
+---
+
+## 附錄 B：資料欄位（可選）
+
+### 輸入欄位範例
+- `station/site_info.csv`: `[Station, Latitude, Longitude, Elevation, ...]`
+- `station/eew_target.csv`: `[station, latitude, longitude, elevation, ...]`
+
+---
+
+## 使用建議
+
+### 單人專案快速檢查清單
+1. **初期**：先填 1–4 節（明確 I/O 與邊界），不必逐章完整。
+2. **開發中**：發現新的邊界情境或外部依賴時，補充到第 4、5、6 節。
+3. **測試前**：確認第 6、9 節的降級與測試覆蓋。
+4. **新增功能**：先更新本文件（尤其 I/O 與邊界），再寫程式。
+
+### 何時升級為完整版
+- 多人協作開始、需求快速變化、或涉及多層級服務時，補充第 7–8 節與完整圖表。
+- 仍需參考原始 spec-template.md 作為參考。
 

.github/task-template.md

@@ -1,70 +1,47 @@
-# Task: <在此填寫任務標題>
+# Task: <標題>
 
 - Task ID: T-<YYYYMMDD>-<shortname>
-- Owner: <name>
 - Date: <YYYY-MM-DD>
-- Status: Planning | In Progress | Review | Done
+- Status: Planning | In Progress | Done
 
 ## 背景與目標
-- 背景：為何需要這個變更？與 `spec/spec.md` 的哪一段相關？
-- 目標：本次要達成的使用者價值與交付物（可量化）。
-- 不在範圍：明確說明此次不處理的部分，避免 scope creep。
+- **背景**：為何需要？與 `spec/spec.md` 的哪一段相關？
+- **目標**：交付物與驗收標準（一句或要點形式）。
+- **不在範圍**：明確避免 scope creep。
 
-## 相關文件與位置
-- 規格：`spec/spec.md`（若公共行為變更，務必同步更新）
-- 主要程式與入口／樣板流程：請參考 `spec/spec.md` 中對應章節（本模板不列舉檔名）
-- 其他：<連結到 PR、議題、筆記、外部參考>
-
-## 不變條件與約束（對齊 spec 要點）
-- 請列出與本任務相關的關鍵不變條件與限制，並指向 `spec/spec.md` 的條目，例如：
-  - I/O shape 與資料欄位約束
-  - 處理批次與資源上限（長度/頻率/數量/逾時/重試）
-  - UI 尺寸與交互限制
-  - 外部依賴的預設值、快取與降級策略
-
-> 若本任務可能影響以上不變條件，請明列風險與必要的 `spec/spec.md` 更新計畫（含相容性與回滾方案）。
-
-## 任務拆解（可勾選，可跨對話沿用）
+## 任務拆解（可勾選）
 - [ ] 子任務 1：<描述>（變更檔案：`...`）
-  - 驗收標準：<明確可驗證的條件>
-  - 測試/冒煙：<如何驗證，輸入/輸出示例>
+  - 驗收：<可驗證的條件>
 - [ ] 子任務 2：<描述>（變更檔案：`...`）
-  - 驗收標準：<...>
-  - 測試/冒煙：<...>
+  - 驗收：<可驗證的條件>
 - [ ] 子任務 3：<描述>（變更檔案：`...`）
-  - 驗收標準：<...>
-  - 測試/冒煙：<...>
-
-> 建議每個子任務都能在 1 小時內完成並可獨立驗收；大型變更請再細分。
-
-## 介面與資料形狀變更評估
-- UI 影響：是否需要新增/修改提示、警告或欄位？
-- I/O shape：輸入/輸出資料結構或欄位是否改變？
-- 向後相容：如何保持既有使用者不受影響？若無法，請先更新 `spec/spec.md` 並標註破壞性變更與遷移策略。
-
-## 降級與記錄策略
-- 可能失敗點：<列出>（例如：外部依賴失敗、輸入不足、格式錯誤、資源不足/逾時等）
-- 降級方案：<對應每一種失敗點的替代行為，需符合 `spec/spec.md`>
-- Logging：<關鍵訊息，包含資訊/警告/錯誤的字串格式，便於追蹤>
-
-## 測試與驗收
-- 單元/整合測試：<若有測試框架，列出測試案例>
-- 手動冒煙：
-  - 啟動方式：請依 `spec/spec.md` 或 `README.md` 中的指引
-  - 驗收步驟：<步驟 1, 2, 3>
-  - 預期結果：<清楚描述>
-- 品質檢查（最低）：
-  - [ ] Build/型別/格式檢查通過
-  - [ ] 關鍵邊界情境可正確降級並記錄 log（依 `spec/spec.md`）
-  - [ ] 與 `spec/spec.md` 之契約一致
-
-## 風險、回滾與後續
-- 風險：<列出主要風險與緩解方式>
-- 回滾：<若出問題如何快速回復>
-- 後續工作：<可選，列出延伸 task>
-
-## 進度紀錄（跨對話追蹤）
-- <YYYY-MM-DD HH:MM>：<進度更新，關鍵決策/PR 連結/驗收結果>
+  - 驗收：<可驗證的條件>
+
+> 每個子任務盡量控制在 1 小時內可完成。
+
+## 不變條件與約束檢查
+- [ ] 是否影響 `spec/spec.md` 中的 I/O shape、欄位、或不變條件？
+- [ ] 如是，已更新 spec 並標註破壞性變更？
+- [ ] 邊界情境（資料缺漏、外部依賴失敗等）是否正確降級並記錄 log？
+
+> 填寫相關 spec 章節編號或行號（如 spec #3, #6）。
+
+## 手動驗收（冒煙測試）
+- **步驟**：
+  1. <步驟 1>
+  2. <步驟 2>
+  3. <步驟 3>
+- **預期結果**：<清楚描述>
+- **失敗情境測試**（若適用）：<一個邊界案例的驗證步驟>
+
+## 完成檢查
+- [ ] 程式碼符合 `spec/spec.md` 約束
+- [ ] 手動驗收通過
+- [ ] 關鍵邊界情況有 log（INFO/WARNING/ERROR）
+- [ ] 若改動 CSV 或模型契約，spec 已同步
+
+## 進度紀錄
+- <YYYY-MM-DD HH:MM>：<進度更新或決策>
 
 ---