timeline-report

Visión general de timeline-report skill

Qué hace timeline-report

La timeline-report skill convierte el historial registrado de claude-mem de un proyecto en un informe narrativo de desarrollo. En lugar de ofrecer un resumen plano del estado actual del código, reconstruye la historia de cómo evolucionó el proyecto con el tiempo: fases principales, giros, decisiones y patrones de avance.

Cuándo encaja mejor timeline-report para Report Writing

Usa timeline-report for Report Writing cuando necesites un documento legible sobre la historia del proyecto, no solo una lista de eventos en bruto. Es una muy buena opción para founders, maintainers, reviewers, consultants o agents que necesitan explicar qué ocurrió a lo largo de la vida del proyecto con un estilo coherente tipo "Journey Into [Project]".

El trabajo real que resuelve

La mayoría de los usuarios no buscan un resumen genérico. Quieren responder preguntas como:

• ¿Cuáles son los grandes capítulos del desarrollo de este proyecto?
• ¿Cómo fue evolucionando el trabajo con el tiempo?
• ¿Qué cambió, qué se frenó o qué se aceleró?
• ¿Cómo convierto datos de timeline en un informe que otra persona realmente pueda leer?

Ahí es donde timeline-report skill resulta más útil que un prompt normal.

Qué hace diferente a timeline-report

El principal factor diferencial es que timeline-report está construido alrededor del timeline persistente de claude-mem, y no solo sobre una inspección puntual del repo. Eso importa si buscas una narrativa histórica, y no únicamente "qué archivos existen ahora". También incluye una guía de flujo de trabajo para resolver correctamente el nombre del proyecto, con una comprobación práctica de worktree para que el informe apunte al proyecto padre y no al directorio equivocado.

Qué necesitas antes de instalarlo

La skill solo encaja bien si se cumplen estas dos condiciones:

• el worker de claude-mem está corriendo en localhost:37777
• el proyecto ya tiene observaciones registradas en claude-mem

Si falta cualquiera de estos requisitos previos, timeline-report install por sí solo no basta; la skill tendrá poco o ningún historial útil que analizar.

Cuándo esta skill no es una buena opción

Omite timeline-report skill si solo necesitas:

• un resumen de la arquitectura actual
• un changelog basado únicamente en Git
• una descripción del proyecto en un párrafo
• reporting para un proyecto sin historial de claude-mem

En esos casos, normalmente será más simple usar un prompt directo u otra skill de análisis de repositorios.

Cómo usar timeline-report skill

Contexto de instalación de timeline-report

La evidencia del repositorio muestra que la skill vive en plugin/skills/timeline-report dentro de thedotmack/claude-mem. El patrón base de instalación es:

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

Después de instalarla, verifica el entorno antes de culpar a la calidad de la salida:

1. confirma que el worker de claude-mem está disponible en localhost:37777
2. confirma que el proyecto objetivo tiene observaciones registradas
3. confirma que conoces el nombre correcto bajo el que se guarda el timeline del proyecto

Lee primero este archivo

Empieza por aquí:

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

Esta skill depende sobre todo del flujo de trabajo, y el mayor riesgo de adopción no es una configuración oculta; es invocarla sobre el proyecto equivocado o sobre un timeline vacío.

Ten claro cuál es la entrada obligatoria

La entrada más importante es el nombre del proyecto tal como lo conoce claude-mem. Si el usuario dice "este proyecto", la guía de la skill sugiere usar el basename del directorio actual, pero solo después de comprobar si estás dentro de un git worktree.

Ese detalle importa porque los worktrees suelen tener nombres de directorio que no coinciden con el timeline del proyecto padre.

Maneja correctamente los git worktrees

El detalle práctico más importante de la skill original es la comprobación de worktree. Si estás en un worktree, usa la identidad del proyecto padre en lugar del nombre de la carpeta del worktree. La calidad del informe puede parecer "rota" si el nombre de proyecto incorrecto apunta a una memoria escasa o no relacionada.

Si no estás seguro, resuelve primero el git common directory y deduce a partir de ahí el proyecto padre antes de pedir el informe.

Cómo se ve timeline-report usage en la práctica

Una petición débil:

• "Write a report on this repo"

Una petición más sólida de 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."

Una petición todavía mejor:

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

Convierte un objetivo difuso en un prompt sólido

Para obtener mejores resultados, incluye estos elementos en el prompt:

• nombre exacto del proyecto
• audiencia objetivo
• formato deseado del informe
• áreas de énfasis
• nivel de detalle

Ejemplo:

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

Esto es mejor que "summarize the project history" porque acota el tono y la estructura de salida.

Flujo de trabajo recomendado para una salida fiable

Un flujo de trabajo práctico:

1. identifica el nombre correcto del proyecto
2. verifica que existen datos de timeline en claude-mem
3. pide el informe en formato narrativo
4. revisa si la salida se centra demasiado en la cronología bruta
5. vuelve a ejecutarlo con instrucciones más claras sobre audiencia, secciones y énfasis

Esta skill se aprovecha mejor de forma iterativa. La primera pasada obtiene el arco temporal; la segunda lo convierte en un informe mejor construido.

Qué conviene pedirle a la skill que enfatice

Algunas opciones útiles de énfasis son:

• hitos principales por encima de eventos menores
• giros de arquitectura o de producto
• progresión hacia la preparación para release
• periodos de debugging o recuperación
• patrones en la toma de decisiones
• temas que expliquen la dirección del proyecto

Sin esta guía, los informes de timeline pueden volverse largos pero poco útiles para tomar decisiones.

Cómo evitar una salida genérica

Para evitar que timeline-report suene como un resumen plano, pide explícitamente:

• fases en lugar de listas de eventos
• explicaciones causales en lugar de solo marcas temporales
• "why this mattered" después de cada cambio importante
• una valoración final sobre la trayectoria del proyecto

Eso empuja la salida hacia un informe real, y no hacia un volcado de memoria.

Bloqueos habituales durante timeline-report install y uso

Los principales bloqueos son operativos, no de estilo:

• el worker de claude-mem no está corriendo
• el proyecto no tiene observaciones
• se está usando el nombre de proyecto equivocado
• se confunde el nombre de un worktree con el del proyecto padre
• el usuario espera un análisis del código actual en lugar de un análisis histórico

Si la adopción falla, revisa estos puntos antes de reescribir el prompt.

Preguntas frecuentes sobre timeline-report skill

¿Es timeline-report mejor que un prompt normal?

Sí, si tu objetivo es generar informes sobre la historia del proyecto a partir de datos de claude-mem. Un prompt normal puede pedir una narrativa, pero timeline-report skill ya encuadra la tarea como análisis histórico del desarrollo y para el caso de uso "Journey Into [Project]".

¿timeline-report es apta para principiantes?

En general sí, siempre que el entorno ya exista. El patrón de uso es simple, pero quienes empiezan pueden atascarse con los requisitos previos: tener el worker en ejecución, contar con observaciones almacenadas y resolver correctamente el nombre del proyecto.

¿Necesito un repositorio con mucha historia?

No necesariamente, pero la skill aporta mucho más valor cuando el timeline tiene suficiente densidad como para revelar fases y cambios a lo largo del tiempo. Una memoria escasa produce informes poco sustanciosos.

¿Puedo usar timeline-report sin claude-mem?

No. La skill depende explícitamente de los datos de timeline de claude-mem y del worker en localhost:37777. Sin ese ecosistema, esta no es la herramienta adecuada.

¿Cuándo no debería usar timeline-report para Report Writing?

No uses timeline-report for Report Writing si necesitas:

• una auditoría del código en su estado actual
• una revisión de seguridad
• documentación de API
• un changelog derivado exclusivamente de Git
• análisis de un proyecto que nunca fue seguido en claude-mem

¿timeline-report también analiza el código actual?

Su valor principal es la narrativa histórica, no la inspección completa del repo. Puedes combinarla con otros pasos de análisis, pero la skill en sí está orientada a la historia de desarrollo basada en observaciones de memoria.

¿Por qué timeline-report devolvió una salida floja o vaga?

Normalmente porque ocurrió una de estas cosas:

• los datos del timeline son escasos
• se apuntó al proyecto equivocado
• el prompt no especificó la audiencia ni el formato del informe
• el usuario pidió un resumen amplio en lugar de un informe narrativo estructurado

Cómo mejorar timeline-report skill

Dale a timeline-report un briefing de reporting preciso

La mejora de calidad más importante suele venir de un mejor briefing. Dile a timeline-report:

• para quién es el informe
• si quieres narrativa o resumen ejecutivo
• qué temas debe sacar a la superficie
• qué debe dejar en segundo plano

Ejemplo:

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

Proporciona primero la identidad correcta del proyecto

Si el informe parece incompleto, verifica el nombre del proyecto antes de cambiar cualquier otra cosa. En configuraciones con worktrees especialmente, esta única corrección puede mejorar la salida más que cualquier ajuste del prompt.

Pide estructura, no solo resumen

Una solicitud de estructura más sólida suele mejorar la legibilidad de inmediato. Pide secciones como:

• origen del proyecto
• fase inicial de construcción
• puntos de inflexión
• consolidación o escalado
• trayectoria actual

Esto ayuda a que la skill produzca un informe fácil de escanear y reutilizar.

Ve más allá de la cronología

Un fallo habitual es que el timeline se lea como una serie de notas fechadas. Mejora timeline-report usage pidiendo interpretación:

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

Mejora la salida después del primer borrador

Después de la primera pasada, haz una única petición de revisión enfocada en lugar de empezar desde cero:

• pide que lo acorte
• pide que tenga un enfoque más ejecutivo
• pide que dé prioridad a decisiones de producto sobre detalle técnico
• pide que añada una valoración final sobre la dirección del proyecto

La iteración funciona bien aquí porque la base histórica se mantiene y lo que mejora es el encuadre editorial.

Ajusta la skill al resultado adecuado

Usa timeline-report skill cuando quieras historia, arco narrativo y contexto de evolución. Si en realidad necesitas documentación técnica, análisis de dependencias o onboarding del repo, cambia de herramienta cuanto antes. Elegir mejor la herramienta adecuada es la forma más rápida de mejorar los resultados.