Skip to content

SKILL

Jump to bottom
Thomas Naughton edited this page Mar 19, 2026 · 7 revisions

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 NAMES_CANONICAL.md in the working year directory, 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 an openQSE year directory such as 2026/ from a transcript and an attendance export. Normalize attendee names and orgs against NAMES_CANONICAL.md, preserve year-directory conventions, and keep the output concise.

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 in the working year directory: NAMES_CANONICAL.md
  • Existing meeting page or template if one already exists for that date

Run the skill from the year directory that contains the meeting files, for example <reporoot>/2026/.

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.

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 working year directory for the meeting date, existing Meeting-*.md files, and NAMES_CANONICAL.md.
  2. Save the input transcript into the year directory as Meeting-YYYY-MM-DD-transcript.docx if the transcript was provided from elsewhere and that filename does not already exist.
  3. Extract transcript text if needed.
  4. Parse and normalize attendance against NAMES_CANONICAL.md.
  5. Show the proposed attendee table and any proposed canonical additions or variants in the chat.
  6. Ask whether to update Meeting-YYYY-MM-DD.md.
  7. After 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.
  8. Verify filenames, transcript link placement, and sections before finishing.

Prompting Sequence

Follow this interaction order:

  1. Confirm the meeting date 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 Meeting-YYYY-MM-DD.md with a standalone, explicit question. Make it visually obvious that no file edit has happened yet.
  5. Apply the 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 working year directory, save a copy into the 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:

  • Be clear and succinct.
  • Use numbered sections for phases or parts of the meeting.
  • Start with a brief synopsis.
  • End with explicit action items as markdown checkboxes.
  • 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.

Attendance Handling

The attendance export in the working 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
  • Concise numbered meeting sections
  • ## 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 synopsis
  • numbered discussion sections
  • ## 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.

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 a synopsis, numbered sections, and action items.
  • 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.

Navigation

Meetings

Resources

Clone this wiki locally