work-timeline-planner

作業タイムラインプランナー

Git の履歴、プロジェクト資料、ユーザーの説明、チャットのメモなどのエビデンスから、読みやすいタイムラインレポートを作成します。出力形式は Markdown、単体の HTML、またはその両方を選べます。

このスキルは、主に次の 2 つのケースで使用します。

• 振り返り：過去の一定期間に、1 つまたは複数のプロジェクトで行った作業を振り返る
• 今後の計画：次に行う作業、その時期、実施順序を計画する

スキルディレクトリの構成

<installed-skill-dir>/
├── SKILL.md
├── references/
│   ├── evidence-model.md
│   ├── output-formats.md
│   └── report-modes.md
└── templates/
    ├── timeline-report.html
    └── timeline-report.md

段階的な読み込み

• 必ず references/evidence-model.md を読みます
• 個人の振り返り、メンター向けレポート、計画レポート、またはハイブリッドのどれを選ぶか判断する際は、references/report-modes.md を読みます
• Markdown、HTML、またはその両方のどれを選ぶか、あるいは Mermaid、Frappe Gantt、Plotly のどれを使うか判断する際は、references/output-formats.md を読みます
• 出力のひな形として templates/timeline-report.md と templates/timeline-report.html を使用します

基本原則

• タイムラインのブロックは、コミット数だけでなく、エビデンスに基づくものにします
• コミットは手がかりであり、全体像ではありません。資料、メモ、ユーザーの状況も組み合わせます
• コミットごとの細かすぎる図よりも、意味のある作業ブロックを少数にまとめることを優先します
• 観測された事実と、推定された日付範囲を区別します
• 対象読者を考慮します。複数プロジェクトにまたがる個人の振り返りは幅広くまとめ、メンター向けの単一プロジェクトレポートは、より焦点を絞って詳しく説明します
• 計画では、確定した作業と、任意または追加目標の作業を分けます
• ユーザーの用途に適した範囲で、最もシンプルなグラフ技術を選びます

ステップ 1 — リクエストを分類する

エビデンスを集める前に、主なモードを特定します。

• personal-review：過去の作業を振り返る。多くの場合、複数のプロジェクトが対象です
• mentor-report：1 つのプロジェクトと 1 人の読者を対象に、過去の作業をまとめる
• next-phase-plan：マイルストーンと依存関係を含め、今後の作業を計画する
• hybrid：最近の作業をまとめてから、次のフェーズを提案する

以下も特定します。

• 期間
• プロジェクトの対象範囲
• 対象読者
• 希望する詳細度
• 出力形式：markdown、html、または both
• グラフエンジン：mermaid、frappe-gantt、または plotly

ユーザーが期間を指定していない場合は、文脈から妥当な期間を推定し、レポート内で明示します。

出力形式のデフォルトポリシー：

• 共有しやすいリポジトリ内レポートには、markdown + mermaid
• よりリッチでインタラクティブな振り返りには、html + frappe-gantt
• アーカイブ可能なレポートと、ローカルで見やすいビジュアライゼーションの両方が必要な場合は、both

ステップ 2 — エビデンスを集める

まず、一次エビデンスを優先します。

対象範囲に含まれる各リポジトリについて、以下を集めます。

git rev-parse --show-toplevel
git log --date=short --stat --reverse --since="<start-date>" --until="<end-date>"
git log --date=short --pretty=format:"%ad%x09%h%x09%s" --since="<start-date>" --until="<end-date>"

次に、以下を加えます。

• README.md、docs/、PROJECT.md、decision-log、実験ログ、進捗メモなどのプロジェクト資料
• ユーザーから提供されたメモや説明
• ユーザーから提供されたチャットの抜粋や議事録

複数プロジェクトの振り返りを希望された場合は、プロジェクトごとにエビデンスを集め、プロジェクト間の境界を明確に保ちます。

リポジトリやメモが不足している場合は、タイムラインを捏造しないために必要な最小限の情報だけを尋ねます。

ステップ 3 — 作業ブロックを作成する

生のエビデンスを、少数の作業ブロックにまとめます。

各ブロックには以下を含めます。

• プロジェクト
• タイトル
• 期間
• 種類：実装、実験、デバッグ、執筆、インフラ、計画、報告、またはレビュー
• エビデンスの根拠
• 簡潔な成果

