Skip to content

A fluent contribution that could not have known the rules

Assistants let anybody produce plausible contributions at volume; the conventions that make one correct are still only in the maintainers.

→ reviewed a well-written contribution that broke a convention it had no way to discover

cost when it happens
high
how often
common
area
governance
context
recognised by
open-source-maintainer
platform-team
agency
enterprise

The moment

The contribution is well written. The tests pass. It uses the pattern the project abandoned two years ago, for reasons that are excellent and recorded nowhere the contributor could reach. The maintainer writes the explanation for the eleventh time.

Why it happens

A project's real conventions are the residue of its arguments, and arguments are not documents. They survive in the maintainers and in old review threads. Assistants changed the economics on one side only: producing a plausible contribution is now nearly free, and transmitting the conventions is exactly as expensive as it was.

Why a better model does not fix it

The contributor's assistant did well with what it had — the code, the README, the tests. None of them contains the reason the abandoned pattern was abandoned. A stronger model makes a more convincing case for the wrong pattern.

What it costs

The maintainer's scarcest resource, spent on repetition. And a queue that grows faster than it drains, which eventually converts an open project into a closed one.

What Majordomus does

The rules are objects, not folklore: the effective set is the vendored baseline plus the project's own, resolved as a dependency graph, each saying whether the tool enforces it or nobody does. The context documents attach to the directories and paths they govern and compose for the path being changed, so a contributor's assistant can be told to resolve them before writing. Decisions carry their reason and the alternative that was rejected, which is the sentence review keeps having to supply.

Before and after

before   review comment #11: "we don't use that pattern here, because ..."

after    $ majordomus context resolve lib/auth
         $ majordomus rules list
         project.no-claim-without-test   blocking   enforced by: review
         majordomus.scope-integrity      blocking   enforced by: check, finish, watch

What it does not do

It does not gate contributions, and it cannot make anyone read anything. It converts the conventions from something a maintainer transmits into something a contributor can load.

What this looks like

Concrete situations, one per audience. Each is declared in the moment's front matter, so the before and the after are data rather than prose a page could drift from.

  1. An assisted pull request open-source-maintainer

    before
    A contributor''s assistant produces a clean, idiomatic change that violates a decision the project made two years ago.
    after
    The conventions and the decisions are objects in the repository, discoverable from the paths they govern, before the change is written.

  2. Review as the only channel platform-team

    before
    Contribution volume rises with assistants and review capacity does not; the queue becomes the bottleneck and the conventions the cost.
    after
    The rules are loadable by whatever is doing the writing, so review stops being the transmission mechanism.

  3. Work from outside the team enterprise

    before
    An external contribution meets the standards it could see and misses the ones held internally.
    after
    The effective rule set is readable — vendored baseline plus the project''s own — and says of each rule whether anything enforces it.

How you would know

The observable symptoms this moment declares. They are the questionnaire on the index and the input of majordomus why diagnose; nothing else defines them.

  • Contributions arrive that are fluent, plausible and wrong in a project-specific way. plausible-and-wrong
  • The same review comment is written repeatedly to different contributors. same-review-comment
  • The only mechanism transmitting the project''s conventions is review. review-is-the-gate

Where this lives in the tool

Everything below is read out of this moment's own front matter and resolved against the repository. A name here that did not exist would fail validation.

the commands that answer it

the capabilities of the executable that answer it

what it supervises — derived from the claims below

the claims that back this page, and the evidence behind each

the rules that govern it

  • majordomus.context-integrity
  • majordomus.rule-package-integrity
  • project.context-locality
  • majordomus.doctrine-wiring-integrity

the use cases that show the way out

If this one is familiar, so is the next

What this moment names, what names it, and what shares its area, audience or tags. The second and third are derived; only the first is written down.

All 38, and how they connect to the tool →