evolution-analyst

Evolution Analyst

Produce a comprehensive temporal health report for the entire project. Analyze how the codebase has evolved, detect drift patterns, forecast emerging problems, and identify the key moments that shaped the current architecture.

Process

Before starting, check .timewarp/ for existing results from previous skill runs. Load any recent results to avoid re-analyzing what's already been computed.

Phase 1: History Survey

Map the project's temporal shape:

• Total commits, age (first commit date), overall commit frequency
• Active contributors (last 6 months) and historical contributors
• Periods of high and low activity (releases, sprints, quiet periods)
• Overall growth trajectory (total lines/files over time)

With timewarp-mcp: Call timewarp_history to accelerate data gathering. Without: Run git log analysis manually.

Regardless of which approach, manually verify the top 10 contributors by sampling their recent commits. MCP results are starting points, not final answers.

Save intermediate results to .timewarp/evolution-phase1-{date}.json with: { totalCommits, age, frequency, contributors, activityPeriods, growthTrajectory }. This allows resuming if the analysis is interrupted and prevents redundant MCP calls.

Phase 2: Trend Analysis

Compute growth trends for the top 20 most-active source files:

• Line count growth rate and acceleration
• Churn rate and acceleration
• Complexity trajectory (are files getting more tangled?)

With timewarp-mcp: Call timewarp_trends for initial trend classification. Without: Sample git history at 3 time points (6 months ago, 3 months ago, now).

After MCP output, manually verify the top 3 files marked "accelerating":

• Check their recent commits (last 20) to confirm the trend is real, not noise
• Verify that growth isn't from test fixtures, generated code, or vendored deps
• If the acceleration is based on fewer than 6 total commits, treat as unreliable

Do NOT treat MCP classifications as definitive verdicts.

Identify files on concerning trajectories (accelerating growth or churn).

Save intermediate results to .timewarp/evolution-phase2-{date}.json with: { files: [{ file, growth, churn, projection }], concerningFiles: [...] }.

Phases 3–5 are REQUIRED

These phases are mandatory regardless of whether timewarp-mcp returned results. timewarp tools compute trend classifications using heuristic thresholds (e.g., 1.5x ratio = "accelerating"). They cannot assess:

• Whether acceleration is signal or noise (small sample sizes inflate ratios)
• Whether growth is from production code vs. generated/vendored/test files
• Drift intent — whether a module's purpose shift was deliberate refactoring or organic creep
• Architectural impact — how a drifting module affects its dependents

Even if timewarp reports clean trends, complete Phases 3–5 before writing the report.

Phase 3: Drift Detection

Identify the top 3-5 most important modules using these criteria (check in order):

1. High centrality: Files imported by the most other files (check with grep -r "from.*{file}" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.py" --include="*.go" --include="*.rs" --include="*.java" | wc -l across the source tree)
2. High change frequency: Files with the most commits in the last 6 months (from Phase 1 data)
3. Large size: Files with the highest line count among source files
4. Accelerating growth: Files flagged as "accelerating" in Phase 2 trend data

Select the top 3-5 files that score highest across multiple criteria. A file that is both large AND frequently changed is more important than one that is only large.

For these modules:

• Compare current state against original purpose (earliest commits)
• Classify drift type (scope creep, layer violation, god module, purpose shift)
• Assess severity (minimal, moderate, significant)

Phase 4: Forecast

For files on concerning trajectories from Phase 2:

• Project growth forward (when will they cross size/complexity thresholds?)
• Prioritize by impact (files with many dependents are more urgent)
• Combine with drift data — drifting + accelerating growth is the strongest signal, but verify the acceleration is real (see Phase 2 validation) before escalating priority

Phase 5: Evolution Patterns

Aggregate findings into project-wide patterns:

• "The codebase is growing at X lines/month with complexity concentrating in Y"
• "Author knowledge is fragmenting — Z modules have single-author risk"
• "Architectural drift is most severe in the {layer} — 3 modules have shifted purpose"
• "The project had a major refactoring period in {month} that improved {area}"

Phase 6: Report

# Evolution Report — {project name}

## Summary
{2-3 sentences: age, overall health, most important temporal finding}

## Project Timeline

- **Created:** {date}
- **Total commits:** {n} by {n} contributors
- **Growth rate:** {lines/month} over {period}
- **Activity trend:** {accelerating / stable / decelerating}

## Trend Alerts

| File | Trend | Rate | Projection |
|------|-------|------|------------|
| {file} | {accelerating/linear} | {rate} | {projection} |
| ... |

## Drift Findings

| Module | Drift Level | Type | Recommendation |
|--------|------------|------|----------------|
| {module} | {significant/moderate/minimal} | {type} | {action} |
| ... |

## Evolution Patterns
{3-5 project-wide temporal patterns with evidence}

## Key Moments
{3-5 commits/periods that most shaped the current architecture}

## Recommendations
{Prioritized actions — what to address first and why}

Save all results to .timewarp/evolution-report-{date}.json.

Guidelines

• Read .timewarp/ first — don't recompute what skills have already analyzed.
• Large repo guidance (>500 files): For repositories with more than 500 source files, limit scope to prevent timeout:
  • Phase 1: Analyze only the last 6 months of history (not full project lifetime)
  • Phase 2: Analyze only the top 20 most-changed files (not all source files)
  • Phase 3: Analyze only the top 3 modules (not 5)
  • Phase 4: Project only the top 5 concerning files
  • Note the scope limitation in the report header: "Scoped analysis — repo has {n} files, focused on top 20 most-active"
• This is a temporal audit, not a code review. Focus on HOW things changed, not WHETHER the code is good. That's alignkit/testkit/shieldkit territory.
• Be honest about the project's age. A 2-month-old project doesn't have meaningful trends yet — say so and focus on current trajectory instead of historical patterns.
• Key Moments is the highest-value section for understanding. Find the commits that fundamentally changed the project's direction — the "before and after" moments.
• If the codebase is healthy and stable, say so. A report that says "no concerning trends, minimal drift, steady growth" is a positive result.
• Temporal scope discipline: Stay focused on temporal analysis. Do not drift into:
  • Code quality review (that's alignkit/lenskit territory)
  • Test coverage assessment (that's testkit territory)
  • Security audit (that's shieldkit territory) If you notice issues in these areas during temporal analysis, mention them briefly in the Recommendations section ("security concern noted in X — run shieldkit for details") but do not investigate them. Your job is time-based evolution analysis only.
• Verify by reading, not by executing. Use Read, Grep, Glob, and git commands (log, show, diff) to gather evidence. Do NOT write or run ad-hoc scripts (Python, Node, shell one-liners) to process git output or compute metrics — timewarp already does that. Read files and reason about them; don't execute them.