From a8524485eb8613ab47de468bca8466524d574098 Mon Sep 17 00:00:00 2001 From: emeraldleaf Date: Fri, 5 Jun 2026 16:07:47 -0600 Subject: [PATCH] docs: surface the encoding-loop disciplines in dev-loop.md, README, and the diagram MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follow-up to #119. The 10 borrowings landed CLAUDE.md disciplines (Presence in the loop, Continue is the verb) but didn't surface them in dev-loop.md / README / dev-loop.svg — the docs and diagram people read at-a-glance to understand the loop. A reader could see the loop in the diagram, then open CLAUDE.md and find two disciplines they weren't told about. docs/dev-loop.md - New "### The disciplines (encoded in CLAUDE.md 'Debugging Discipline')" subsection under "The reflexive step" — catalogs all 6 disciplines (cross-reference convention, file-move, doc-and-diagram, lean-CLAUDE.md, presence-in-loop, continue-is-the-verb) with their layered enforcement (which 4 have mechanical floors, which 2 are convention-tier only). Points at CLAUDE.md "Debugging Discipline" for full text. README.md - "Continuous Rule Encoding" callout adds a sentence naming the 6 disciplines + the lean-CLAUDE.md / presence / continue framings. Adds /feature-spec's value gate (3 CXO questions) and hole-test to the feature-handoff description. docs/dev-loop.svg (the rendered diagram on the README) - "Continuous Rule Encoding" footer in the diagram gets a new "Disciplines →" row listing all 6 by name, with a muted note about the split between mechanical and convention-tier - Rect height extended 180 → 220, viewBox height 1940 → 1985, bottom footer line moved 1915 → 1960 to avoid overlap This makes the README a faithful surface-up of what's actually in CLAUDE.md. Anyone reading the diagram now sees the disciplines and can follow the pointer to the canonical rule text. Verification: - broken-link guard on README + dev-loop.md: exit 0 - SVG renders without overlap (rect extended, footer pushed down, viewBox grown by 45px to match) Co-Authored-By: Claude Opus 4.7 --- README.md | 2 +- docs/dev-loop.md | 19 +++++++++++++++++++ docs/dev-loop.svg | 21 +++++++++++++-------- 3 files changed, 33 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 6106d240..4f8944ae 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ NextAurora demonstrates a production-style distributed system with event-driven > **How it was built — AI-assisted, multi-model review, verification at every layer.** > - **Two AI reviewers, not one.** [Claude Code](https://claude.com/claude-code) (Opus 4.7) is the primary pair-programmer — reads [`CLAUDE.md`](CLAUDE.md) plus the [`.claude/`](.claude/) folder beside it (agents, [skills](.claude/skills/), [slash commands](.claude/commands/), hook scripts, hook + permission wiring) every session, and a persistent project memory. **GitHub Copilot (GPT-5)** sits in-editor for second-opinion diff review, with project conventions encoded in [`.github/copilot-instructions.md`](.github/copilot-instructions.md). Disagreement between the two is treated as a signal to dig deeper, not pick the louder voice. The principle is not "AI wrote it" — it's *two models + a human author + automated checks all sign off before merge*. The working loop: implement → run unit + integration tests → cross-model review → fix → commit. -> - **Continuous Rule Encoding — the compounding feedback loop.** Every meaningful finding (CodeRabbit catch, test failure, architecture-reviewer agent flag, manual code review, prod incident, even community articles audited via [`/article-audit`](.claude/commands/article-audit.md)) gets the question: *"could the next person repeat this?"* If yes, the rule gets written down at the right tier of an enforcement spectrum — **Convention** (CLAUDE.md + `.claude/`), **PR-review automation** ([`.coderabbit.yaml`](.coderabbit.yaml) + the [architecture-reviewer agent](.claude/agents/architecture-reviewer.md)), or **Mechanical** (build-fail / hook-block / CI-grep). Rules move down the spectrum as they prove their value — the looser the tier, the more you rely on noticing, and noticing always degrades first. CLAUDE.md itself stays lean (~300 lines; CI-guarded soft cap at 400, hard fail at 500); deep dives live in [`docs/`](docs/) and the [`dotnet-performance` skill](.claude/skills/dotnet-performance/SKILL.md). New features run through [`/feature-spec`](.claude/commands/feature-spec.md), which drafts the structured handoff (goal + acceptance + auto-referenced CLAUDE.md constraints) so the spec → implementation → encoding loop stays closed. Full mechanics + the 5 encoding surfaces: [`docs/dev-loop.md`](docs/dev-loop.md); scaffolding diagram: [`docs/dev-loop-scaffolding.svg`](docs/dev-loop-scaffolding.svg). +> - **Continuous Rule Encoding — the compounding feedback loop.** Every meaningful finding (CodeRabbit catch, test failure, architecture-reviewer agent flag, manual code review, prod incident, even community articles audited via [`/article-audit`](.claude/commands/article-audit.md)) gets the question: *"could the next person repeat this?"* If yes, the rule gets written down at the right tier of an enforcement spectrum — **Convention** (CLAUDE.md + `.claude/`), **PR-review automation** ([`.coderabbit.yaml`](.coderabbit.yaml) + the [architecture-reviewer agent](.claude/agents/architecture-reviewer.md)), or **Mechanical** (build-fail / hook-block / CI-grep). Rules move down the spectrum as they prove their value — the looser the tier, the more you rely on noticing, and noticing always degrades first. CLAUDE.md itself stays lean (~300 lines; CI-guarded soft cap at 400, hard fail at 500); deep dives live in [`docs/`](docs/) and the [`dotnet-performance` skill](.claude/skills/dotnet-performance/SKILL.md). Six **disciplines** sit alongside the surfaces — *cross-reference convention, file-move, doc-and-diagram, lean-CLAUDE.md, presence-in-the-loop, continue-is-the-verb* — the first four with mechanical floors (hooks, CI guards, size budget), the last two convention-tier (judgment calls about presence and stopping). New features run through [`/feature-spec`](.claude/commands/feature-spec.md), which opens with a value gate (who needs this, would we still build it at engineering-time cost, who owns saying no), then drafts a structured handoff (goal + acceptance + upstream dependencies + auto-referenced CLAUDE.md constraints) and closes with a hole-test (*imagine handing this to someone not in your head — where would they have to guess?*). Full mechanics + the 5 encoding surfaces + the disciplines catalog: [`docs/dev-loop.md`](docs/dev-loop.md); scaffolding diagram: [`docs/dev-loop-scaffolding.svg`](docs/dev-loop-scaffolding.svg). > - **Verification at every layer.** Build: `TreatWarningsAsErrors` + four build-time analyzers (Meziantou, SonarAnalyzer.CSharp, Roslynator, BannedApiAnalyzers — the last rejects concrete concurrency hazards at compile). Tests: 100+ unit + integration tests, with integration slices for all four DB-touching services via [Testcontainers](https://dotnet.testcontainers.org/) — Catalog (Postgres + Redis), Order (SQL Server + stubbed Wolverine transport), Payment (SQL Server), Shipping (Postgres). Each slice runs as its own step in CI so a single-slice failure doesn't mask the rest. CI: GitHub Actions runs build + tests + Coverlet/Cobertura coverage on every PR. Security: CodeQL on every push + weekly schedule. Dependencies: Dependabot weekly NuGet bumps (grouped per ecosystem). Local dev: Aspire orchestrates Postgres / SQL Server / Service Bus emulator / Redis / Keycloak in Docker so integration issues surface *before* push. > - **Testing strategy was decided upfront, not retrofitted.** Unit tests cover handlers + domain rules with mocked infrastructure (NSubstitute, FakeTimeProvider). Integration tests use live containers to prove what mocks can't: EF migrations apply cleanly to fresh DBs, HybridCache actually invalidates on write, the `xmin` / `RowVersion` concurrency tokens actually fire under racing writes, Wolverine's transactional outbox + saga handlers actually persist and dispatch. Cross-service E2E over a live Azure Service Bus wire is tracked as deferred in [STATUS.md](docs/STATUS.md). Open issues and other deferred cleanups live there too. diff --git a/docs/dev-loop.md b/docs/dev-loop.md index 6fc4b63f..3e791e84 100644 --- a/docs/dev-loop.md +++ b/docs/dev-loop.md @@ -124,6 +124,25 @@ For invocation patterns — when to use an agent vs a slash command vs a skill, and how each is triggered — see [`.claude/README.md`](../.claude/README.md). The decision tree there is the single source of truth. +### The disciplines (encoded in CLAUDE.md "Debugging Discipline") + +Disciplines are the **convention-tier** rules that operate alongside the +five surfaces. They don't change the loop's structure — they say *how* to +work within it. Full text and rationale lives in +[CLAUDE.md "Debugging Discipline"](../CLAUDE.md#debugging-discipline); +the catalog below is the pointer. + +| Discipline | One-line meaning | Layered enforcement | +|---|---|---| +| **Cross-reference convention** (`See CLAUDE.md.`) | Every paraphrase of a CLAUDE.md rule ends with the literal token so it's greppable | PostToolUse hook on Edit + `/check-rules` audit | +| **File-move discipline** | When renaming/deleting a file, grep the repo for refs to the old path and update them in the same PR | PostToolUse hook on Bash (`check-file-moves.sh`) + CI broken-link audit + CodeRabbit `**` path_instruction | +| **Doc-and-diagram discipline** | Docs + paired SVG diagrams are the review surface, not byproducts — when behavior changes, the depiction changes in the same PR | CI diagram-pair audit + CodeRabbit topology-file path_instructions | +| **Lean-CLAUDE.md** | One-paragraph maximum per rule in CLAUDE.md; detail moves to docs/ or skills/; CLAUDE.md gets a pointer | CI size budget (soft 400 lines, hard 500) | +| **Presence in the loop, not approval at the gate** | For non-pattern-conforming features, stay present during build, don't just review the diff at the end | Convention — relies on the `/feature-spec` Significance Check to flag when this applies | +| **Continue is the verb that gets you in trouble. Build is not.** | Prototypes get a token budget + stop-time up front; experiments end at sunset, not when interest runs out | Convention — relies on the `/feature-spec` Value Gate to surface "this is an experiment, not a feature" early | + +The first four have **mechanical floors** (hooks, CI guards, size budgets); the last two are **convention-tier only** because they're judgment calls about presence and stopping — no machine catches them. That's why they're named explicitly in CLAUDE.md — naming them is what makes them survive in practice. + --- ## The enforcement spectrum diff --git a/docs/dev-loop.svg b/docs/dev-loop.svg index c29e7018..1215394e 100644 --- a/docs/dev-loop.svg +++ b/docs/dev-loop.svg @@ -1,7 +1,7 @@ - + - +