draft-pr: PR bodies should be professionally formatted (bullets, fenced commands, backticked/fenced HTML)

[JoshuaVSherman]

Problem

Draft PRs opened via create-draft-pr.sh often render with poor formatting: run-on summary sentences, and — worse — raw HTML/code (e.g. <sup>35</sup>) passed as plain text gets rendered or eaten by GitHub markdown, garbling the description (PR #82 was an example: "<sup>35</sup> Then" collapsed to "35 Then" in the body).

Root cause

scripts/create-draft-pr.sh interpolates whatever strings are passed to --summary / --test-plan / --test-evidence verbatim under their headers. It doesn't (and shouldn't) reformat content — so professional formatting has to come from the caller filling those flags with proper markdown. Today nothing instructs the agent to do that.

Desired behavior

PR bodies should be professionally formatted every time, regardless of which agent/lane opened them:

• Summary as bullet points, not a single run-on sentence.
• Shell commands in fenced ```sh code blocks.
• Any HTML or code wrapped in backticks or a fenced code block so GitHub renders it literally (never pass raw <tag> as prose).
• Optionally a short before/after example where it aids clarity.

Fix (guidance, since the script can't infer structure)

Add a "PR body formatting" section + a concrete template/example to the PR-authoring guidance, in all three places that tell an agent how to call the script:

• skills/draft-pr/SKILL.md (Claude Code lane)
• agy/webjam-tasks/skills/next/SKILL.md (agy /next lane)
• AGENTS.md (ad-hoc path)

(Consider whether create-draft-pr.sh should additionally warn when a flag value contains an unfenced <...> HTML tag — optional, low priority.)

Acceptance criteria

• The three PR-authoring docs include explicit formatting rules (bullets, fenced commands, backticked/fenced HTML+code) and a template example.
• Guidance is consistent across all three so any lane produces the same professional formatting.
• A subsequently opened PR demonstrates the formatting (no run-on summary; no raw/rendered HTML in the body).

Related

• create-draft-pr: shared draft-PR script + skill for Claude Code and agy (always draft, always base dev, Closes #N baked in) #49 — create-draft-pr.sh (the shared PR script)
• agy PR descriptions ship as unfilled placeholders (both /next and ad-hoc paths) #77 / PR agy PR descriptions ship as unfilled placeholders (both /next and ad-hoc paths) #78 — recent PR-authoring guidance changes (same files)
• PR Fix daily-devotional email output: send as HTML, fix header mojibake, superscript verse number #82 — concrete example of the mangled formatting