timeline-report

Visão geral da skill timeline-report

O que a timeline-report faz

A skill timeline-report transforma o histórico registrado no claude-mem de um projeto em um relatório narrativo de desenvolvimento. Em vez de entregar um resumo raso do estado atual do código, ela reconstrói a história de como o projeto evoluiu ao longo do tempo: fases principais, mudanças de direção, decisões e padrões de progresso.

Melhor encaixe da timeline-report para redação de relatórios

Use timeline-report for Report Writing quando você precisa de um documento legível sobre a trajetória do projeto, e não apenas de eventos brutos. Ela é mais indicada para founders, maintainers, reviewers, consultores ou agentes que precisam explicar o que aconteceu ao longo da vida de um projeto em um formato coeso, no estilo "Journey Into [Project]".

O trabalho real que ela resolve

A maioria dos usuários não está procurando uma recapitulação genérica. O que eles querem responder é:

• Quais são os grandes capítulos no desenvolvimento deste projeto?
• Como o trabalho evoluiu ao longo do tempo?
• O que mudou, travou ou acelerou?
• Como transformar dados de timeline em um relatório que outra pessoa realmente consiga ler?

É aí que a skill timeline-report é mais útil do que um prompt comum.

O que diferencia a timeline-report

O principal diferencial é que a timeline-report foi construída em torno da timeline persistente do claude-mem, e não apenas de uma inspeção pontual do repositório. Isso faz diferença se o seu objetivo é uma narrativa histórica, e não só "quais arquivos existem agora". Ela também traz orientação de workflow para resolver o nome correto do projeto, incluindo uma checagem prática de worktree para garantir que o relatório aponte para o projeto pai, e não para o diretório errado.

O que você precisa antes de instalar

A skill só é uma boa escolha se estas duas condições forem verdadeiras:

• o worker do claude-mem está rodando em localhost:37777
• o projeto já tem observações registradas no claude-mem

Se qualquer um desses pré-requisitos estiver faltando, timeline-report install por si só não resolve; a skill terá pouco ou nenhum histórico útil para analisar.

Quando esta skill não é a melhor escolha

Evite a timeline-report skill se você só precisa de:

• um resumo da arquitetura atual
• um changelog baseado apenas em Git
• uma descrição do projeto em um único parágrafo
• relatórios para um projeto sem histórico no claude-mem

Nesses casos, um prompt direto ou outra skill de análise de repositório costuma ser mais simples.

Como usar a skill timeline-report

Contexto de instalação da timeline-report

As evidências no repositório mostram que a skill fica em plugin/skills/timeline-report dentro de thedotmack/claude-mem. O padrão básico de instalação é:

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

Depois de instalar, valide o ambiente antes de culpar a qualidade da saída:

1. confirme que o worker do claude-mem está disponível em localhost:37777
2. confirme que o projeto de destino tem observações registradas
3. confirme que você sabe o nome correto sob o qual a timeline do projeto foi armazenada

Leia este arquivo primeiro

Comece por:

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

Esta skill é guiada principalmente por workflow, e o maior risco de adoção não está em alguma configuração escondida; está em executá-la contra o projeto errado ou contra uma timeline vazia.

Entenda a entrada obrigatória

A entrada mais importante é o nome do projeto tal como é conhecido pelo claude-mem. Se o usuário disser "este projeto", a orientação da skill sugere usar o basename do diretório atual, mas só depois de verificar se você está dentro de um git worktree.

Esse detalhe importa porque worktrees frequentemente têm nomes de diretório que não correspondem à timeline do projeto pai.

Trate git worktrees da forma correta

O detalhe prático mais importante na skill original é a checagem de worktree. Se você estiver em um worktree, use a identidade do projeto pai em vez do nome da pasta do worktree. A qualidade do relatório pode parecer "quebrada" se o nome errado do projeto apontar para uma memória esparsa ou sem relação.

Se houver dúvida, resolva primeiro o diretório comum do Git e derive a partir dele o projeto pai antes de pedir o relatório.

Como o uso da timeline-report aparece na prática

Um pedido fraco:

• "Write a report on this repo"

Um pedido de timeline-report usage mais forte:

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

Um pedido ainda melhor:

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

Transforme um objetivo vago em um prompt forte

Para obter os melhores resultados, inclua estes elementos no prompt:

• nome exato do projeto
• público-alvo
• formato desejado do relatório
• áreas de ênfase
• nível de detalhe

Exemplo:

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

Isso funciona melhor do que "summarize the project history" porque restringe o tom e a estrutura da saída.

Workflow sugerido da timeline-report para saída confiável

Um workflow prático:

1. identifique o nome correto do projeto
2. verifique se existem dados de timeline no claude-mem
3. peça o relatório em formato narrativo
4. revise se a saída está focando demais na cronologia bruta
5. execute novamente com instruções mais claras sobre público, seções e ênfase

A timeline-report funciona melhor de forma iterativa. A primeira passada captura o arco da timeline; a segunda transforma isso em um relatório melhor acabado.

O que pedir para a timeline-report enfatizar

Opções úteis de ênfase incluem:

• marcos importantes em vez de eventos menores
• mudanças de direção de arquitetura ou produto
• progressão rumo à prontidão para release
• períodos de debugging ou recuperação
• padrões na tomada de decisão
• temas que expliquem a direção do projeto

Sem esse tipo de orientação, relatórios de timeline podem ficar longos, mas menos úteis para tomada de decisão.

Como evitar uma saída genérica

Para impedir que a timeline-report soe como um resumo sem graça, peça explicitamente:

• fases em vez de listas de eventos
• explicações causais em vez de apenas timestamps
• "why this mattered" após mudanças importantes
• uma avaliação final da trajetória do projeto

Isso empurra a saída para um relatório de verdade, em vez de um dump de memória.

Bloqueios comuns na instalação e no uso da timeline-report

Os principais bloqueios são operacionais, não de estilo:

• o worker do claude-mem não está rodando
• o projeto não tem observações
• o nome errado do projeto foi usado
• o nome do worktree foi confundido com o do projeto pai
• o usuário espera análise do código atual, quando a skill foi feita para análise histórica

Se a adoção falhar, cheque esses pontos antes de reescrever o prompt.

FAQ da skill timeline-report

A timeline-report é melhor do que um prompt normal?

Sim, se o seu objetivo é produzir relatórios sobre a história do projeto a partir dos dados do claude-mem. Um prompt comum pode pedir uma narrativa, mas a timeline-report skill já estrutura a tarefa em torno da análise histórica do desenvolvimento e do caso de uso "Journey Into [Project]".

A timeline-report é amigável para iniciantes?

Em grande parte, sim, desde que o ambiente já exista. O padrão de uso é simples, mas iniciantes podem travar nos pré-requisitos: rodar o worker, ter observações armazenadas e resolver o nome correto do projeto.

Eu preciso de um repositório com histórico longo?

Não necessariamente, mas a skill se torna muito mais valiosa quando a timeline tem densidade suficiente para revelar fases e mudanças ao longo do tempo. Memória esparsa gera relatórios superficiais.

Posso usar timeline-report sem claude-mem?

Não. A skill depende explicitamente dos dados de timeline do claude-mem e do worker em localhost:37777. Sem esse ecossistema, esta é a ferramenta errada.

Quando eu não devo usar timeline-report para Report Writing?

Não use timeline-report for Report Writing se você precisa de:

• uma auditoria do código no estado atual
• uma revisão de segurança
• documentação de API
• um changelog puramente derivado de Git
• análise de um projeto que nunca foi acompanhado no claude-mem

A timeline-report também analisa o código atual?

O valor central dela é a narrativa histórica, não uma inspeção completa do repositório. Você pode combiná-la com outras etapas de análise, mas a skill em si é voltada ao histórico de desenvolvimento a partir das observações de memória.

Por que a timeline-report retornou uma saída fraca ou vaga?

Normalmente porque aconteceu uma destas coisas:

• os dados de timeline são esparsos
• o projeto errado foi escolhido
• o prompt não especificou o público nem o formato do relatório
• o usuário pediu um resumo amplo em vez de um relatório narrativo estruturado

Como melhorar a skill timeline-report

Dê à timeline-report um briefing de relatório preciso

O maior salto de qualidade vem de um briefing melhor. Diga à timeline-report:

• para quem é o relatório
• se você quer narrativa ou resumo executivo
• quais temas devem aparecer
• o que deve receber menos destaque

Exemplo:

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

Informe primeiro a identidade correta do projeto

Se o relatório parecer incompleto, verifique o nome do projeto antes de mudar qualquer outra coisa. Em setups com worktree especialmente, essa única correção pode melhorar mais a saída do que qualquer ajuste de prompt.

Peça estrutura, não apenas resumo

Um pedido por estrutura mais forte costuma melhorar a legibilidade imediatamente. Peça seções como:

• origem do projeto
• fase inicial de construção
• pontos de virada
• consolidação ou escala
• trajetória atual

Isso ajuda a skill a produzir um relatório que as pessoas conseguem escanear e reaproveitar.

Vá além da cronologia

Um modo de falha comum é uma timeline que soa como notas datadas. Melhore o timeline-report usage pedindo interpretação:

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

Melhore a saída depois do primeiro rascunho

Depois da primeira passada, faça um pedido de revisão focado em vez de começar do zero:

• peça para encurtar
• peça para deixar mais executivo
• peça para enfatizar decisões de produto acima de detalhes técnicos
• peça para adicionar uma avaliação final sobre a direção do projeto

A iteração funciona bem aqui porque a base histórica permanece a mesma, enquanto o enquadramento editorial melhora.

Alinhe a skill ao resultado certo

Use a timeline-report skill quando você quiser história, arco narrativo e contexto de desenvolvimento. Se o que você realmente precisa é documentação técnica, análise de dependências ou onboarding no repositório, troque de ferramenta cedo. Tomar a decisão certa de encaixe é a forma mais rápida de melhorar os resultados.