diff --git a/.agents/skills/create-pr/SKILL.md b/.agents/skills/create-pr/SKILL.md index d11d8cc3737..58b671ca625 100644 --- a/.agents/skills/create-pr/SKILL.md +++ b/.agents/skills/create-pr/SKILL.md @@ -78,11 +78,24 @@ Creates GitHub PRs with titles that pass n8n's `check-pr-title` CI validation. body structure, then populate each section with actual content before creating the PR: - **Summary**: describe what the PR does + - **Why**: explain why the change is needed (see Why below) - **How to test**: describe how to test the changes. Include an example workflow if appropriate - **Related tickets**: add the Linear ticket URL (`https://linear.app/n8n/issue/[TICKET-ID]`) and any GitHub issue links - **Checklist**: keep as-is from the template - Add a "🤖 PR Summary generated by AI" at the end of the body + Before you create the PR, proofread the body with these checks. Rewrite + each sentence that fails a check: + 1. The Summary and the Why together are under the word budget. If not, + first remove the details that the reviewer reads in the diff, then + shorten the Why. + 2. Each sentence names who does what: a component, a process, or a person + as the subject, with a plain technical verb. + 3. Each domain term has a plain definition where it first appears. + 4. Each sentence is true for the diff. + + When a later commit changes a fact in the body, update the body. + ```bash gh pr create --draft --title "(): " --body "$(cat <<'EOF' @@ -94,12 +107,43 @@ Creates GitHub PRs with titles that pass n8n's `check-pr-title` CI validation. Based on `.github/pull_request_template.md`: -Write the PR body in ASD-STE100 Simplified Technical English: use short -sentences, the active voice, and one instruction for each sentence. +Write for a reviewer who does not know this area of the code. The reviewer +must understand the change before they open the diff. Use ASD-STE100 +Simplified Technical English: short sentences, active voice. +1. Keep the Summary and the Why together under about 200 words. A small PR + needs much less. +2. Define each domain term in plain words where it first appears. Do not use + a ticket ID or an internal name as an explanation. +3. Leave out details that the reviewer reads in the diff: error cases, status + codes, renamed fields, the order of calls, file lists, test names. Mention + one only when it changes behaviour that a reviewer could miss. Also leave + out what reviewers already know (framework behaviour). +4. Use plain technical verbs, not metaphors ("passes the value", not + "hands the value" or "lets the value through"). -### Summary Section -- Describe what the PR does -- Include screenshots/videos for UI changes +### Summary: what the PR does +1. Start with one to three sentences of background for a reader who is new to + the area. Then state what the PR does. +2. Write **prose** about behaviour, not a list of code edits. Name a class or + a function when it represents an essential/core concept and it helps + the reader to navigate the change. +3. If the PR changes no product code, say so in the first sentence + (for example: "This PR only adds tests."). +4. Do not justify the change here. The justification goes in the Why. +5. Include screenshots or videos for UI changes. + +### Why: the reasoning +Always fill the `## Why` section. The Summary and the core of the +Why are what the reviewer needs most. Keep the core short: +1. Do not repeat the Summary. +2. State the problem or the constraint that makes the pre-existing code unfit. +3. If there are accepted gaps, or changes for existing code paths, state them + in a separate short paragraph. + +Add rejected alternatives only when a reviewer would otherwise ask about them, +if any. Use one or two sentences for each alternative: state the concrete +reason it fails. Write an alternative that was never built in the conditional. +Together, the alternatives must be shorter than the core Why section. ### How to test Section - Explain how to test the changes diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index affa78d5877..2c1b0874177 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,8 +1,15 @@ ## Summary + +## Why + + ## How to test