feat(templates): aim PR bodies at outside readers #218

Merged

claudiomaradonna merged 1 commit from docs/pr-template-readers into main 2026-11-11 12:09:31 +01:00

Conversation 0 Commits 1 Files changed 3 +115 -55

motoko commented 2026-11-11 12:08:10 +01:00

Collaborator

Copy link

Why

Agent Foundry gives a repository the instructions its coding agents
follow. When an agent finishes a change, the deliver skill has it open
a pull request whose body it writes from one template,
.agents/templates/pull-request.md; a Forgejo repository also shows a
copy to people who open one in the web form.

The template wrote for a reviewer who already knows the project, so a
contributor, an adopter, or the maintainer months later could not tell
from a body why a change mattered or check that it worked. In the last
eight merged pull requests, Why opened on a commit hash or an audit;
What changed listed edits file by file; How to verify asked the reader
to read a file, used placeholders such as <branch>, or relied on the
author's machine; and issues linked in prose closed only the first of
two, or none.

Set aside: reading as enough for every change to what agents read,
which shows nothing about what the agent does, and the billed
behavioral evals as the standard scenario.

What changed

Before, the template named one reader with the diff beside them. Now
Why and How to verify speak to a person new to the project, and What
changed and Considerations to the reviewer.

Before, Why could open on a commit and link its issue in any form. Now
it opens with what the touched part is and who uses it, then the problem
as a person meets it, and ends with one Closes #<n> or Refs #<n>
line per issue. What changed tells before and after, then names files in
one sentence.

Before, How to verify asked for repeatable steps, main's result
optional. Now each scenario shows the problem on main, then its absence
on the branch, by the same literal commands, which create every input,
with versions and both results quoted; a change to what agents read
gives a trial repository and the exact prompt. Only a change that alters
nothing a person or an agent does is verified by reading. The author
runs each scenario or says it was not run.

AGENTS.md now sizes a pull request body at about two minutes, counted
without its How to verify, instead of one.

The template's comments, their Forgejo copy, and the size bullet of
AGENTS.md § Writing for readers hold the change.

How to verify

What to have first: Git 2.48 or later, and Claude Code 2.1.322 or later
logged in to an account that can run a session.

The problem, on main: make a trial clone holding the commit of #195 with
main's template, and ask an agent for that commit's body.

git clone https://git.unitoo.it/claudiomaradonna/agent-foundry.git pr-trial
cd pr-trial
git fetch origin docs/pr-template-readers
git switch -c trial 1641a72
git checkout origin/main -- .agents/templates/pull-request.md
claude -p "Write the body of a pull request for commit 1641a72 alone, as step 5 of the deliver skill asks, into ../body-main.md. Push nothing and open nothing."

Expected on main: ../body-main.md opens Why on the diagnose skill's
steps rather than on what the skill is for, and its How to verify asks
the reader to read step 4, or gives steps with placeholders and no
result on main.

The solution, on the branch: the same steps with the branch's template.

git checkout origin/docs/pr-template-readers -- .agents/templates/pull-request.md
claude -p "Write the body of a pull request for commit 1641a72 alone, as step 5 of the deliver skill asks, into ../body-branch.md. Push nothing and open nothing."

Expected on the branch: ../body-branch.md opens Why on what
diagnose is and who runs it, and its How to verify makes a trial
repository with literal commands and gives an exact prompt, with what
the agent does on main and on the branch, both quoted.

Checks run on the tip: bash tests/verify-agent-config.sh (234 tests),
bash tests/agent-config/real-source.sh (6 tests, including the one
that keeps the Forgejo copy equal to the template),
bash tests/check-work-folder.sh (46 tests),
.agents/hooks/shellcheck.sh repo, prettier --check '**/*.md',
scripts/verify-agent-config.sh, and git diff --check main, all
passing. The change adds no regression test, since no test reads the
template's comments.

Could not be tried: the scenario above was not run, since each of its
two agent sessions is a billed run; its expected results come from the
template's text, not from a session.

Considerations

A body now takes longer to write, since its author runs each scenario
first. Set aside from review: whether Forgejo closes another
repository's issue from Closes and its full URL, unverified, and the
form AGENTS.md already requires.

## Why Agent Foundry gives a repository the instructions its coding agents follow. When an agent finishes a change, the `deliver` skill has it open a pull request whose body it writes from one template, `.agents/templates/pull-request.md`; a Forgejo repository also shows a copy to people who open one in the web form. The template wrote for a reviewer who already knows the project, so a contributor, an adopter, or the maintainer months later could not tell from a body why a change mattered or check that it worked. In the last eight merged pull requests, Why opened on a commit hash or an audit; What changed listed edits file by file; How to verify asked the reader to read a file, used placeholders such as `<branch>`, or relied on the author's machine; and issues linked in prose closed only the first of two, or none. Set aside: reading as enough for every change to what agents read, which shows nothing about what the agent does, and the billed behavioral evals as the standard scenario. ## What changed Before, the template named one reader with the diff beside them. Now Why and How to verify speak to a person new to the project, and What changed and Considerations to the reviewer. Before, Why could open on a commit and link its issue in any form. Now it opens with what the touched part is and who uses it, then the problem as a person meets it, and ends with one `Closes #<n>` or `Refs #<n>` line per issue. What changed tells before and after, then names files in one sentence. Before, How to verify asked for repeatable steps, main's result optional. Now each scenario shows the problem on main, then its absence on the branch, by the same literal commands, which create every input, with versions and both results quoted; a change to what agents read gives a trial repository and the exact prompt. Only a change that alters nothing a person or an agent does is verified by reading. The author runs each scenario or says it was not run. `AGENTS.md` now sizes a pull request body at about two minutes, counted without its How to verify, instead of one. The template's comments, their Forgejo copy, and the size bullet of `AGENTS.md` § Writing for readers hold the change. ## How to verify What to have first: Git 2.48 or later, and Claude Code 2.1.322 or later logged in to an account that can run a session. The problem, on main: make a trial clone holding the commit of #195 with main's template, and ask an agent for that commit's body. ```sh git clone https://git.unitoo.it/claudiomaradonna/agent-foundry.git pr-trial cd pr-trial git fetch origin docs/pr-template-readers git switch -c trial 1641a72 git checkout origin/main -- .agents/templates/pull-request.md claude -p "Write the body of a pull request for commit 1641a72 alone, as step 5 of the deliver skill asks, into ../body-main.md. Push nothing and open nothing." ``` Expected on main: `../body-main.md` opens Why on the `diagnose` skill's steps rather than on what the skill is for, and its How to verify asks the reader to read step 4, or gives steps with placeholders and no result on main. The solution, on the branch: the same steps with the branch's template. ```sh git checkout origin/docs/pr-template-readers -- .agents/templates/pull-request.md claude -p "Write the body of a pull request for commit 1641a72 alone, as step 5 of the deliver skill asks, into ../body-branch.md. Push nothing and open nothing." ``` Expected on the branch: `../body-branch.md` opens Why on what `diagnose` is and who runs it, and its How to verify makes a trial repository with literal commands and gives an exact prompt, with what the agent does on main and on the branch, both quoted. Checks run on the tip: `bash tests/verify-agent-config.sh` (234 tests), `bash tests/agent-config/real-source.sh` (6 tests, including the one that keeps the Forgejo copy equal to the template), `bash tests/check-work-folder.sh` (46 tests), `.agents/hooks/shellcheck.sh repo`, `prettier --check '**/*.md'`, `scripts/verify-agent-config.sh`, and `git diff --check main`, all passing. The change adds no regression test, since no test reads the template's comments. Could not be tried: the scenario above was not run, since each of its two agent sessions is a billed run; its expected results come from the template's text, not from a session. ## Considerations A body now takes longer to write, since its author runs each scenario first. Set aside from review: whether Forgejo closes another repository's issue from `Closes` and its full URL, unverified, and the form `AGENTS.md` already requires.

motoko added 1 commit 2026-11-11 12:08:15 +01:00

feat(templates): aim PR bodies at outside readers ... b04e7781d7

Bodies written from the template assumed a reader who knows the
project: Why opened on commits and audits, What changed listed edits
file by file, and How to verify gave steps nobody could repeat on
another machine. The template now names its two readers, has How to
verify show the problem on main before the solution on the branch, and
gives each closed issue its own closing line, which the forge acts on.

A body that says this much exceeds a minute, so the size rule gives it
about two, counted without its How to verify.

claudiomaradonna merged commit b04e7781d7 into main 2026-11-11 12:09:31 +01:00

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

claudiomaradonna/agent-foundry!218

No description provided.