ravnhq/transcript-notes

Transcript Notes

Convert a raw meeting transcript .txt file into a structured .md notes file.

Prerequisites

• Raw transcript .txt file — supports speaker-turn format (speaker name on its own line, dialogue as paragraph) and timestamped formats (e.g., [00:01:23] Speaker: text)
• Target notes directory exists or will be created

Workflow

1. Read & Analyze Transcript

• Read the transcript file
• Identify: participants, series name, episode number, date, duration (estimate from content length if not stated)
• Map the conversation flow: what topics were discussed, in what order, by whom

2. Extract & Structure

• Meeting Metadata: Series, Episode, Date (if inferable), Duration (if inferable), Participants
• TL;DR: Single paragraph, 2-4 sentences, captures the meeting's purpose and key outcomes
• Key Topics: Each topic gets a **bold title** -- one-line summary bullet, then a ### subsection with 2-5 sentences or bullets expanding it
• Action Items: **Person/Group:** action description format
• Quotes: 3-5 notable quotes using > "quote" -- Speaker Name (context) format — prioritize quotes that capture decisions, insights, or strong positions over casual remarks

3. Write & Verify

• Create the notes directory if it doesn't exist: notes/{series-slug}/
• Write the .md file mirroring the transcript filename (e.g., 001.txt → 001.md, kickoff-meeting.txt → kickoff-meeting.md)
• Verify: all template sections present, Key Topics list matches subsections 1:1, quotes are verbatim from transcript

Output Template

# {Series Name} - {Episode NNN or Date}

## Meeting Metadata
- **Series:** {series name}
- **Episode:** {NNN, if applicable}
- **Date:** {date, if inferable}
- **Duration:** {duration, if inferable}
- **Participants:** {comma-separated full names}

## TL;DR
{Single paragraph, 2-4 sentences}

## Key Topics
- **{Topic}** -- {One-line summary}
- **{Topic}** -- {One-line summary}
...

### {Topic Heading}
{2-5 sentences or bullet points}

### {Topic Heading}
...

## Action Items
- **{Person/Group}:** {Action description}
...

## Quotes
> "{Quote}" -- {Speaker Name} ({optional context})
...

Quality Rules

• TL;DR must be a single paragraph — no bullets, no multiple paragraphs
• Key Topics bullet list and ### subsections must correspond 1:1 and appear in the same order
• Action items must name a specific person or group
• Quotes must be actual words from the transcript, not paraphrased
• Use -- (double dash) not — (em dash) for separators in topic summaries and quotes
• Series slug for directory: kebab-case version of series name
• Optional metadata fields (Date, Duration) — include only when inferable from transcript content
• Long transcripts (>5000 words) — process in sections, then merge; do not truncate or skip content
• Preserve speaker terminology — keep acronyms, jargon, and domain-specific terms as spoken; do not rephrase or "clean up" technical language
• TL;DR must focus on outcomes and decisions, not just list what was discussed — "The team decided X" not "The team discussed X"
• Action items must include deadlines or timeframes when mentioned in the transcript — "by Friday" or "next sprint", not just the task
• Key Topics must appear in chronological order as discussed in the transcript, not reordered by importance

Examples

Positive Trigger

User: "Process the meeting transcript at transcripts/ai-platform-sync/003.txt — generate formatted notes with metadata, key topics, action items, and quotes"

Expected behavior: Reads the transcript file, extracts participants, topics, action items, and quotes, then writes a structured .md notes file.

Non-Trigger

User: "Create a template agenda for our weekly sync meeting"

Expected behavior: This is meeting agenda creation, not transcript processing. The user wants to plan a future meeting, not convert an existing recording.

Troubleshooting

• Error: Cannot determine series name

  • Cause: Transcript has no meeting context or header identifying the series.
  • Solution: Ask user for the series name before proceeding.

• Error: No clear action items found

  • Cause: Meeting was informational only with no commitments or next steps.
  • Solution: Write "No action items identified" in the Action Items section, or extract implicit next steps.

• Error: Cannot estimate duration

  • Cause: No timing cues, timestamps, or length indicators in transcript.
  • Solution: Omit Duration from the Meeting Metadata section.

• Error: Transcript has overlapping or unclear speaker labels

  • Cause: Multiple speakers share similar names or labels are inconsistent (e.g., "John" vs "John S." vs "JS").
  • Solution: Normalize speaker names to full names where identifiable; ask user for disambiguation if ambiguous.

• Error: Transcript has no speaker labels

  • Cause: Raw transcript is a continuous text block without speaker attribution (e.g., auto-generated without diarization).
  • Solution: Ask user if speaker info is available separately; otherwise attribute all content to "Unknown Speaker" and note the limitation in metadata.

• Error: Transcript is in a non-English language

  • Cause: Meeting was conducted in another language.
  • Solution: Write notes in the same language as the transcript unless user requests translation. Keep all quotes in the original language.

• Error: Multiple transcript files for one meeting (Part 1, Part 2)

  • Cause: Recording was split into segments.
  • Solution: Read all parts in order and produce a single unified notes file. De-duplicate topics that span the split point.