talk-stage1-extract

Original source / Raw SKILL.md

---
name: talk-stage1-extract
description: Stage 1 — Extract and structure source material into a talk summary. Auto-detects REX vs Concept type.
tags: [talk, pipeline, presentation, stage-1]
allowed-tools:
  - Write
  - Read
  - AskUserQuestion
---

# Talk Stage 1: Extract

Transforms raw material (article, transcript, notes, or a mix) into a structured summary ready for the pipeline's downstream stages. Auto-detects source type.

## When to Use This Skill

- Starting a new talk from any source material
- First step of the talk pipeline (always run before other stages)
- Auditing existing source material before committing to a talk

## What This Skill Does

1. **Collects metadata** — asks for slug, event, date, duration, audience, mode if not provided
2. **Reads the source** — loads the source file or inline content
3. **Detects source type** — REX (real-world proof) vs Concept (ideas/thesis) based on content signals
4. **Extracts the narrative arc** — chronological for REX, thematic for Concept
5. **Extracts metrics** — every measurable number with its source
6. **Identifies main themes** — 3-7 themes
7. **Flags gaps** — what's missing for a complete talk
8. **Writes `{slug}-summary.md`**

## Input

Required:
- Source file path or inline content (article `.mdx`, transcript `.md`, notes)
- Metadata: `slug`, `event`, `date`, `duration`, `audience`, `type` (--rex or --concept)

If metadata is missing → `AskUserQuestion` before proceeding.

## Output

`talks/{YYYY}-{slug}-summary.md`

## Source Type Detection

| REX signals | Concept signals |
|-------------|-----------------|
| Specific dates | Theses, arguments |
| Measured metrics | General observations |
| Project/tool names | Trend observations |
| Commits, releases, PRs | Analogies, metaphors |
| "I shipped", "We built" | "I think", "In my opinion" |

If hybrid → note both components in the summary.

## Output Format

```markdown
# Talk Summary — {Provisional Title}

**Slug** : {slug}
**Event** : {event}
**Date** : {date}
**Duration** : {duration} min
**Audience** : {audience description}
**Type detected** : REX | Concept | Hybrid
**Source** : {source file path}

---

## Narrative Arc

{Arc description: 3-5 sentences. Chronological if REX, thematic if Concept.}

## Main Themes

| # | Theme | Short description | Weight |
|---|-------|------------------|--------|
| 1 | {theme} | {description} | High/Medium/Low |
...

## Key Metrics Extracted

{All measurable numbers found in the source}

Format: `{value}` — {context} — Source: {section/page/git}

Examples:
- `1,200 commits` over 7 months — Source: "acceleration" section
- `-97% traffic` after SSE migration — Source: CHANGELOG v1.1.0

If none → "No verifiable metrics found (Concept mode)"

## Narrative Potential

{3-5 sentences on the strengths and possible narrative angles.
What makes this talk potentially strong. What might be missing.}

## Gaps Identified

- [ ] {gap 1} — {how to fill it}
- [ ] {gap 2} — {how to fill it}

If no obvious gaps → "No major gaps identified."

## Recommendations for next stages

- **Research**: {recommended / not applicable (Concept mode)} — {why}
- **Concepts**: {priority themes to explore}
- **Position**: {angles already visible from the source material}

---

*Generated by talk-stage1-extract — {date}*
*Source: {source path}*
```

## Metric Extraction Rules

- Do not round without indicating it
- Always include the metric's source
- If two sources contradict → flag both, do not pick one
- No invented metrics to fill gaps
- Use `{before} → {after}` format for evolutions

## Anti-patterns

- Vague summary ("This text is about AI...")
- Omitting metrics — even approximate ones with their source
- Hiding gaps — naming them is better than pretending they don't exist
- Changing the detected type without justification
- Inventing a narrative arc not present in the source

## Validation Checklist

- [ ] Source type detected and justified
- [ ] Narrative arc in 3-5 clear sentences
- [ ] All measurable metrics extracted with their source
- [ ] Main themes listed (3-7 max)
- [ ] Gaps explicitly identified
- [ ] File saved to `talks/{YYYY}-{slug}-summary.md`

## Tips

- Run this before the orchestrator if you want to verify the source material is usable
- The summary is the foundation — every downstream stage reads it
- Hybrid sources (part REX, part Concept) are fine — name both components clearly

