validmind-docs-coverage skill: two refinements from first outside-author run

[panchicore]

While using skills/validmind-docs-coverage for SC-16823 (PR #1434) — first run by an author other than the skill's creator — two small gaps surfaced. Proposing them for consideration, @cachafla.

1. Warn about {{< var >}} inside headings (cost a render cycle)

A new section heading ## Manage {{< var vm.checker >}} runs rendered with an unusable auto-generated id:

<h2 data-anchor-id="manage-b58fc729-690b-4000-b19f-365a4093b2ff7b7b3c2076617220766d2e636865636b6572203e7d7d-runs">

which silently broke a cross-page footnote link targeting #manage-document-checker-runs. Fix is a one-liner (explicit {#manage-document-checker-runs} on the heading), but the skill doesn't mention it, and any run that adds a heading using a product-name variable will hit it. Suggested addition to SKILL.md §3 (Implement an approved update):

Headings that contain {{< var >}} shortcodes get unusable auto-generated ids — add an explicit {#id} to any heading used as a link target.

2. Branch naming is codex-specific

§3 prescribes codex/sc-<story-id>-<slug>, but in practice author-prefixed branches coexist (juan/sc-16822/... #1425, panchicore/sc-16823-... #1434) and the pr_previews/<branch>/ preview works the same. Suggest wording like:

Start from current origin/main on an author-prefixed branch, e.g. <author>/sc-<story-id>-<slug>.

🤖 Generated with Claude Code

[panchicore]

One more observation from the same run, this one org-level rather than a SKILL.md tweak — flagging it here for consideration since it's adjacent:

3. Two overlapping docs skills, unclear entry point

There are now two org-owned skills that both start from "give me a Shortcut link and I'll handle the docs":

• create-user-documentation (validmind/skills, ~480 lines) — the authoring workflow + ValidMind style conventions for writing .qmd, referenced from this repo's README for Cursor users.
• skills/validmind-docs-coverage (this repo) — the release-coverage workflow: evidence from merged PRs, gap classification, render validation, preview links, tracker updates.

They overlap at the entry point (Shortcut context gathering, PR inspection) but diverge in focus (style/authoring vs. coverage/verification/release). An agent — or a new contributor — can reasonably pick either and miss what the other enforces.

Possible resolution, if it matches your intent for the pilot: make validmind-docs-coverage the single entry point (when/what to document + PR/tracker mechanics) and have it reference create-user-documentation only for the style conventions — or fold the style material into this repo alongside it. Happy to discuss.

🤖 Generated with Claude Code

[panchicore]

Verified both points empirically before proposing an implementation PR:

1. Reproduced. Rendered a scratch page containing ## Manage {{< var vm.checker >}} runs on current main (Quarto 1.9.38):

<h2 class="anchored" data-anchor-id="manage-b58fc729-690b-4000-b19f-365a4093b2ff7b7b3c2076617220766d2e636865636b6572203e7d7d-runs">

Identical garbage id as reported (the trailing hex decodes to the literal {{< var vm.checker >}} shortcode). Current SKILL.md has no mention of heading anchors or explicit {#id}s.

2. Confirmed. SKILL.md §3 prescribes codex/sc-<story-id>-<slug>, while author-prefixed branches already coexist and preview fine:

• [SC-16822] Documentation: Risk Tiering #1425 → juan/sc-16822/documentation-risk-tiering
• [SC-16823] Documentation: Document Checker runs, publishing, and artifacts #1434 → panchicore/sc-16823-document-checker-runs (preview returns 200)
• [SC-16959] Documentation: workflow execution taken path and Step Detail panels #1436 → panchicore/sc-16959-execution-viewer-docs (fresh end-to-end confirmation: validate passed and all six preview pages return 200)

PR implementing both wording changes incoming.

🤖 Generated with Claude Code