work-timeline-planner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Work Timeline Planner

工作时间线规划工具

Turn evidence such as git history, project documents, user descriptions, and chat notes into a readable timeline report. The output can be Markdown, standalone HTML, or both.

Use this skill for two main cases:

retrospective review: what was done over a past period, across one project or multiple projects
forward planning: what should happen next, when, and in what sequence

将git历史记录、项目文档、用户描述和聊天记录等信息转化为可读性强的时间线报告。输出格式支持Markdown、独立HTML，或同时生成两种格式。

本工具主要适用于两类场景：

回顾性复盘：总结某一时间段内单个或多个项目的完成工作
前瞻性规划：制定后续工作的内容、时间节点和执行顺序

Skill Directory Layout

工具目录结构

text

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

text

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

Progressive Loading

渐进式加载规则

Always read
```
references/evidence-model.md
```
Read
```
references/report-modes.md
```
when choosing between personal review, mentor report, planning report, or a hybrid
Read
```
references/output-formats.md
```
when choosing between Markdown, HTML, or both, or when deciding between Mermaid, Frappe Gantt, and Plotly

Use

templates/timeline-report.md

and

templates/timeline-report.html

as the output skeletons

必须阅读
```
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

作为输出模板框架

Core Principles

核心原则

Timeline blocks should be evidence-backed, not just commit-count-backed
Commits are signals, not the full story; combine them with docs, notes, and user context
Prefer a few meaningful work blocks over a noisy commit-by-commit chart
Distinguish observed facts from inferred date ranges
Keep audience in mind: personal multi-project review is broader; mentor-facing single-project reports should be tighter and more explanatory
For planning, separate committed work from optional or stretch work
Choose the lightest chart technology that still fits the user's use case

时间线模块需有证据支撑，不能仅基于提交次数
提交记录是信号而非完整事实；需结合文档、笔记和用户上下文信息
优先呈现少量有意义的工作模块，而非杂乱的逐提交图表
区分已观测事实与推断的时间范围
考虑受众需求：个人多项目复盘范围更广；面向导师的单项目报告需更紧凑、更具解释性
规划时，区分已确定的工作与可选或拓展性工作
选择最轻量化且符合用户需求的图表技术

Step 1 — Classify the Request

步骤1 — 分类请求

Identify the primary mode before gathering evidence:

```
personal-review
```
: review past work, often across multiple projects
```
mentor-report
```
: summarize past work for one project and one audience
```
next-phase-plan
```
: plan upcoming work with milestones and dependencies
```
hybrid
```
: summarize recent work and then propose the next phase

Also identify:

time window
project scope
audience
desired level of granularity
output format:
```
markdown
```
,
```
html
```
, or
```
both
```
chart engine:
```
mermaid
```
,
```
frappe-gantt
```
, or
```
plotly
```

If the user did not specify a time window, infer a reasonable one from context and state it explicitly in the report.

Default output policy:

```
markdown
```
+
```
mermaid
```
for shareable repo-native reports
```
html
```
+
```
frappe-gantt
```
for richer interactive review
```
both
```
when the user wants an archiveable report plus a better local visualization

在收集证据前，先确定主要模式：

```
personal-review
```
：复盘过往工作，通常涉及多个项目
```
mentor-report
```
：为特定受众总结单个项目的过往工作
```
next-phase-plan
```
：规划未来工作的里程碑和依赖关系
```
hybrid
```
：总结近期工作并提出下一阶段计划

同时明确：

时间窗口
项目范围
受众
所需粒度
输出格式：
```
markdown
```
、
```
html
```
或
```
both
```
图表引擎：
```
mermaid
```
、
```
frappe-gantt
```
或
```
plotly
```

若用户未指定时间窗口，需根据上下文推断合理范围，并在报告中明确说明。

默认输出策略：

可共享的原生仓库报告使用
```
markdown
```
+
```
mermaid
```
更丰富的交互式复盘使用
```
html
```
+
```
frappe-gantt
```
当用户需要可存档报告+本地可视化时，选择
```
both
```

Step 2 — Gather Evidence

步骤2 — 收集证据

Prefer primary evidence first.

For each in-scope repo, gather:

bash

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

Then layer in:

project docs such as
```
README.md
```
,
```
docs/
```
,
```
PROJECT.md
```
,
```
decision-log
```
, experiment logs, or progress notes
user-provided notes or descriptions
user-provided chat excerpts or meeting notes

If the user wants a multi-project review, gather evidence per project and keep project boundaries explicit.

If one or more repos or notes are missing, ask only for the minimum missing inputs needed to avoid hallucinating the timeline.

优先收集原始证据。

针对每个范围内的仓库，收集以下信息：

bash

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
```
、决策日志、实验日志或进度笔记
用户提供的笔记或描述
用户提供的聊天片段或会议记录

若用户需要多项目复盘，需按项目收集证据，并明确区分项目边界。

若缺少部分仓库或笔记，仅询问必要的缺失信息，避免凭空生成时间线。

Step 3 — Build Work Blocks

步骤3 — 构建工作模块

Convert raw evidence into a small set of work blocks.

Each block should have:

project
title
date range
type: implementation, experiment, debugging, writing, infra, planning, reporting, or review
evidence basis
short outcome

Do not map one commit to one Gantt task unless the user explicitly wants that level of detail.

