version: "1.0.1" name: talk-stage2-research description: "Performs git archaeology, changelog analysis, and builds a verified factual timeline by cross-referencing git history with source material. REX mode only (skipped automatically in Concept mode). Use when building a REX talk and you need verified commit metrics, release timelines, and contributor data from a git repository." allowed-tools: Write Read Bash effort: low

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)

# 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

Related

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