The encoding loop

The problem it solves

A code review catches a bad pattern. You fix it. Six sessions later the same pattern comes back, because nothing about that conversation persisted: not for the agent, not for the next person, not for future-you. The fix lived in a PR; the rule lived nowhere.

The encoding loop makes that a defect. A merged fix without its corresponding encoding is a half-finished job: the same session that surfaces a non-obvious failure also writes it down, on exactly one surface, the smallest one that holds it. The threshold is a single question: if the next person could repeat this mistake, or would have to re-derive the rule from first principles, it belongs in writing.

This is deliberately the dual of spec-driven development. Spec-driven encodes per-feature requirements up front and regenerates code from them. This encodes codebase-wide invariants once, and every feature after it starts smarter. Roughly zero upfront cost per feature; the encoding cost amortizes across every future session. Its failure mode is honest too: rule sprawl, and encoding fatigue.

Five surfaces, ordered by enforcement strength

Rules are encoded on the softest surface that works, and promoted down the spectrum only when they earn it: when the soft version keeps getting missed.

Those five cluster into three tiers, and the tiers are the point. Convention (1–2) relies on someone noticing, and noticing is the first thing that degrades under deadline. PR automation (3–4) fires on its own but can be dismissed. Mechanical gates (5) fail loudly and need no human in the loop at all. Most rules should never reach tier three. The ones that do are the ones that already bit twice.

All five stop at the repo boundary. A lesson encoded here protects this repo and nothing else, and that limit is what okl exists to answer: a ledger the surfaces are mined into, read before a task starts and written back to after, fail-closed, so an unreachable store is never mistaken for "no lessons apply". It runs in this site, in okl itself and in Quartzose. Scope is the whole trick: a lesson marked for the org is meant for every repo, one marked for a repo never leaves it. Each of the three keeps its own store today, so a shared lesson travels when its seed file is loaded, and the shared service okl ships is not yet pointed at. In a held-fixed A/B with committed receipts (48 runs per comparison, blind cross-model judging), defect reproduction with the briefing has stayed at 4–13% while the unbriefed baseline read 33–50% across runs; in the first runs a briefed budget model (12%) also beat the unbriefed frontier model (33%), a result not yet repeated. Method, limits and raw receipts are in the repo (evals/REPORT.md), and the story is told in the five-part series.

Wired into a real repo

Everything below is checked into NextAurora, the five-service .NET event-driven system you can break live. It is the working instance of the method, not a description of one.

Edit time: .claude/

• Hooks that reject a bad diff before it lands. A PreToolUse hook rejects .Result / .Wait() / .GetAwaiter().GetResult() in proposed edits. The build-time analyzer catches the same patterns later. The hook catches them earlier, so the bad diff never exists. Another fires on every edit to the canon and lists the files that paraphrase it, so drift gets reviewed the same session.
• An architecture-reviewer agent. Loads the canon plus a repo-wide code graph and evaluates a target against a per-file-category checklist. It reports; it never edits. Step 7 of its workflow is the loop closing: which surface does this finding belong on?
• Seven slash commands, among them: scaffolding a feature slice to the canonical shape, drafting a feature spec with the relevant constraints auto-referenced, auditing an external article against the canon, /check-rules, which audits every paraphrase of a canon rule against the canonical text and flags drift, and /drift-audit, which checks every doc, comment and canon rule against the code as it is now. Its first run confirmed 137 findings after every mechanical gate had passed.
• Eleven skills, tiered honestly. Five are load-bearing (performance guidance for .NET and for React, diagram authoring, plan writing, plan execution). Four are ambient: their discipline is absorbed into the canon and shapes every PR without the skill being invoked by name. Two are dormant by design, waiting on a trigger that hasn’t happened. Listing them that way is the point: a tooling inventory that overclaims is worse than none.

A second AI reviewer (GitHub Copilot, in-editor) runs against its own instruction file. The operating principle: disagreement between two models is a signal to dig, not a vote to settle.

Build time: the analyzer wall

TreatWarningsAsErrors and AnalysisMode=All. Zero warnings allowed, so every rule below is a build break, not a suggestion.

