change-request-writing

Change Request Writing Skill

Applicable to titles and bodies submitted to reviewers/maintainers, such as GitHub Issue/PR and GitLab Issue/MR. Platform commands are left to SKILL.md / SKILL.md; this skill only handles the copy content.

Pre-creation checks

Before creating an Issue, PR, or MR, first check the platform templates, forms, and current resource state.

1. Prioritize checking repository constraints such as issue / PR / MR templates, platform configuration, project documentation, required fields, labels, base/target branches, and squash policy.
2. If the repository requires a specific title format, body structure, linked issues, checklists, or other platform fields, prepare according to the repository requirements first, then supplement with this skill's default format.
3. Before formally creating, check whether the current code, branch, and commit state are consistent with the content to be submitted to the platform, to avoid creating an Issue, PR, or MR that does not match the current state.

Title and body principles

When creating or updating a title and body, describe only the final information that currently needs to be submitted to the reviewer/maintainer.

• A PR/MR must describe only the net change from the current state of the target branch to the final state of the current branch; do not write based on commit history, development process, temporary experiments, or leftover old body content.
• First confirm the base/head or target/source, then use the final net diff as the basis for the body:git fetch then view git diff --stat <base-or-target>...HEAD and git diff --name-status <base-or-target>...HEAD; if necessary, also review the key file diff or platform diff.
• The body must not include: intermediate commit order, debugging process, failed attempts, temporary solutions, merge/rebase/conflict resolution process, or behavior that was once implemented but no longer exists in the final diff.
• The body must not include local absolute paths, home directories, agent workspace paths, temporary body file paths, or other information that would expose personal/machine environment details; if repository files need to be referenced, use relative paths or Markdown links.
• By default, the PR/MR body does not include Validation. Only add it when the verification content provides high-signal behavioral evidence that the reviewer cannot see in the diff or platform CI status. ## Validation。
• Do not write CI, pipeline, workflow, job, formatting, lint, type checking, build, ordinary unit tests, repository standard test commands, or "tests pass" into the body; these are merge gates already shown by the platform and add little information.
• Even if go test ./...、cargo test、pnpm build、ruff check and other commands were actually run locally, do not write them into the PR/MR body just to prove "I tested it"; unless it is a deliberately constructed red/green regression verification and CI will not naturally cover this signal.
• What can be written under Validation should focus on results CI cannot see: real environment/online/test cluster verification, manual UI/API/CLI behavior confirmation, external service integration, migration dry-run, performance or compatibility data, security boundary verification, or a stable reproduction case in a bug fix going from failing to passing.
• When writing Validation , describe "what behavior and result were verified", not a command log. Do not record exploratory failures, debugging commands, or temporary injected failures unless it is a known risk in the final delivery.
• When updating an existing PR/MR body, do not make partial patches on the old body; first read back the current body, then rewrite the complete body based on the final net diff and replace outdated content.
• If the body has undergone experimental revisions, review the complete PR/MR body again before the final update to ensure it only describes the final diff; do not write rerun、after removing、now、previously or similar wording that exposes the process, unless the process itself is evidence the reviewer needs to examine.
• Judge breaking changes by the final net diff / external behavior, not by mechanically inheriting from intermediate commits; only mark it in the title and body when the final net change actually breaks existing usage.

Issue

1. If the repository requires an issue to include specific fields, labels, reproduction steps, version information, a minimal example, or a category, organize the content accordingly first; do not skip required items.
2. If the issue is related to the current local changes or branch context, first check the relevant code, branch, and commit information to confirm that the issue description matches the current state; do not submit content that is outdated or inconsistent with the code.
3. Keep the title and description concise and clear, and do not write draft paths or other local paths in the body.

PR/MR

The default title and body format is as follows; if it conflicts with team, repository, or platform templates, the existing constraints take precedence. If there are explicit requirements (such as Chinese), follow them first.

1. Title style: English, following the semantic commit convention (such as feat(scope): short summary), concise and describing the core purpose; even if the title is required to be in Chinese, the semantic prefix should still be in English.
2. When there is a breaking change, use type(scope)!: short summaryin the title and add BREAKING CHANGE: in the body to explain the impact and migration approach; otherwise do not add ! or BREAKING CHANGE:。
3. Description style: English, short sentences and bullet points, prioritizing helping readers who do not look at the code quickly understand the motivation, changes, and impact, and avoiding a running account and excessive implementation details. When proprietary terms, function names, method names, class names, API names, or configuration keys are involved, wrap them in inline code (backticks).
4. Default body format:
   • ## Why: 1-2 short sentences explaining why this change is being made, focusing on the problem background or goal.
   • ## What: 1-3 items describing the main changes, focusing on functional or behavioral changes, without listing trivial implementation details.
5. By default, do not add ## Validation; add it only when there is high-signal behavioral evidence that CI cannot see, otherwise omit it.
6. Optional body blocks: add only when truly necessary BREAKING CHANGE:、## Risks or ## Notes。