## Related

- [Stage 2: Research](../stage-2-research/SKILL.md) — git archaeology (REX mode)
- [Stage 3: Concepts](../stage-3-concepts/SKILL.md) — reads this summary
- [Orchestrator](../orchestrator/SKILL.md) — runs all stages in sequence


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### ../stage-2-research/SKILL.md

```markdown
---
name: talk-stage2-research
description: Stage 2 (REX mode only) — Git archaeology, changelog analysis, verified factual timeline. Skip automatically in Concept mode.
tags: [talk, pipeline, presentation, stage-2, git]
allowed-tools:
  - Write
  - Read
  - Bash
---

# 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)

```

### ../stage-3-concepts/SKILL.md

```markdown
---
name: talk-stage3-concepts
description: Stage 3 — Build a numbered, scored concept catalogue. Every concept gets HIGH / MEDIUM / LOW talk-potential rating.
tags: [talk, pipeline, presentation, stage-3]
allowed-tools:
  - Write
  - Read
---

# Talk Stage 3: Concepts

Builds an exhaustive catalogue of all identifiable concepts in the source material. Each concept is numbered, categorized, and scored for its talk potential.

## When to Use This Skill

- After Stage 1 (and Stage 2 if REX mode)
- Before Stage 4 (Position needs the concept catalogue)
- When you want a structured inventory of what's available before choosing an angle

## What This Skill Does

1. **Reads the summary** — loads `{slug}-summary.md`
2. **Reads the timeline** (if available) — enriches scoring with verified dates
3. **Extracts concepts** — full scan of the source material
4. **Categorizes** — assigns each concept to a domain category
5. **Scores** — HIGH / MEDIUM / LOW for talk potential
6. **Optional repo enrichment** — if repo_path is provided, analyzes AI config concepts
7. **Writes output files**

## Input

- `talks/{YYYY}-{slug}-summary.md` (required)
- `talks/{YYYY}-{slug}-timeline.md` (optional — enriches REX concepts)
- `repo_path` (optional — for config/infrastructure concept extraction)

## Output

- `talks/{YYYY}-{slug}-concepts.md` (main catalogue)
- `talks/{YYYY}-{slug}-concepts-enriched.md` (if repo_path provided)

## Scoring Criteria

### HIGH — Strong potential
- Demonstrable live or with a screenshot
- Counter-intuitive or surprising (triggers a reaction)
- Associated with verifiable numbers
- Concrete and actionable (explainable in 30 seconds)
- Differentiator vs other talks on the same topic

### MEDIUM — Moderate potential
- Useful but expected (not surprising)
- Missing concrete proof or numbers
- Too specific to one particular context
- Needs too much explanation for a 30-min talk

### LOW — Weak potential
- Too abstract or philosophical without concrete grounding
- Already heavily covered by other speakers
- Requires specific technical background
- Hard to illustrate in a slide

**Scoring discipline**: Max 30% HIGH. If everything is HIGH, nothing is.

## Standard Categories

| Category | Description |
|----------|-------------|
| **Architecture** | Technical decisions, stack, structural patterns |
| **Tooling** | Tools, workflows, automations |
| **Philosophy** | Principles, mindsets, approaches |
| **Workflow** | Work processes, habits |
| **Knowledge Transfer** | Onboarding, team, knowledge sharing |
| **Problems** | Obstacles encountered, trade-offs |
| **Open Source** | Contributions, sharing, community |
| **AI Config** | AI configuration, profiles, knowledge feeding |
| **AI Infrastructure** | Agents, skills, hooks, commands |
| **AI Quality** | Review, tests, anti-patterns |
| **AI Security** | Security hooks, guardrails |
| **Optimization** | Performance, cost/token reduction |

Adapt or create categories if the talk has domain-specific areas.

## Output Format

### concepts.md

```markdown
# Key Concepts — {provisional title}

**Date**: {date}
**Source**: {source path} × Summary × Timeline (if available)

---

## Concept table

| # | Concept | Category | Short description | Talk potential |
|---|---------|----------|------------------|----------------|
| 1 | **{Concept name}** | {Category} | {1-2 concrete sentences} | HIGH / MEDIUM / LOW |
...

---

## Category breakdown

