Repository navigation
Host the PR-body-as-spec template org-wide; adopt the convention here #50
Description
Activity
This was generated by AI during triage.
Triage outcome:
ready-for-human, scope narrowed to step 1Splitting. Step 1 stays here. Steps 2 and 3 move to a follow-up issue, because verification turned up a blocker they cannot clear as written.
Step 2 would mis-instruct 21 repos
The org default is inherited by everything without a local template. Measured across the 28 non-archived repos:
- 5 have their own
.github/PULL_REQUEST_TEMPLATE.md—.github,chat-app,faststream-outbox,modern-di,that-depends. - 23 inherit the org default.
- 23 still carry
planning/. - The overlap is 21 repos.
Replacing the org default with the convention form would hand those 21 a template instructing "file an ADR in
docs/adr/", "no change file", "no lane to pick" — while they still runplanning/withplanning/decisions/, change files, andjust check-planningas a gate. The template would contradict each repo's own workflow on the day it lands, with nothing in CI to notice. That is the same class of defect the body identifies in the generic template, pointed the other way.Only two repos have actually adopted the convention:
modern-diandfaststream-outbox. Every other repo is on the old one.The two templates differ in more than two places
The body says they are "identical-in-shape, differing only in the package path and the test command". Diffing them shows three parameterizable axes and one semantic divergence:
Divergence Kind package path ( modern_di/vsfaststream_outbox/)parameter, as claimed test recipe ( just test-civsjust test)parameter, as claimed just bench-checkas a stated gate — onlyfaststream-outboxthird parameter, not accounted for ADR route: modern-direquires "with a revisit trigger";faststream-outboxdropped that phrasedrift, not a parameter The last one is not cosmetic, and it shows in practice:
modern-dihas a revisit trigger in 27 of 27 ADRs;faststream-outboxin 1 of 2. The template that omits the requirement is the repo that doesn't do it. This is precisely the silent drift the body warns about — "there is no signal when the two drift" — except it has already happened, before the org default was even touched.Whichever way step 2 goes, that phrase needs a deliberate ruling rather than being inherited from whichever copy is used as the base.
Status correction
The body lists
faststream-outbox#159as open. It merged on 2026-09-05. Both named repos are fully on the convention now —planning/andarchitecture/are gone from both — so step 3's "the local copies come out" is the only part of those two repos still pending.What stays here: step 1
Adopting the convention in this repo is self-contained, needs none of the above settled, and is the part the body correctly argues should go first — "deciding for the org while running the older convention here is the awkward part". It also does what the body wants it to: proves the migration on a docs-shaped repo rather than a library.
ready-for-humanrather thanready-for-agent, because the migration is a series of judgment calls, not a mechanical transform:- This repo has 24 change files and 1 decision file under
planning/, plus anarchitecture/tree with 5 capability pages and adeferred.md. Retiringplanning/means ruling on each: promote intoarchitecture/, convert to an ADR under a newdocs/adr/, become an issue, or drop.modern-didid this over several PRs (#429–#431, #439), not one. - This repo has no
docs/adr/yet, and itsdocs/is the published MkDocs source for modern-python.org — so an ADR directory needs anot_in_navorexclude_docsdecision, which the library repos did not face. just check-planningis a CI gate here and would need retiring with the tree.- The agent-skills config merged in docs(agents): configure the engineering skills for this repo #52 documents
architecture/+planning/as this repo's domain homes. It is written to be rewritten as part of this migration; whoever does step 1 should updatedocs/agents/domain.mdin the same PR.
Out of scope for this issue: the org-default template and the local-copy removals, now tracked separately.
- 5 have their own
- added 2 commits that reference this issue
on Sep 6, 2026
What
Two repos have now moved to a convention where the PR body is the spec for a change — there is
no committed change file, no lane to pick, and no
planning/tree:modern-di— PRs #424–#450faststream-outbox— chore: adopt the modern-di convention; drop planning/ and architecture/ faststream-outbox#159 (open)Both carry an identical-in-shape
.github/PULL_REQUEST_TEMPLATE.md, differing only in the packagepath and the test command. This repo already hosts the org-default template at
.github/PULL_REQUEST_TEMPLATE.md, so it is the natural home — but the default is currently thegeneric Summary / Changes / Checklist form, which does not carry the parts that make the convention
work.
Why the generic template is not enough
The convention's template is not a nicer checklist; four of its prompts are the convention:
it; enforceable → a test; a user needs it →
docs/; otherwise it does not get written. Withoutthis prompt at review time, prose accretes and the
planning/tree grows back.claim and whose docstring opens
INVARIANT:and says what breaks it.docs/adr/, not intothe PR body where it is lost on merge.
The generic template's "Docs updated if behavior or public API changed" asks the old question —
did you update the page? — which is what let the capability pages in both repos ratchet toward
restating code.
Proposed
planning/.convention-versionis still2.0.0, and thisrepo still carries
planning/andarchitecture/. Deciding for the org while running the olderconvention here is the awkward part; doing it first also proves the migration on a docs-shaped
repo rather than a library.
.github/PULL_REQUEST_TEMPLATE.mdwith the convention form, writtengenerically — the two repo-specific bits are the package directory and the test command, which
can be phrased as "the package" and "the repo's full-suite recipe".
modern-diandfaststream-outboxdelete their own.github/PULL_REQUEST_TEMPLATE.mdand inherit it. Both aredeliberately keeping theirs until step 2 lands, since a repo-local template silently wins over
the org default and there is no signal when the two drift.
Open question
Whether the generic form loses too much. The value of the checklist is partly that it names the
repo's actual gate (
just testat 100% coverage infaststream-outbox,just test-ciinmodern-di). If the generic version reads as boilerplate, the alternative is to keep the templatelocal per repo and instead put the convention — the admission check and the four routes — in this
repo's
CLAUDE.mdas an org-wide rule, with each repo's template referencing it.