Repository navigation
Delete the local PR templates; keep the generic org default #53
Description
What changed
This issue was "host the PR-body-as-spec template as the org default, and retire
the local copies". Measuring the templates before sequencing the swap inverted the
conclusion: the PR template does no work in this org, and hosting it centrally
would not change that. The work is now three deletions and four reference fixes.
The measurement
Mechanism. gh pr create reads .github/PULL_REQUEST_TEMPLATE.md only in its
interactive editor path or when passed -T/--template. --body and --body-file
skip it. gh 2.98.0's own help is explicit: "--body to skip this". An agent
opening a PR with --body-file never touches the template. Only the web compare UI
applies it automatically.
Authorship. 26 of the 28 non-archived org repos have exactly one PR author,
lesnik512, opening PRs through gh. The two exceptions are
fastapi-sqlalchemy-template (4 outside humans across 47 PRs) and that-depends.
Where the convention checklist actually appears, in the four repos carrying it:
| repo | ### Before merging present |
|---|---|
modern-di |
20 of the last 40 merged PRs, and none since #432 (11 consecutive without it) |
faststream-outbox |
0 of 20 |
chat-app |
0 of 11 |
.github |
1 of 20, and that one is #61, the PR that installed it |
Where a template does work. that-depends is the only repo with real
contributor traffic: 9 distinct PR authors, lesnik512 a minority at 28 of 100,
xelandernt at 54. Across its last 25 PRs, xelandernt (web UI) filled the
template in 8 of 9, checklist included. lesnik512 (agent, --body) filled it
in 0 of 16.
Where a template does not work even on humans. fastapi-sqlalchemy-template
inherits the generic default, so its 4 outside contributors were all shown it.
Their PR bodies: 1726 characters, 159, 78, and one empty.
What did spread. The Why / Design / Non-goals / Verification shape is
used consistently, including in this repo (#62, #63, #65) whose own template says
Summary / Changes / Checklist. faststream-outbox #141-#157 carried the
convention template locally and produced bare ## Verification bodies. The shape
tracks AGENTS.md, which is loaded on every turn. It does not track the template,
which is never opened.
The conclusion: what the agent reads persists, and what it does not read decays. The
convention already lives in each repo's AGENTS.md, which is the only channel that
reaches the party writing the PR.
Why not host it centrally anyway
Two reasons the original plan does not survive the measurement.
It would duplicate AGENTS.md. The checklist's four routes restate the
"Where a fact goes" table and the two-things-outlive-the-PR paragraph that each
adopting repo's AGENTS.md already carries. By the admission check, a fact
derivable from a file the agent already loads does not get written.
AGENTS.md is not inheritable, so the central-hosting argument does not
transfer. GitHub's default community health files are CODE_OF_CONDUCT.md,
CONTRIBUTING.md, discussion category forms, FUNDING.yml, issue and pull request
templates plus config.yml, SECURITY.md, and SUPPORT.md. AGENTS.md is not on
that list, and no repo's AGENTS.md references this one. The 27 copies are
independent by necessity; that duplication is accepted deliberately rather than
solved with a generator.
The work
.github (this repo)
.github/PULL_REQUEST_TEMPLATE.md: keep it as the org default, and delete the one
checklist lineDocs updated if behavior or public API changed. That line asks the
pre-convention question ("did you update the page?") and is the only part of the
generic form that is untrue for a repo on the convention. Everything else stands:
lint, type check, tests, build, metadata are true under either convention.AGENTS.md: drop the opening claim that its conventions apply across all repos in
the org. No other repo has ever read this file. Reword the Workflow blockquote so
the generic default reads as a deliberate choice rather than a pending replacement.
modern-di, faststream-outbox, chat-app
- Delete
.github/PULL_REQUEST_TEMPLATE.md. All three fall back to the org default. AGENTS.md: drop the sentence naming the template as the carrier of the shape. The
AGENTS.mdline "the spec for a change is its PR body: why, design, non-goals,
verification" stays and is now the whole statement of it.
that-depends
- Nothing. Its template is the only one measurably in use, its
mypy/pyrefly
checklist line is a legitimate reason to stay local, and it keeps its own copy.
Deliberately not done
- The per-section guidance is dropped, not relocated. The templates were the only
place explaining what belongs under each heading. The four section names carry
enough on their own; moving ten lines of prose into fourAGENTS.mdfiles trades a
file nobody reads for weight on a file loaded every turn. - No ADR. The reasoning is this issue body.
- No drift check. With no local templates left outside
that-depends, there is
nothing to silently override, which was the only reasonmodern-diand
faststream-outboxheld their copies back. - Nothing about the 22
planning/repos. The original blocker was that a
convention template would land on repos whose ownAGENTS.mdforbids it. With the
generic default staying, nothing collides, so this issue neither needs nor waits on
their migration. That migration is tracked independently in Migrate the remaining repos off the planning/ convention #67. - The revisit-trigger clause is dropped.
modern-di's template said an ADR needs
one andfaststream-outbox's did not; neither repo'sAGENTS.mdsays it. It is
not being added.chat-appenforces it mechanically injust check-adrsand is
unaffected.
Revisit trigger
A repo other than that-depends starts taking regular outside contributions. At that
point a template becomes load-bearing for that repo, and it should get a local one
matching what its contributors need.
Related
- Host the PR-body-as-spec template org-wide; adopt the convention here #50, Rename CLAUDE.md to AGENTS.md org-wide, with CLAUDE.md as a symlink #51 (both closed; their step 1 and the
AGENTS.mdrename have landed) - that-depends has no agent instructions file #69 —
that-dependshas no agent instructions file - chat-app is half-migrated: the PR body is the spec, but planning/ is still a merge gate #70 —
chat-appis mid-migration offplanning/
Activity
docs: adopt the PR-body-as-spec convention, retiring planning/ and ar…
[-]Host the PR-body-as-spec template as the org default, and retire the local copies[/-][+]Delete the local PR templates; keep the generic org default[/+]lesnik512 commentedon Sep 6, 2026
Four PRs open, one per repo:
AGENTS.mdclaiming org-wide reachthat-dependsis untouched, as decided.Two items deliberately left out of all four, both noted in #73's non-goals:
.github's ownAGENTS.md. This issue decided not to propagate it to the other repos; removing it here would change this repo's own ADR practice and is a separate call.CONTEXT.md:8repeats the org-wide claim that docs: keep the generic PR template as a deliberate org default #73 deletes fromAGENTS.md. It needs the same fix.lesnik512 commentedon Sep 6, 2026
Done. Four PRs merged:
Docs updated if behavior or public API changedline, stopAGENTS.mdclaiming org-wide reachthat-dependskeeps its template, as decided.Two changes beyond the original scope, both to
AGENTS.mdand both maintainer calls made during the work:## Workflowsection to what nothing else supplies. The ADR and issue routes were already written indocs/agents/domain.mdanddocs/agents/issue-tracker.md, andNNNN-slug.md, sequentialcomes from the domain-modeling skill's ADR format. The negative clauses ("no change file, no lane to choose, noplanning/tree") described directories that do not exist.AGENTS.mdentirely, matching the same removal in the three repos above. The shape is expected to come from the agent-skills convention rather than each repo'sAGENTS.md.One thing worth watching: the shape statement in
AGENTS.mdis what producedWhy/Design/Non-goals/Verificationbodies in this repo while its own PR template saidSummary/Changes/Checklist. Nothing asserts it now. If PR bodies degrade over the next few PRs, that is the signal the skills convention has not picked it up yet.Still open and unaddressed:
CONTEXT.mdmay still repeat the org-wide-conventions claim that #73 removed fromAGENTS.md, andchat-app/planning/README.mdstill states the PR-body shape (it goes away with #70).