| Category | Count | HIGH concepts | Examples |
|----------|-------|---------------|---------|
| {category} | {n} | {n} | {examples} |
...
| **TOTAL** | **{N}** | **{N HIGH}** | |

---

## Recommendations for positioning

{3-5 sentences on concept clusters that could form the talk's acts.
Which HIGH concepts reinforce each other? What narrative arc is emerging?}
```

### concepts-enriched.md (if repo available)

Same structure but focused on what the repo analysis reveals:
- Specialized agents (count, size, roles)
- Invocable skills (catalogue, domains covered)
- System hooks (events, logic)
- Modular config (profiles, modules, pipeline)
- Project-specific code patterns

For each enriched concept, include:
- **Exact source**: file and approximate line
- **Demo-able**: yes/no (can it be shown in a slide or live?)

## Anti-patterns

- Creating overly granular concepts (one feature = one concept max)
- Scoring HIGH by default — be selective
- Omitting LOW concepts (they're useful in positioning as "angles to avoid")
- Duplicating very similar concepts (merge them instead)
- Analyzing repo code if the repo isn't accessible

## Validation Checklist

- [ ] Minimum 15 concepts identified (20+ for REX with repo)
- [ ] Each concept has a 1-2 sentence concrete description
- [ ] Scores are calibrated (not all HIGH, not all LOW)
- [ ] Categories cover the summary's themes
- [ ] Positioning recommendations present
- [ ] Files saved to correct paths

## Tips

- The concept catalogue is what Stage 4 (Position) draws from — the richer it is, the better the angle choices
- LOW concepts are valuable: they define the boundaries of what NOT to put in the talk
- If two concepts feel very similar, merge them — a smaller, sharper list beats a long diluted one

## Related

- [Stage 1: Extract](../stage-1-extract/SKILL.md) — prerequisite
- [Stage 2: Research](../stage-2-research/SKILL.md) — provides timeline (REX)
- [Stage 4: Position](../stage-4-position/SKILL.md) — reads this catalogue
- [Orchestrator](../orchestrator/SKILL.md)

```

### ../orchestrator/SKILL.md

```markdown
---
name: talk-pipeline
description: Orchestrator for the complete talk preparation pipeline (REX or Concept mode). Runs all 6 stages in sequence with human-in-the-loop checkpoints.
tags: [talk, pipeline, presentation, orchestrator]
allowed-tools:
  - Write
  - Read
  - AskUserQuestion
  - Task
---

# Talk Pipeline Orchestrator

Orchestrates the complete talk preparation pipeline — from raw material to revision sheets. Can run the full pipeline or a single isolated stage.

## Modes

- `--rex`: REX talk with git/code proof (changelog, commits, measured metrics)
- `--concept`: Conceptual talk from article, ideas, notes (skips Stage 2)

## Usage

```
/talk-pipeline                          # full pipeline, asks for context
/talk-pipeline --stage=extract          # run a single isolated stage
/talk-pipeline --rex                    # REX mode (git archaeology included)
/talk-pipeline --concept                # Concept mode (skip research)
/talk-pipeline --rex --slug=my-talk --event="Conf 2026" --date=2026-06-15 --duration=30
```

## Context Collection

Ask with AskUserQuestion if not provided:

```
- slug         : kebab-case identifier (e.g., my-talk-topic)
- event        : event name (e.g., Conf 2026, Tech Meetup)
- date         : talk date (YYYY-MM-DD)
- duration     : duration in minutes (e.g., 30)
- audience     : audience profile (e.g., senior devs, tech leads, non-tech)
- type         : --rex or --concept
- source_path  : path to source material (article .mdx, transcript .md, notes)
- repo_path    : (REX only) path to git repository for archaeology
```

## Workflow

1. **Collect context** — AskUserQuestion for required metadata
2. **Route by mode** — `--rex` vs `--concept` (skip Stage 2 if concept)
3. **Run Stage 1** — `/talk-stage1-extract` — always first
4. **Run Stages 2-4 in parallel** (after Stage 1 confirmed)
   - REX: extract → research + concepts + position (in parallel)
   - Concept: extract → concepts + position (in parallel, skip research)
5. **CHECKPOINT** — wait for angle + title choice (Stage 4 output)
6. **Run Stage 5** — `/talk-stage5-script` with validated choice
7. **Run Stage 6** — `/talk-stage6-revision`
8. **Final summary** — list all generated files with their paths

## Dependency Graph

```
         extract (Stage 1)
               |
    ┌──────────┼──────────┐
    v          v          v
