timeline-report

timeline-reportスキルの概要

timeline-reportでできること

timeline-report は、プロジェクトに記録された claude-mem の履歴を、物語として読める開発レポートに変換するスキルです。現在のコードベースを平面的に要約するのではなく、プロジェクトが時間とともにどう進化したかを再構成し、主要フェーズ、方向転換、意思決定、進捗のパターンまで含めて描き出します。

レポート作成でtimeline-reportが特に向いている場面

読みやすいプロジェクト履歴ドキュメントが必要で、単なるイベント一覧では足りないなら、timeline-report for Report Writing が適しています。特に、創業者、メンテナー、レビュー担当者、コンサルタント、エージェントなど、プロジェクト全体の歩みを「Journey Into [Project]」のような一貫したストーリーとして説明したい人に向いています。

timeline-reportが解決する本当の課題

多くのユーザーが欲しいのは、汎用的な振り返りではありません。知りたいのは、たとえば次のようなことです。

• このプロジェクト開発の大きな章立ては何か
• 作業は時間とともにどう変化してきたか
• 何が変わり、何が停滞し、何が加速したか
• タイムラインのデータを、他人が実際に読めるレポートにどう落とし込むか

こうした問いに答えるとき、timeline-reportスキルは普通のプロンプトより実用的です。

timeline-reportが他と違う理由

最大の違いは、timeline-report が場当たり的なリポジトリ調査だけでなく、claude-mem の永続的なタイムラインを前提に作られている点です。欲しいのが「今あるファイルの説明」ではなく、歴史のあるナラティブなら、この違いは重要です。

さらに、正しいプロジェクト名を特定するための運用ガイダンスも含まれており、特に worktree 環境では、誤ったディレクトリではなく親プロジェクトを対象にレポートするための実践的な確認手順が用意されています。

インストール前に必要なこと

このスキルが有効なのは、次の2条件をどちらも満たしている場合だけです。

• claude-mem worker が localhost:37777 で動作している
• 対象プロジェクトに claude-mem の観測履歴がすでに記録されている

どちらかが欠けている場合、timeline-report install だけでは不十分です。分析できる履歴自体がほとんど、あるいはまったく存在しないため、有用な結果は得にくくなります。

timeline-reportスキルが向かないケース

次の用途だけが目的なら、timeline-report skill は見送ったほうがよいです。

• 現在のアーキテクチャ概要が欲しい
• Git だけから changelog を作りたい
• 1段落で済むプロジェクト説明が欲しい
• claude-mem 履歴がないプロジェクトをレポートしたい

この場合は、直接プロンプトを書くか、別の repo 分析スキルを使うほうがシンプルです。

timeline-reportスキルの使い方

timeline-reportのインストール前提

リポジトリ上の情報を見ると、このスキルは thedotmack/claude-mem 内の plugin/skills/timeline-report にあります。基本のインストール方法は次のとおりです。

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

インストール後、出力品質を疑う前に、まず環境を確認してください。

1. claude-mem worker が localhost:37777 で利用可能か確認する
2. 対象プロジェクトに観測履歴が記録されているか確認する
3. タイムラインがどのプロジェクト名で保存されているか、正しく把握しているか確認する

最初に読むべきファイル

まず確認したいのは次のファイルです。

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

このスキルは設定中心ではなく、ワークフロー中心です。導入時の最大のつまずきポイントは、隠れた設定ではなく、空のタイムラインや誤ったプロジェクトに対して実行してしまうことです。

必須入力を理解する

もっとも重要な入力は、claude-mem が認識している project name です。ユーザーが「このプロジェクト」とだけ言う場合、スキルのガイダンスでは現在のディレクトリ名を使う案が示されていますが、その前に git worktree 内かどうかを確認することが勧められています。

この点は重要です。worktree では、ディレクトリ名と親プロジェクトのタイムライン名が一致しないことがよくあります。

git worktreeを正しく扱う

上流のスキルで特に実務的に効くのが、worktree の確認です。worktree 内にいる場合は、worktree フォルダ名ではなく、親プロジェクトの識別子を使う必要があります。誤った project name を指定すると、参照される memory が薄かったり無関係だったりして、レポート品質が「壊れている」ように見えることがあります。

迷ったら、まず 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."

曖昧な依頼を強いプロンプトに変える

より良い結果を得るには、次の要素をプロンプトに含めるのが有効です。

• 正確な project name
• 想定読者
• 求めるレポートの形
• 強調したい観点
• 詳細度

例:

• "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."

これは単に「プロジェクト履歴を要約して」と頼むよりも、トーンと出力構成をきちんと制約できるぶん、はるかに有効です。

安定した出力を得るための推奨ワークフロー

実践的な流れは次のとおりです。

1. 正しい project name を特定する
2. claude-mem のタイムラインデータが存在することを確認する
3. ナラティブ形式でレポートを依頼する
4. 出力が時系列の羅列に寄りすぎていないか確認する
5. 読者・セクション構成・強調点を明確にして再実行する

このスキルは反復的に使うのが向いています。1回目でタイムラインの大きな流れをつかみ、2回目で読みやすいレポートとして整える、という使い方が効果的です。

timeline-reportで何を強調させるべきか

強調ポイントとして有用なのは、たとえば次のような観点です。

