docs(dev-loop): refresh around Continuous Rule Encoding + tier skills honestly

[emeraldleaf]

Summary

dev-loop.md drifted since the simplicity refactor. The Stage 1-5 scaffolding was still accurate, but the doc was missing the most important architectural developments since it was last written, AND was framing the skills table in a way that overclaimed (the same overclaim trap the doc itself warns about). Refresh closes both gaps.

Structural changes to dev-loop.md

• Pulled "Continuous Rule Encoding" up to load-bearing section 2 (was buried after Stage 5). Enumerated the six surfaces explicitly with a "Catches violations at..." column, named the encoding threshold, documented the cross-reference convention (See CLAUDE.md.) and the two mechanical enforcers (the PostToolUse hook + /check-rules).
• Added "Enforcement spectrum" H2 — convention → architecture tests → project split. The NetArchTest rung (commit 8cba0d4) gives VSA the dependency-rule guarantee that Clean's project split would give, without the four-project ceremony. Includes the Promotion Signal table from CLAUDE.md verbatim.
• Added "Loop comparison: spec-driven vs rule-encoding" — 7-row side-by-side table + honest takeaway. Names Spec Kit, Kiro, AGENT.md, OpenAPI-first, TDD-as-spec as the spec-driven lineage. CLAUDE.md plays the AGENT.md role here. Explicit anti-recommendation: grafting Spec Kit mechanics would convert the compounding speed advantage into ceremony.
• Added Gap 9 (distributed rate-limiting — in-memory limiter weakens at N× per instance once anything scales out) and Gap 10 (/specify-saga skill — the one spec-driven element worth keeping in mind, explicitly don't build yet).

Stage-by-stage updates

• Stage 3 now shows four integration slices (Catalog/Order/Payment/Shipping) instead of two — Payment + Shipping landed in PR test(integration): add Payment + Shipping integration projects (real DB + Wolverine) #53.
• Stage 3 gained "Required-test patterns" sub-section: AAA narrative comments, IDOR test required, outbox-non-handler test, handler-DI-registration check. Each links the reference template from CLAUDE.md "Testing."
• Stage 3 lists Wolverine.Tracking as test tooling (used by the new integration projects).
• Stage 4 adds a .coderabbit.yaml path_instructions sub-section describing the glob set as encoding surface build(deps): bump actions/cache from 4 to 5 #2 of the rule loop.
• Stage 1 stops describing CLAUDE.md as "25 KB" (no longer accurate) and AwesomeAssertions migration as a currency signal (migration is done).

Skills tiering — the load-bearing honesty pass

Both dev-loop.md AND .claude/README.md had skills tables that listed all ten skills as if they fire equally on triggers. They don't. Closed the overclaim:

• Tier 1 — Actively used: dotnet-performance (reference target for Performance Rules), excalidraw-diagram (fires on diagram changes — three lesson-encoding commits in history), writing-plans + executing-plans (canonical: Hetzner full-saga deployment plan).
• Tier 2 — Ambient (discipline absorbed into CLAUDE.md; skill is the reach-for surface): verification-before-completion, systematic-debugging, test-driven-development, variant-analysis. The principles shape behavior on every PR via CLAUDE.md rules + PR template; the skills themselves fire when the discipline needs to be re-established or taught.
• Tier 3 — Dormant by design: skill-security-auditor (only fires on new community-skill installs), using-git-worktrees (the project uses ordinary feature branches). Named explicitly as dormant-correctly, not dormant-by-neglect.

.claude/README.md got an additional trigger-phrase column so each skill is reachable by the exact catch-yourself moment that should make you load it (the word "should," two failed bug attempts, "I just fixed one — are there more?", etc.) — plus a "meta-pattern" callout at the bottom listing the five highest-signal trigger phrases for fast lookup during work. The dev-loop.md and .claude/README.md skills sections now share the same tier vocabulary.

What's preserved

• All ten skills are still listed in both surfaces. This was a framing refresh, not a pruning.
• Voice and pragmatic gap-sizing philosophy unchanged.
• Stages 2, 5 unchanged (they were accurate).
• "What we deliberately don't use" table preserved + gained one row (Spec Kit /specify flow, with the honest "would convert speed advantage into ceremony" reason).

Test plan

• No code changed — docs-only PR
• Internal links to reference test templates, .claude/scripts/*, .claude/commands/*, .coderabbit.yaml, tests/NextAurora.ArchitectureTests/DependencyRuleTests.cs all verified during refresh
• Both docs (dev-loop.md and .claude/README.md) use the same tier vocabulary (consistency check)

Related work

• Pairs with PR test(arch): add NetArchTest suite enforcing the dependency rule in VSA #52 (NetArchTest architecture-tests suite) and PR test(integration): add Payment + Shipping integration projects (real DB + Wolverine) #53 (Payment + Shipping integration tests) — both shipped this session and are now reflected in the doc. This PR is independent of both and can land in any order.
• Implements the "/check-rules audit recommendation": dev-loop.md is now consistent with the CLAUDE.md sections it paraphrases (Continuous Rule Encoding, Testing, Promotion Signal). Inline rule-paraphrase markers (See CLAUDE.md.) added where appropriate.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Expanded skills inventory with tiered organization (active, ambient, dormant) and defined trigger phrases for each skill.
  • Enhanced development loop specification with detailed six-step process, rule-encoding mechanisms, tooling requirements, test pattern standards, and configuration guidance.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 1d1ca68f-323f-4aed-85ec-95cb5790dec8

📥 Commits

Reviewing files that changed from the base of the PR and between c19fbee and 100f319.

📒 Files selected for processing (2)

• .claude/README.md
• docs/dev-loop.md

---

Walkthrough

Documentation expanded to formalize continuous rule-encoding as the development loop's reflexive sixth step. Skills reorganized into trigger-phrase-keyed tiers. Each development stage detailed with enforcement mechanisms: Stage 1 ref-check hooks and audits, Stage 3 required test patterns, Stage 4 CodeRabbit path rules. Added loop comparison against spec-driven approaches with pragmatic gap closures.

Changes

Development Loop Specification with Reflexive Rule-Encoding

Layer / File(s)	Summary
Reflexive rule-encoding mechanism docs/dev-loop.md	Opening description reframed to emphasize reflexive rule-encoding as the development loop's closing step. New section (lines 14–131) defines continuous rule encoding across six canonical surfaces (CLAUDE.md rules, CodeRabbit config, agent checklists, skill catalog, supporting docs), documents See CLAUDE.md. conventions, and describes architecture-reviewer prompts for rule promotion. Stage 1 canonical rules entry updated to explicitly reference the encoding loop.
Skills inventory reorganization .claude/README.md	Current inventory section reworked from compact table into tiered structure: Tier 1 (actively used), Tier 2 (ambient), Tier 3 (dormant), each with explicit trigger-phrase wording. Expanded guidance for dotnet-performance, excalidraw-diagram, plan-related, verification/testing/debugging, git-worktrees, and security-auditor skills. Meta-pattern bullet list maps catch-yourself phrases ("should work", "two attempts", "I just fixed one", "this will take a while", "about to write query/cache/migration") to corresponding skills.
Development stage specifications with encoding enforcement docs/dev-loop.md	Stage 1 tooling extended with check-claude-md-refs.sh PostToolUse hook, expanded slash-command audit workflow, and architecture-reviewer agent prompt mechanism. Stage 3 test-time adds dedicated tooling table, clarifies "four today" integration slices with proving points, and specifies required-test patterns (AAA narrative comments, IDOR tests expecting 404, outbox-in-non-handler tests, handler DI-registration checks). Stage 4 PR-time expanded with detailed .coderabbit.yaml path_instructions covering glob categories (features, domain IDs, endpoints/IDOR, recovery-job atomicity, migrations, test conventions, service defaults) and reviewers section reflecting CodeRabbit/CodeQL/Codecov/architecture-reviewer cadence.
Comparative analysis and pragmatic gap closures docs/dev-loop.md	New "Loop comparison" section contrasts spec-driven development (Spec Kit/Kiro) with rule-encoding loop on artifact generation, feedback speed, testability, and enforcement maturity. Expanded "Gaps" section provides sized resolutions for 10 gaps: E2E via real ASB wire, performance baselining, Claude settings cleanup, action pinning, coverage gating, smoke scheduling, secret scanning, production migration automation, rate-limiting scaling, and eventual /specify-saga skill. Updated "deliberately don't use" rationale and source links for performance/data-correctness and agent architecture references.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• emeraldleaf/NextAurora#27: Both PRs update the same continuous rule-encoding documentation surfaces—main PR extends docs/dev-loop.md with reflexive rule-encoding/"six surfaces" mechanism and reorganizes .claude/README.md skills into tiered trigger-phrase inventories matching the retrieved PR's additions.
• emeraldleaf/NextAurora#20: Both PRs modify the same docs/dev-loop.md development-loop specification—the main PR expands it with explicit reflexive/continuous rule-encoding and detailed tooling/spec conventions on top of the staged loop inventory introduced in the retrieved PR.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main changes: documentation refresh focused on Continuous Rule Encoding and honest tiering of skills, which aligns with the substantial updates to dev-loop.md and .claude/README.md described in the PR objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/dev-loop-refresh

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!