ユーザーがその詳細度を明示的に希望していない限り、1 つのコミットを 1 つのガントタスクに対応させないでください。

代わりに、以下のようにします。

• 関連するコミットを、まとまりのある 1 つのブロックに統合する
• 目的が明らかに変わった箇所で、ブロックを分割する
• コミットだけでは情報が少ない期間に作業が行われていた場合は、資料やメモを使って説明する

日付範囲を明示的な情報ではなく推定から導いた場合は、文章の要約でそのことを伝えます。

ステップ 4 — レポートの形式を選ぶ

references/report-modes.md のガイダンスに従ってください。

デフォルトでは、次のようにします。

• personal-review の場合は、プロジェクトごとに分類し、その後、作業ストリームごとに分類します
• mentor-report の場合は、技術的な分岐ごとではなく、プロジェクトのフェーズまたは成果物ごとに分類します
• next-phase-plan の場合は、マイルストーンと依存関係ごとに分類します

最終出力には、通常、次の内容を含めます。

• 簡潔なスコープの概要
• エビデンスに関する注記
• 図表またはタイムラインのビジュアル表示
• 主要なブロックを簡潔にまとめた説明
• 必要に応じた次のフェーズのアクション

ステップ 5 — 出力レポートを作成する

references/output-formats.md に従ってください。

Markdown 出力には、基本構成として templates/timeline-report.md を使用します。

HTML 出力には、基本構成として templates/timeline-report.html を使用します。

通常、チャートエンジンは次のように選択します。

• mermaid：リポジトリに保存したり、チャットで共有したりする軽量な Markdown レポートのデフォルト
• frappe-gantt：ユーザーがローカルで、より使いやすい UI を使って確認したい単独の HTML のデフォルト
• plotly：構造化されたタスクデータがすでに整っており、特に Python 主導のワークフローでインタラクティブなタイムラインが必要な場合にのみ使用

Markdown では、デフォルトのガントチャートに Mermaid を使用します。

```mermaid
gantt
    title Example
    dateFormat  YYYY-MM-DD
    section Project A
    Baseline experiments :done, a1, 2026-04-01, 5d
    Model fixes          :done, a2, after a1, 4d
    Next ablation        :active, a3, 2026-04-12, 6d

ガイドライン：

• プロジェクトまたはマイルストーングループごとにセクションを 1 つ設けます
• タスク名は短くします
• 正確でも煩雑な詳細より、読みやすいブロックを優先します
• 役立つ場合は、完了した過去の作業に done を付けます
• 時期に根拠がある場合に限り、現在または計画中の作業に active、または通常の未来タスクを付けます
• HTML 出力では、ユーザーが明示的に大規模な成果物を希望しない限り、複数ファイルの小規模アプリよりも自己完結型の単一ファイルを優先します

ステップ 6 — 必要に応じて計画を追加する

ユーザーが今後の計画を希望する場合：

1. 完了した作業と計画中の作業を分けます
2. 依存関係とブロッカーを特定します
3. 日ごとの見せかけの精密さではなく、マイルストーン単位のブロックを提案します
4. 不確実性を明示します

計画には次の内容を含めます。

• 優先度
• 依存関係
• 期待される成果
• 関連する場合は担当者

ステップ 7 — 最終化する前に妥当性を確認する

レポートを提示する前に、次を確認します。

• 主要なブロックすべてが実際のエビデンスに基づいている
• 対象期間が明示されている
• 複数プロジェクトのレポートで、プロジェクトごとの担当範囲が曖昧になっていない
• メンター向けレポートでは、活動だけでなく成果も説明している
• 計画中の作業を完了済みの作業と混同していない
• 選択したチャート構文または埋め込みデータが構造的に有効である

出力に関する期待事項

最終出力は通常、ユーザーが保存または共有できるドキュメントにします。

リポジトリへの保存を依頼された場合は、目的に合ったパスを使用します。たとえば、次のとおりです。

• docs/reports/work_timeline_YYYY_MM.md
• docs/reports/mentor_update_YYYY_MM.md
• docs/plans/next_phase_timeline.md
• docs/reports/work_timeline_YYYY_MM.html
• docs/reports/mentor_update_YYYY_MM.html

チャットでの下書きのみを希望する場合でも、そのままファイルに保存できるような構成にします。