Instead:

merge related commits into one coherent block
split blocks when the goal clearly changed
use docs or notes to explain periods where work happened but commits alone are sparse

When a date range is inferred rather than explicit, say so in the text summary.

将原始证据转化为少量工作模块。

每个模块需包含：

所属项目
标题
时间范围
类型：实现、实验、调试、文档编写、基础设施、规划、汇报或评审
证据依据
简短成果

除非用户明确要求，否则不要将单个提交映射为单个甘特图任务。

正确做法：

将相关提交合并为一个连贯模块
当目标明显变化时拆分模块
当提交记录稀疏但存在工作时，使用文档或笔记补充说明

若时间范围为推断而非明确给出，需在文本总结中注明。

Step 4 — Choose the Report Shape

步骤4 — 选择报告结构

Follow the guidance in

references/report-modes.md

As a default:

for
```
personal-review
```
, group by project, then by workstream
for
```
mentor-report
```
, group by project phase or deliverable, not by every technical branch
for
```
next-phase-plan
```
, group by milestone and dependency

The final output should usually contain:

a short scope summary
an evidence note
a chart or timeline visualization
a concise narrative summary of the key blocks
optional next-phase actions

遵循

references/report-modes.md

中的指导。

默认规则：

```
personal-review
```
：按项目分组，再按工作流分组
```
mentor-report
```
：按项目阶段或交付成果分组，而非每个技术分支
```
next-phase-plan
```
：按里程碑和依赖关系分组

最终输出通常应包含：

简短的范围摘要
证据说明
图表或时间线可视化
关键模块的简洁叙述总结
可选的下一阶段行动建议

Step 5 — Write the Output Report(s)

步骤5 — 编写输出报告

references/output-formats.md

For Markdown output, use

templates/timeline-report.md

as the base structure.

For HTML output, use

templates/timeline-report.html

as the base structure.

The chart engine should usually be chosen like this:

```
mermaid
```
: default for lightweight Markdown reports kept in a repo or shared in chat
```
frappe-gantt
```
: default for standalone HTML that the user wants to inspect locally with a better UI
```
plotly
```
: use only when you already have clean structured task data and want an interactive timeline, especially from Python-driven workflows

For Markdown, the default Gantt should be Mermaid:

markdown

```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

undefined

Guidelines:

use one section per project or milestone group
keep task names short
prefer readable blocks over exact but cluttered detail
mark completed retrospective work with
```
done
```
when useful
mark current or planned work with
```
active
```
or plain future tasks only when the timing is justified
for HTML output, prefer one self-contained file over a many-file mini app unless the user explicitly wants a larger artifact

遵循

references/output-formats.md

中的指导。

Markdown输出以

templates/timeline-report.md

为基础结构。

HTML输出以

templates/timeline-report.html

为基础结构。

图表引擎的选择规则：

```
mermaid
```
：存储在仓库或聊天中共享的轻量Markdown报告默认使用
```
frappe-gantt
```
：用户本地查看的独立HTML报告默认使用，具备更优UI
```
plotly
```
：仅当已有清晰结构化任务数据，且需要交互式时间线时使用，尤其适用于Python驱动的工作流

Markdown的默认甘特图使用Mermaid：

markdown

```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

undefined

指导原则：

每个项目或里程碑组使用一个章节
任务名称保持简短
优先可读模块而非精确但杂乱的细节
必要时用
```
done
```
标记已完成的回顾性工作
仅当时间合理时，用
```
active
```
标记当前或计划中的工作，或直接标记未来任务
HTML输出优先使用单文件独立结构，除非用户明确需要多文件小型应用

Step 6 — Add Planning When Needed

步骤6 — 按需添加规划内容

If the user wants forward planning:

separate completed work from planned work
identify dependencies and blockers
propose milestone-sized blocks, not pseudo-precise day-by-day fiction
mark uncertainty explicitly

For planning, include:

priority
dependency
expected outcome
owner, if relevant

若用户需要前瞻性规划：

区分已完成工作与计划工作
识别依赖关系和障碍
提出里程碑级别的模块，而非虚假精确的逐日计划
明确标记不确定性

规划内容需包含：

优先级
依赖关系
预期成果
负责人（如有）

Step 7 — Sanity-Check Before Finalizing

步骤7 — 最终确认前的检查

Before presenting the report, check:

all major blocks are supported by actual evidence
the time window is stated explicitly
multi-project reports do not blur project ownership
mentor-facing reports explain outcomes, not just activity
planned work is not mixed with already completed work
the chosen chart syntax or embedded data is structurally valid

提交报告前，检查以下内容：

所有主要模块均有实际证据支撑
时间窗口已明确说明
多项目报告未混淆项目归属
面向导师的报告解释成果而非仅活动
计划工作与已完成工作未混合
所选图表语法或嵌入数据结构有效

Output Expectations

输出预期

The final output should usually be a document the user can keep or share.

If asked to save it into a repo, use a path that matches the user's purpose, for example:

```
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
```

If the user only wants a draft in chat, still structure it as if it could be saved directly to a file.

最终输出应为用户可保存或共享的文档。

若要求保存到仓库，需使用符合用户用途的路径，例如：

```
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
```

若用户仅需要聊天中的草稿，仍需按可直接保存到文件的结构编写。