trigger: model_decision description: rules to apply to pull request descriptions
@CONTRIBUTING.md
Pull Request Conventions
Before drafting any pull request description, strictly adhere to the rules in CONTRIBUTING.md above.
Prevent Agent Oversight of CONTRIBUTING.md
- Always include
@CONTRIBUTING.md in rule definitions so that PR formatting rules are injected into context whenever PR workflows run.
Commit & PR Types
fix: / feat:: User-visible changes ONLY.build: / build(release):: Internal release tooling (dev/release/), developer workflows, and build scripts. Always prefer build(release): over chore: or chore(release):.docs:: Documentation and issue templates (.github/ISSUE_TEMPLATE/).ci:: .bazelci and Buildkite CI configurations.workflow: / workflows:: GitHub Actions workflow configurations (.github/workflows/).tests:: Test-only changes and test-helper fixes (never fix: or fix(tests):).agents: / agents(<scope>):: Agent rules, skills, and prompts (.agents/).refactor:: Internal refactoring and fixes for unreleased changes. Never use fix: or feat: unless modifying released, user-visible behavior.
PR Commit Workflow Invariant
- Once a Pull Request is created, always make new commits or merge commits.
- NEVER amend or rebase commits on an active PR branch to avoid breaking code review threads.
- PR Metadata Discrepancies: If a PR title or description diverges from the branch's actual scope, notify the user of the discrepancy and ask for confirmation before updating GitHub.
- NEVER include a list of per-file edits, changelog bullet points of individual file modifications, test execution logs/checklists, or AI disclosure metadata in PR descriptions or commit messages.
- AI Disclosure & Comment Etiquette: Keep the PR description clean for use as the merge commit message. Only when initially creating a new PR, post a separate comment so maintainers understand who/what they are interacting with: explain how comments on the PR will be handled (whether an agent autonomously monitors and replies, whether a human reviews/approves agent responses before posting, or whether the human responds directly). Do not post a standalone AI disclosure comment when merely pushing commits to an existing PR (such as a Dependabot PR); instead, disclose AI authorship only on comments you actually post (see below). Never post comments for every CI run or narrate build IDs, commit SHAs, line counts, or trivial diff details (e.g., “comment-only”); comment
PTAL only when ready for re-review. - High-level overview only: state why the change is made and how at a conceptual level. Link related issues (e.g.
Work towards #<issue>). - Conciseness & Style (Strunk & White): Omit needless words. Use clear, active, and direct phrasing for why and how.
- Preserve Existing Descriptions: Preserve the author's wording unless instructed to change it. Wrap bodies at 72 columns.
- Open Questions & Follow-Up Items:
- Add the
"do not merge" label to the PR when the PR description contains open questions (e.g., gh pr edit <pr> --repo bazel-contrib/rules_python --add-label "do not merge"). - During code review, inspect the PR description and comments for open questions,
TODO items, or “Things we could do / follow-up” notes. Evaluate each item against the diff and project rules, flag unresolved items with BLOCKER, QUESTION, or HUMAN-SIGN-OFF, and verify the "do not merge" label is applied if open questions remain.
PR Review Comments & Thread Resolution
- End every posted PR comment or review reply with an italicized disclosure line:
- If the exact comment text was not shown to and approved by the user before posting (including automatic PR AI disclosure comments):
*This is an automatically generated agent comment.* - Only if the user was shown the exact comment text and explicitly approved posting it:
*This is an agent-generated comment reviewed and approved by the user.*
- After fixing an inline PR review thread, reply with the commit hash and explanation (
addPullRequestReviewThreadReply) and resolve the thread (resolveReviewThread) via gh api graphql, batching at most 3-4 threads per request to avoid 502 Bad Gateway timeouts.