|
| 1 | +--- |
| 2 | +name: analyze-innersource-video |
| 3 | +description: Analyze an InnerSource conference talk transcript and relate it to the InnerSourcePatterns library. Identifies which existing patterns the talk instantiates (Known Instance candidates), where it suggests clarifications to an existing pattern, and whether it justifies drafting a new pattern. Use when given a transcript of an InnerSource-related talk and asked to relate it to this repo's pattern library. |
| 4 | +--- |
| 5 | + |
| 6 | +# Analyze InnerSource Video |
| 7 | + |
| 8 | +## When to use |
| 9 | + |
| 10 | +The user provides a transcript of an InnerSource talk — plus whatever metadata comes with it (speaker, org, event, date) — and asks you to compare it to the patterns in this repo. |
| 11 | + |
| 12 | +Goals: surface known instances, propose surgical clarifications to existing patterns, and identify genuinely new InnerSource pattern candidates. |
| 13 | + |
| 14 | +## Default behavior |
| 15 | + |
| 16 | +**Propose, never auto-edit.** Always present analysis and use `AskUserQuestion` to confirm direction before making file changes. Never commit or PR without explicit confirmation. |
| 17 | + |
| 18 | +## Workflow |
| 19 | + |
| 20 | +### Step 1 — Confirm the transcript and metadata |
| 21 | + |
| 22 | +You need the transcript text, plus speaker, organization, event/channel, and date. If any of that's missing, ask the caller for it before guessing — a placeholder in a Known Instance citation is worse than asking (see Step 7). |
| 23 | + |
| 24 | +**If you still need to pull a transcript from a video**, get it with the `youtube-transcript-api` Python library (already available; pip-installable if not). Do *not* try `WebFetch` on a YouTube watch page — it returns only the footer. |
| 25 | + |
| 26 | +Write a script to `.tmp/fetch_transcript.py`: |
| 27 | + |
| 28 | +```python |
| 29 | +from youtube_transcript_api import YouTubeTranscriptApi |
| 30 | + |
| 31 | +video_id = "<VIDEO_ID>" |
| 32 | +api = YouTubeTranscriptApi() |
| 33 | +transcript = api.fetch(video_id) |
| 34 | +with open(".tmp/transcript_raw.txt", "w", encoding="utf-8") as f: |
| 35 | + for s in transcript: |
| 36 | + f.write(f"[{s.start:.1f}] {s.text}\n") |
| 37 | +``` |
| 38 | + |
| 39 | +Then collapse it to a flat readable form in `.tmp/transcript_flat.txt` (strip timestamps, join, normalize whitespace). |
| 40 | + |
| 41 | +**If speaker/org/date are still missing** and the transcript came from a video, pull them with `yt-dlp` via `python -m yt_dlp` (the `yt-dlp` binary may not be on PATH on Windows even when the package is installed). Write `.tmp/fetch_metadata.py`: |
| 42 | + |
| 43 | +```python |
| 44 | +import json, yt_dlp |
| 45 | +opts = {"quiet": True, "skip_download": True, "no_warnings": True} |
| 46 | +with yt_dlp.YoutubeDL(opts) as ydl: |
| 47 | + info = ydl.extract_info("<URL>", download=False) |
| 48 | +keys = ["title", "uploader", "channel", "upload_date", "duration", "description", "tags"] |
| 49 | +out = {k: info.get(k) for k in keys} |
| 50 | +with open(".tmp/video_metadata.json", "w", encoding="utf-8") as f: |
| 51 | + json.dump(out, f, ensure_ascii=False, indent=2) |
| 52 | +print(out["title"]); print(out["channel"]); print(out["description"]) |
| 53 | +``` |
| 54 | + |
| 55 | +**The description usually contains speaker name and affiliation when the transcript does not** — this is the single most important reason to fetch metadata even when you have the transcript. Speakers often introduce themselves with just a first name or nickname. |
| 56 | + |
| 57 | +**Fallback for title + channel only:** the YouTube oEmbed endpoint (`https://www.youtube.com/oembed?url=<URL>&format=json`) works through `WebFetch`. |
| 58 | + |
| 59 | +### Step 2 — Summarize the talk |
| 60 | + |
| 61 | +Produce a brief synthesis covering: |
| 62 | + |
| 63 | +- **Title** (from metadata, not from the transcript's spoken title — they often differ) |
| 64 | +- **Speaker** — full name; note any nickname the speaker uses in the talk |
| 65 | +- **Organization** |
| 66 | +- **Event** — typically an InnerSource Commons community call; note the specific summit or webinar if named |
| 67 | +- **Date** — useful for citation |
| 68 | +- **Core thesis** in one or two sentences |
| 69 | +- **Main artifacts / frameworks** the speaker introduces (named structures, checklists, blueprints, mantras) |
| 70 | +- **Memorable lines** — verbatim quotes can become useful in the pattern's Known Instance description |
| 71 | + |
| 72 | +### Step 3 — Survey adjacent patterns |
| 73 | + |
| 74 | +Read the "List of Patterns" section of the repo's own `README.md` — it already has every pattern's title and patlet, grouped by maturity level, kept current as patterns are added. Read it in full; you want the patlet, not just the title, to judge relevance. |
| 75 | + |
| 76 | +Then pick the 3–6 patterns whose patlets sit closest to the talk's theme and read those files in full. Don't rely solely on patlets to judge a match: the talk's content may overlap meaningfully with parts of a pattern that the patlet doesn't surface. |
| 77 | + |
| 78 | +### Step 4 — Categorize the talk's content |
| 79 | + |
| 80 | +For each substantive point in the talk, assign it to one of: |
| 81 | + |
| 82 | +**A. Known Instance candidate** — the talk validates, exemplifies, or vividly re-derives an existing pattern's solution. The right action: add a citation under the pattern's `## Known Instances` section. |
| 83 | + |
| 84 | +**Before citing a match, re-read the pattern's `## Problem` and `## Solution` sections, not just its patlet or title.** A talk can share a topic word with a pattern — "developer environment," "onboarding," "platform" — while doing something structurally different from what that pattern actually solves. Internal Developer Platform is a real trap here: it's specifically about a centralized, deployed, org-run self-service system (a portal, CI/CD orchestration, infrastructure provisioning) — not any tool that touches "developer environments." A story about a contributor's local setup (a containerized dev kit they run on their own laptop) is not a Known Instance of it, however similar the vocabulary sounds. The test is whether the talk's example does the same thing the pattern's Solution describes, not whether it shares a theme with the patlet. |
| 85 | + |
| 86 | +**B. Clarification candidate** — the talk surfaces a real gap or vagueness in an existing pattern. The right action: a small, surgical edit that fills the gap without reframing the pattern. Bias toward additions over rewrites; bias toward concrete guidance over editorial framing. |
| 87 | + |
| 88 | +**C. New pattern candidate** — the talk presents a problem/solution pair that no existing pattern covers. The right action: propose drafting a new pattern using the AI-assisted prompt in `meta/pattern-drafts-with-ai.md`. |
| 89 | + |
| 90 | +### Step 5 — Apply the "uniquely InnerSource" filter |
| 91 | + |
| 92 | +**This is the most important judgment call and the easiest mistake to make.** A talk can contain genuinely good engineering advice that is *not* uniquely InnerSource. Examples that look like new patterns but probably aren't: |
| 93 | + |
| 94 | +- "Treat docs like code" — general dev advice; well-trodden outside InnerSource. |
| 95 | +- "Write better READMEs" — general OSS / dev advice. |
| 96 | +- "Use linters / CI / automation" — general engineering. |
| 97 | + |
| 98 | +What *is* uniquely InnerSource — the signal you're looking for: |
| 99 | + |
| 100 | +- It addresses the specific dynamic of **contributors who are not on the host team** (no shared context, no shared OKRs, no shared manager). |
| 101 | +- It addresses **cross-team collaboration friction** inside one company (Trusted Committers, escalation, ownership ambiguity, dual-line-management tension). |
| 102 | +- It addresses **incentive misalignment** between a developer's team goals and contributing to a shared project. |
| 103 | +- It addresses **scaling InnerSource adoption** across an organization (ambassadors, ISPO, governance levels). |
| 104 | + |
| 105 | +If the talk's central insight would be equally at home in a generic "good engineering" talk, it is not new-pattern material. It may still be a Known Instance or a clarification. |
| 106 | + |
| 107 | +### Step 6 — Present analysis |
| 108 | + |
| 109 | +Present a clear, three-part writeup to the user: |
| 110 | + |
| 111 | +1. **Talk summary** (5–10 lines: speaker, org, thesis, blueprint) |
| 112 | +2. **Mapping to existing patterns** with confidence labels (strong match, partial match, tangential) |
| 113 | +3. **Candidate actions** organized as: Known Instances to add, clarifications to make, new pattern candidates (with the "uniquely InnerSource" filter applied) |
| 114 | + |
| 115 | +Then use `AskUserQuestion` to confirm which actions to take. **Do not edit any file before this confirmation.** If the user is non-committal ("you decide"), make a confident recommendation in your own voice rather than asking again. |
| 116 | + |
| 117 | +### Step 7 — Apply chosen actions |
| 118 | + |
| 119 | +**For Known Instance citations:** |
| 120 | + |
| 121 | +- Match the existing style of that pattern's Known Instances section — typically `* **<Organization>** - <one-or-two-sentence description>` with the URL inline. |
| 122 | +- The lead bold should be the speaker's *organization*, not "Community talk" or similar meta-labels — the existing entries are all organizational, so use the same convention. If you cannot find an organization, ask the user before defaulting to a placeholder. |
| 123 | +- Quote a memorable line or describe the framework concisely. Cite the source link. |
| 124 | + |
| 125 | +**For clarifications:** |
| 126 | + |
| 127 | +- Stay surgical. Prefer adding a new subsection or bullet over rewriting an existing one. |
| 128 | +- If the change touches the pattern's templates (e.g. `templates/README-template.md`), edit those too. |
| 129 | +- Cross-link to other related patterns when distinguishing what the talk adds vs. what's already covered (e.g. distinguishing a contributor-facing system map from ADRs). |
| 130 | + |
| 131 | +**For new patterns:** |
| 132 | + |
| 133 | +- Use the prompt in `meta/pattern-drafts-with-ai.md` as the basis for drafting. |
| 134 | +- File name: lowercase, hyphenated, matching the title. Place in `patterns/1-initial/`. |
| 135 | +- Set Status to `Initial`, Known Instances to the talk itself, Author to TBD, omit Acknowledgments. |
| 136 | +- **One talk is enough to draft at Initial — don't hold back.** Per `meta/contributor-handbook.md`, maturity level 1 (Initial) has no validation requirement at all; it's explicitly for a single unstructured idea, even a "donut" with missing sections. One known instance clears the bar for level 2 (Structured); only 3+ instances need level 3 (Validated). So a genuine new-pattern candidate from one talk should be drafted at Initial, not held back for more evidence that this process — one talk at a time — will never accumulate on its own. |
| 137 | + |
| 138 | +### Step 8 — Git workflow |
| 139 | + |
| 140 | +- **Always branch off `main`**, not whichever branch the user is currently on. Confirm with `git status` and `git branch --show-current` first. |
| 141 | +- **One talk = one PR.** Bundle everything the analysis found for a single talk into one PR — Known Instance citations across several patterns, clarifications, a new pattern draft, whatever applies — the way #909 added Thales as a Known Instance across five patterns in one PR. Only split into separate PRs when the changes come from genuinely different source talks, not because they touch different patterns or different candidate types. |
| 142 | +- Match the repo's commit message style: sentence-case subject, no conventional-commit prefix (check `git log --oneline -5` for recent style). |
| 143 | +- Write the commit message body to `.tmp/commit_msg.txt` and use `git commit -F` (per user's no-heredocs rule). |
| 144 | +- Open the PR against `InnerSourceCommons/InnerSourcePatterns` upstream `main` (the user's fork is `origin`). |
| 145 | +- Include a `## Test plan` checklist in the PR body — the repo's convention. |
| 146 | +- Ask the user before pushing/PRing rather than auto-proceeding. |
| 147 | + |
| 148 | +## Anti-patterns to avoid |
| 149 | + |
| 150 | +- Don't use `WebFetch` on YouTube watch pages — it returns only the footer. Use `youtube-transcript-api` and `yt-dlp` instead. |
| 151 | +- Don't trust the spoken introduction for the speaker's organization — get it from the video description. |
| 152 | +- Don't add a Known Instance entry labeled "Community talk" or similar generic placeholder — the convention is to lead with the speaker's organization. |
| 153 | +- Don't propose "Treat docs like code" or similar generic-engineering ideas as new InnerSource patterns. Apply the Step 5 filter. |
| 154 | +- Don't split one talk's findings across multiple PRs — bundle Known Instances, clarifications, and new pattern drafts from the same talk into one PR (see Step 8). |
| 155 | +- Don't auto-commit or auto-push without confirmation from the user, even on "high confidence" calls — community library content warrants a human in the loop. |
| 156 | +- Don't write the commit message via heredoc — write to `.tmp/commit_msg.txt` and use `git commit -F`. |
| 157 | + |
| 158 | +## Output format for the user-facing analysis |
| 159 | + |
| 160 | +Structure the final writeup as: |
| 161 | + |
| 162 | +``` |
| 163 | +## Talk summary |
| 164 | +<5–10 lines> |
| 165 | +
|
| 166 | +## How it maps to the existing pattern library |
| 167 | +
|
| 168 | +### Strong match — Known Instance candidate |
| 169 | +**[Pattern Name](patterns/.../file.md)** |
| 170 | +<why this talk is a known instance> |
| 171 | +
|
| 172 | +### Partial / adjacent match |
| 173 | +**[Pattern Name](patterns/.../file.md)** |
| 174 | +<what overlaps, what differs> |
| 175 | +
|
| 176 | +### Candidate new patterns |
| 177 | +**Candidate A — "<name>"** |
| 178 | +<problem/solution; "uniquely InnerSource" rationale or honest reason it's borderline> |
| 179 | +
|
| 180 | +## Recommendation |
| 181 | +<which actions to take, in confident voice> |
| 182 | +``` |
| 183 | + |
| 184 | +Then `AskUserQuestion` to confirm. |
0 commit comments