• 細かなイベントより主要マイルストーン
• アーキテクチャやプロダクトの方向転換
• リリース準備の進み方
• デバッグや復旧に費やした期間
• 意思決定のパターン
• プロジェクトの方向性を説明するテーマ

こうした指示がないと、timeline-report は長くても意思決定に使いにくいレポートになりがちです。

汎用的すぎる出力を避ける方法

timeline-report を無難な要約文で終わらせないためには、明示的に次を求めると効果的です。

• イベント列挙ではなくフェーズ分け
• タイムスタンプだけでなく因果の説明
• 大きな転換のたびに「なぜ重要だったか」を述べること
• 最後にプロジェクトの今後の軌道に対する評価を入れること

これにより、出力は単なる memory dump ではなく、実際に読めるレポートへ近づきます。

timeline-reportのインストール時・運用時によくある詰まりどころ

主な障害は、文体ではなく運用面にあります。

• claude-mem worker が起動していない
• プロジェクトに観測履歴がない
• 間違った project name を使っている
• worktree 名を親プロジェクト名と取り違えている
• ユーザーが履歴分析ではなく現在コードの分析を期待している

うまく導入できない場合、プロンプトを書き直す前にまずここを確認してください。

timeline-reportスキルのFAQ

timeline-reportは普通のプロンプトより優れている？

目的が claude-mem データを使ったプロジェクト履歴レポートなら、はい。通常のプロンプトでもナラティブは依頼できますが、timeline-report skill はもともと歴史的な開発分析と「Journey Into [Project]」という用途に合わせて設計されています。

timeline-reportは初心者でも使いやすい？

概ね使いやすいです。前提環境が整っていれば、使い方自体はシンプルです。ただし初心者は、worker の起動、観測履歴の保存、正しい project name の特定といった前提条件でつまずきやすいです。

長い履歴を持つリポジトリでないと使えない？

必須ではありません。ただし、timeline にある程度の密度があり、フェーズや変化が見えてくるほど、このスキルの価値は高まります。memory が疎だと、どうしても薄いレポートになります。

timeline-reportはclaude-memなしでも使える？

使えません。このスキルは明示的に claude-mem のタイムラインデータと localhost:37777 上の worker に依存しています。この仕組みがないなら、選ぶツールが違います。

レポート作成でtimeline-reportを使わないほうがいいのはいつ？

次のものが必要なら、timeline-report for Report Writing は使わないでください。

• 現在時点のコード監査
• セキュリティレビュー
• API ドキュメント
• Git 由来のみの changelog
• claude-mem で一度も追跡されていないプロジェクトの分析

timeline-reportは現在のコードベースも分析する？

このスキルの中核価値は、完全な repo 調査ではなく、履歴に基づくナラティブです。他の分析手順と組み合わせることはできますが、スキル自体の主眼は memory observation をもとにした開発履歴の可視化にあります。

timeline-reportの出力が弱い、または曖昧になるのはなぜ？

多くの場合、原因は次のいずれかです。

• タイムラインデータが疎い
• 対象プロジェクトを間違えている
• プロンプトで読者やレポート形式を指定していない
• 構造化されたナラティブではなく、広すぎる要約を求めている

timeline-reportスキルを改善する方法

timeline-reportには明確なレポート要件を渡す

品質を最も大きく左右するのは、依頼内容の精度です。timeline-report には少なくとも次を伝えてください。

• 誰向けのレポートか
• ナラティブが欲しいのか、エグゼクティブサマリーが欲しいのか
• どのテーマを表に出したいか
• 逆に何を弱めたいか

例:

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

まず正しいプロジェクト識別子を確認する

レポートが不完全に見えるなら、他を触る前に project name を確認してください。特に worktree 構成では、この1点を直すだけで、どんなプロンプト調整より大きく改善することがあります。

要約ではなく構造を求める

構成を明示するだけで、読みやすさがすぐ上がることは少なくありません。たとえば次のようなセクションを指定できます。

• プロジェクトの起点
• 初期構築フェーズ
• 転換点
• 収束・拡張フェーズ
• 現在の軌道

こうすると、スキルは流し読みしやすく再利用しやすいレポートを出しやすくなります。

単なる時系列を超えるよう促す

よくある失敗は、タイムラインが日付付きメモの羅列になってしまうことです。timeline-report usage を改善したいなら、解釈を明示的に求めてください。

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

初稿のあとで出力を磨く

最初の出力のあと、最初からやり直すのではなく、1回の焦点を絞った修正依頼を入れるのが効果的です。

• もっと短くしてほしいと頼む
• 経営層向けに寄せてほしいと頼む
• 技術詳細よりプロダクト判断を重視してほしいと頼む
• 最後にプロジェクトの方向性評価を追加してほしいと頼む

ここでは反復がよく効きます。履歴の土台はそのままに、編集上の見せ方だけを改善できるからです。

timeline-reportスキルは適切な用途で使う

timeline-report skill は、ストーリー性、全体のアーク、開発の文脈が欲しいときに使うべきです。本当に必要なのが技術ドキュメント、依存関係分析、repo オンボーディングなら、早めに別のツールへ切り替えたほうが結果は良くなります。適材適所の判断こそ、最短で品質を上げる方法です。