talk-stage2-research

# 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

1. **Reads the summary** — understands the period and themes from Stage 1
2. **Git archaeology** — extracts velocity metrics (read-only commands only)
3. **Changelog analysis** — scans releases, features, documented metrics
4. **Cross-references** — aligns git, CHANGELOG, and summary
5. **Builds the timeline** — verified dates, not estimated
6. **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)

```bash
# 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

```markdown
# 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

```markdown
# 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
{Pivots, 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

```markdown
# Factual Timeline — {slug}

**Period**: {start} → {end} ({n} months)
**Cross-referenced sources**: Summary × Git history × 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 × {CHANGELOG path} × {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

## Related

- [Stage 1: Extract](../stage-1-extract/SKILL.md) — prerequisite
- [Stage 3: Concepts](../stage-3-concepts/SKILL.md) — reads this timeline
- [Orchestrator](../orchestrator/SKILL.md)