The gap (operator-surfaced: "guide authoring !== release notes; if that skill misses it, there is a gap")
The render-verify-Mermaid discipline lives ONLY in guide-authoring. Two sibling narrative-doc skills that also require Mermaid -- release-notes-workflow and blog-post -- carry none of it. Different skills, different artifact classes: an author following the release-notes (or blog) skill adds diagrams but is never told to verify them.
V-B-A (grep all three skill sources, 2026-07-03)
| skill |
Mermaid required? |
render-verify discipline? |
guide-authoring/references/guide-authoring-bar.md §3 |
yes |
YES -- render-verify before merge (no local headless renderer -> route to a browser-backed peer or confirm on the portal); TD Mermaid (SKILL.md L3: "render-verified TD Mermaid"); no self-loops; no reserved-word node IDs; explicit note "#14340 merged broken-green because CI does not validate Mermaid" |
release-notes-workflow.md |
yes (§5 "Mermaid before/afters where the story is architectural") |
NONE -- 0 mentions of render / TD / diagram pitfalls; §7 cut-readiness checklist never verifies diagrams |
blog-post/references/blog-authoring-guide.md |
yes ("Diagrams (Mermaid) earn their place...") |
NONE |
Contract Ledger
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback / Edge Case |
Docs |
Evidence |
.agents/skills/blog-post/references/blog-authoring-guide.md |
This ticket's V-B-A table + guide-authoring/references/guide-authoring-bar.md §3 |
Blog authors see that Mermaid diagrams must be render-verified before merge and are routed to the canonical full discipline. |
Full Mermaid mechanics stay in the guide-authoring bar; the blog surface remains a pointer, not a duplicate rule body. |
Update this reference payload only; no SKILL.md router or manifest change expected. |
rg "render-verified before merge" .agents/skills/blog-post/references/blog-authoring-guide.md; Skill Manifest Lint. |
.agents/skills/release-notes/references/release-notes-workflow.md |
This ticket's V-B-A table + guide-authoring/references/guide-authoring-bar.md §3 |
Release-note Mermaid before/afters explicitly inherit the render-verified-before-merge discipline. |
Full Mermaid mechanics stay in the guide-authoring bar; the release-notes surface remains a pointer, not a duplicate rule body. |
Update this reference payload only; no SKILL.md router or manifest change expected. |
rg "render-verified before merge" .agents/skills/release-notes/references/release-notes-workflow.md; Skill Manifest Lint. |
Empirical trigger
#14554: I authored release-notes Mermaid following release-notes-workflow, shipped flowchart LR unrendered, it overflowed the portal width, merged, and Vega fixed it LR -> TD (#14556). guide-authoring-bar §3 ALREADY prescribes TD, the render-verify method, and even the "CI won't catch it" warning -- but it's in the sibling skill the release-notes author never opens.
Fix -- factor-shared (the grep says all three need it)
Extract the Mermaid-render discipline into ONE shared reference (promote/relocate guide-authoring-bar §3 to a shared payload) that guide-authoring, release-notes-workflow, and blog-post each cite. Single source, no drift, closes the gap for all three. Plus:
- release-notes-workflow §7 cut-readiness gains an item: "every diagram render-verified at final head."
- Release-notes-specific method note: a staging note is NOT portal-routed pre-publish, so its render-verify path is a browser-backed-peer render, not "confirm on the portal."
Implementation note from PR #14776: current shipped shape keeps guide-authoring-bar §3 as the canonical shared source and adds pointer-sized discipline to the sibling skill payloads, avoiding copy-fan-out while closing the authoring gap.
Adjacent (note, don't scope here)
§3 already flags "#14340 merged broken-green because CI does not validate Mermaid" -> a CI Mermaid-parse validator is the mechanical backstop; larger separate lane.
#14557 was my mis-framed version -- attributed the requirement to guide-authoring §5 for a release-notes artifact (wrong skill), and assumed no render method exists (wrong -- §3 documents one). Closing in favor of this.
Scope note: .agents/skills/* edit = substrate; the fix PR takes cross-family review. Operator-directed.
Owner: @neo-opus-grace. Refs #14554, #14556, #14340, part of #14310.
Authored by Grace (@neo-opus-grace, Claude Opus 4.8).
The gap (operator-surfaced: "guide authoring !== release notes; if that skill misses it, there is a gap")
The render-verify-Mermaid discipline lives ONLY in guide-authoring. Two sibling narrative-doc skills that also require Mermaid -- release-notes-workflow and blog-post -- carry none of it. Different skills, different artifact classes: an author following the release-notes (or blog) skill adds diagrams but is never told to verify them.
V-B-A (grep all three skill sources, 2026-07-03)
guide-authoring/references/guide-authoring-bar.md§3#14340merged broken-green because CI does not validate Mermaid"release-notes-workflow.mdblog-post/references/blog-authoring-guide.mdContract Ledger
.agents/skills/blog-post/references/blog-authoring-guide.mdguide-authoring/references/guide-authoring-bar.md§3SKILL.mdrouter or manifest change expected.rg "render-verified before merge" .agents/skills/blog-post/references/blog-authoring-guide.md; Skill Manifest Lint..agents/skills/release-notes/references/release-notes-workflow.mdguide-authoring/references/guide-authoring-bar.md§3SKILL.mdrouter or manifest change expected.rg "render-verified before merge" .agents/skills/release-notes/references/release-notes-workflow.md; Skill Manifest Lint.Empirical trigger
#14554: I authored release-notes Mermaid following release-notes-workflow, shipped
flowchart LRunrendered, it overflowed the portal width, merged, and Vega fixed itLR -> TD(#14556). guide-authoring-bar §3 ALREADY prescribes TD, the render-verify method, and even the "CI won't catch it" warning -- but it's in the sibling skill the release-notes author never opens.Fix -- factor-shared (the grep says all three need it)
Extract the Mermaid-render discipline into ONE shared reference (promote/relocate guide-authoring-bar §3 to a shared payload) that guide-authoring, release-notes-workflow, and blog-post each cite. Single source, no drift, closes the gap for all three. Plus:
Implementation note from PR #14776: current shipped shape keeps
guide-authoring-bar§3 as the canonical shared source and adds pointer-sized discipline to the sibling skill payloads, avoiding copy-fan-out while closing the authoring gap.Adjacent (note, don't scope here)
§3 already flags "
#14340merged broken-green because CI does not validate Mermaid" -> a CI Mermaid-parse validator is the mechanical backstop; larger separate lane.Supersedes #14557
#14557 was my mis-framed version -- attributed the requirement to guide-authoring §5 for a release-notes artifact (wrong skill), and assumed no render method exists (wrong -- §3 documents one). Closing in favor of this.
Scope note:
.agents/skills/*edit = substrate; the fix PR takes cross-family review. Operator-directed.Owner: @neo-opus-grace. Refs #14554, #14556, #14340, part of #14310.
Authored by Grace (@neo-opus-grace, Claude Opus 4.8).