Talk Stage 2: Research (REX mode only)

Builds the git proof for a REX talk. Cross-references git history, CHANGELOG, and the Stage 1 summary to produce a verified timeline and velocity analysis.

Automatically skipped in --concept mode. Only runs when the source material is a REX with git repository access.

When to Use This Skill

After Stage 1 (Extract) when building a REX talk
When you have access to the project's git repository
To verify metrics mentioned in the source material against actual git data

What This Skill Does

Reads the summary: understands the period and themes from Stage 1
Git archaeology: extracts velocity metrics (read-only commands only)
Changelog analysis: scans releases, features, documented metrics
Cross-references: aligns git, CHANGELOG, and summary
Builds the timeline: verified dates, not estimated
Writes 3 output files

Input

talks/{YYYY}-{slug}-summary.md (from Stage 1, required)
repo_path: absolute path to the git repository
Optional: CHANGELOG path if different from {repo_path}/CHANGELOG.md

Output

Three files:

talks/{YYYY}-{slug}-git-archaeology.md
talks/{YYYY}-{slug}-changelog-analysis.md
talks/{YYYY}-{slug}-timeline.md

Git Commands (read-only only)

# Commits by month
git -C {repo_path} log --pretty=format:"%Y-%m" | sort | uniq -c

# Commits by contributor
git -C {repo_path} shortlog -sn --no-merges

# First and last date
git -C {repo_path} log --pretty=format:"%ad" --date=short | tail -1
git -C {repo_path} log --pretty=format:"%ad" --date=short | head -1

# Merged PRs (if merge commit convention)
git -C {repo_path} log --merges --oneline | wc -l

# Tags (releases)
git -C {repo_path} tag --sort=version:refname

# Velocity peak (busiest months)
git -C {repo_path} log --pretty=format:"%Y-%m" | sort | uniq -c | sort -rn | head -5

Output Formats

git-archaeology.md

# Git Archaeology: {slug}

**Repo**: {repo_path}
**Period analyzed**: {start date} -> {end date}
**Commands run**: {list}

## Global Metrics

| Metric | Value | Source |
|--------|-------|--------|
| Total commits | {n} | git log |
| Total merges/PRs | ~{n} | git log --merges |
| Total releases (tags) | {n} | git tag |
| Human contributors | {n} | git shortlog |
| Period covered | {n} months | first -> last date |

## Monthly Velocity

| Month | Commits | Notes |
|-------|---------|-------|
| {YYYY-MM} | {n} | {context if notable} |
...

## Contributors

| Rank | Name | Commits | % |
|------|------|---------|---|
| 1 | {name} | {n} | {%} |
...

---
*Generated by talk-stage2-research: {date}*

changelog-analysis.md

# Changelog Analysis: {slug}

**Source**: {CHANGELOG path}
**Releases analyzed**: {n} (v{first} -> v{last})

## Features by release (summary)

| Release | Date | Key features | Metrics mentioned |
|---------|------|--------------|------------------|
| {version} | {date} | {features} | {metrics} |
...

## Patterns identified

### Acceleration
{Periods of high velocity and what drove them}

### Inflection points
{Direction changes, major releases}

### Verifiable metrics in CHANGELOG
{Exhaustive list of numbers mentioned in CHANGELOG with their release}

---
*Generated by talk-stage2-research: {date}*

timeline.md

# Factual Timeline: {slug}

**Period**: {start} -> {end} ({n} months)
**Cross-referenced sources**: Summary x Git history x CHANGELOG

---

## Month-by-month timeline

| Month | Commits | Releases | Versions | Key features | Talk event |
|-------|---------|----------|----------|--------------|-----------|
| {YYYY-MM} | {n} | {n} | {versions} | {features} | {anecdote/event} |
...

## Cross-reference: Conflicts and inconsistencies

{If dates or metrics contradict between sources, note here}

---
*Generated by talk-stage2-research: {date}*
*Sources: git log x {CHANGELOG path} x {summary path}*

Key Rules

Read-only only: no git commands that modify repo state
Verify before asserting: a date not found in git = "unverified"
Cross-reference: flag inconsistencies between sources, don't pick one arbitrarily
Granularity: month by month minimum; week by week if the period is short (< 2 months)

Anti-patterns

Running git commands that modify the repository
Estimating dates instead of verifying them in git
Rounding metrics without flagging it
Silently merging contradictory data from different sources
Omitting quiet periods (plateaus tell a story too)

Validation Checklist

[ ] Only read-only git commands executed
[ ] Timeline covers the full period from summary
[ ] All metrics have an explicit source (git or CHANGELOG)
[ ] Conflicts between sources flagged in dedicated section
[ ] 3 files generated and saved

Tips

The timeline is what Stage 3 (Concepts) uses to enrich concept scores; a good timeline makes the concept catalogue stronger
"Quiet periods" in git velocity often correspond to hardest engineering challenges, worth noting
If the CHANGELOG has no version tags, fall back to date-based anchoring

Stage 1: Extract: prerequisite
Stage 3: Concepts: reads this timeline
Orchestrator