path: root/.ai/workflows/process-meeting-transcript.org

#+TITLE: Process Meeting Transcript Workflow
#+AUTHOR: Craig Jennings & Claude
#+DATE: 2026-02-03

* Overview

This workflow defines the process for processing meeting recordings from start to finish: finding recordings, extracting audio, transcribing via AssemblyAI, identifying speakers, correcting errors, and archiving files.

* When to Use This Workflow

Trigger this workflow when:
- Craig says "process the transcript" or "process the recording" or similar
- New recording files (.mkv) appear in ~/sync/recordings/ after meetings
- Craig wants to process meeting recordings into labeled transcripts

* Prerequisites

- Recording file(s) exist in ~/sync/recordings/ (*.mkv)
- Calendar files available at ~/.emacs.d/data/*cal.org for meeting titles
- AssemblyAI transcription script at ~/.emacs.d/scripts/assemblyai-transcribe
- AssemblyAI API key stored in ~/.authinfo.gpg (machine api.assemblyai.com)
- ffmpeg available for audio extraction

* The Workflow

** Step 1: Set Up Session Context and Engagement Homes

Before starting transcript processing:

1. *Note the destination homes for files that classify as this project's* (classification itself is per file, in Step 2):
   - Assets: ~{engagement}/assets/~ (e.g., ~deepsat/assets/~)
   - Meetings: ~{engagement}/meetings/~ (e.g., ~deepsat/meetings/~)
   - Knowledge: ~{engagement}/knowledge.org~ for reference

2. Update .ai/session-context.org with current status:
   - Note that we're about to process a meeting transcript
   - Get meeting name by checking ~/.emacs.d/data/*cal.org (match date/time to transcript timestamp)
   - If meeting not found in calendar, ask Craig for the meeting title

Classification is per recording, not per session — a single run can carry this-project, cross-project, and personal recordings (the 2026-06-10 run had a kit-project recording alongside two DeepSat ones), so no session-level engagement default exists.

** Step 2: Find Recording Files

Find and match recording files with calendar events. *Run sub-steps 1 and 3 (recording list + calendar dump) as a single parallel batch* — they're independent. Sub-step 2 (parse timestamps) and sub-step 4 (matching) work from those two outputs in-memory, so they're sequential after the batch.

1. **List recordings:** Find all recording files in ~/sync/recordings/ (video .mkv or audio-only .m4a)
   #+begin_src bash
   ls -la ~/sync/recordings/*.mkv ~/sync/recordings/*.m4a 2>/dev/null
   #+end_src
   Audio-only recordings (.m4a) are used when no screen content is expected. These skip Step 3 (audio extraction) since they're already in a transcribable format.

2. **Extract timestamps:** Parse date/time from each filename (format: YYYY-MM-DD-HH-MM-SS.mkv or .m4a)

3. **Match with calendar:** Check ~/.emacs.d/data/*cal.org for meetings at those times
   #+begin_src bash
   cat ~/.emacs.d/data/dcal.org | grep -A2 "YYYY-MM-DD"
   #+end_src

4. **Classify every file, then present the selection table to Craig.** Classification happens BEFORE transcription, from the calendar match and attendees. Three values: this project / another .ai project (name it) / personal. No file proceeds unclassified — an unmatchable file is a question for Craig, not a default.

   | Filename                    | Meeting / Date-Time             | Engagement             |
   |-----------------------------+---------------------------------+------------------------|
   | 2026-02-03_10-00-00.mkv     | DeepSat Standup (from calendar) | this project (DeepSat) |
   | 2026-06-10_15-00-00.m4a     | Arusyak sync (from calendar)    | kit                    |
   | 2026-02-03_14-30-00.mkv     | 2026-02-03 14:30 (no match)     | ASK CRAIG              |

5. **Craig selects files:** One, several, or all files to process

6. **Queue for processing:** Selected files ordered oldest → newest for serial processing

*** Cross-project routing (files classified as another project's)

Per =cross-project.md=: transcribe and label here, then deliver the *labeled transcript PLUS an outcome note* via =inbox-send <project> --file ...=, and copy the recording to the owning project's =meetings/= dir. File NOTHING in this project's assets. The outcome note carries the same extraction Step 11 requires (summary, decisions, the owner's owed actions) so the receiving project can fold it without re-reading the transcript. Worked example: kit's =2026-06-10-1554-from-work-handoff-arusyak-sync-outcome.org=. Personal recordings route the same way to the personal project that owns the topic.

** Step 3: Extract Audio (video recordings only)

*Skip this step for .m4a files* — they are already audio and can go directly to transcription.

For .mkv video recordings, extract audio for transcription:

#+begin_src bash
ffmpeg -i ~/sync/recordings/FILENAME.mkv -vn -ac 1 -c:a aac -b:a 96k /tmp/FILENAME.m4a
#+end_src

Settings:
- =-vn= : no video (audio only)
- =-ac 1= : mono channel (sufficient for speech, smaller file)
- =-c:a aac= : AAC codec
- =-b:a 96k= : 96kbps bitrate (sufficient for speech transcription)

Output: /tmp/FILENAME.m4a (temporary, deleted after transcription)

** Step 4: Transcribe with AssemblyAI

1. **Run transcription:**
   #+begin_src bash
   # For .mkv files (audio was extracted to /tmp/):
   ~/.emacs.d/scripts/assemblyai-transcribe /tmp/FILENAME.m4a > ~/sync/recordings/FILENAME.txt
   # For .m4a files (transcribe directly):
   ~/.emacs.d/scripts/assemblyai-transcribe ~/sync/recordings/FILENAME.m4a > ~/sync/recordings/FILENAME.txt
   #+end_src

2. **Clean up:** Delete intermediate .m4a file after successful transcription (only for .mkv extractions — do NOT delete original .m4a recordings)
   #+begin_src bash
   rm /tmp/FILENAME.m4a
   #+end_src

3. **Output format:** The script produces speaker-diarized output:
   #+begin_example
   Speaker A: First speaker's text here.
   Speaker B: Second speaker's response.
   Speaker A: First speaker continues.
   #+end_example

4. Continue to speaker identification workflow below.

** Step 5: Locate Files

Confirm the transcript and recording files are ready:

1. **Verify transcript exists:**
   #+begin_src bash
   ls -la ~/sync/recordings/FILENAME.txt
   #+end_src

2. **Verify recording exists:**
   #+begin_src bash
   ls -la ~/sync/recordings/FILENAME.mkv
   #+end_src

3. **Get meeting title:** If not already known from Step 2, check calendar
   - Calendar location: ~/.emacs.d/data/*cal.org
   - Match the meeting time to the transcript timestamp

** Step 6: Read and Analyze Transcript

1. Read the full transcript file

2. Identify speakers by analyzing context clues:
   - Names mentioned in conversation ("Thanks, Ryan")
   - Role references ("as the developer", "on the IT side")
   - Project-specific knowledge (who works on what)
   - Previous meeting context (known attendees)
   - Speaking order patterns

3. Build a speaker identification table:
   | Speaker | Person | Evidence |
   |---------|--------|----------|
   | A       | Name   | Clues... |

** Step 7: Confirm Speaker Identifications

Present the speaker identification table to Craig for confirmation:
- List each speaker label and proposed name
- Include the evidence/reasoning
- Ask about any uncertain identifications
- Note any new people to add to notes.org contacts

** Step 8: Create Labeled Transcript

1. Replace all speaker labels with actual names

2. Correct transcription errors:
   - Common mishearings (names, technical terms, company names)
   - Known substitutions from this project:
     - "Vanetti" → "Vineti"
     - "Fresh" → "Vrezh"
     - "Clean4" / "clone" → "CLIN 4"
     - "Vascan" → "Vazgan"
     - "Hike" / "Ike" → "Hayk"
     - "High Tech" → "HyeTech"
     - "Java software" → "JAMA software"
     - "JSON" (person) → "Jason"
     - "their S" / "ress" → "Nerses"
   - Technical terms specific to DeepSat (GovCloud, AFRL, SOUTHCOM, etc.)

3. Save to engagement assets folder:
   - Location: ~{engagement}/assets/~ (e.g., ~deepsat/assets/~)
   - Filename: YYYY-MM-DD-meeting-name.txt
   - Example: deepsat/assets/2026-02-03-standup-ipm-grooming.txt

** Step 9: Copy Recording to Meetings Folder

1. Ensure engagement meetings folder exists and patterns are in .gitignore (~*/meetings/*.mkv~ and ~*/meetings/*.m4a~)

2. Copy the recording file with descriptive name:
   #+begin_src bash
   # Video recordings:
   cp ~/sync/recordings/YYYY-MM-DD-HH-MM-SS.mkv {engagement}/meetings/YYYY-MM-DD_HH-MM-meeting-name.mkv
   # Audio-only recordings:
   cp ~/sync/recordings/YYYY-MM-DD-HH-MM-SS.m4a {engagement}/meetings/YYYY-MM-DD_HH-MM-meeting-name.m4a
   #+end_src
   Example: ~deepsat/meetings/2026-02-03_11-02-standup-ipm-grooming.mkv~

3. Verify the copy succeeded

** Step 10: Update Session Context with Meeting Summary

Add a meeting summary section to .ai/session-context.org including:

1. **Attendees** - List all participants

2. **Key Decisions** - Important choices made

3. **Action Items** - Tasks assigned, especially for Craig

4. **New Information** - Things learned that should be noted

5. **New Contacts** - People to add to notes.org

** Step 11: Analyze and Extract (mandatory)

Per transcript, after speaker labeling and filing. This is the step that forces analysis into durable homes — the workflow's old defect was ending at file hygiene with nothing landing in todo.org or knowledge.org.

1. *Action items → todo.org.* Every action item gets an owner. Craig-owed items become tasks (or dated folds into the existing task they advance) per =todo-format.md=; teammate-owned items are recorded in the relevant task body as expectations, not as Craig tasks. Link the transcript from every task it feeds.
2. *Decisions + new ground truth → knowledge.org* (or the engagement's knowledge home): partner/vendor signals, architecture decisions, capability states, cost signals.
3. *Architecture-relevant meetings* → offer the =fold-meeting-into-architecture= workflow (project-specific where present).
4. *Cross-project transcripts* → the same extraction goes into the inbox-send outcome note instead of local files.

This mirrors meeting-prep.org Phase 6 (post-meeting action-item extraction) — the same discipline, now also covering recordings processed in bulk rather than meetings that had a prep doc.

** Step 12: Write Session Context File

Update .ai/session-context.org with:
- Files created this session (transcript, recording)
- Summary of what was processed
- Next steps (file to assets, update notes.org, etc.)

*** Context Management (for multiple files)

When processing multiple recordings in a queue:

1. **After completing each file's workflow**, update .ai/session-context.org with:
   - Files processed so far
   - Current position in queue
   - Summary of meeting just processed

2. **Ask Craig if compact is needed** before starting next file:
   - Transcript processing uses significant context
   - Compacting preserves session context for recovery

3. **If autocompact occurs**, reread session-context.org to:
   - Resume at correct position in queue
   - Avoid reprocessing already-completed files

** Step 13: Clean Up Source Files (gated — see the Exit Gate)

Only after the Exit Gate below passes, delete the source files from ~/sync/recordings/:

1. **Delete the original recording:**
   #+begin_src bash
   rm ~/sync/recordings/FILENAME.mkv
   #+end_src

2. **Delete the raw transcript** (if generated):
   #+begin_src bash
   rm ~/sync/recordings/FILENAME.txt
   #+end_src

This step happens last to ensure all files are safely copied/processed before deletion. If anything goes wrong earlier in the workflow, the source files remain intact for retry.

* Output Files

| File               | Location                                              | Purpose                            |
|--------------------+-------------------------------------------------------+------------------------------------|
| Labeled transcript | {engagement}/assets/YYYY-MM-DD-meeting-name.txt       | Corrected transcript for reference |
| Meeting recording  | {engagement}/meetings/YYYY-MM-DD_HH-MM-meeting-name.mkv | Video for review (gitignored)      |
| Session context    | .ai/session-context.org                              | Crash recovery, meeting summary    |
| Knowledge base     | {engagement}/knowledge.org                            | Team, infrastructure, corrections  |

* Common Transcription Errors

Keep this list updated as new patterns emerge:

| Heard As      | Correct       | Context                                        |
|---------------+---------------+------------------------------------------------|
| Vanetti       | Vineti        | Company where Craig, Nerses, Eric, Ryan worked |
| Fresh         | Vrezh         | Developer name                                 |
| Clean4, clone | CLIN 4        | Contract milestone                             |
| Vascan        | Vazgan        | MagicalLabs AI team member                     |
| Hike, Ike     | Hayk          | CTO name                                       |
| High Tech     | HyeTech       | Armenian tech community org                    |
| Java software | JAMA software | Requirements traceability tool                 |
| JSON (person) | Jason         | DevSecOps or advisor                           |
| their S, ress | Nerses        | CEO name                                       |
| sir Keith     | Sarkis        | BD/investor relations                          |
| Fastgas       | MagicalLabs   | Armenian AI contractor                         |
| Sitelix       | Cytellix      | CMMC security/compliance partner               |

* Tips

1. **Read the whole transcript first** - Context from later in the meeting often helps identify speakers from earlier

2. **Use the calendar** - Meeting names help set expectations for who attended

3. **Check engagement knowledge.org** - Team roster and transcription corrections specific to this engagement

4. **Ask about unknowns** - If a new person appears, ask Craig for context

5. **Note new learnings** - Update engagement knowledge.org with new contacts, corrections, or context after processing

* Exit Gate (hard contract)

The workflow is not complete, and Step 13 (delete sources) MUST NOT run, until every line below holds. Deleting recordings is the irreversible step, so it stays last and gated. A skipped step must be impossible to mistake for a completed one — the same principle as the triage engine's SCAN FAILED rule.

- [ ] Every recording is classified (this project / named other project / personal) — none defaulted
- [ ] Session context written before starting
- [ ] Recording files listed and matched with calendar; Craig selected files
- [ ] Audio extracted, AssemblyAI transcription completed, intermediate .m4a deleted
- [ ] All speakers identified and confirmed with Craig
- [ ] This-project transcripts corrected and saved to {engagement}/assets/; recordings copied to {engagement}/meetings/
- [ ] Cross-project files delivered: labeled transcript + outcome note via inbox-send, recording copied to the owning project's meetings/, nothing filed in this project's assets
- [ ] Step 11 ran per transcript: every extracted action item written to todo.org (or the outcome note) with an owner; decisions and ground truth written to knowledge.org (or the outcome note)
- [ ] Session context updated with the meeting summary AND the session log records the extraction
- [ ] New contacts/info flagged for {engagement}/knowledge.org update
- [ ] (If multiple files) Queue position tracked in session context
- [ ] Only then: source files deleted from ~/sync/recordings/