• SonarAnalyzer.CSharp: code smells, bugs, vulnerabilities. Same engine as SonarQube, running as a Roslyn analyzer at compile time rather than as a hosted dashboard.
• Meziantou.Analyzer: ~200 rules across design, performance, security, usage.
• Roslynator.Analyzers: refactoring and style.
• BannedApiAnalyzers against a repo-root BannedSymbols.txt: Task.WaitAll, Parallel.For, Thread.Sleep and friends, each with custom replacement guidance in the error message.
• Nullable reference types: null-state analysis catches most NREs at compile.

Test time: Testcontainers, not mocks

Integration tests run against real engines in Docker. That choice is what makes the rest of the architecture affordable: with a real database one command away, the repository wrapper that exists only to be mocked stops earning its keep, and handlers can take the DbContext directly.

Three test patterns are required, not encouraged, and every review pass checks for them:

• An IDOR test on the ownership boundary. Authenticate as one tenant, touch another tenant’s resource, assert 404, not 403, because 403 leaks existence. The absence of exactly this test is how the original GET /orders/{id} IDOR survived the lifetime of the codebase.
• An outbox test on every publish from outside a message handler. Background sweepers and recovery jobs don’t get the framework’s automatic transaction, so the test asserts the envelope row lands in the same transaction as the entity write. A recovery-job outbox bug survived precisely because nothing asserted that.
• AAA with narrative comments. A junior developer reads one test top to bottom and understands the contract and the failure mode without opening the code under test.

Architecture tests (NetArchTest) hold the line that a four-project Clean Architecture split would otherwise hold: every service’s Domain/ namespace is asserted to have no dependency on EF Core, ASP.NET, the message bus, or any data provider. Same boundary, one test-suite slot, none of the ceremony. The full argument is written up here.

PR time: three reviewers, three lenses

• CodeRabbit on every diff, configured assertive with request_changes_workflow on and 23 path-scoped instruction globs: VSA slice shape, aggregate factory rules, endpoint authorization and the 404-not-403 shape, the outbox-outside-a-handler trap, migration immutability, test conventions, middleware order. That file is surface #4: it is how a rule written once in the canon gets re-checked at review time without anyone re-deriving it.
• CodeQL weekly and on every PR (security-and-quality query set), plus Gitleaks secret scanning that blocks the merge, and Dependabot on a weekly NuGet cadence.
• The architecture-reviewer agent, invoked by hand when an architectural pattern is genuinely in play. Different cadence, different lens. Not redundant with CodeRabbit.

CI itself runs three parallel jobs: build plus unit tests, the frontend (lint, typecheck, Vitest with Testing Library and MSW, build), and the Testcontainers integration suite in its own job so a fast unit signal is never gated on container startup. Both .NET jobs upload Cobertura coverage to Codecov under separate unit and integration flags, and test results surface as an annotated PR check rather than a buried job log. Coverage gates only on regression: total coverage falling by more than a point fails the check, while coverage of the lines a PR adds is posted for review and never blocks. The number is a floor against backsliding, not a claim about quality.

The guards nobody ships off the shelf

These are the interesting ones. Each exists because something specific went wrong once, and each is a short script run in CI: the smallest mechanism that closes the hole.

Considered and skipped

A tooling list that only grows is a smell. These were evaluated and left out, on the record:

The decay problem

Every method eventually decays toward the thing it replaced. Agile decayed into spec-process-with-shorter-cycles. Spec-driven development started as goal-direction and decayed into 1,300-line specs. TDD decayed into coverage-gaming. There is no reason to assume this one is exempt, so the defenses are built in: a hard size budget on the canon so it can’t bloat into the spec it replaced; a drift audit so paraphrases stay aligned with the source; an explicit separation between lessons from this feature and what this feature must do, so the rule set never collapses into per-feature ceremony; and a promotion spectrum, so the rules that matter become loud failures rather than quiet conventions.

The claim isn’t that AI made the work faster. A 2025 controlled trial found experienced developers were measurably slower with AI while feeling faster. Being wrong while feeling fast is the whole failure in one sentence. The claim is narrower and testable: the build eventually enforces what used to be a fifteen-minute PR review conversation, and that conversation never has to happen again.

Read further

• The full dev-loop inventory: every tool, hook, agent, skill and config by the stage it fires in, with an honest gap list and a right-sized fix proposed for each
• Agent vs. slash command vs. skill: the decision tree, and why picking wrong costs you
• Vertical slices vs. Clean Architecture: architecture tests instead of a project split
• The method, written up: five surfaces, softest to strongest
• Less ceremony, same boundaries: the architecture argument the testing strategy makes possible