docs: encoding-loop infographic + audit logs + rule consolidation (closes #66)#126
Merged
Conversation
The system behind "AI that codes the way I want" — the methodology canon
for AI-assisted code that compounds quality.
- docs/encoding-loop-hero.jpg: v16 hero (Nano Banana Pro at 2K). Navy +
amber + cream. Signature ratchet wheel hub with 5 trigger entry points
feeding into "Pick smallest surface." 5 surfaces ordered by enforcement
strength (soft → strong). 3-tier spectrum. Live YAML CI gate. 6
disciplines (4 mechanical + 2 convention). Pandey-style numbered grid.
- docs/encoding-loop-infographic.{excalidraw,svg}: canonical editable
reference. Deterministic counterpart to the hero — same content, fully
versionable, every text element exact.
- CONTEXT.md: domain vocabulary glossary. Defines encoding loop, 5
surfaces, 3 tiers, mechanical floor, harness vs method, agentic coding
tools. Pattern stolen from mattpocock/skills. Distinct from CLAUDE.md
(rules) — this is vocabulary, not conventions.
- .claude/commands/grid-infographic.md: new skill for the Nano Banana Pro
pipeline at 2K. Includes blueprint-approval gate so content errors get
caught before any API call (avoids burning generations on misframed
prompts).
- .claude/commands/*.md: disable-model-invocation: true on all six
user-invoked slash commands. Stops them auto-firing on description
match — they're explicit rituals, not assistive guesses.
- .claude/scripts/render-hero.sh: deterministic HTML → PNG renderer via
Playwright. Counterpart to rebuild-diagrams.sh for the Excalidraw
pipeline.
- docs/skill-bucket-organization.md: engineering / productivity bucket
convention for .claude/commands/. Adapted from mattpocock/skills.
- .gitignore: adds docs/post-ideas/ as the post-draft sandbox.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Same problem identified (AI lacks decision context); mechanism explicitly
rejected via docs/dev-loop.md:583 ("MCP servers | Not building an MCP server")
+ :586 (Spec Kit per-feature flow as ceremony). Canon-in-repo is the project's
answer. No action — optional one-line consolidation flagged for next
dev-loop.md edit (MCP entry rationale is currently tautological).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Anton Martyniuk infographic on VSA "bad if" vs "amazing if" rules. Most rules aligned with NextAurora's encoding (no MediatR, no IHandler interface, simple handler class, no business logic in endpoint). Two material divergences: file granularity (NextAurora: 1 file per slice; Anton: 4 files per slice) and expected-error handling (NextAurora throws exceptions; Anton recommends Result<T>). Both NextAurora positions are intentional choices or unmade-decisions-by-default; neither warrants flipping. Three optional consolidations flagged for next CLAUDE.md edit: line-count soft cap on feature files, exception-vs-Result stance, no-IHandler-interface rationale. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Encodes four rules surfaced by recent audits (Miro MCP, VSA-when-it-works): 1. dev-loop.md MCP servers row — replace tautological "Not building an MCP server" with the rationale (canon-in-repo + auto-load gives persistent decision context; MCP bridge is convergence-in-the-wrong-direction). Paraphrase in .github/AI_WORKFLOW.md mcp-builder row updated to match per the cross-reference rule. Source: 2026-06-07 Miro audit. 2. CLAUDE.md Project Structure — feature-file size soft cap (~300 lines). Co-location stays the canon; "giant file" warning is enforced via size cap, not file count per slice. Largest feature today (PlaceOrder.cs) is 182 lines. Source: 2026-06-08 VSA audit. 3. CLAUDE.md Key Conventions — exception-based control flow is the canon. No Result<T> / OneOf<T> / ErrorOr<T> discriminated-union error type. Defensible trigger to flip named (profiled exception cost in hot path OR saga step with high expected-failure rate). Source: 2026-06-08 VSA audit. 4. CLAUDE.md Communication Patterns — no IRequestHandler / IFooHandler interface per handler. Wolverine assembly-scans Features/ and binds message-type → handler-type directly; the MediatR-style "interface for testability" pattern doesn't apply (Wolverine's bus IS the abstraction). Source: 2026-06-08 VSA audit. All four rules pass the cross-reference grep (only one paraphrase found outside the edited files — AI_WORKFLOW.md MCP row, updated in this commit). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…onale Cross-reference cleanup that should have shipped with 360c879. The mcp-builder row in .github/AI_WORKFLOW.md was the only paraphrase of the dev-loop.md MCP-servers rule found by the cross-reference grep. Now consistent with the canonical wording. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
LinkedIn long-form version of yesterday's Anton Martyniuk VSA infographic. Same author, same core thesis — verdict and divergences identical to 2026-06-08-vsa-when-it-works.md. Today's post adds teaser content for tomorrow's newsletter (Shared/ folder rules, auto-registration, cross-slice events without MediatR, PublicApi pattern), which can't be audited until the actual newsletter ships. No new encoding work; the four rules from yesterday's audit shipped this morning in 360c879 + 9323aff. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Mukesh Murugan's JWT-in-ASP.NET-Core walkthrough. Most claims aligned or out-of-scope (NextAurora uses Keycloak as IdP — signing key, login, refresh token aren't NextAurora's responsibility). One material divergence: ClockSkew (article: Zero for exact expiry; NextAurora: 30s to tolerate NTP drift while limiting linger). One consolidation flagged for next ServiceDefaults edit — explicit MapInboundClaims = false to make the claim-mapping flow auditable instead of relying on the Microsoft-flavored default. NextAurora's encoding is materially stricter on the adjacent authorization pattern: IDOR-prevention via predicate-in-WHERE-clause + 404-not-403 + integration test required, plus middleware order threading CorrelationIdMiddleware between auth and authz. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
Warning Review limit reached
More reviews will be available in 12 minutes and 29 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more credits in the billing tab to continue. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (5)
WalkthroughThis PR consolidates documentation, command-framework, and asset updates: five command frontmatter flags are aligned to disable model invocation; new canonical guidance rules and a project vocabulary glossary are added; a new ChangesDocumentation Framework & Development Rules
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Warning Review ran into problems🔥 ProblemsStopped waiting for pipeline failures after 30000ms. One of your pipelines takes longer than our 30000ms fetch window to run, so review may not consider pipeline-failure results for inline comments if any failures occurred after the fetch window. Increase the timeout if you want to wait longer or run a Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with 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.
Inline comments:
In @.claude/commands/grid-infographic.md:
- Around line 84-115: The inner triple-backtick fence inside the outer
```markdown block (the "Code block (Section 06)" example) prematurely closes the
outer fence; update the sample so the inner code fence is escaped or represented
literally (e.g., replace the inner ``` with escaped backticks like \`\`\` or use
an indented/code-quote representation) so the outer ```markdown block remains
intact; look for the ```markdown opening and the "Code block (Section 06)"
heading and change the inner triple-backticks there.
- Around line 310-311: The link in .claude/commands/grid-infographic.md points
to docs/post-ideas/two-readers-one-canon.md which is not tracked
(docs/post-ideas/ is gitignored), so update the link: either replace it with a
tracked in-repo document (e.g., link to an existing file under docs/ that is
committed), remove the broken link, or change it to a full external URL where
the content is hosted; locate the reference to "two-readers-one-canon.md" in
.claude/commands/grid-infographic.md and modify the target accordingly so the
link resolves in-repo or points to a valid external resource.
In @.claude/scripts/render-hero.sh:
- Around line 41-43: The src assignment uses raw string interpolation
("file://${SRC}") which can produce invalid URIs for paths with spaces/special
chars; change the script to construct the file:// URI via Python's pathlib
(e.g., Path(SRC).resolve().as_uri()) instead of inserting SRC directly, and
assign that result to src; update the line that sets src (currently src =
"file://${SRC}") to call Python/pathlib to produce a properly encoded URI before
writing out or using OUT.
In @.gitignore:
- Around line 510-514: The gitignore rule excluding the local sandbox
"docs/post-ideas/" causes committed markdown links in CONTEXT.md (lines linking
to docs/post-ideas/two-readers-one-canon.md and
docs/post-ideas/measuring-the-encoding-loop.md) and
.claude/commands/grid-infographic.md to point at ignored files; either remove or
narrow the .gitignore entry for "docs/post-ideas/" so those files are tracked,
or update the three link targets in CONTEXT.md and
.claude/commands/grid-infographic.md to point to a tracked location (move the
files into docs/ or docs/drafts/ and update the links accordingly) to restore
valid references—adjust the .gitignore rule name "docs/post-ideas/" or the links
consistently so the files become resolvable.
In `@docs/dev-loop.md`:
- Line 584: The markdown link in docs/dev-loop.md referencing
../.claude/audits/2026-06-07-miro-mcp-shared-context.md is broken because that
audit file is missing; either add the missing audit file named
.claude/audits/2026-06-07-miro-mcp-shared-context.md to the repo (with the
referenced content) or update the link in docs/dev-loop.md to point to an
existing audit (for example .claude/audits/INDEX.md or the correct audit
filename) so the cross-reference resolves; locate the link string
"../.claude/audits/2026-06-07-miro-mcp-shared-context.md" in docs/dev-loop.md
and change it or add the corresponding file accordingly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 30591278-f814-4296-b44d-33bebe057949
⛔ Files ignored due to path filters (2)
docs/encoding-loop-hero.jpgis excluded by!**/*.jpgdocs/encoding-loop-infographic.svgis excluded by!**/*.svg
📒 Files selected for processing (15)
.claude/audits/INDEX.md.claude/commands/article-audit.md.claude/commands/check-rules.md.claude/commands/feature-spec.md.claude/commands/grid-infographic.md.claude/commands/new-feature-slice.md.claude/commands/sync-status.md.claude/scripts/render-hero.sh.github/AI_WORKFLOW.md.gitignoreCLAUDE.mdCONTEXT.mddocs/dev-loop.mddocs/encoding-loop-infographic.excalidrawdocs/skill-bucket-organization.md
Comment on lines
+84
to
+115
| ```markdown | ||
| ## Blueprint for review — please verify before I generate | ||
|
|
||
| **Main title:** <<TITLE>> | ||
| **Subtitle:** <<SUBTITLE>> | ||
| **Author byline:** <<BYLINE>> | ||
| **Terminal corner:** <<TERMINAL>> | ||
|
|
||
| **Sections:** | ||
|
|
||
| | # | Title | Content summary | | ||
| |---|---|---| | ||
| | 01 | <<S01_TITLE>> | <<S01_SUMMARY>> | | ||
| | 02 | <<S02_TITLE>> | <<S02_SUMMARY>> | | ||
| | 03 | <<S03_TITLE>> *(HERO)* | <<S03_SUMMARY>> | | ||
| | 04 | <<S04_TITLE>> | <<S04_SUMMARY>> | | ||
| | 05 | <<S05_TITLE>> | <<S05_SUMMARY>> | | ||
| | 06 | <<S06_TITLE>> *(CODE)* | <<S06_SUMMARY>> | | ||
| | 07 | <<S07_TITLE>> | <<S07_SUMMARY>> | | ||
| | 08 | <<S08_TITLE>> | <<S08_SUMMARY>> | | ||
|
|
||
| **Hero centerpiece (Section 03) details:** | ||
| - Hub title: <<HUB_TITLE>> | ||
| - Spine (4 boxes): <<SPINE>> | ||
| - Callouts (4): <<CALLOUTS>> | ||
| - Triggers feeding in (5, optional): <<TRIGGERS>> | ||
| - Signature element: <<SIGNATURE>> (e.g. ratchet teeth ring, flywheel, etc.) | ||
|
|
||
| **Code block (Section 06):** | ||
| ``` | ||
| <<CODE>> | ||
| ``` |
There was a problem hiding this comment.
Fix nested fenced-code rendering in the blueprint example.
At Line 113, the inner triple backticks terminate the outer ```markdown block, so the “Code block (Section 06)” sample won’t render as intended.
Suggested diff
```markdown
## Blueprint for review — please verify before I generate
@@
**Code block (Section 06):**
-```
-<<CODE>>
-```
+\`\`\`
+<<CODE>>
+\`\`\`
@@</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>
[warning] 113-113: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
---
[warning] 115-115: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
---
[warning] 115-115: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/commands/grid-infographic.md around lines 84 - 115, The inner
triple-backtick fence inside the outer markdown block (the "Code block (Section 06)" example) prematurely closes the outer fence; update the sample so the inner code fence is escaped or represented literally (e.g., replace the inner with escaped backticks like ``` or use an indented/code-quote
representation) so the outer ```markdown block remains intact; look for the
inner triple-backticks there.Source: Linters/SAST tools
Comment on lines
+41
to
+43
| src = "file://${SRC}" | ||
| out = "${OUT}" | ||
|
|
There was a problem hiding this comment.
Build the file URI via pathlib instead of raw string interpolation.
Line 41 can fail for valid paths (spaces/special chars/quotes) because file://${SRC} is not URI-encoded and is injected directly into Python source.
Suggested diff
-from playwright.sync_api import sync_playwright
-import os, sys
+from playwright.sync_api import sync_playwright
+from pathlib import Path
+import os
-src = "file://${SRC}"
-out = "${OUT}"
+src = Path(r"${SRC}").resolve().as_uri()
+out = str(Path(r"${OUT}").resolve())🤖 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 @.claude/scripts/render-hero.sh around lines 41 - 43, The src assignment uses
raw string interpolation ("file://${SRC}") which can produce invalid URIs for
paths with spaces/special chars; change the script to construct the file:// URI
via Python's pathlib (e.g., Path(SRC).resolve().as_uri()) instead of inserting
SRC directly, and assign that result to src; update the line that sets src
(currently src = "file://${SRC}") to call Python/pathlib to produce a properly
encoded URI before writing out or using OUT.
| | **SonarQube** (self-hosted) | Self-hosting infrastructure overhead doesn't pay back at this project size. | | ||
| | **Frontend testing tools** (Playwright, etc.) | Storefront + SellerPortal are static-file scaffolds — no frontend to test. | | ||
| | **MCP servers** | Not building an MCP server. | | ||
| | **MCP servers** | Canon in `CLAUDE.md` + paired `docs/*.md` + every-session auto-load + greppable surfaces already gives Claude Code persistent decision context. An MCP server adds an external tool layer on top of decisions that already live in the repo where the code does — convergence in the wrong direction. Tools live near the decisions, not vice versa. See [`.claude/audits/2026-06-07-miro-mcp-shared-context.md`](../.claude/audits/2026-06-07-miro-mcp-shared-context.md) for the worked comparison (canon-in-repo vs Miro+MCP). | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Check if the referenced audit file exists
# Check if the audit file exists
if [ -f ".claude/audits/2026-06-07-miro-mcp-shared-context.md" ]; then
echo "✓ Audit file exists"
head -20 .claude/audits/2026-06-07-miro-mcp-shared-context.md
else
echo "✗ Audit file not found - should be added in this PR per summary"
fi
# List all audit files for context
echo "All audit files:"
fd -e md . .claude/audits/Repository: emeraldleaf/NextAurora
Length of output: 171
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Searching for miro/mcp audit filenames:"
fd -e md . .claude/audits/ | rg -i 'miro|mcp|shared-context|context' || true
echo
echo "Listing all .claude/audits/*.md:"
fd -e md . .claude/audits/ | sort
echo
echo "Checking for any links to miro-mcp-shared-context: (repo-wide)"
rg -n "miro-mcp-shared-context" . || trueRepository: emeraldleaf/NextAurora
Length of output: 787
Fix broken audit cross-reference in docs/dev-loop.md (line 584)
The link to ../.claude/audits/2026-06-07-miro-mcp-shared-context.md points to a file that isn’t present in the repo (only .claude/audits/INDEX.md exists). Add the missing audit file in this PR or update the link to the correct existing audit.
🤖 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` at line 584, The markdown link in docs/dev-loop.md
referencing ../.claude/audits/2026-06-07-miro-mcp-shared-context.md is broken
because that audit file is missing; either add the missing audit file named
.claude/audits/2026-06-07-miro-mcp-shared-context.md to the repo (with the
referenced content) or update the link in docs/dev-loop.md to point to an
existing audit (for example .claude/audits/INDEX.md or the correct audit
filename) so the cross-reference resolves; locate the link string
"../.claude/audits/2026-06-07-miro-mcp-shared-context.md" in docs/dev-loop.md
and change it or add the corresponding file accordingly.
docs/post-ideas/ and .claude/audits/*.md are deliberately local-only (gitignored); markdown-linking them fails CI's broken-link audit. Convert to backtick path references — the pointer survives, the link contract doesn't.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Docs-only branch bundling the encoding-loop work plus the paraphrase-drift fix from #66:
docs/encoding-loop-infographic.{excalidraw,svg}+docs/encoding-loop-hero.jpg, with the/grid-infographiccommand,render-hero.shscript, andCONTEXT.mdsupporting infradocs/skill-bucket-organization.md— skill/command bucket layout notesReview notes
Run /check-rules locally to audit paraphrases against this diff.
No code changes — docs,
.claude/config, and diagram assets only.🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
Chores