rewind

Rewind

Show me this code as it was, and explain what changed. Not a raw diff — an annotated evolution that explains WHY each change was made, which changes were intentional design decisions, and which were accumulated patches.

Workflow

1. Parse Arguments

• File is required. If not provided, ask the user which file to rewind.
• Period is optional. Default: 3 months ago. Accepts: "3 months ago", "6 months ago", "before the auth refactor", a commit hash, a date.

2. Find the Historical Version

With timewarp-mcp (preferred): Call timewarp_history with the file and period to get structured commit data — this tells you total commits, classifications, and authors for the file during the rewind period. Use this to understand the volume and nature of changes before diving into individual commits. If timewarp_trends is available, use it to note whether the file is still on a growth/churn trajectory today.

Rename detection: Before looking up the historical version, check if the file was renamed: git log --follow --diff-filter=R --format="%H %s" -- {file}. If a rename is found, use the old path for historical lookups. Note the rename in the output: "This file was renamed from {old-path} to {new-path} on {date}."

Then find the specific historical commit:

# Find the commit closest to the requested time
git log --oneline --before="{date}" -1 -- {file}

# Or if a commit hash was given, use it directly
git show {commit}:{file}

If the file didn't exist at the requested time, find the earliest version:

git log --oneline --diff-filter=A --follow -- {file}

3. Read Both Versions

Read the historical version and the current version. Note:

• Lines added, removed, modified
• Functions added or removed
• Imports added or removed
• Structural changes (reorganization, new classes, extracted helpers)

4. Annotate the Differences

Annotate the top 8-10 most significant changes between the two versions. If there are more changes, note the remainder count: "...and N additional minor changes not annotated." This limit keeps the report focused on what matters.

For each significant change, find the commit(s) that introduced it and explain WHY:

# Find commits between the two points
git log --oneline {old-commit}..HEAD -- {file}

Classify each change:

• Intentional design decision — planned feature, deliberate refactor, architectural change
• Bug fix — correcting broken behavior (note what was broken)
• Accumulated patch — small fixes layered on without holistic rethinking
• Dependency-driven — changed because a dependency changed
• Unknown — commit message doesn't explain the reasoning

5. Present

Report format:

## Rewind — {file}

**Then:** {date/commit} ({lines} lines, {functions} functions)
**Now:** {lines} lines, {functions} functions
**Changes:** +{added} -{removed} lines across {n} commits

### Summary
{2-3 sentences: what's fundamentally different and why}

### Key Changes

1. **{Change description}** (commit {hash}, {date})
   Type: {design decision / bug fix / accumulated patch / dependency-driven}
   Why: {from commit message / PR context / inferred}
   Lines: +{n} -{n}

2. **{Another major change}** (commit {hash}, {date})
   Type: {classification}
   Why: {why it happened}
   Lines: +{n} -{n}

### What Stayed the Same
{What hasn't changed — core API, fundamental approach, key abstractions.
This is useful for understanding what's stable vs volatile.}

### Observations
{Any patterns: "most changes are bug fixes in the validation logic, suggesting
it's under-tested" or "the core algorithm hasn't changed, just the interfaces around it"}

6. Cache Results

Save results to .timewarp/rewind-{sanitized-file}-{date}.json with:

• Historical version metadata (commit hash, date, line count, function count)
• Current version metadata
• List of annotated changes with classifications
• Stability summary

Path sanitization: Replace / with -- and remove leading dots in the filename. Example: src/services/auth-service.ts becomes src--services--auth-service.ts.

Read existing caches: Before starting, check .timewarp/ for:

• drift-* files — if the same file has drift data, note whether changes align with drift
• forecast-* files — if the file is on a concerning trajectory, mention it
• dissect-* files — if complexity archaeology exists, reference the structural commits

Guidelines

• Annotate the IMPORTANT changes, not every single diff line. Group related changes (multiple commits fixing the same bug) into single entries.
• "Unknown" is an honest annotation. If the commit message says "fix" with no context, don't fabricate an explanation.
• "What Stayed the Same" is as valuable as what changed — it tells the developer what they can trust as stable.
• If very little changed, say so. "This file is remarkably stable — 3 minor fixes in 6 months" is a useful finding.

Related Skills

• /dissect — For deeper analysis of HOW a specific complexity layer was added
• lenskit /explain — For understanding the current code in full context

Additional Resources

• references/rewind-patterns.md — Change classification rubric, annotation methodology, "What Stayed the Same" detection guidance