research    concepts   position
(Stage 2)   (Stage 3)  (Stage 4)
[--rex only]            [CHECKPOINT]
    |          |          |
    └──────────┼──────────┘
               v
          script (Stage 5)
               |
               v
         revision (Stage 6)
```

## Stage Routing (--stage=X)

If `--stage` is provided, run only the corresponding skill:

| Stage | Skill to invoke |
|-------|----------------|
| extract | /talk-stage1-extract |
| research | /talk-stage2-research |
| concepts | /talk-stage3-concepts |
| position | /talk-stage4-position |
| script | /talk-stage5-script |
| revision | /talk-stage6-revision |

## Output Naming Convention

```
talks/{YYYY}-{slug}-summary.md           # extract
talks/{YYYY}-{slug}-git-archaeology.md   # research
talks/{YYYY}-{slug}-changelog-analysis.md
talks/{YYYY}-{slug}-timeline.md
talks/{YYYY}-{slug}-concepts.md          # concepts
talks/{YYYY}-{slug}-concepts-enriched.md
talks/{YYYY}-{slug}-angles.md            # position
talks/{YYYY}-{slug}-titre.md
talks/{YYYY}-{slug}-descriptions.md
talks/{YYYY}-{slug}-feedback-draft.md
talks/{YYYY}-{slug}-pitch.md             # script
talks/{YYYY}-{slug}-slides.md
talks/{YYYY}-{slug}-kimi-prompt.md
talks/{YYYY}-{slug}-revision-sheets.md   # revision
```

## Final Summary Format

After Stage 6 completes, display:

```
Pipeline complete. Files generated:

Stage 1 — Extract:
  ✓ talks/{YYYY}-{slug}-summary.md

Stage 2 — Research (REX only):
  ✓ talks/{YYYY}-{slug}-git-archaeology.md
  ✓ talks/{YYYY}-{slug}-changelog-analysis.md
  ✓ talks/{YYYY}-{slug}-timeline.md

Stage 3 — Concepts:
  ✓ talks/{YYYY}-{slug}-concepts.md
  ✓ talks/{YYYY}-{slug}-concepts-enriched.md (if repo available)

Stage 4 — Position:
  ✓ talks/{YYYY}-{slug}-angles.md
  ✓ talks/{YYYY}-{slug}-titre.md
  ✓ talks/{YYYY}-{slug}-descriptions.md
  ✓ talks/{YYYY}-{slug}-feedback-draft.md

Stage 5 — Script:
  ✓ talks/{YYYY}-{slug}-pitch.md
  ✓ talks/{YYYY}-{slug}-slides.md
  ✓ talks/{YYYY}-{slug}-kimi-prompt.md   ← copy-paste into kimi.com

Stage 6 — Revision:
  ✓ talks/{YYYY}-{slug}-revision-sheets.md

Next step: open kimi-prompt.md, verify no {PLACEHOLDER} remains, paste into kimi.com.
```

## Anti-patterns

- Do not run Stage 5 without an explicit angle + title choice from the user
- Do not run Stage 2 (research) in `--concept` mode
- Do not proceed to the next stage if an upstream stage failed
- Do not invent metrics or dates not present in the source material

## Validation

- [ ] All upstream files exist before launching a downstream stage
- [ ] Stage 4 CHECKPOINT respected before script
- [ ] Outputs named per convention `talks/{YYYY}-{slug}-{stage}.md`
- [ ] No empty placeholders in generated files

## Tips

- The orchestrator is the recommended entry point for first use
- For repeat users who know the pipeline, running individual stage skills is faster
- The `--stage=X` flag is useful for rerunning a single stage without redoing the full pipeline

## Related

- [Stage 1: Extract](../stage-1-extract/SKILL.md)
- [Stage 2: Research](../stage-2-research/SKILL.md)
- [Stage 3: Concepts](../stage-3-concepts/SKILL.md)
- [Stage 4: Position](../stage-4-position/SKILL.md)
- [Stage 5: Script](../stage-5-script/SKILL.md)
- [Stage 6: Revision](../stage-6-revision/SKILL.md)
- [Full workflow guide](../../../guide/workflows/talk-pipeline.md)

```