Retrospective

Skill: Retrospective

What This Skill Does

Reconstructs "why" documentation from git history that generate-docs cannot produce. While generate-docs analyzes the current codebase (what exists now), retrospective analyzes the project's evolution (how it got here and why).

Produces:

• Architecture Decision Records (ADRs): significant technical decisions detected from large refactors, dependency changes, or structural reorganizations
• Module Chronology: when each module was introduced, major changes, and growth patterns
• Pattern Evolution: how coding patterns changed over time (e.g., callback → promise → async/await migration)
• Contributor Map: who owns which areas of the codebase (based on commit concentration)

When to Use

• When onboarding to an existing project with no documentation
• When the team asks "why was this built this way?"
• When preparing architecture documentation for a project with years of history
• After generate-docs has created the "what" docs, to add the "why" context

Do NOT use this for projects with fewer than ~50 commits — there isn't enough history to analyze meaningfully.

Execution Model

• Phase 1: the primary agent gathers git metadata (lightweight, git commands only).
• Phase 2: the primary spawns doc-explorer to write the retrospective documents based on the gathered metadata.
• Rationale: Phase 1 is cheap (git log parsing). Phase 2 requires writing multiple documents, which is doc-explorer's domain.

Workflow

Step 1: Assess Git History Scope

Get a high-level picture of the project's history:

# Total commits and date range
git log --oneline | wc -l
git log --reverse --format="%ai" | head -1
git log --format="%ai" | head -1

# Contributors
git shortlog -sn --no-merges | head -10

# Most changed files (hotspots)
git log --format=format: --name-only | sort | uniq -c | sort -rn | head -20

If the project has fewer than 50 commits, inform the user and suggest generate-docs instead.

Step 2: Detect Significant Events

Scan the git history for events that indicate architectural decisions:

1. Large commits (>20 files changed): likely refactors or structural changes

   git log --oneline --shortstat | awk '/files? changed/ {if ($1 > 20) print prev" "$0} {prev=$0}'
   

2. Dependency changes: additions/removals of major dependencies

   git log --oneline --all -- package.json pyproject.toml go.mod Cargo.toml
   

3. New directories: creation of new top-level or module directories

   git log --diff-filter=A --oneline --name-only -- '*/README.md' '*/index.*' '*/mod.*' '*/main.*'
   

4. Renames/moves: structural reorganization

   git log --diff-filter=R --summary --oneline | head -30
   

5. Merge patterns: feature branches, release branches

   git log --merges --oneline | head -20
   

Step 3: Analyze Key Events

For each significant event detected in Step 2, gather context:

• Read the commit message (often contains rationale)
• Check the diff stats (which files/directories were affected)
• Look for related commits in the surrounding timeframe
• Check for PR/merge commit messages that may contain discussion summaries

Do NOT read full diffs — this would be extremely expensive. Use --stat and commit messages only.

Step 4: Build Module Timeline

For each module (directory) in the project, construct a timeline:

# When was it created?
git log --reverse --oneline --diff-filter=A -- <module_path>/ | head -1

# Major milestones (commits with >5 files changed in this module)
git log --oneline --shortstat -- <module_path>/ | head -20

Step 5: Detect Pattern Evolution

Look for patterns that changed over time:

• File extension changes (.js → .ts: TypeScript migration)
• Directory structure changes (flat → nested: modularization)
• Config file additions (ESLint, TypeScript, Docker: tooling adoption)
• Test framework changes

Step 6: Generate Retrospective Documents

Delegate to doc-explorer with the gathered metadata. The subagent writes:

1. docs/retrospective.md — overview of the project's evolution with timeline
2. docs/adrs/ — individual ADR files for each detected significant decision. You MUST use the exact same heading structure and order as adr-create:

# ADR-NNN: <Title>

## Status

Accepted | Proposed | Superseded by ADR-NNN

## Date

<YYYY-MM-DD, inferred from commit date>

## Context
<what was happening in the project at the time, detected from git>

## Decision
<what was changed and why (inferred from commit messages and diff patterns)>

## Alternatives Considered

### Alternative A: <name>
- **Pros**: ...
- **Cons**: ...
- **Why rejected**: ...

### Alternative B: <name>
- **Pros**: ...
- **Cons**: ...
- **Why rejected**: ...

## Consequences

### Positive
- <expected benefit based on observed outcomes>

### Negative
- <expected downside or trade-off>

### Risks
- <what could go wrong>

## References

- Commit: <hash> — <message>
- Files affected: <count>

Step 7: Present Summary

Present a summary of findings to the user and ask:

• Are the inferred decisions accurate?
• Should any be merged, split, or removed?
• Is there additional context the user can provide for ambiguous events?

Rules

1. Git metadata only: use git log, git shortlog, git diff --stat. Never read full file contents from historical commits. The goal is to reconstruct context from metadata, not to re-analyze old code.
2. Infer, don't fabricate: clearly mark inferred decisions with language like "appears to be" or "likely motivated by". The git history provides evidence, not certainty.
3. Commit messages are gold: well-written commit messages are the primary source of "why" information. Poorly written messages ("fix", "update") provide less value — note this in the retrospective.
4. Focus on decisions, not changes: the goal is to document WHY things changed, not WHAT changed. Module docs already cover the "what".
5. Chronological order: present events in chronological order. This helps readers understand the project's evolution narrative.
6. Reasonable scope: for projects with >1000 commits, focus on the top 10-20 most significant events. Do not attempt to document every commit.
7. No built-in explore agent: do NOT use the built-in explore subagent type.