SKILL

---

name: openqse-mtg description: Build openQSE meeting notes from a transcript and attendance export. Use when Codex needs to turn a meeting transcript (.docx or extracted text) plus a Teams attendance CSV into markdown notes, normalize attendees against the repo-root canonical names file .NAMES_CANONICAL.md, include attendance directly in the meeting page, surface proposed canonical-name changes for review, and optionally update .NAMES_CANONICAL.md only after explicit user approval.

openQSE Meeting Notes

Produce meeting notes for openQSE meeting materials stored under a year directory such as 2026/ from a transcript and an attendance export. Normalize attendee names and orgs against the repo-root canonical names file .NAMES_CANONICAL.md, preserve year-directory conventions, and make the notes section detailed and transcript-grounded.

Example Invocation

Use this skill by mentioning it in the prompt, for example:

• $openqse-mtg
• Use openqse-mtg for Meeting-2026-03-16-transcript.docx and Meeting-2026-03-16-attendance.csv
• Use the openqse-mtg skill to draft the March 16 meeting notes

Do not rely on /openqse-mtg slash-command syntax unless the client explicitly supports it.

Inputs

Gather these inputs before writing anything:

• Transcript file, usually Meeting-YYYY-MM-DD-transcript.docx
• Attendance export, usually Meeting-YYYY-MM-DD-attendance.csv
• Canonical attendee reference at the top of the repo: .NAMES_CANONICAL.md
• Existing meeting page or template if one already exists for that date

The skill may be run from <reporoot>/ or from a year directory such as <reporoot>/2026/. Resolve canonical names from <reporoot>/.NAMES_CANONICAL.md, not from a year-local copy. Determine the target year directory from the strongest available meeting-date evidence in the provided inputs. If the correct YYYY/ directory cannot be determined confidently, stop before editing and ask the user to confirm it. Treat .NAMES_CANONICAL.md as mutable repo-level working data. It may be gitignored by the wiki checkout, but the skill may update it after explicit user approval.

If one input is missing, continue with the available artifact and state what could not be derived.

Source Boundaries

Use only the provided meeting inputs:

• transcript
• attendance export
• existing meeting page for the same date
• .NAMES_CANONICAL.md

Rules:

• Do not search the web.
• Do not use outside documents or prior meeting notes unless the user explicitly provides them for this meeting task.
• Do not add factual details that are not supported by the inputs.
• Do not infer affiliations, decisions, or action items unless they are stated or strongly evidenced in the transcript or attendance data.
• If something seems likely but is not clearly supported, either omit it or label it as uncertain.

Date Resolution

Resolve the meeting date from the strongest available source in this order:

1. Explicit user statement
2. Existing meeting page for the same meeting
3. Transcript filename or transcript content
4. Attendance filename

If these sources disagree, stop before editing and ask the user to confirm the date. Do not guess. If an attendance filename appears to contain a typo but the user confirms the intended date, use the confirmed date and call out the filename mismatch briefly.

Use the resolved meeting date to choose the target year directory YYYY/. If the date is known but the matching year directory is missing or multiple plausible locations exist, stop and ask before creating or editing files.

Safety Rules

• Prompt before any file edit. Do not edit the meeting page, .NAMES_CANONICAL.md, or any other file until the user has confirmed the specific edit step.
• Treat the meeting-page edit as a hard approval gate. After presenting the proposed attendee table and note changes, stop and ask a direct approval question such as Approve updating Meeting-YYYY-MM-DD.md now? Do not imply the update already happened.
• Never modify .NAMES_CANONICAL.md automatically.
• Never overwrite an existing Meeting-YYYY-MM-DD.md without first reading it and updating it in place.
• If a meeting page already exists and may contain manual edits, update it in place carefully rather than replacing it wholesale.
• Use the meeting date from the user request or the provided transcript or attendance filenames. Do not guess based on the newest file in the directory.
• Do not create YYYY-MM-DD-attendees.md or YYYY-MM-DD-folks-updates.md.

Quick Workflow

1. Inspect the provided inputs and repo layout to determine the meeting date and target YYYY/ directory, then verify that <reporoot>/.NAMES_CANONICAL.md exists.
2. If the target year directory cannot be identified confidently, ask the user before editing anything.
3. Save the input transcript into the target year directory as Meeting-YYYY-MM-DD-transcript.docx if the transcript was provided from elsewhere and that filename does not already exist.
4. Extract transcript text if needed.
5. Parse and normalize attendance against <reporoot>/.NAMES_CANONICAL.md.
6. Show the proposed attendee table and any proposed canonical additions or variants in the chat.
7. Ask whether to update YYYY/Meeting-YYYY-MM-DD.md.
8. After YYYY/Meeting-YYYY-MM-DD.md is updated, ask whether to apply canonical updates to .NAMES_CANONICAL.md, one proposed person or variant at a time.
9. Verify filenames, transcript link placement, and sections before finishing.

Prompting Sequence

Follow this interaction order:

1. Confirm the meeting date, target year directory, and inputs if there is any mismatch or ambiguity.
2. Summarize what will be updated.
3. Show the proposed attendee table and proposed canonical changes in the chat.
4. Ask for approval to update YYYY/Meeting-YYYY-MM-DD.md with a standalone, explicit question. Make it visually obvious that no file edit has happened yet.
5. Apply the YYYY/Meeting-YYYY-MM-DD.md edit only after approval.
6. Ask for approval for each proposed .NAMES_CANONICAL.md change, one item at a time.
7. Apply only the approved canonical changes.

Do not combine these approvals into a single implicit step.

Transcript Handling

If the user provides a transcript from outside the target year directory, save a copy into that year directory using the repo convention Meeting-YYYY-MM-DD-transcript.docx, but only when that exact file does not already exist. Never overwrite an existing transcript file silently. If the correctly named transcript file is already present, prompt the user to decide whether to reuse the existing file or replace it with the newly provided transcript.

For .docx transcripts, prefer built-in extraction before writing custom code:

textutil -convert txt -stdout Meeting-2026-03-09-transcript.docx

If textutil is unavailable, use another local extractor. Do not block the workflow on perfect formatting; the goal is readable text for summarization.

Summarize from the transcript with these rules:

• Use this notes structure inside ## **Notes**:
  • ### Brief Summary
  • ### Detailed Notes
• Keep Brief Summary short, high-signal, and focused on the main topics, decisions, and outcomes.
• Make Detailed Notes as detailed as the transcript support allows. Capture the flow of the discussion, key technical points, clarifications, questions, tradeoffs, concerns, and stated next steps.
• Do not repeat the participant list in Detailed Notes; attendance already lives in ## Attendance.
• Do not restate the meeting date in Detailed Notes; the date already appears at the top of the page.
• Prefer prose and subsection headings over shallow bullet fragments when detail matters.
• Use numbered subsections within Detailed Notes for major discussion segments or topic shifts when that improves readability.
• End with explicit action items as markdown checkboxes when actions are stated.
• Keep claims grounded in the transcript. If a point is ambiguous, phrase it cautiously.
• If the transcript is truncated, noisy, or incomplete, say so explicitly rather than filling gaps.
• Use 2026/Meeting-2026-03-16.md as the style example for section placement, but apply the structure above even if the existing file uses older headings such as Brief Overview, Synopsis, or Detailed Meeting Minutes.

Attendance Handling

The attendance export in the target year directory is typically a Microsoft Teams tab-delimited file, often encoded as UTF-16. You may use the helper script to parse and normalize the CSV, but treat it as an internal parser only, not as a generator of deliverable files.

python3 ~/.codex/skills/openqse-mtg/scripts/extract_attendance.py \
  --attendance Meeting-2026-03-09-attendance.csv \
  --folks ../.NAMES_CANONICAL.md \
  --date 2026-03-09

Use the parsed results to build the ## Attendance table directly inside the meeting page.

If extract_attendance.py is used, consume its parsing and normalization logic as a helper step only. Do not present any sidecar files as final outputs, and do not rely on those sidecars as part of the user-facing workflow.

If extract_attendance.py is unavailable, parse the attendance CSV directly in-memory. Handle UTF-16, tab-delimited Teams exports, normalize names against .NAMES_CANONICAL.md, and continue without creating any intermediate attendance artifacts.

If the CSV is missing, build the attendance section manually from available context and state that canonical update suggestions could not be derived from the attendance export.

Canonicalization Rules

• Trust .NAMES_CANONICAL.md over raw CSV values.
• Keep all present participants from the CSV.
• Prefer the canonical org from the people table when a person matches.
• When a participant is not found, derive the cleanest reasonable display name from the raw value and use Unknown unless an org hint is explicit.
• Do not write a separate canonical-update file.
• Instead, show proposed additions and new seen-name variants in the chat and ask whether to add them to .NAMES_CANONICAL.md.
• Apply canonical changes only after the user confirms, and handle those confirmations one proposal at a time.
• If attendance matching is uncertain, keep the cleaned raw name in the meeting notes and present the possible canonical match as a question instead of silently applying it.
• Never silently change the canonical org for an existing person. Treat that as an explicit user-approved correction.

Normalization Heuristics

When normalizing attendance names:

• Convert Last, First to First Last.
• Strip (Unverified) markers before matching, but preserve them as seen variants when proposing canonical updates.
• Treat parenthetical text as an org hint when it appears to describe an institution.
• Collapse repeated whitespace and remove surrounding punctuation noise.
• Deduplicate identical attendees after normalization.
• If a row appears to be only a fragment or ambiguous display name, keep the cleaned best-effort form and flag it as uncertain rather than over-matching.

Existing File Policy

• If Meeting-YYYY-MM-DD.md already exists, read it first and update it in place.
• Preserve unrelated content such as agenda, links, upcoming meetings, and manually added notes.
• If the existing file is heavily hand-edited and the safe update path is unclear, pause and ask before making a broad rewrite.
• Only create Meeting-YYYY-MM-DD.new.md when the user asks for a draft copy or when in-place updating would risk overwriting unclear manual edits.

Final Meeting Page

Preserve the repo's existing meeting-page style. In this repo the current convention is Meeting-YYYY-MM-DD.md, even though earlier prompt text may suggest other filename forms. Follow the repo convention unless the user explicitly asks for a different output name.

Include:

• Meeting heading and date block if the page already uses them
• ## Attendance with a Person | Institution markdown table
• ## **Notes**
• AI-generated notice if the page already uses one
• ### Brief Summary
• ### Detailed Notes
• Detailed transcript-grounded discussion content under Detailed Notes
• ## Action Items or equivalent checklist block if actions exist
• A transcript-download line at the end of the meeting notes in this exact form: * [Download Transcript](https://raw.githubusercontent.com/wiki/openQSE/openqse-admin/YYYY/Meeting-YYYY-MM-DD-transcript.docx)

When updating an existing file, preserve unrelated content such as agenda, links, and upcoming meeting details.

Meeting Notes Template

Prefer this structure unless the existing page already uses a close variant:

• meeting heading and date block
• upcoming meetings, if already present
• agenda, if already present
• ## Attendance
• ## **Notes**
• ### Brief Summary
• short summary paragraph
• ### Detailed Notes
• detailed discussion sections or subsections grounded in the transcript
• ## Action Items, if any
• files or transcript link block, uncommented and updated if present, otherwise added

When a transcript link already exists but is commented out, malformed, or points to the wrong date or filename, uncomment and correct it instead of adding a duplicate.

If there are no explicit action items in the transcript, omit the section or write No explicit action items captured.

For example, for the March 16, 2026 meeting page at 2026/Meeting-2026-03-16.md, the refined notes body should favor:

• ### Brief Summary for a compact synthesis of the Qiskit architecture presentation and resulting discussion
• ### Detailed Notes for the technical walkthrough and Q&A details
• no attendee recap inside Detailed Notes
• no restated meeting date inside Detailed Notes

Canonical Update Prompt Format

Present proposed canonical changes in small, explicit units:

• New person: Add <Canonical Name> | <Canonical Org> | <Seen Name Variants>?
• New variant: Add variant for <Canonical Name> | <Canonical Org> | <Variant>?
• Org correction: Change org for <Canonical Name> from <Old Org> to <New Org>?

Do these one at a time and wait for approval before editing .NAMES_CANONICAL.md.

Output Checklist

Before finishing, confirm that:

• The attendee table uses canonical names and orgs.
• The attendee list is included directly in the main meeting page.
• The transcript file exists in the year directory as Meeting-YYYY-MM-DD-transcript.docx, unless an existing correctly named file was reused.
• The main meeting page contains ### Brief Summary and ### Detailed Notes.
• Detailed Notes is specific and substantial, not a thin outline.
• Detailed Notes does not repeat the attendee list or meeting date.
• The end of the meeting notes includes an uncommented * [Download Transcript](https://raw.githubusercontent.com/wiki/openQSE/openqse-admin/YYYY/Meeting-YYYY-MM-DD-transcript.docx) line with the correct year and date.
• Empty sections were omitted or replaced with a brief explicit note.
• Any proposed .NAMES_CANONICAL.md additions or variants were shown in the chat before editing.
• Any update to .NAMES_CANONICAL.md was performed only after explicit user approval.
• Any missing transcript or attendance input is called out explicitly.
• The final response lists every file updated during the run.

If the meeting page has not yet been edited because approval is still pending, the response must say that plainly and end with a direct approval prompt. Do not describe the meeting-page update as completed, drafted, or applied unless the file edit has actually been made.

At the end of the skill run, always show the filenames of all updated files.

References

• Read references/file-conventions.md when the repo layout or filename choice is unclear.