Skip to content

Improve PR template guidance and add a pull-requests skill - #80699

Open
jeryj wants to merge 6 commits into
trunkfrom
update/ai-pr-instructions
Open

Improve PR template guidance and add a pull-requests skill#80699
jeryj wants to merge 6 commits into
trunkfrom
update/ai-pr-instructions

Conversation

@jeryj

@jeryj jeryj commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

Note: This PR Description was entirely written by the AI Agent following the new PR Skill and Template. For another example, see the PR Description for #80699 as well (I asked my agent to follow this branch's instructions when writing the PR description).

What?

Sharpens the PR template's authoring guidance and adds a pull-requests skill so AI agents produce PR descriptions that are easier for humans to review. Follow-up to #80650, which established the skills pattern this builds on.

Why?

Testing instructions in PR descriptions are often not actionable: they restate checks that commit hooks and CI already enforce, describe methodology instead of executable steps, or omit where a reviewer would observe the result. Agent-authored descriptions repeat these failures predictably (observed while developing #80650). Guidance that helps human authors belongs in the template; the agent-specific residue belongs in a skill per the conventions established in #80650 — not in ever-growing template comments.

How?

  • .github/PULL_REQUEST_TEMPLATE.md: Testing Instructions comments now require only manual reviewer steps (checks enforced by hooks/CI are omitted), each step easy to verify pass/fail, with the example modeling a "Confirm " shape. The What/How and AI-disclosure comments are tightened.
  • skills/pull-requests/SKILL.md (new): the agent-specific rules — describe the committed diff rather than the local working tree; name where each result is observable ("confirm it where?" must never be a question); assume the standard reviewer setup, no boilerplate.
  • AGENTS.md: the skills routing line now lists skills/pull-requests/SKILL.md as the route for PR-description tasks.

Testing Instructions

  1. In a fresh agent session on this branch, prompt: Draft the PR description for the current branch.
  2. Confirm in the session transcript (every file read is echoed in the conversation) that skills/pull-requests/SKILL.md is read before the description is produced.
  3. Read the produced description's testing steps and confirm each "Confirm" names where to look (a URL, screen element, command output, or file) — any step that leaves you asking "confirm it where?" is a failure.

Use of AI Tools

Template wording and the skill were drafted with Claude Code (Claude Fable 5) in interactive sessions, directed and reviewed by the author; the skill's rules were validated against transcript-captured agent runs.

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Jul 24, 2026

Copy link
Copy Markdown

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

  • Required label: Any label starting with [Type].
  • Labels found: [Type] Task, [Type] Developer Documentation.

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

@github-actions

Copy link
Copy Markdown

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

  • Required label: Any label starting with [Type].
  • Labels found: .

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

@github-actions

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: jeryj <jeryj@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@jeryj jeryj added [Type] Developer Documentation Documentation for developers [Type] Task Issues or PRs that have been broken down into an individual action to take labels Jul 24, 2026
jeryj added 3 commits July 24, 2026 15:00
AI is producing overly verbose and unnecessary items in PR descriptions. This is an attempt to improve results.
@jeryj
jeryj force-pushed the update/ai-pr-instructions branch from 5c7fd2d to 32954c9 Compare July 24, 2026 19:02
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Type] Developer Documentation Documentation for developers [Type] Task Issues or PRs that have been broken down into an individual action to take

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant