You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airflow.apache.org by po...@apache.org on 2026/09/24 13:08:28 UTC

(airflow) branch main updated: Require a human-written summary in agent-drafted PR descriptions (#73660)

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 <ja...@potiuk.com>
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