Skip to content

docs: surface the encoding-loop disciplines in dev-loop.md + README + dev-loop.svg #120

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
emeraldleaf merged 1 commit into from
Jun 6, 2026
Merged

docs: surface the encoding-loop disciplines in dev-loop.md + README + dev-loop.svg #120

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
19 changes: 19 additions & 0 deletions docs/dev-loop.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Comment on lines +135 to +145

@coderabbitai coderabbitai Bot Jun 5, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Verify claimed enforcement mechanisms exist

# Check for CI diagram-pair audit workflow or step
echo "=== Searching for diagram-pair audit in CI ==="
rg -n "diagram.*pair|pair.*diagram" .github/workflows/

# Check for Significance Check in feature-spec command
echo -e "\n=== Searching for Significance Check in feature-spec ==="
rg -nC3 -i "significance.*check" .claude/commands/feature-spec.md

Repository: emeraldleaf/NextAurora

Length of output: 883

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "=== CI diagram-pair audit context (ci.yml around line 207) ==="
python3 - <<'PY'
import itertools,sys,os
path=".github/workflows/ci.yml"
start=190
end=240
with open(path,'r',encoding='utf-8') as f:
    for i,line in enumerate(f, start=1):
        if start <= i <= end:
            print(f"{i}:{line.rstrip()}")
        if i > end:
            break
PY

echo -e "\n=== feature-spec Significance check context ==="
python3 - <<'PY'
path=".claude/commands/feature-spec.md"
needle="Significance check"
start=1
# find first occurrence line number
with open(path,'r',encoding='utf-8') as f:
    lines=f.readlines()
ln=None
for idx,l in enumerate(lines, start=1):
    if needle.lower() in l.lower():
        ln=idx
        break
if ln is None:
    print("No matching heading found.")
    sys.exit(0)
s=max(1, ln-40)
e=min(len(lines), ln+80)
for i in range(s, e+1):
    print(f"{i}:{lines[i-1].rstrip()}")
PY

Repository: emeraldleaf/NextAurora

Length of output: 9702

🏁 Script executed:

#!/bin/bash
set -euo pipefail

rg -n -i "presence|loop|approval|gate|stay present|during build|build|ship|implementation" .claude/commands/feature-spec.md

Repository: emeraldleaf/NextAurora

Length of output: 2497

Fix the enforcement mapping for the “Presence in the loop” discipline in docs/dev-loop.md

  • “CI diagram-pair audit” matches .github/workflows/ci.yml (“Diagram-pair audit — every .excalidraw needs a sibling .svg”).
  • “Presence in the loop, not approval at the gate” incorrectly claims it relies on /feature-spec’s “Significance check — ADR or not?”; that section only decides whether to draft a sibling ADR and doesn’t enforce staying present during build/relying on end-of-diff review. Update the row to cite the actual /feature-spec mechanism (or adjust the wording to match what’s enforced).
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/dev-loop.md` around lines 135 - 145, The "Presence in the loop, not
approval at the gate" row currently misattributes enforcement to the
`/feature-spec` "Significance Check"; update that mapping so it cites the actual
`/feature-spec` mechanism that enforces presence (or reword the row to match
reality). Specifically, in docs/dev-loop.md change the enforcement cell for
"Presence in the loop, not approval at the gate" to reference `/feature-spec`
Value Gate (or otherwise remove the incorrect "Significance Check — ADR or not?"
claim) so the table accurately maps the "Presence in the loop" discipline to the
`/feature-spec` Value Gate (or a corrected enforcement description).

---

## The enforcement spectrum
Expand Down
21 changes: 13 additions & 8 deletions docs/dev-loop.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading