What house conventions should you pin into the context you give a drafting model before it writes a case?

## Why an unpinned draft always looks foreign A drafting model's default style is an average of everything it has ever read. That average is coherent, defensible and completely unlike your repository. It picks a naming scheme, a level of abstraction, a way of arranging preconditions and a way of phrasing assertions - all reasonable, none of them yours. Nothing in the request signals that your team decided differently three years ago and wrote the decision down somewhere the model never saw. The result is a draft that is *correct and unmergeable*. It proves the right behaviour and violates six local decisions, so the reviewer's attention is spent on style instead of on whether the case is any good. **Every convention you leave unpinned is a correction you will make again on every future draft.** That per-draft framing is the point. A convention you explain once to a new colleague is explained once. A convention you never wrote into the drafting context is explained every single time, forever, by whoever happens to be reviewing. ## What is worth pinning | Convention | What a draft does without it | |---|---| | Case naming | Names the steps taken rather than the behaviour proved | | Placement | Invents a folder, or drops everything into one | | Domain vocabulary | Uses generic words where your product has its own | | Level of abstraction | Inlines interaction detail the codebase deliberately hides | | What a failure records | Leaves a bare difference with no identity for the record it touched | | Case independence | Writes cases that quietly assume an earlier one ran | | Banned constructs | Reaches for whatever is common elsewhere | Two rules of thumb decide what makes the list. A convention is worth pinning when **a reviewer has corrected it more than twice**, and when **a reader could not infer it from the code around them**. Conventions visible in every neighbouring file usually need no written rule at all, because an exemplar carries them for free. ## Rules and exemplars do different jobs A rule states a constraint and has to be interpreted. An exemplar *is* the answer already. Two or three real cases pulled from the repository convey naming, placement, structure, vocabulary and the expected level of detail simultaneously, and they never drift silently, because they are files that other changes keep honest. Prose describing a style goes stale the moment the style moves; a referenced case cannot. Rules still earn their place for the things an exemplar cannot show: what is *forbidden*, and what is required in situations the exemplars do not happen to cover. Write each of those with a one-line counter-example. A rule without a counter-example leaves an ambiguity, and the ambiguity gets resolved by the model rather than by you. ## Keep it short enough to be attended to Context has a budget of attention as well as a budget of size. A long standards document dilutes the request it travels with, and most of its content describes rules the drafts already follow - so the four rules actually being broken are buried among forty that were never at risk. Prune aggressively. A rule that has produced no correction in a quarter is a candidate for deletion, not a badge of thoroughness. ## Maintaining it: the recurring correction is the signal Treat the rulebook as a living artefact with an explicit feedback loop: 1. When reviewing a draft, record each correction as a category rather than as prose. 2. When a category shows up on three separate drafts, that is a missing rule. Add it, with its counter-example. 3. When a rule produces no correction for a quarter, propose dropping it and see whether anyone objects. 4. When the codebase changes a convention, update the exemplar cases first - they are what the drafts actually imitate. The diagnostic sentence to keep in mind: if you find yourself typing the same review comment for the third time, the defect is in the input, not the output. You are debugging the context, and the fix belongs there. ## What pinning does not fix Conventions make a draft look like it belongs. They do not make it prove the right thing. A perfectly conventional case can still assert something meaningless, and a suite of immaculately named cases can still be worthless. Pinning conventions buys back a reviewer's attention so that it can be spent on the question that matters - which is the argument for doing it, not a claim that it is sufficient. There is also a cost worth naming honestly. A pinned convention makes drafts uniform, and uniformity can entrench a bad convention just as efficiently as a good one. If the rulebook says preconditions are arranged a particular way and that way turns out to be wrong, every draft from now on is wrong the same way, and the uniformity makes the mistake harder to notice. Review the rulebook itself occasionally, on its own terms, rather than only ever appending to it.