This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 56bfaf70fe6 Require a human-written summary in agent-drafted PR
descriptions (#73660)
56bfaf70fe6 is described below
commit 56bfaf70fe6f4758670ba4f94e9f2687341e1b6c
Author: Jarek Potiuk <[email protected]>
AuthorDate: Thu Sep 24 15:08:19 2026 +0200
Require a human-written summary in agent-drafted PR descriptions (#73660)
Reviewers need a signal that a person understood and owns an agent-assisted
change. A short summary in the author's own words, kept separate from the
agent's description, gives them that - but only if the agent never writes
it.
Generated-by: Claude Opus 5
---
.agents/skills/airflow-pr-draft-summary/SKILL.md | 39 ++++++++++++++++++++++++
.agents/skills/airflow-publish-changes/SKILL.md | 21 +++++++++++--
AGENTS.md | 2 ++
contributing-docs/05_pull_requests.rst | 4 +++
dev/skill-evals/last-eval-hash.txt | 2 +-
5 files changed, 64 insertions(+), 4 deletions(-)
diff --git a/.agents/skills/airflow-pr-draft-summary/SKILL.md
b/.agents/skills/airflow-pr-draft-summary/SKILL.md
index 780f6c82b96..9df8f540b23 100644
--- a/.agents/skills/airflow-pr-draft-summary/SKILL.md
+++ b/.agents/skills/airflow-pr-draft-summary/SKILL.md
@@ -62,6 +62,45 @@ For `airflow-core` (and `chart/`, `dev/mypy/`)
**user-facing** changes, add a ne
- NEVER add Co-Authored-By with yourself as co-author of the commit. Agents
cannot be authors, humans can be, Agents are assistants.
+## PR descriptions: Human Summary and AI Summary
+
+An agent-drafted PR description starts with a `## Human Summary`: a few
sentences
+**typed by the human author in their own words** — why the change is needed,
the key
+decision or trade-off, and anything reviewers should watch for. The
agent-written
+description goes below it, collapsed under `## AI Summary`. Reviewers read the
Human
+Summary as evidence that a person understood and owns the change, so it must
never be
+produced by an agent. PRs written by humans with the regular template are
unaffected.
+
+1. **Ask the user to type the Human Summary** — e.g. "Please type a short
Human Summary
+ (2–5 sentences, your own words: why this change, key decisions, caveats). I
will paste
+ it verbatim." Then wait for their reply.
+2. **Paste the reply verbatim.** Do not reword, expand, shorten, translate,
reformat, or
+ "fix" it — typos included.
+3. **Never write, draft, suggest, or pre-fill it yourself** — not a proposed
wording for
+ the user to approve, not a paraphrase of something the user said earlier in
the
+ session, not a summary of the commits, not a copy of the AI Summary. If the
user asks
+ you to write it, decline and explain that it has to come from them.
+4. If the user prefers to type it in the browser, leave only the `<!-- ... -->`
+ placeholder under the heading. Do not put any agent text there.
+
+```markdown
+closes: #ISSUE (if applicable)
+
+## Human Summary
+
+<!-- The human author's own words, pasted verbatim. Agents must never write
this. -->
+
+## AI Summary
+
+<details><summary>Click here</summary>
+
+Agent-written description of what the PR changes and why.
+
+</details>
+```
+
+The Gen-AI disclosure block from the repository template follows after a `---`.
+
## GitHub messages drafted by agents
Anything an agent drafts that ends up posted to GitHub on the user's
diff --git a/.agents/skills/airflow-publish-changes/SKILL.md
b/.agents/skills/airflow-publish-changes/SKILL.md
index cc4fe94beb7..aadd48df2f8 100644
--- a/.agents/skills/airflow-publish-changes/SKILL.md
+++ b/.agents/skills/airflow-publish-changes/SKILL.md
@@ -129,16 +129,30 @@ git rebase upstream/<target_branch>
If there are conflicts, resolve them and continue the rebase. If the rebase is
too complex,
ask the user for guidance.
+Before creating the PR, ask the user to type the `## Human Summary` and paste
it
+verbatim — never write it yourself. See
+[PR descriptions: Human Summary and AI
Summary](../airflow-pr-draft-summary/SKILL.md#pr-descriptions-human-summary-and-ai-summary).
+
Then push the branch to your fork (`origin`) and open the PR creation page in
the browser
with the body pre-filled (including the generative AI disclosure already
checked):
```bash
git push -u origin <branch-name>
gh pr create --web --title "Short title (under 70 chars)" --body "$(cat <<'EOF'
-Brief description of the changes.
-
closes: #ISSUE (if applicable)
+## Human Summary
+
+<!-- The human author's own words, pasted verbatim. Agents must never write
this. -->
+
+## AI Summary
+
+<details><summary>Click here</summary>
+
+Agent-written description of what the PR changes and why.
+
+</details>
+
---
##### Was generative AI tooling used to co-author this PR?
@@ -157,7 +171,8 @@ pre-fills the PR template with the generative AI disclosure
already completed.
Remind the user to:
1. Review the PR title — keep it short (under 70 chars), in the imperative
mood, and focused on user impact. Do not use Conventional Commits prefixes
(`fix:`, `feat:`, `chore:`, …).
-2. Add a brief description of the changes at the top of the body.
+2. Check the `## Human Summary` is their own words — or type it in the browser
now if they
+ left it for later.
3. Reference related issues when applicable (`closes: #ISSUE` or `related:
#ISSUE`).
## Golden rule: when a fix is imminent, open the PR, not an issue
diff --git a/AGENTS.md b/AGENTS.md
index b8ff11f1efe..0ef55585787 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -191,6 +191,8 @@ Before working on an issue, check for existing PRs. Push
only to the user's fork
never upstream or `main`. Never list an agent as a commit co-author. Retain the
required Gen-AI disclosure and GitHub-message attribution; do not tag
individuals
outside the exceptions in the message guidance. Drafting does not authorize
posting.
+Agent-drafted PR descriptions start with a `## Human Summary` that the user
types and
+you paste verbatim — never write, suggest, or paraphrase it yourself.
## apache-magpie framework
diff --git a/contributing-docs/05_pull_requests.rst
b/contributing-docs/05_pull_requests.rst
index f8889d4eb13..ce9716d9666 100644
--- a/contributing-docs/05_pull_requests.rst
+++ b/contributing-docs/05_pull_requests.rst
@@ -239,6 +239,10 @@ adhere to the following guidelines:
* Make sure to run all relevant static checks and tests locally to verify that
the generated code works as
intended and does not introduce any issues.
* State in your PR description that you have used Gen-AI tools to assist in
creating the PR.
+* When an agent drafts the PR description, start it with a short ``## Human
Summary`` that you type
+ yourself (why the change is needed, key decisions, caveats), and put the
agent-written text below
+ it under a collapsed ``## AI Summary``. Never let the agent write the Human
Summary. PRs written
+ without Gen-AI tools keep using the regular PR template unchanged.
* Be prepared to explain and justify the use of Gen-AI tools if asked by
project maintainers or reviewers.
* Remember that the final responsibility for the code in your PR lies with
you, regardless of whether
it was generated by a tool or written by you.
diff --git a/dev/skill-evals/last-eval-hash.txt
b/dev/skill-evals/last-eval-hash.txt
index d3cf53abff5..2f14d413b18 100644
--- a/dev/skill-evals/last-eval-hash.txt
+++ b/dev/skill-evals/last-eval-hash.txt
@@ -1,3 +1,3 @@
# Generated by dev/skill-evals/eval.py — do not edit or resolve conflicts by
hand.
# Run `prek run run-skill-eval --hook-stage manual --all-files` to regenerate.
-485f916101818db48c8311bd3e96770695e8681411e9c063a1ff05bc1d051d7c
+b845e771c378087ff85e7a813cfcf04659415b1926af932a19857437e4134d31
