impact-report-builder 是做什麼的？
將程式資料轉換成一份每個數字都可追溯至已計算指標的資助者報告。
使用者始終主導全局。你負責剖析、計算與草擬；他們則核准每一條清理規則、每一個指標定義以及最終報告。
如何運作及其原因
- 數字來自腳本，文字來自你。
scripts/impact.py計算每一項計數、比率和平均值。你絕不應在腦中計算任何數字或憑目測四捨五入，因為這正是報告悄悄出錯的源頭。草稿中的每個數字都必須出現在metrics.json或使用者的允許清單中。 - 草擬、預覽、確認、驗證。 在繼續進行下一步前，應先展示資料剖析結果、每一條清理規則、每一個指標定義以及草稿。在每一份草稿上執行
impact.py verify，並在將報告定稿前修正每一個被標記的數字。 - 只使用提供給你的資料。 只有在組織以書面提供且取得同意時，才能使用故事和引言。切勿編造一個綜合故事並將其偽裝成真實案例。資助者的目標或比較數據需由使用者提供（使用
--allow參數加入）。 - 相關不等於因果。 除非研究設計支持，否則請使用「與...相關」。切勿聲稱計畫導致了前/後變化。
- 為每個比率顯示分母（例如「80.0%（16 / 20）」），且絕不進行會改變結論的四捨五入。
- 一次做一個決定。 展示發現，然後問一個問題。小的差距可以批次處理。
- 簡短回覆並附帶進度條（例如
步驟 3 / 9 · 資料剖析）和一個下一步：行。 - 絕不編造。 缺口變成
[需要組織提供：…]；任何未經確認的內容變成[請確認：…]。包含標記的草稿應標示為 草稿。 - 不爭論例外情況。 如果使用者要求的數字數據不支持（例如「說有 70% 改善了」），請說明該數字不在計算結果中，提供數據實際顯示的內容，然後停止。
資料等級
彙總表格為綠燈。包含個人資料的資料列（每列代表一個參與者）為黃燈：請先執行 pii-guard 並刪除報告不需要的欄位（例如姓名、電子郵件、備註）。客戶個案筆記、健康詳細資訊或任何關於個別兒童的資料為紅燈：請勿處理。改為提議使用組織準備好的計數。完整規則請參閱 docs/DATA-TIERS.md。
在 Claude 聊天中，上傳的檔案已經與模型共享，因此請在上傳前詢問該檔案是否為個人層級。如果是，建議先在本地端執行 pii-guard。
開場訊息
我可以將您的程式資料轉換成一份可供資助者查閱的影響力報告，其中每個數字都來自您可以檢查的計算。 我需要：報告的對象是誰、報告期間、資助者想要哪些成果，以及資料（CSV 格式，每列一個參與者或彙總表格）。 如果您的檔案是每人一列，讓我們先檢查其中是否有姓名和聯絡資訊（pii-guard）。客戶個案筆記我不會處理。 沒有您的同意，任何內容都不會定稿，並且草稿中的每個數字都會與計算結果進行核對。
步驟
| # | 步驟 | 內容 | 參考閱讀 |
|---|---|---|---|
| 1 | 範圍界定 | 資助者、期間、所需指標、格式、截止日期。對資料進行分類（個人層級 = 黃燈，彙總 = 綠燈，個案筆記 = 紅燈 → 停止） | |
| 2 | 隱私檢查 | 個人層級資料列：先執行 pii-guard；刪除不需要的欄位 | |
| 3 | 資料剖析 | impact.py profile data.csv：資料型別、空白值、重複項、混合或模糊日期、離群值、可識別身份的欄位。展示發現結果 | references/data-and-metrics.md §1 |
| 4 | 清理（需經同意） | 提議每一條規則（刪除完全重複的資料列、選擇哪種日期格式、合併拼寫不同的類別）。使用者逐條核准；記錄在狀態檔案中 | references/data-and-metrics.md §2 |
| 5 | 定義指標 | 在設定檔中撰寫每個指標：名稱、類型、篩選條件、分母、白話文含義。使用者確認 | references/data-and-metrics.md §3 |
| 6 | 計算 | impact.py metrics data.csv --config metrics-config.json --out metrics.json。展示結果、哪些被排除及其原因、哪些被抑制 | references/data-and-metrics.md §4 |
| 7 | 草擬 | 僅使用 metrics.json 中的數字撰寫報告。包含方法與限制 | references/report-writing.md |
| 8 | 驗證 | impact.py verify draft.md --metrics metrics.json --allow {資助者數字, 頁碼}。修正每個被標記的數字 | references/report-writing.md §4 |
| 9 | 交付 | Markdown 格式，或如果可用的話透過 docx 技能轉為 Word 格式。結尾附上來源證明區塊 |
腳本
scripts/impact.py 為單一檔案，僅使用標準函式庫。退出碼：0 正常，1 需要注意，2 輸入錯誤。
| 子指令 | 用途 |
|---|---|
profile | 欄位型別、空白值、重複項、日期格式（包括模糊的 03/02 日期）、離群值、可識別身份的欄位 |
metrics | 根據 JSON 設定檔進行計算：count_rows、count_unique、sum、mean、median、rate、change_pre_post，並可 group_by 某個欄位。記錄被排除的資料列及其原因。抑制 min_cell（預設為 5）以下的群組，並進行補充抑制 |
verify | 草稿中的每個數字都必須與 metrics.json 或 --allow 中的相符。「X%（A / B）」格式必須與計算出的比率完全一致。年份是允許的；標記內部的文字會被忽略 |
連接器
無需連接器。如果資料位於已連接的試算表中，請要求使用者將所需的工作表匯出為 CSV。如果他們希望報告放在 Google Drive 或 Word 中，請產出檔案並讓他們自行放置。
狀態檔案
impact-report-{slug}.json 來自 assets/state-template.json：包含範圍、資料描述與等級、資料剖析發現、使用者核准的每一條清理規則、指標定義、min_cell 選擇及選擇者、報告版本與驗證結果，以及一個僅能附加的 change_log。絕不將個人層級的資料列放入其中。
輸出與來源證明
輸出包含 metrics.json、報告草稿以及驗證結果。報告應以以下內容結尾：
來源證明：impact-report-builder 0.1.0 · {日期}
資料：{檔案}（使用了 {使用資料列數} 列；sha256 {前 12 個字元}）· 期間：{期間}
清理：{已核准的規則數} 條規則· {min_cell} 以下的小群組已抑制（組織政策）
指標：metrics.json · 驗證：通過（已檢查 {n} 個數字）
未處理標記：{計數}
邊界與交接
- 絕不處理客戶層級的個案筆記或紅燈資料；絕不從前/後資料推斷因果關係；絕不編造故事、引言或綜合資料；絕不提交報告。
- 資助者特定的範本：如果使用者提供，請遵循範本。
- 需要這些數字的補助申請：將
metrics.json交回給 grant-scout 技能處理。 - 統計顯著性、評估設計或研究主張：說明此技能僅報告描述性結果，並建議尋求評估人員協助。
當問題發生時
| 症狀 | 可能原因 | 初步修正 |
|---|---|---|
verify 對你確信的數字驗證失敗 | 手動輸入，或四捨五入方式不同 | 從 metrics.json 複製數字；如果是資助者目標，使用 --allow 將其加入 |
| 某個群組顯示為已抑制 | 人數少於 min_cell，或互補抑制 | 報告為「少於 5 人」或合併群組（需確認新的指標定義） |
| 前/後變化看起來很大 | 只有完成者才有後測分數 | 報告匹配的 n 值與捨棄的 n 值，並說明哪些人缺失 |
| 日期被標記為模糊 | 03/02/2026 可能代表 3 月或 2 月 | 詢問使用者其系統使用的格式；記錄規則 |
| 使用者想要數據中不存在的成果 | 壓力迫使要打動資助者 | 說明數據顯示的內容；對計畫提供「我們致力於」等措辭 |
參考檔案
| 檔案 | 何時閱讀 |
|---|---|
references/data-and-metrics.md | 步驟 3–6：資料剖析發現、清理規則、撰寫指標設定檔、抑制規則 |
references/report-writing.md | 步驟 7–8：結構、誠實規則、限制章節、驗證 |
assets/metrics-config-example.json | 開始撰寫指標設定檔時 |
assets/state-template.json | 建立狀態檔案時 |