timeline-report

Overview of timeline-report skill

What timeline-report does

The timeline-report skill turns a project's recorded claude-mem history into a narrative development report. Instead of giving a flat summary of the current codebase, it reconstructs the story of how the project evolved over time: major phases, pivots, decisions, and progress patterns.

Best fit for Report Writing

Use timeline-report for Report Writing when you need a readable project-history document, not just raw events. It is best for founders, maintainers, reviewers, consultants, or agents who need to explain what happened across a project's lifespan in a coherent "Journey Into [Project]" style.

The real job to be done

Most users are not looking for a generic recap. They want to answer questions like:

• What are the major chapters in this project's development?
• How did the work evolve over time?
• What changed, stalled, or accelerated?
• How can I turn timeline data into a report someone else can actually read?

That is where the timeline-report skill is more useful than a normal prompt.

What makes timeline-report different

The main differentiator is that timeline-report is built around claude-mem's persistent timeline rather than ad hoc repo inspection alone. That matters if you want historical narrative, not just "what files exist now." It also includes workflow guidance for resolving the correct project name, including a practical worktree check so the report targets the parent project instead of the wrong directory.

What you need before installing

The skill is only a good fit if both of these are true:

• the claude-mem worker is running on localhost:37777
• the project already has claude-mem observations recorded

If either prerequisite is missing, timeline-report install is not enough by itself; the skill will have little or no useful history to analyze.

When this skill is a poor fit

Skip timeline-report skill if you only need:

• a current architecture summary
• a changelog from Git alone
• a one-paragraph project description
• reporting for a project with no claude-mem history

In those cases, a direct prompt or another repo-analysis skill is usually simpler.

How to Use timeline-report skill

Install context for timeline-report

The repository evidence shows the skill lives at plugin/skills/timeline-report inside thedotmack/claude-mem. The baseline install pattern is:

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

After installation, verify your environment before blaming output quality:

1. confirm the claude-mem worker is available on localhost:37777
2. confirm the target project has recorded observations
3. confirm you know the correct project name the timeline is stored under

Read this file first

Start with:

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

This skill is mostly workflow-driven, and the key adoption risk is not hidden configuration; it is invoking it against the wrong project or against an empty timeline.

Know the required input

The most important input is the project name as known to claude-mem. If the user says "this project," the skill guidance suggests using the current directory basename, but only after checking whether you are inside a git worktree.

That detail matters because worktrees often have directory names that do not match the parent project timeline.

Handle git worktrees correctly

The strongest practical detail in the upstream skill is the worktree check. If you are in a worktree, use the parent project's identity rather than the worktree folder name. The report quality can look "broken" if the wrong project name points to sparse or unrelated memory.

If you are unsure, resolve the git common directory first and derive the parent project from there before asking for the report.

What timeline-report usage looks like in practice

A weak request:

• "Write a report on this repo"

A stronger timeline-report usage request:

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

An even better request:

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

Turn a rough goal into a strong prompt

For best results, include these prompt ingredients:

• exact project name
• target audience
• desired report shape
• emphasis areas
• level of detail

Example:

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

This is better than "summarize the project history" because it constrains tone and output structure.

Suggested workflow for reliable output

A practical workflow:

1. identify the correct project name
2. verify claude-mem timeline data exists
3. ask for the report in narrative form
4. review whether the output over-focuses on raw chronology
5. rerun with clearer instructions on audience, sections, and emphasis

This skill is best used iteratively. The first pass gets the timeline arc; the second pass shapes it into a better report.

What to ask the skill to emphasize

Useful emphasis options include:

• major milestones over minor events
• architecture or product pivots
• release readiness progression
• debugging or recovery periods
• patterns in decision-making
• themes that explain the project's direction

Without this guidance, timeline reports can become long but less decision-useful.

How to avoid generic output

To keep timeline-report from sounding like a bland summary, explicitly ask for:

• phases instead of event lists
• causal explanations instead of timestamps alone
• "why this mattered" after major shifts
• a closing assessment of the project's trajectory

That pushes the output toward actual report writing rather than a memory dump.

Common blockers during timeline-report install and use

The main blockers are operational, not stylistic:

• claude-mem worker is not running
• the project has no observations
• the wrong project name is used
• a worktree name is mistaken for the parent project
• the user expects current-code analysis instead of historical analysis

If adoption fails, check these before rewriting the prompt.

timeline-report skill FAQ

Is timeline-report better than a normal prompt?

Yes, if your goal is project-history reporting from claude-mem data. A normal prompt can ask for a narrative, but timeline-report skill already frames the task around historical development analysis and the "Journey Into [Project]" use case.

Is timeline-report beginner-friendly?

Mostly yes, provided the environment already exists. The usage pattern is simple, but beginners may get stuck on prerequisites: running the worker, having stored observations, and resolving the correct project name.

Do I need a repository with a long history?

Not necessarily, but the skill is far more valuable when the timeline has enough density to reveal phases and changes over time. Sparse memory leads to thin reports.

Can I use timeline-report without claude-mem?

No. The skill explicitly depends on claude-mem timeline data and the worker on localhost:37777. Without that ecosystem, this is the wrong tool.

When should I not use timeline-report for Report Writing?

Do not use timeline-report for Report Writing if you need:

• a present-state code audit
• a security review
• API documentation
• a pure Git-derived changelog
• analysis of a project that was never tracked in claude-mem

Does timeline-report analyze the current codebase too?

Its core value is historical narrative, not full repo inspection. You can combine it with other analysis steps, but the skill itself is aimed at development history from memory observations.

Why did timeline-report return weak or vague output?

Usually because one of these happened:

• the timeline data is sparse
• the wrong project was targeted
• the prompt did not specify audience or report shape
• the user asked for a broad summary instead of a structured narrative report

How to Improve timeline-report skill

Give timeline-report a precise reporting brief

The biggest quality upgrade is a better brief. Tell timeline-report:

• who the report is for
• whether you want narrative or executive summary
• what themes to surface
• what to de-emphasize

Example:

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

Provide the right project identity first

If the report seems incomplete, verify the project name before changing anything else. In worktree setups especially, this single correction can improve output more than any prompt tweak.

Ask for structure, not just summary

A stronger structure request often improves readability immediately. Ask for sections such as:

• project origin
• early build phase
• turning points
• consolidation or scaling
• present trajectory

This helps the skill produce a report people can scan and reuse.

Push beyond chronology

A common failure mode is a timeline that reads like dated notes. Improve timeline-report usage by asking for interpretation:

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

Improve output after the first draft

After the first pass, do one focused revision request instead of starting over:

• ask to shorten
• ask to make it more executive-facing
• ask to emphasize product decisions over technical detail
• ask to add a final assessment of the project's direction

Iteration works well here because the historical base stays the same while the editorial framing improves.

Match the skill to the right outcome

Use timeline-report skill when you want story, arc, and developmental context. If what you really need is technical documentation, dependency analysis, or repo onboarding, switch tools early. Better fit decisions are the fastest way to improve results.