Skip to content

docs(agents): drop the fact-placement convention from AGENTS.md - #64

Merged
lesnik512 merged 2 commits into
mainfrom
docs/drop-fact-placement-convention
Sep 7, 2026
Merged

docs(agents): drop the fact-placement convention from AGENTS.md#64
lesnik512 merged 2 commits into
mainfrom
docs/drop-fact-placement-convention

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Why

AGENTS.md carried a per-repo copy of a doc-placement convention: a four-homes table, an admission check to run "before writing a line anywhere", an ADR row prescribing NNNN-slug.md and revisit triggers, and a ratchet rule.

Doc placement is a domain-modeling convention. Restating it in every repo means ~25 copies that can drift from it, in a file loaded on every turn — the failure the removed text itself named: "it is always loaded, so a line that restates a docstring… costs every turn and rots in two places at once."

The local ADR rule was also weaker than the convention it duplicated: it had no reversibility gate, so any non-obvious rejected alternative qualified.

Piloted and merged in lite-bootstrap (#188); this applies the same cut here.

Design

Removed:

  • the Where a fact goes section in full — four-homes table, the "before writing a line anywhere" admission check, "prose about mechanism has no home", the ratchet rule
  • Workflow's "the spec for a change is its PR body" rule, the "two things outlive the PR" ADR sentence, "there is no change file and no lane to choose", and "there is no separate truth-home directory"
  • Architecture's "behaviour detail has no prose home… run the admission check" tail, where present

Kept:

  • the INVARIANT: docstring shape, with its ADR and lychee clauses trimmed
  • one Workflow fact: unscheduled work becomes a GitHub issue
  • every other section, unchanged
  • inline docs/adr/ citations inside architecture prose. Those cite a specific decision at the point it is relevant; they are not the convention being dropped.

No replacement pointer is added, by design.

Non-goals

  • No ADR is changed, removed or renumbered. docs/adr/ is untouched.
  • No code or test changes.

Verification

The remaining docs/adr/ mentions in this file, if any, are inline citations to specific decisions, not a rule about when to write one.

Where a fact goes, its admission check and the ADR convention all go; doc
placement is a domain-modeling convention. The INVARIANT: docstring shape stays.
The remaining docs/adr/ references were citations inside architecture prose,
or an index of them. The prose stays; the pointers go.
@lesnik512
lesnik512 merged commit 8c0b59f into main Sep 7, 2026
8 checks passed
@lesnik512
lesnik512 deleted the docs/drop-fact-placement-convention branch September 7, 2026 05:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant