Skip to content

Delete the local PR templates; keep the generic org default #53

Description

@lesnik512

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 line Docs 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.md line "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 four AGENTS.md files 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 reason modern-di and
    faststream-outbox held their copies back.
  • Nothing about the 22 planning/ repos. The original blocker was that a
    convention template would land on repos whose own AGENTS.md forbids 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 and faststream-outbox's did not; neither repo's AGENTS.md says it. It is
    not being added. chat-app enforces it mechanically in just check-adrs and 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

Activity

  1. added
    documentationImprovements or additions to documentation
    enhancementNew feature or request
    needs-infoWaiting on reporter for more information
    on Sep 6, 2026
  2. added
    ready-for-agentFully specified, ready for an AFK agent
    and removed
    needs-infoWaiting on reporter for more information
    on Sep 6, 2026
  3. changed the title [-]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[/+] on Sep 6, 2026
  4. lesnik512 commented on Sep 6, 2026

    @lesnik512
    MemberAuthor

    Four PRs open, one per repo:

    that-depends is untouched, as decided.

    Two items deliberately left out of all four, both noted in #73's non-goals:

    • The ADR revisit-trigger phrase still stands in .github's own AGENTS.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:8 repeats the org-wide claim that docs: keep the generic PR template as a deliberate org default #73 deletes from AGENTS.md. It needs the same fix.
  5. lesnik512 commented on Sep 6, 2026

    @lesnik512
    MemberAuthor

    Done. Four PRs merged:

    that-depends keeps its template, as decided.

    Two changes beyond the original scope, both to AGENTS.md and both maintainer calls made during the work:

    • docs: cut the Workflow section to what nothing else supplies #77 cut the ## Workflow section to what nothing else supplies. The ADR and issue routes were already written in docs/agents/domain.md and docs/agents/issue-tracker.md, and NNNN-slug.md, sequential comes from the domain-modeling skill's ADR format. The negative clauses ("no change file, no lane to choose, no planning/ tree") described directories that do not exist.
    • docs: stop asserting the PR-body shape in AGENTS.md #79 dropped the PR-body shape statement from AGENTS.md entirely, matching the same removal in the three repos above. The shape is expected to come from the agent-skills convention rather than each repo's AGENTS.md.

    One thing worth watching: the shape statement in AGENTS.md is what produced Why/Design/Non-goals/Verification bodies in this repo while its own PR template said Summary/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.md may still repeat the org-wide-conventions claim that #73 removed from AGENTS.md, and chat-app/planning/README.md still states the PR-body shape (it goes away with #70).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or requestready-for-agentFully specified, ready for an AFK agent

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions