Agent skill
talk-stage2-research
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.
Install this agent skill to your Project
npx add-skill https://github.com/FlorianBruniaux/claude-code-ultimate-guide/tree/main/examples/skills/talk-pipeline/stage-2-research
SKILL.md
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.mdtalks/{YYYY}-{slug}-changelog-analysis.mdtalks/{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
{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
# 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 — prerequisite
- Stage 3: Concepts — reads this timeline
- Orchestrator
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
eval-skills
Audit all skills in the current project for frontmatter completeness, effort level appropriateness, allowed-tools scoping, and content quality. Produces a scored report with effort-level recommendations for each skill. Use when onboarding to a new project, reviewing skill quality before shipping, or adding effort fields to an existing skill library.
git-ai-archaeology
Analyze AI config evolution in a git repo — first commits per path, monthly distribution, major PRs, maturity phases
design-patterns
Detect, suggest, and evaluate GoF design patterns in TypeScript/JavaScript codebases. Use when refactoring code, applying singleton/factory/observer/strategy patterns, reviewing pattern quality, or finding stack-native alternatives for React, Angular, NestJS, and Vue.
rtk-optimizer
Wrap high-verbosity shell commands with RTK to reduce token consumption. Use when running git log, git diff, cargo test, pytest, or other verbose CLI output that wastes context window tokens.
pr-triage
4-phase PR backlog management with audit, deep code review, validated comments, and optional worktree setup. Use when triaging pull requests, catching up on pending code reviews, or managing a backlog of open PRs. Args: 'all' to review all, PR numbers to focus (e.g. '42 57'), 'en'/'fr' for language, no arg = audit only.
guide-recap
Transform CHANGELOG entries into social content (LinkedIn, Twitter/X, Newsletter, Slack) in FR + EN. Use after releases or weekly to generate release notes, announcements, social media posts, or recap summaries from guide updates.
Didn't find tool you were looking for?