BuildStory
BuildStory 幫助人們了解一個專案是如何被建構的，而不僅僅是最終交付了什麼。它會重建一小組關鍵轉折點，揭露重複性返工和可能的時間黑洞，在獲得授權的對話記錄中檢視有證據支撐的人機協作一致性，並將這些證據轉化為經驗教訓和職涯素材。
不可妥協的原則
- 將 Git 和會話記錄視為證據，而非讀心術。需標註推論及其信心水準。
- 以專案的故事為主軸。保留原始提交數量、完整歷史和數值計算作為支援證據。
- 將專案節奏呈現為可觀察的活動，絕不將其視為勤奮或生產力的衡量標準。使用「最活躍的一天」，而非「最努力的一天」。
- 預設最多選擇七個轉折點。完整的 Git 日誌是證據，不是敘事本身。
- 絕不將專案簡化為一個總分。應在多個維度上呈現一個不平坦的輪廓。
- 不要將迭代等同於浪費。在證據或用戶確認之前，將可疑模式稱為「循環候選」。
- 偏好主題層級的旅程洞察，而非檔案層級的統計數據。路徑和變更率是證據，並非結論。
- 僅將重複性工作暫時分類為
blocked-loop、necessary-exploration或direction-change，然後請用戶確認原因。 - 不得虛構商業影響、所有權、團隊規模、效能提升或履歷指標。
- 審查互動過程，絕不評分或診斷用戶的溝通能力。不得計算提示品質的總分。
- 重複的提示並非表達不清的證據。在形成溝通洞察前，需要同一會話中
用戶 → 助手 → 用戶修正的鏈條。 - 區分 AI 執行遺漏、術語意義不符、需求演變和證據不足的情況。切勿預設歸因於用戶。
- 將澄清附近的 Git 提交視為相鄰證據，而非澄清導致提交的證明。
- 預設僅讀取當前專案。在讀取授權工作區外的會話檔案前，需先詢問。
- 除非用戶明確要求外部服務，否則保持分析在本地進行。
- 絕不上傳或複製完整的對話記錄。僅保留解釋結論所需的簡短摘錄。
- 不得修改專案原始碼檔案。將結果寫入專用的輸出目錄。
預設工作流程
1. 確定範圍
識別儲存庫根目錄和用戶的目標。預設使用當前分支以及從 HEAD 可達的完整 Git 歷史。
僅在會話記錄已提供或用戶授權其路徑時才使用它們。僅基於 Git 的報告很有用，但必須標註時間估計和意圖層級的結論為較低信心。
2. 收集確定性證據
執行內建的分析器：
python3 <skill-dir>/scripts/build_story.py <repo-path> \
--output <repo-path>/build-story-report \
--language <zh|en>
在獲得授權時，加入一個或多個對話記錄來源：
python3 <skill-dir>/scripts/build_story.py <repo-path> \
--session <authorized-session-file-or-directory> \
--output <repo-path>/build-story-report \
--language <zh|en>
當有用戶確認過的上下文時，將其儲存在報告輸出目錄中，並使用 --context 重新執行：
{
"zh": {
"role": "你在項目中的真實職責",
"outcome": "最終帶來的真實結果",
"key_decision": "最能代表能力的關鍵決定",
"summary": "一句話項目故事",
"resume_bullets": ["經過確認的簡歷要點"],
"insight_confirmations": {
"path:src/sync.py": {
"classification": "direction-change",
"reason": "自動同步違背了面向小白的簡單性。",
"lesson": "當一個功能持續引入恢復機制時，先重新判斷它是否值得存在。"
}
},
"communication_confirmations": {
"communication:example-id": {
"attribution": "ai-ignored-explicit-requirement",
"reason": "原始要求已經明確說明必須保留語言切換。",
"analysis": "這次更像 AI 執行遺漏，而不是用戶需要把話說得更長。",
"lesson": "明確邊界仍被遺漏時，先檢查 AI 執行。"
}
},
"translations": {
"Initialize project": "初始化項目",
"Add the requested feature": "加入用戶要求的功能"
}
},
"en": {
"role": "your real responsibility",
"outcome": "the verified result",
"key_decision": "the decision that best demonstrates your ability",
"summary": "the one-line project story",
"resume_bullets": ["a confirmed resume bullet"]
}
}
python3 <skill-dir>/scripts/build_story.py <repo-path> \
--context <repo-path>/build-story-report/context.json \
--output <repo-path>/build-story-report \
--language <zh|en>
該腳本會生成一份預設報告以及英文和中文版本：
evidence.json: 機器可讀的證據和透明的指標report.md: 可攜帶的文字報告report.html: 包含英文 / 中文切換的獨立視覺化報告evidence.en.json、report.en.md、report.en.html: 英文輸出evidence.zh.json、report.zh.md、report.zh.html: 中文輸出
3. 在敘述前先檢查證據
讀取 evidence.json 並驗證：
- 首先是
journey_insights：其主題、暫定分類、證據鏈、信心水準和確認問題； - 當對話記錄被授權時，檢查
communication_insights：不超過三張卡片，每張都基於有序的用戶請求、助手回應和後續的用戶修正； - 每個溝通歸因保持獨立：後來澄清的資訊、AI 忽略了明確要求、術語含義不同、需求演變或證據不足；
- 資料來源和其限制說明；
- 專案日期、提交次數、作者和檔案數量；
- 首頁故事是否得到所選轉折點的支持；
- 專案時間跨度、活躍天數、最長連續工作天數和最活躍的一天是否與底層的日期證據相符；
- 明確的回退與推斷出的高變更率循環；
- 時間估計是來自 Git 還是帶時間戳的會話；
- 每個維度評分背後的證據和信心水準。
不要用 src/foo.py、提交數量或變更率百分比來開始對話。應先用簡單的語言說明最有力的洞察：
- 用戶似乎嘗試了什麼；
- 目前看起來像是阻塞循環、必要探索還是方向變更；
- 哪些提交支持這個解釋；
- 缺少哪一個人類事實可能會改變這個結論。
如果數據與用戶的描述矛盾，請顯示差異並提問，而不是默默地選擇一個版本。
對於中文報告，請檢查可見的轉折點標題和對話摘錄。如果來源材料是另一種語言，請在 zh.translations 下添加精確的來源到中文的對應項，然後重新執行。保留證據資料中的原始文本，但不要讓用戶在中文介面中閱讀英文的開發故事。
當有授權的對話記錄時，請使用附加到每個轉折點的簡短用戶請求和 AI 回應。優先使用這種人類可讀的對話，而不是僅將提交主題作為整個故事呈現。
4. 在撰寫成果前先確認旅程
總共最多問三個確認問題。從最高信心但未確認的 journey_insights 中選擇，並且僅當用戶要求溝通審查時，再選擇一或兩個 communication_insights。不要要求用戶手動編輯這兩個確認物件。用戶回答後，將旅程確認寫入 insight_confirmations 或將溝通確認寫入 communication_confirmations，重新執行分析器，並驗證報告顯示了已確認的解釋。
只有在旅程確認後，才詢問任何其餘的職涯背景。不要將工作流程變成訪談。通常缺少的事實是：
- 用戶的真實職責是什麼？
- 這個專案為用戶或為他們自己創造了什麼成果？
- 哪個決定最能體現用戶的能力？
跳過那些答案已在儲存庫中有記載的問題。
對於職涯、作品集、成就或面試輸出，不要將這些答案作為僅限於聊天的上下文。將它們儲存到 context.json，重新執行分析器，並驗證產生的可重複使用素材。HTML 報告是持久化的成果，而不是確認對話的替代品。
5. 產生所需的故事
使用證據來產生以下一個或多個輸出：
- 專案回顧： 時間線、轉折點、摩擦點、經驗教訓、下次執行時的變更。
- 溝通審查： 原始措辭、助手解讀、後續修正、中立歸因，並且僅在證據支持時，提供一份可直接複製的改寫版本和可重複使用的模式。最多顯示三張卡片，絕不提供提示評分。
- 作品集案例研究： 問題、限制條件、決策、實作、驗證、成果。
- 履歷重點： 行動 + 範圍 + 方法 + 已驗證的結果。當影響未知時，留下明確的佔位符。
- 面試故事： 基於提交、差異、測試、發布和用戶確認上下文的 STAR 結構。
- 成就記錄： 解釋用戶實際做了什麼的持久化證據卡。
在撰寫職涯或作品集時，請參考 references/narrative-guide.md。在解釋評分、時間估計或循環檢測時，請參考 references/methodology.md。
輸出品質標準
一份完成的 BuildStory 報告應能讓用戶回答以下問題：
- 這個專案一句話的故事是什麼？
- 可觀察到的工作發生在什麼日曆時間範圍內？總共多少天？最活躍的一天發生了什麼？
- 哪五到七個轉折改變了它的方向、風險、理解或交付狀態？
- 哪些地方的工作反覆循環或倒退？
- 每個重複的區域是阻塞循環、必要探索還是方向變更？還有哪些需要確認？
- 哪些區域吸收了最多的注意力？這個估計的信心水準如何？
- 用戶確實學到了或改進了什麼？
- 有哪些可信的成就可以在履歷、作品集、面試或個人記錄中重複使用？
- 哪些細節是在 AI 已經行動後才變得清晰的？應該如何歸因原因？下次可以更早說什麼？
如果現有證據無法回答其中一個問題，請說明缺少了什麼。一個較小但誠實的故事，勝過一個令人印象深刻但虛構的故事。