docs(git-and-github): plain-language-first PR/issue body templates

[lklimek]

TL;DR: PR and issue descriptions now share one plain-language-first template — TL;DR, user story, scenario, then technical detail — and the templates live in their own files instead of being copy-pasted inside the skill instructions.

User story

As a developer or reviewer reading a Claudius-authored PR or issue, I want to understand what changed/what's wrong and why in one glance, without wading through implementation detail, to achieve a quick approve/triage decision.

Scenario

Base flow

Claudius (or any agent using the git-and-github skill) opens a pull request or an issue.

Actual behavior

PR descriptions led with a "Why this PR exists" section mixing plain rationale with technical language, with no separation from the rest of the body. Issues only had a bare one-line rule ("feature/enhancement issues need a User Story section") and no real structure otherwise. Both the PR skeleton and its gh CLI fallback example duplicated the same markdown block in two places inside the skill.

Expected behavior

PRs and issues both lead with a one-sentence TL;DR, a plain-language user story, and a scenario (base flow / actual behavior / expected behavior) any reader can follow at a glance — technical/bug-repro terminology optional depending on doc type. Everything technical (what was done, testing, breaking changes, checklist, attribution, prior work for PRs; free-form notes for issues) nests under "Detailed discussion" for implementors and AI agents. The literal skeletons live once each, in references/pr-body-template.md and references/issue-body-template.md; SKILL.md and the gh CLI fallback doc just link to them.

Detailed discussion

What was done

• Replaced the "Why this PR exists" PR-body skeleton in skills/git-and-github/SKILL.md §Creating a PR with TL;DR → ## User story → ## Scenario (### Base flow / ### Actual behavior / ### Expected behavior) → ## Detailed discussion (nests What was done/Testing/Breaking changes/Checklist/Attribution/Prior work).
• Unified §Issues onto the same skeleton, replacing the old bare "User Story" bullet. For bug reports, Scenario doubles as the reproduction; feature requests with nothing to reproduce may drop it.
• Externalized both skeletons out of SKILL.md prose into skills/git-and-github/references/pr-body-template.md and references/issue-body-template.md — SKILL.md and references/gh-cli-fallback.md now link to them instead of inlining copies (the gh CLI fallback now fills in the template and passes it via --body-file instead of a giant inline heredoc).
• skills/push/SKILL.md updated to reference the new skeleton by name.
• Mid-review, renamed "Reproduction scenario" to "Scenario" — "Reproduction" presumes a bug and read oddly for feature PRs; "Scenario" keeps the same sub-structure and applies to both.
• Added a trailing ### Prior work section to both templates — links to possibly related/similar PRs or issues, each with a one-sentence summary of how it relates to the one being filed (see this PR's own Prior work below for a worked example).
• Merged main in: #75 landed agent-watchdog --dump-job on main with its own plugin.json bump to 5.13.0 — collided with this branch's own 5.12.1 → 5.13.0 bump (identical target version, different content, no merge-conflict marker since the value matched). Re-bumped this branch to 5.14.0 and reordered the CHANGELOG.md entries so 5.14.0 (this PR) sits above the now-merged 5.13.0 (#75). Also fixed a CI ruff format --check failure on the two new test files.

Testing

• python3 -m pytest tests/test_pr_body_template.py tests/test_issue_body_template.py -v — 9/9 pass.
• python3 -m pytest tests/ -q — 614 passed (611 + 3 from the merged-in #75), 2 skipped, 4 pre-existing failures unrelated to this change (missing python3-reportlab apt package in this environment, not caused by this diff).
• ruff format --check . — clean after fixing the two flagged test files.
• Independently validated with plugin-dev:plugin-validator and plugin-dev:skill-reviewer after each round of edits; both flagged nitpicks (duplication, wording) which were fixed before this description was written.

Breaking changes

None — this changes the default PR/issue-body skeleton produced by the git-and-github/push skills going forward. No code interface changes; existing PR/issue descriptions are untouched.

Checklist

• I have performed a self-review of my own change
• I have added/updated relevant tests (tests/test_pr_body_template.py, tests/test_issue_body_template.py)
• I have made corresponding documentation changes (CHANGELOG.md, references/pr-body-template.md, references/issue-body-template.md, references/gh-cli-fallback.md, push/SKILL.md)

Attribution

_{🤖 Co-authored by Claudius the Magnificent AI Agent}

Prior work

• docs(git-and-github): PR bodies lead with "Why this PR exists" (4.4.0) #43 — "PR bodies lead with 'Why this PR exists'": introduced the section this PR fully replaces; this PR keeps the same "rationale before mechanics" goal but restructures it into TL;DR/User story/Scenario for a non-technical reader, with implementation detail demoted to Detailed discussion.
• docs(review-pr): Pass C v1.1 — fenced-body heuristic + doc refinements (4.5.0) #44 — "review-pr Pass C v1.1 — fenced-body heuristic + doc refinements": hardened review-pr's parsing of PR-body ## Summary/## What changed headers with a bullet-list fallback; this PR's new skeleton doesn't use either heading, so it falls through to that same bullet-list fallback unaffected — confirmed during this PR's own review, no changes needed there.
• feat(agent-watchdog): add --dump-job one-shot CLI lookup #75 — "agent-watchdog: add --dump-job one-shot CLI lookup": unrelated feature, merged into main while this PR was open; caused the version-bump collision described above, resolved by merging main in and re-bumping to 5.14.0.

[Copilot]

Pull request overview

This PR restructures how Claudius-authored pull request and issue bodies are generated by the git-and-github (and indirectly push) skill, adopting a shared “plain-language-first” template and externalizing the literal skeletons into reference files to avoid duplication.

Changes:

• Externalized PR/issue body skeletons into skills/git-and-github/references/{pr,issue}-body-template.md and updated git-and-github + CLI fallback docs to link to them.
• Updated push and added/updated regression tests to pin the new heading set and prevent templates from being inlined back into skill prose.
• Bumped plugin version to 5.13.0 and documented the behavioral change in CHANGELOG.md.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
tests/test_pr_body_template.py	Updates regression guard to validate the externalized PR template structure and prevent inlining in skills.
tests/test_issue_body_template.py	Adds a matching regression guard for the externalized issue template.
skills/push/SKILL.md	Updates PR-body guidance to reference the new template structure.
skills/git-and-github/SKILL.md	Replaces the inlined PR/issue-body guidance with links and plain-language-first requirements.
skills/git-and-github/references/pr-body-template.md	Adds the canonical PR body template.
skills/git-and-github/references/issue-body-template.md	Adds the canonical issue body template.
skills/git-and-github/references/gh-cli-fallback.md	Updates CLI fallback instructions to use --body-file and link to templates.
CHANGELOG.md	Documents the template overhaul and externalization under 5.13.0.
.claude-plugin/plugin.json	Version bump 5.12.1 → 5.13.0.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.