📝 docs: Add Gem refinement spec and implementation plan

After the first real use of the Meeting Secretary Gem for a Fedora Docs Team meeting (2026-04-21), the AI-generated output required significant human editing. The spec captures the systematic differences between the AI output and the human-edited final version across four categories: template compliance failures, missing community conventions, editorial judgment gaps, and URL construction. Design decisions were made collaboratively through a structured brainstorming session exploring alternatives for greeting style, URL construction, @username conventions, topic list filtering, ticket reference format, tangent handling, strikethrough rules, and example placement strategy (hybrid approach: condensed inline excerpts in the definition plus a full golden reference file). The implementation plan breaks the refinement into six tasks covering the example file, template updates, definition changes, and placeholder consistency verification. Assisted-by: Claude Opus 4.6 (1M context) Signed-off-by: Justin Wheeler <jwheel@redhat.com>
2026-04-22 19:27:05 -04:00 · 2026-04-22 19:27:05 -04:00 · dabbf35688
commit dabbf35688
parent dfd6d4ad71
2 changed files with 472 additions and 0 deletions
--- a/docs/superpowers/plans/2026-04-22-gem-refinement.md
+++ b/docs/superpowers/plans/2026-04-22-gem-refinement.md
@ -0,0 +1,377 @@
+# Gem Refinement Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+>
+> **Commit workflow:** This project uses a manual commit workflow. Never run `git commit` directly. Instead, print commit messages, write them to temp files, and present staging + commit commands for the user to execute. See the project's `CLAUDE.md` for the full commit protocol.
+
+**Goal:** Refine the Meeting Secretary Gem definition and templates so AI-generated output matches Fedora community conventions and requires less human editing.
+
+**Architecture:** Three files change — the discourse post template gets structural updates (heading levels, greeting flexibility, topic list guidance), the Gem definition gets a new conventions section and condensed inline example, and a golden reference example is added. The example file is also attached to the Gem as a knowledge file.
+
+**Tech Stack:** Markdown, Google Gemini Gem system prompt (XML-tagged sections)
+
+**Spec:** `docs/superpowers/specs/2026-04-22-gem-refinement-design.md`
+
+---
+
+### Task 1: Create golden reference example
+
+**Files:**
+- Create: `examples/output/2026-04-21-docs-discourse.md`
+
+- [ ] **Step 1: Create the example file**
+
+Create `examples/output/2026-04-21-docs-discourse.md` with the HTML provenance comment and the full human-edited Discourse post from the 2026-04-21 Fedora Docs Team meeting.
+
+The file begins with:
+
+```html
+<!--
+  Golden reference output: Fedora Docs Team meeting, 2026-04-21.
+  Generated by Google Gemini, then human-edited by @jflory7.
+  Used as a quality and formatting baseline for the Meeting Secretary Gem.
+-->
+```
+
+Followed by the complete post body, starting with the greeting line and ending with the Closing bullet. Use the exact content from the spec's source (the user's final human-edited version). This includes real Meetbot URLs, real @usernames, and real Forgejo ticket links.
+
+- [ ] **Step 2: Verify the file**
+
+Check that the example file contains all four meeting log links, all four action items, and all six detailed log sections (Announcements, Action Items from Last Week, Ticket #18, Ticket #19, Docs Graveyard, Ticket #23, Open Floor).
+
+- [ ] **Step 3: Commit**
+
+Commit message scope: adding the golden reference example.
+Suggested gitmoji: 📝 (docs) or ✨ (new feature).
+Component: `examples`.
+
+---
+
+### Task 2: Update discourse post template structure
+
+**Files:**
+- Modify: `templates/discourse-post.md`
+
+- [ ] **Step 1: Update the greeting line**
+
+Replace:
+
+```markdown
+Happy {{DAY_OF_WEEK}}, Fedora folks! :waving_hand: Here is a summary of the recent meeting of the **{{TEAM_NAME}}** held on **{{MEETING_DATE}}**.
+```
+
+With:
+
+```markdown
+{{GREETING}} :waving_hand: Here is the summary of the {{MEETING_DATE}}, {{TEAM_NAME}} meeting.
+```
+
+- [ ] **Step 2: Update the meeting links heading**
+
+Replace:
+
+```markdown
+**Meeting Links:**
+```
+
+With:
+
+```markdown
+## 🔗 Links to Meeting Logs
+```
+
+- [ ] **Step 3: Update section heading levels to h2 with emojis**
+
+Replace these three headings:
+
+```markdown
+# Executive Summary
+```
+```markdown
+# Action Items
+```
+```markdown
+# Detailed Meeting Log
+```
+
+With:
+
+```markdown
+## 📝 Executive Summary
+```
+```markdown
+## ✅ Action Items
+```
+```markdown
+## 📜 Detailed Meeting Log
+```
+
+- [ ] **Step 4: Update the placeholder reference table**
+
+Remove the `{{DAY_OF_WEEK}}` row:
+
+```markdown
+| `{{DAY_OF_WEEK}}` | Day of week the meeting was held (e.g., "Monday") | Derived from meeting date |
+```
+
+Add a `{{GREETING}}` row:
+
+```markdown
+| `{{GREETING}}` | A casual, varied greeting (e.g., "Hey folks!", "Happy Monday, Fedora folks!", "Hi everyone!", "Good morning, Fedora friends!") — vary naturally across posts | Generated by Gem |
+```
+
+Update the `{{MEETING_DATE}}` row — change the description from:
+
+```
+Meeting date in YYYY-MM-DD format
+```
+
+To:
+
+```
+Meeting date in long format (e.g., "April 21, 2026")
+```
+
+Update the `{{TEAM_CONTEXT_SENTENCE}}` row — change the description from:
+
+```
+One sentence describing what the team does or current focus
+```
+
+To:
+
+```
+1-2 sentences: one describing the team's role in the Fedora Project, one describing this meeting's thematic focus
+```
+
+Update the `{{TOPICS_BULLETED_LIST}}` row — change the description from:
+
+```
+Markdown bulleted list of major topics covered
+```
+
+To:
+
+```
+Markdown bulleted list of substantive discussion topics only — exclude announcements, introductions, housekeeping, and minor asides
+```
+
+- [ ] **Step 5: Verify template structure**
+
+Read the modified template end-to-end. Verify:
+1. The post body section flows: greeting → team context → topics list → AI disclaimer → meeting links → executive summary → action items → detailed log.
+2. All section headings are `##` (h2), not `#` (h1).
+3. The placeholder reference table has entries for every `{{PLACEHOLDER}}` used in the post body, and no entries for removed placeholders.
+4. The `{{DAY_OF_WEEK}}` placeholder does not appear anywhere in the file.
+
+- [ ] **Step 6: Commit**
+
+Commit message scope: template structure updates — flexible greeting, h2 headings with emojis, updated placeholder descriptions.
+Suggested gitmoji: ♻️ (refactor).
+Component: `templates`.
+
+---
+
+### Task 3: Add conventions section to Gem definition
+
+**Files:**
+- Modify: `definition.md`
+
+- [ ] **Step 1: Insert the `<conventions>` section**
+
+Insert the following block between the closing `</task>` tag (currently line 89) and the opening `<output_format>` tag (currently line 91):
+
+```markdown
+
+<conventions>
+**People References:**
+* In the Executive Summary, introduce key actors on first mention as `FirstName (@username)`. All subsequent mentions in the Executive Summary use `@username` only.
+* In the Detailed Meeting Log, always use `@username` only. Readers at this depth have already seen the introductions in the Executive Summary.
+
+**Ticket References:**
+* Use the `### Ticket:` prefix for all ticket-related section headers in the Detailed Meeting Log, regardless of issue tracker.
+* Format section headers as: `### Ticket: [shorthand](full_url) (Optional Description)`
+  - Forgejo: use cross-repo shorthand `org/repo#number` — e.g., `[docs/tickets#19](https://forge.fedoraproject.org/docs/tickets/issues/19)`
+  - Bugzilla: `[BZ#12345](url)`
+  - GitHub: `[org/repo#number](url)`
+* Use the same linked shorthand format when referencing tickets inline in prose (Executive Summary, Detailed Meeting Log).
+
+**Proper Nouns:**
+* Use correct capitalization for project and tool names. Common examples: "AsciiDoc" (not "ASCIIDoc" or "Asciidoc"), "Quick Docs" (not "QuickDocs"), "Forgejo", "Pagure".
+
+**Fedora Organizational Naming:**
+* Use "Mindshare branch" when referring to the Mindshare Committee's branch of the org chart. Do not append "& Outreach."
+
+**Off-Topic Tangents:**
+* If a tangent does not produce a decision, action item, or follow-up, omit it entirely from the summary.
+* If a tangent leads to a concrete outcome, include it but focus on the outcome, not the tangent itself.
+
+**Completed Action Items:**
+* If an action item is "post the meeting summary on Fedora Discussion" (or equivalent), apply strikethrough formatting (`~~text~~`) since that action is completed by the act of posting the summary itself.
+
+**Topics Bulleted List:**
+* The `{{TOPICS_BULLETED_LIST}}` must contain only substantive discussion topics — items that drove decisions, action items, or significant technical discussion. Exclude announcements, introductions, greetings, housekeeping, and minor asides.
+</conventions>
+```
+
+- [ ] **Step 2: Verify placement**
+
+Read `definition.md` and verify the `<conventions>` section appears between `</task>` and `<output_format>`, with blank lines separating it from both.
+
+- [ ] **Step 3: Commit**
+
+Commit message scope: adding community conventions and editorial rules to the Gem definition.
+Suggested gitmoji: ✨ (new feature).
+Component: `definition`.
+
+---
+
+### Task 4: Update definition constraints and context
+
+**Files:**
+- Modify: `definition.md`
+
+- [ ] **Step 1: Add template fidelity constraint**
+
+In the `<constraints>` section, add this bullet after the existing `**Ticket coverage**` bullet (the last one before `</constraints>`):
+
+```markdown
+* **Template fidelity:** Follow the templates in `discourse-post.md` and `forgejo-comment.md` exactly. Match the heading levels, bullet styles (`-` not `*`), Markdown link syntax, and section order. Do not substitute alternative formatting. The template is the source of truth for structure and presentation.
+```
+
+- [ ] **Step 2: Add example file reference to context**
+
+In the `<context>` section, under the **Output Templates** list (after the `forgejo-comment.md` bullet), add:
+
+```markdown
+- **`examples/output/2026-04-21-docs-discourse.md`**: A validated golden reference of a complete Discourse post output. Consult this example to understand the target output quality, formatting conventions, and style. When in doubt about a formatting choice, match this example.
+```
+
+- [ ] **Step 3: Verify changes**
+
+Read the `<constraints>` section and verify the new bullet is present and consistent with the existing constraint style. Read the `<context>` section and verify the example file reference appears after the template references.
+
+- [ ] **Step 4: Commit**
+
+Commit message scope: strengthening template compliance constraint and referencing golden example.
+Suggested gitmoji: ✨ (new feature).
+Component: `definition`.
+
+---
+
+### Task 5: Add condensed inline example to definition
+
+**Files:**
+- Modify: `definition.md`
+
+- [ ] **Step 1: Insert the `<example>` section**
+
+Insert the following block after the closing `</constraints>` tag and before the closing `</output>` tag:
+
+```markdown
+
+<example>
+The following excerpts from a validated Docs Team meeting summary demonstrate the expected formatting conventions.
+For the complete golden reference, see `examples/output/2026-04-21-docs-discourse.md`.
+
+**Greeting, introduction, and topics list:**
+
+{{GREETING}} :waving_hand: Here is the summary of the April 21, 2026, Fedora Docs Team meeting.
+
+As a core part of the Fedora Mindshare branch, the Docs Team ensures that Fedora's official documentation is accurate, accessible, and well-maintained.
+Today's meeting focused on modernizing our build infrastructure on Forgejo, managing the archiving of legacy documentation, and sustaining our growing community.
+
+**Topics discussed in this meeting:**
+- Removing GitLab and Pagure references from documentation repositories
+- Container registry exploration for Antora build images
+- SHA256 git repository compatibility workaround
+- Establishing a `docs-archive` organization for legacy content
+
+---
+
+**Executive Summary excerpt — note `FirstName (@username)` on first mention, `[org/repo#number](url)` for tickets:**
+
+A primary focus was placed on removing legacy GitLab and Pagure references across our repositories ([docs/tickets#19](https://forge.fedoraproject.org/docs/tickets/issues/19)). @korora volunteered to work on this. To address the fragmentation of the `docsbuilder.sh` scripts and the missing Containerfile, the team is exploring the use of Forgejo's native container registries to host the Antora build images. Hristo (@hricky) has volunteered to lead this investigation.
+
+---
+
+**Action Items excerpt — note strikethrough on "post meeting summary":**
+
+* **@jflory7**: ~~Post a meeting summary on Fedora Discussion~~ and ticket updates for all discussed tickets in today's meeting
+
+---
+
+**Detailed Meeting Log section header — note `### Ticket:` prefix with linked shorthand:**
+
+### Ticket: [docs/tickets#19](https://forge.fedoraproject.org/docs/tickets/issues/19) (Removing GitLab/Pagure References)
+
+**Detailed Meeting Log body — note bare `@username`, no first names:**
+
+@pbokoc requested help fixing the references primarily in the template repository to establish a "known good" setup before propagating the changes elsewhere. @korora took an action item to lead this effort.
+
+However, @cstrauf pointed out that the biggest underlying issue is the missing Containerfile, which builds the custom Fedora Antora styles.
+</example>
+```
+
+- [ ] **Step 2: Verify placement and content**
+
+Read `definition.md` and verify:
+1. The `<example>` section appears between `</constraints>` and `</output>`.
+2. The example excerpts demonstrate all five conventions: flexible greeting, `FirstName (@username)` in executive summary, `[org/repo#number](url)` ticket shorthand, strikethrough on completed action items, bare `@username` in detailed log.
+3. The section references the full golden example file by path.
+
+- [ ] **Step 3: Commit**
+
+Commit message scope: adding condensed inline example to demonstrate formatting conventions.
+Suggested gitmoji: ✨ (new feature).
+Component: `definition`.
+
+---
+
+### Task 6: Verify placeholder consistency across files
+
+**Files:**
+- Read: `definition.md`
+- Read: `templates/discourse-post.md`
+- Read: `examples/output/2026-04-21-docs-discourse.md`
+
+- [ ] **Step 1: Check placeholder names match**
+
+Run the following to extract all `{{PLACEHOLDER}}` names from both files:
+
+```bash
+grep -oP '\{\{[A-Z_]+\}\}' templates/discourse-post.md | sort -u
+grep -oP '\{\{[A-Z_]+\}\}' definition.md | sort -u
+```
+
+Verify that every placeholder used in the template's post body section has a corresponding entry in the placeholder reference table, and that any placeholders referenced in the definition match the template's names exactly.
+
+- [ ] **Step 2: Check removed placeholders are fully removed**
+
+```bash
+grep -n 'DAY_OF_WEEK' templates/discourse-post.md definition.md
+```
+
+Expected: no matches. `{{DAY_OF_WEEK}}` should not appear in either file.
+
+- [ ] **Step 3: Check inline example matches template structure**
+
+Read the `<example>` section in `definition.md` and verify the excerpt formatting (heading levels, bullet style, link syntax) matches the updated template in `discourse-post.md`. Specifically:
+- Meeting links heading is `## 🔗 Links to Meeting Logs` (not shown in excerpt, but consistent)
+- Section headings are `##` with emojis (not shown in excerpt, but consistent)
+- Bullets use `-` for lists
+- Ticket references use `[org/repo#number](url)` format
+
+- [ ] **Step 4: Check golden example is structurally consistent with template**
+
+Compare the section order in `examples/output/2026-04-21-docs-discourse.md` with `templates/discourse-post.md`:
+1. Greeting line
+2. Team context sentence(s)
+3. Topics bulleted list (note: the golden example predates the topics list addition — this is expected and acceptable since the example was the first real use)
+4. AI disclaimer
+5. Meeting links
+6. Executive Summary
+7. Action Items
+8. Detailed Meeting Log
+
+Note: the golden example may not have the `**Topics discussed:**` bulleted list since it was created before this template change. This is acceptable — the example demonstrates formatting conventions, not template compliance for the topics section.
--- a/docs/superpowers/specs/2026-04-22-gem-refinement-design.md
+++ b/docs/superpowers/specs/2026-04-22-gem-refinement-design.md
@ -0,0 +1,95 @@
+# Gem Refinement — Post-First-Use Feedback
+
+## Overview
+
+After the first real use of the Meeting Secretary Gem (Fedora Docs Team, 2026-04-21), the AI-generated output required significant human editing before posting to Fedora Discussion.
+This spec captures the systematic differences between the AI output and the human-edited final version, and defines changes to the Gem definition, templates, and examples to bring the AI output closer to the desired result.
+
+## Problem
+
+The Gem's output deviated from the template and Fedora community conventions in several categories:
+
+1. **Template compliance failures** — the AI used different heading levels, bullet styles, link formats, and AI disclaimer wording than specified in the template.
+2. **Missing community conventions** — the AI didn't know Fedora-specific patterns like `@username` reference style, Forgejo cross-repo ticket shorthand, correct proper noun capitalization, or organizational branch naming.
+3. **Editorial judgment gaps** — the AI included off-topic tangents, used overly formal greetings, and missed conventions like strikethrough for completed action items.
+
+## Changes
+
+### 1. `templates/discourse-post.md`
+
+**1a. Greeting line** — Replace fixed greeting with flexible placeholder:
+
+- Current: `Happy {{DAY_OF_WEEK}}, Fedora folks! :waving_hand: Here is a summary of the recent meeting of the **{{TEAM_NAME}}** held on **{{MEETING_DATE}}.`
+- New: `{{GREETING}} :waving_hand: Here is the summary of the {{MEETING_DATE}}, {{TEAM_NAME}} meeting.`
+- `{{GREETING}}` description lists example greetings for variety: "Hey folks!", "Happy Monday, Fedora folks!", "Hi everyone!", "Good morning, Fedora friends!"
+- `{{MEETING_DATE}}` description changes to long date format ("April 21, 2026").
+- Remove `{{DAY_OF_WEEK}}` placeholder (absorbed into `{{GREETING}}`).
+
+**1b. Team context** — Update `{{TEAM_CONTEXT_SENTENCE}}` description to "1-2 sentences: one describing the team's role in the Fedora Project, one describing this meeting's thematic focus."
+
+**1c. Topics bulleted list** — Update `{{TOPICS_BULLETED_LIST}}` description: "Substantive discussion topics only. Exclude announcements, introductions, meeting housekeeping, and minor asides. These are the agenda items that drove decisions or action items."
+
+**1d. Meeting links heading** — Change from `**Meeting Links:**` to `## 🔗 Links to Meeting Logs`.
+
+**1e. Section heading levels** — Change from h1 to h2 with emojis:
+
+- `# Executive Summary` → `## 📝 Executive Summary`
+- `# Action Items` → `## ✅ Action Items`
+- `# Detailed Meeting Log` → `## 📜 Detailed Meeting Log`
+
+**1f. Placeholder reference table** — Update descriptions for `{{GREETING}}`, `{{MEETING_DATE}}`, `{{TEAM_CONTEXT_SENTENCE}}`, `{{TOPICS_BULLETED_LIST}}`. Remove `{{DAY_OF_WEEK}}`.
+
+### 2. `definition.md`
+
+**2a. New `<conventions>` section** — Placed between `<task>` and `<output_format>`. Encodes community writing conventions and editorial judgment rules:
+
+- **People references:** Executive Summary uses `FirstName (@username)` on first mention, then `@username`. Detailed Meeting Log always uses `@username` only.
+- **Ticket references:** `### Ticket:` prefix for all section headers. Forgejo cross-repo shorthand `[org/repo#number](url)`. Same linked shorthand inline in prose. Adapts for other trackers (Bugzilla, GitHub).
+- **Proper nouns:** Correct capitalization — "AsciiDoc", "Quick Docs", "Forgejo", "Pagure".
+- **Fedora organizational naming:** "Mindshare branch", not "Mindshare & Outreach branch".
+- **Off-topic tangents:** Omit unless they produce a decision, action item, or follow-up.
+- **Completed action items:** Strikethrough for "post the meeting summary" items.
+- **Topics bulleted list:** Substantive topics only.
+
+**2b. Strengthen template compliance** — New constraint:
+
+> **Template fidelity:** Follow the templates exactly. Match heading levels, bullet styles (`-` not `*`), Markdown link syntax, and section order. The template is the source of truth for structure and presentation.
+
+**2c. Reference example file** — Add to `<context>` under Output Templates:
+
+> `examples/output/2026-04-21-docs-discourse.md`: A validated golden reference of a complete Discourse post output. Consult this example to understand the target output quality, formatting conventions, and style.
+
+**2d. Condensed inline example** — New `<example>` section after `<constraints>`. Short labeled excerpts (~30-40 lines total) drawn from the Docs Team golden reference, demonstrating:
+
+- Flexible greeting + long date format + team context + substantive topics list
+- Executive summary with `FirstName (@username)` first mention and `[org/repo#number](url)` inline
+- Action items with strikethrough on "post meeting summary"
+- Detailed log `### Ticket:` section header with linked shorthand
+- Detailed log body with `@username` only
+
+### 3. `examples/output/2026-04-21-docs-discourse.md`
+
+New file: the full human-edited Discourse post from the 2026-04-21 Fedora Docs Team meeting.
+Includes an HTML comment provenance note at the top explaining it was generated by Google Gemini, then human-edited by @jflory7.
+Contains real Meetbot URLs (not placeholders) — this is a real output, not a template.
+Referenced by the Gem definition as a golden quality and formatting baseline.
+
+## Decisions made during design
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Greeting style | Flexible with examples | Variety prevents robotic repetition across posts |
+| Meetbot URL construction | Keep as placeholders | User prefers to fill in URLs manually for safety |
+| @username convention | FirstName in exec summary, @username in detailed log | Exec summary introduces actors; detailed log assumes familiarity |
+| Topics bulleted list | Keep, substantive only | Surfaces the heart of the meeting without housekeeping noise |
+| Ticket section headers | Always `### Ticket:` with linked shorthand | Consistent regardless of tracker; clickable references |
+| Off-topic tangents | Omit unless they produce outcomes | Tangents that generate action items are meeting content |
+| Strikethrough | Auto-apply for "post summary" items only | That case is definitionally complete; other completions are human judgment |
+| Example placement | Hybrid: full file + condensed inline excerpts | Maximum few-shot learning signal without bloating the definition |
+| Example URLs | Keep real URLs | Real example should look like a real post |
+
+## Out of scope
+
+- Changes to `templates/forgejo-comment.md` (no issues identified in this round).
+- Changes to `knowledge/teams.md` or `knowledge/meetbot-commands.md`.
+- Meetbot URL auto-construction (explicitly declined).