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. version: "v2" last_updated: "2026-07-17"

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:

• Default to the repo's numbered-outline meeting-notes format when generating the notes body.
• Use a numbered outline structure inside ## **Notes** unless the user explicitly asks for another format.
• Do not use prose-heavy summary blocks by default.
• Organize content by topic, not by raw transcript chronology.
• Preserve factual rigor while still synthesizing the discussion into readable notes.
• 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.
• Treat the structured numbered outline below as the primary style reference for section ordering, subsection granularity, bullet density, and action-item presentation.

Preferred Note Style

When generating meeting notes, emulate this style:

• Match the structure and tone of the preferred openQSE numbered-outline notes format described in this skill.
• Use concise, high-signal outline notes instead of prose-heavy summaries.
• Use bullets as the default unit of explanation within sections and subsections.
• Do not use ### Brief Summary or ### Detailed Notes unless the user explicitly asks for prose.
• Immediately after the ## **Notes** heading, include this notice exactly: * **NOTICE:** Notes generated using AI; please verify accuracy.
• If an AI-generated-content notice already exists, normalize it to the exact notice above instead of adding a duplicate.
• The ## **Notes** body must use this top-level section order by default:
  • 1. Opening
  • 2. Presentation Overview (<speaker>)
  • 3. Discussion & Q&A
  • 4. Key Takeaways
  • 5. Action Items
  • 6. Closing
• Under sections 2 and 3, use numbered subsections such as 2.1, 2.2, 3.1, 3.2 whenever the transcript supports that granularity.
• Under numbered subsections, use short bullets for claims, architectural points, tradeoffs, questions, and responses.
• Capture questions and responses distinctly in the Q&A section when possible.
• 4. Key Takeaways should be a concise bullet list of the main conclusions.
• 6. Closing should capture wrap-up, thanks, end-of-meeting cues, and any commitments to share slides or materials.
• Include an action-items table when actions are present.
• If there are no explicit action items, still include section 5. Action Items and state No explicit action items captured.
• 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 directly under ## **Notes** in this exact form: * **NOTICE:** Notes generated using AI; please verify accuracy.
• 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 user explicitly asks for something else:

• meeting heading and date block
• upcoming meetings, if already present
• agenda, if already present
• ## Attendance
• ## **Notes**
• * **NOTICE:** Notes generated using AI; please verify accuracy.
• a numbered-outline notes body using numbered sections and subsection bullets
• 1. Opening
• 2. Presentation Overview (<speaker>)
• 3. Discussion & Q&A
• 4. Key Takeaways
• 5. Action Items
• 6. Closing
• files or transcript link block, uncommented and updated if present, otherwise added

Do not replace the numbered-outline body with prose headings such as Brief Summary or Detailed Notes unless the user explicitly requests prose output.

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, keep section 5. Action Items and write No explicit action items captured.

For content modeling, use the section structure and formatting rules in this skill as the primary worked example.

Do not depend on external example files being present in the repo. If a separate example such as BETTER.md was mentioned in the user request, absorb its style into these instructions rather than referencing that file as a required runtime dependency.

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.
• Do not use checkbox lists for action items unless the user explicitly asks for that format.

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.
• The notes section includes the exact notice * **NOTICE:** Notes generated using AI; please verify accuracy. directly under ## **Notes**.
• 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.