timeline-report

timeline-report 技能總覽

timeline-report 是做什麼的

timeline-report 會把專案中已記錄的 claude-mem 歷史，整理成一份帶敘事性的開發報告。它不是只給你目前程式碼庫的平面摘要，而是重建這個專案一路如何演變的故事：重要階段、方向轉折、關鍵決策，以及整體推進節奏。

最適合用在報告撰寫的情境

當你需要的是一份可閱讀的專案歷程文件，而不是原始事件清單時，就很適合使用 timeline-report for Report Writing。它特別適合創辦人、維護者、審查者、顧問，或需要用連貫「Journey Into [Project]」風格說清楚專案一路發生了什麼的代理人。

真正要解決的核心需求

多數使用者要的不是泛泛而談的回顧，而是想回答這類問題：

• 這個專案的開發過程可以分成哪些主要篇章？
• 工作是如何隨時間演進的？
• 哪些地方改變了、停滯了，或突然加速？
• 要怎麼把 timeline 資料整理成別人真的看得懂的報告？

這也是 timeline-report 比一般 prompt 更有用的地方。

timeline-report 的差異在哪裡

timeline-report 的核心差異，在於它是以 claude-mem 的持久化 timeline 為基礎，而不是只靠臨時的 repo 檢查。若你要的是歷史敘事，而不只是「現在有哪些檔案」，這點就很重要。它也提供了辨識正確專案名稱的工作流程指引，包含實用的 worktree 檢查，避免報告誤打到錯的目錄，而不是對準父層專案。

安裝前你需要先具備什麼

只有在以下兩件事都成立時，這個技能才真正適合安裝：

• claude-mem worker 正在 localhost:37777 上運行
• 目標專案已經有記錄過 claude-mem observations

如果少了任何一項，光做 timeline-report install 並不夠；這個技能幾乎沒有可用歷史能分析，或只能產出很薄弱的結果。

哪些情況不適合這個技能

如果你只需要以下內容，建議跳過 timeline-report skill：

• 目前架構摘要
• 單靠 Git 產生的 changelog
• 一段式的專案介紹
• 沒有 claude-mem 歷史的專案報告

這些情況通常直接下 prompt，或改用其他 repo 分析技能，會更簡單。

如何使用 timeline-report 技能

timeline-report 的安裝脈絡

從 repository 內容可確認，這個技能位於 thedotmack/claude-mem 內的 plugin/skills/timeline-report。基本安裝方式如下：

npx skills add thedotmack/claude-mem --skill timeline-report

安裝完後，先檢查環境，不要一開始就把輸出品質問題怪到技能本身：

1. 確認 claude-mem worker 可於 localhost:37777 存取
2. 確認目標專案已有 recorded observations
3. 確認你知道 timeline 儲存時使用的正確專案名稱

先看這個檔案

請先從這裡開始：

• plugin/skills/timeline-report/SKILL.md

這個技能本質上很依賴工作流程；最大的採用風險不是藏在什麼設定裡，而是你拿錯專案來跑，或是對著空的 timeline 執行。

先搞清楚必要輸入

最重要的輸入是 claude-mem 所認得的專案名稱。如果使用者只說「這個專案」，技能指引建議你先取目前目錄 basename，但前提是要先檢查自己是不是在 git worktree 裡。

這個細節很重要，因為 worktree 的資料夾名稱，常常跟父層專案在 timeline 裡的名稱對不起來。

正確處理 git worktrees

上游技能裡最實用、也最關鍵的細節，就是 worktree 檢查。如果你目前在 worktree 內，應該使用父層專案的識別，而不是 worktree 資料夾名稱。若專案名稱用錯，報告品質看起來就會像「壞掉了一樣」，因為它可能指到稀疏甚至無關的記憶資料。

如果你不確定，請先解析 git common directory，再從那裡推回父層專案，再要求產生報告。

實際上 timeline-report 該怎麼下指令

較弱的請求方式：

• "Write a report on this repo"

較好的 timeline-report usage 請求方式：

• "Use timeline-report to generate a Journey Into my-app based on its claude-mem timeline. Focus on major phases, important decisions, pivots, and the overall development arc."

更理想的請求方式：

• "Use timeline-report for my-app. Produce an executive-readable report with sections for origin, milestone phases, key decision points, setbacks, and current trajectory. Base it on the full claude-mem timeline rather than the current repo snapshot."

把模糊需求轉成有力的 prompt

想拿到更好的結果，prompt 最好包含以下元素：

• 精確的專案名稱
• 目標讀者
• 想要的報告形式
• 要強調的面向
• 細節深度

範例：

• "Use timeline-report on tokyo. Write a narrative report for stakeholders, not developers. Explain how the project started, what changed over time, where momentum increased or dropped, and what themes define its evolution."

這會比 "summarize the project history" 好，因為它把語氣與輸出結構都限制得更清楚。

讓輸出更穩定的建議流程

一套實用流程如下：

1. 先找出正確的專案名稱
2. 確認 claude-mem timeline 資料確實存在
3. 要求產出敘事型報告
4. 檢查輸出是否過度偏向原始時間順序
5. 若需要，再用更明確的受眾、章節與重點要求重跑一次

