Pull Request Description Guidelines & Template for Remediation Agents
This reference defines the required structure, writing guidelines, and standard template for Pull Request descriptions generated by remediation agents.
PR Title Guidelines
- Descriptive & Actionable: The title must clearly describe the specific code or documentation fix being made so anyone reviewing PR lists immediately understands what it addresses (e.g.,
fix(swift): create missing top-level README in swift/coreordocs(spec): sync component schema with core types). - Conventional Commits Format: Follow standard conventional commit format (
type(scope): concise summary). - No Generic Numbers: Do NOT include generic issue or recommendation numbers (such as
issue #2178 recommendation 3) in the PR title. The issue reference belongs exclusively in the PR body.
Writing Guidelines
- Focus on Intent ("Why") over Mechanics ("How"): Explain what problem in the compliance report is being solved and why the specific code/doc change addresses it.
- Factual, Plain Language: Avoid hyperbolic prose or filler. State changes concisely and objectively.
- Markdown Formatting:
- Use backticks for file paths, CLI commands, variable names, and symbols (e.g.
python/a2ui_agent). - Include references to the compliance report issue (e.g.,
Addresses #2178). - Quote hashtag references with backticks if they are not meant to be GitHub issue links.
- Use backticks for file paths, CLI commands, variable names, and symbols (e.g.
Mandatory PR Description Structure
When creating the PR description file (e.g. pr_description.md), follow this exact structure, replacing ${ISSUE_NUMBER} and ${RECOMMENDATION_INDEX} with the target issue number and recommendation index:
## Summary
[Provide a 1-2 sentence overview of the remediation fix, referencing the original compliance report issue and recommendation index, e.g., "Addresses recommendation 3 from compliance report issue #2178 by creating `swift/core/README.md`."]
## Changes
- [Bulleted list of specific files added, modified, or deleted.]
- [Summary of primary code, blueprint, or documentation modifications made.]
## Impact & Risks
- [Notes on any potential side effects, public API changes, or dependencies. State "No breaking changes or external dependency impacts" if applicable.]
## Testing
- [Step-by-step list of verification checks performed, e.g., unit test execution, linter output, static checks.]
---
### How to Inspect or Modify This Branch Locally
To check out and make additional changes to this PR branch:
```bash
# Check out the PR branch locally using GitHub CLI
gh pr checkout <PR_NUMBER>
# Make your edits, then commit and push back
git commit -am "fix: additional adjustments for recommendation ${RECOMMENDATION_INDEX}"
git push
```