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:

• Prefer clear, readable meeting notes over rigid adherence to a single rhetorical format.
• Organize the notes in the most natural structure for the meeting content, while keeping the page easy to scan.
• The model may use compact prose, bullets, numbered subsections, or a hybrid of those when appropriate.
• A good default is to separate:
  • meeting opening or framing
  • main presentation or discussion topics
  • Q&A or follow-up discussion
  • key takeaways
  • action items, if any
  • closing, if useful
• These headings are preferred patterns, not mandatory section names. Adapt them when a simpler or clearer structure is better.
• Group related content by topic rather than mechanically following transcript order when that improves clarity.
• Synthesize and normalize the discussion into useful meeting notes rather than retelling the transcript line by line.
• Keep claims grounded in the transcript. If a point is ambiguous, phrase it cautiously.
• Synthesis is allowed, invention is not.
• Do not repeat the participant list in the notes body; attendance already lives in ## Attendance.
• Do not restate the meeting date in the notes body; the date already appears at the top of the page.
• If the transcript is truncated, noisy, or incomplete, say so explicitly rather than filling gaps.
• Use 2026/Meeting-2026-03-16.md as a rough placement example, but prefer whatever note structure best matches the meeting.

Preferred Note Style

When generating meeting notes, emulate this style:

• Concise, well-structured, high-signal notes
• Topic-first organization rather than a raw transcript retelling
• Use hierarchy where it helps, but do not force an outline if concise prose is clearer
• Make the distinction between presentation content and follow-up discussion clear when the transcript supports it
• Include synthesis and takeaways when they add value
• Prefer the kind of formatting a strong general-purpose meeting-notes model would naturally choose

Do not let the outline style reduce factual rigor. If a takeaway or action item is not supported by the transcript, omit it or mark it as tentative.

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
• transcript-grounded notes using the clearest structure for the meeting
• action items section if actions exist, or a short explicit note if none were captured
• 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**
• a clear meeting-notes body that may use prose, bullets, subsections, or a hybrid
• prefer natural topic grouping over line-by-line transcript recitation
• include synthesis and discussion structure when they improve readability
• ### Action Items or equivalent, using the action-item format below, if actions exist
• 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, 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:

• a compact opening or framing section
• a clear summary of the main architecture walkthrough
• readable separation of the follow-up discussion where useful
• a compact synthesis of the main points
• no attendee recap inside the notes body
• no restated meeting date inside the notes body

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.

Action Item Format

• Use an action-items table when actions are present: | Action | Owner | Notes |
• Only include an owner when the transcript supports it.
• If the owner is unclear, use Unknown rather than guessing.
• If a follow-up is implied but not explicitly committed, note that uncertainty in the Notes column.

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 notes body is clear, well-structured, and transcript-grounded.
• The notes are organized for readability rather than as a raw transcript dump.
• Major presentation content and follow-up discussion are distinguishable where the meeting structure supports that distinction.
• The notes body does not repeat the attendee list or meeting date.
• Key Takeaways reflects synthesis from the transcript, not unsupported invention.
• Action Items uses the Action | Owner | Notes table format when actions exist.
• 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.