這個技能最適合用迭代方式使用。第一輪先抓出 timeline 的整體弧線，第二輪再把它修成更像正式報告。

可以要求 timeline-report 著重哪些內容

實用的強調方向包括：

• 重大里程碑，而不是零碎事件
• 架構或產品方向的轉折
• 朝 release readiness 推進的過程
• 除錯或復原階段
• 決策模式的變化
• 能解釋專案方向的核心主題

若沒有這些指引，timeline 報告很容易變得很長，但對決策幫助不大。

如何避免輸出變得太空泛

如果你不想讓 timeline-report 聽起來像一份平淡摘要，請明確要求：

• 用階段來整理，而不是事件列表
• 提供因果解釋，而不只是時間戳
• 在每次重大轉變後說明「這件事為什麼重要」
• 以對專案走向的總結評估作結

這樣能把輸出推向真正的報告寫作，而不是單純倒出記憶資料。

timeline-report 安裝與使用時常見卡點

主要卡點是操作層面，不是文風層面：

• claude-mem worker 沒有啟動
• 專案沒有 observations
• 使用了錯誤的專案名稱
• 把 worktree 名稱誤認成父層專案
• 使用者期待的是現況程式碼分析，而不是歷史分析

如果採用效果不佳，先檢查這些，再考慮重寫 prompt。

timeline-report 技能 FAQ

timeline-report 比一般 prompt 更好嗎？

如果你的目標是根據 claude-mem 資料撰寫專案歷程報告，那答案是肯定的。一般 prompt 也能要求敘事，但 timeline-report skill 已經把任務框定在歷史發展分析，以及「Journey Into [Project]」這種使用情境上。

timeline-report 對新手友善嗎？

大致上算友善，前提是環境已經存在。使用方式本身不複雜，但新手常會卡在前置條件：worker 是否啟動、是否已有儲存 observations，以及是否找對專案名稱。

我一定要有很長的 repository 歷史才能用嗎？

不一定，但 timeline 有一定密度時，這個技能的價值會高很多，因為它才能看出階段與變化。若記憶資料太稀疏，報告就會偏薄。

不用 claude-mem 也能用 timeline-report 嗎？

不能。這個技能明確依賴 claude-mem 的 timeline 資料，以及 localhost:37777 上的 worker。沒有這套生態，就代表你用錯工具了。

什麼時候不該把 timeline-report 用在 Report Writing？

如果你需要的是以下內容，就不要使用 timeline-report for Report Writing：

• 現況程式碼稽核
• 安全性審查
• API 文件
• 純粹由 Git 推導出的 changelog
• 從未被 claude-mem 追蹤過的專案分析

timeline-report 也會分析目前的 codebase 嗎？

它的核心價值在歷史敘事，不在完整 repo 檢查。你可以把它和其他分析步驟搭配使用，但這個技能本身主要是根據記憶 observations 來重建開發歷程。

為什麼 timeline-report 回傳的內容很弱或很模糊？

通常是以下原因之一：

• timeline 資料太稀疏
• 指到錯的專案
• prompt 沒有指定受眾或報告形式
• 使用者要求的是寬泛摘要，而不是結構化的敘事報告

如何改進 timeline-report 技能的使用效果

給 timeline-report 一份精準的報告 brief

品質提升幅度最大的做法，就是把 brief 寫得更清楚。請明確告訴 timeline-report：

• 報告是寫給誰看的
• 你要的是敘事型還是 executive summary
• 想凸顯哪些主題
• 哪些內容要淡化

範例：

• "Use timeline-report on my-app for an investor-style update. Focus on momentum, milestones, pivots, and evidence of execution."

先提供正確的專案識別

如果報告看起來不完整，先確認專案名稱，再改其他東西。尤其在 worktree 環境裡，光是修正這一點，帶來的改善常常就比任何 prompt 微調都更大。

要求結構，不要只說摘要

更強的結構要求，往往能立刻提升可讀性。你可以指定這類章節：

• 專案起源
• 早期建置階段
• 關鍵轉折點
• 收斂或擴張階段
• 當前走向

這能幫助技能產出更容易掃讀、也更方便重用的報告。

不要只停留在時間順序

常見失敗模式，是 timeline 讀起來像一串按日期排列的筆記。想改善 timeline-report usage，請主動要求它做出解讀：

• "group events into phases"
• "identify the main inflection points"
• "explain what changed after each pivot"
• "highlight recurring themes"

拿到第一版後再精修

完成第一輪後，不要整份重來，先下一次聚焦的修訂要求：

• 要求縮短
• 要求更偏向高階主管可讀
• 要求更強調產品決策而不是技術細節
• 要求補上一段對專案方向的最終評估

這裡很適合用迭代，因為歷史基底不變，改的是編輯呈現方式。

讓技能對準正確成果

當你要的是故事性、發展弧線與演進脈絡時，就該用 timeline-report skill。但如果你真正需要的是技術文件、相依性分析，或 repo onboarding，請盡早換工具。選對工具，往往是提升結果品質最快的方法。