Document the resources page's embedded-video convention in AGENTS.md

[fullsend-ai-retro]

What happened

On PR #548 a new resource entry for the Red Hat Summit 2026 demo initially shipped without an embedded video iframe. The fullsend review agent flagged the missing {{< rawhtml >}} embed as a low structural-consistency finding, softening it because a prior article-only entry also omitted the embed. A human maintainer (simonbaird) then submitted a change-request review asking for an embedded video player. The contributor added an iframe embed in a follow-up push and the change was accepted. website/content/resources/_index.md contains 5+ YouTube iframe embeds already, so the convention is clearly established in the code; it just is not written down anywhere the reviewer can point to as a firm rule.

What could go better

The delta between the agent review and the human review is the severity assigned to the missing embed. The agent read the file, noticed the convention, but treated one counter-example (an article-only entry) as license to downgrade the finding to low. The human treated the same signal as change-requesting. If the convention were documented as a rule in AGENTS.md, the review agent would have a firm anchor to raise the finding to at least medium, and future contributors would know the expectation up front — closing the delta without further human intervention. Uncertainty: I am confident the site already follows this convention and confident that documenting it would move the agent's severity assignment; I am less sure whether "video resources must embed" needs any escape hatch (e.g., videos hosted on platforms without iframe support). The wording of the rule should include an explicit fallback, e.g., "...when the hosting platform provides an iframe embed URL; otherwise, link only."

Proposed change

Edit AGENTS.md in conforma/conforma.github.io to add a short subsection (under a new or existing "Website content conventions" heading) stating: "Resource entries for videos in website/content/resources/_index.md should include an inline video embed using the {{< rawhtml >}} shortcode with an <iframe> when the hosting platform exposes an embed URL (e.g., YouTube /embed/, Google Drive /preview). Entries that link to articles or non-embeddable media may omit the embed." Optionally, add the same guidance as a short note near the top of website/content/resources/_index.md so contributors see it while editing.

Validation criteria

On the next 3 PRs that add a video-based resource entry: the initial commit includes an embed iframe (no human change-request needed to add one), and the fullsend review agent either raises no embed-related finding or, if the embed is missing, flags it at medium severity citing the new AGENTS.md rule. Track whether human reviewers still need to ask for embeds on subsequent PRs — the target is zero such asks in the next 3 video-resource PRs.

---

Generated by retro agent from #548

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 6:54 AM UTC · Completed 6:57 AM UTC

Commit: cd01138 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-7 · Effort: high · Cost: $0.79

[fullsend-ai-triage]

Triage summary

This is a small, well-scoped documentation change. AGENTS.md exists at the repo root with a numbered-section structure the new guidance can slot into, and the proposed wording already includes the escape hatch called out in the issue (non-embeddable platforms).

Points worth flagging for the implementer

• Match AGENTS.md's tone. Existing sections are terse and imperative ("Write only the code required...", "Modify only what the issue authorizes..."). Keep the new subsection in the same voice — a couple of sentences, no meta-commentary about review agents.
• Placement. There is no existing "Website content conventions" heading, so the change will either create a new numbered top-level section (e.g., ## 10. Website content conventions) or nest under an adjacent one. The former is cleaner given there is no natural parent today.
• Optional mirror in _index.md. The issue suggests a short note near the top of website/content/resources/_index.md. Treat this as truly optional — the primary win is the AGENTS.md rule the review agent can anchor to. Adding a duplicate note in the content file risks drift.
• Scope discipline. Per AGENTS.md §3, do not restructure existing resource entries or normalize the pre-existing article-only entry as part of this change.

Validation

Docs-only change; verification is behavioral and runs outside CI. Success is measured over the next 3 video-resource PRs: the initial commit includes an embed iframe, and if it does not, the review agent flags it at medium severity citing the new rule.

Proposed test case

Given: a PR adds a new video-based resource entry without an iframe embed.
When:  the fullsend review agent runs.
Then:  it raises a finding at medium severity, citing the new AGENTS.md rule.

Given: a PR adds a video-based resource entry with the {{< rawhtml >}}
       <iframe> embed on the first push.
When:  the review agent runs.
Then:  no embed-related finding is raised.

Edge: a resource entry whose source lacks an embed URL falls under the
      fallback clause and should not trigger a finding.

---

Next steps:

• /fs-code — agent creates a PR to implement this issue
• /fs-code <your instruction> — agent implements with your specific guidance

[fullsend-ai-coder]

🤖 Finished Code · ✅ Success · Started 6:59 AM UTC · Completed 7:04 AM UTC

Commit: cd01138 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-7 · Effort: high · Cost: $1.96