What a convention is

A convention is a fact about how your repository already does something, derived by parsing it, and carrying the evidence that supports it.

That definition is doing real work. A convention is not:

• a rule we think you should follow;
• a best practice from a blog post;
• something a language model noticed.

It is a pattern that is already in your code, stated back to you with the file and line numbers that make it true.

Why derive rather than configure

The alternative is a config file where you declare your standards. Everyone who has tried this knows what happens: the file is written once, during onboarding, by someone with strong opinions, and then reality drifts away from it. Six months later the config describes a team that no longer exists.

Derivation cannot drift, because it is recomputed from the code. If your team stopped snake-casing resource names eight months ago, the convention decays and stops being enforced — without anyone remembering to update a file.

It also means Garboard is useful on day one, on a repository nobody has configured, which is the only honest way to evaluate a tool like this.

The four families

Evidence is not optional

Every convention carries file-and-line evidence and a support count — “seen in 6/7 resources”. Both are shown, and both matter:

• The evidence lets you check it. Open the file, look at the line, decide.
• The support tells you how strong it is. Six of seven is a convention. Two of seven is a coincidence.

A convention you disagree with is one you can see the evidence for and delete.

The one-sentence version

The rest of the industry ships you rules and asks you to configure them down. Garboard reads what you already do and asks you to correct it. Both are opinionated; only one starts by being right about your repository.