docs: surface the encoding-loop disciplines in dev-loop.md + README + dev-loop.svg#120
Merged
Merged
Conversation
…nd the diagram 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 <noreply@anthropic.com>
|
Too much diff to scan? Review this PR in Change Stack to start with the highest-impact changes. WalkthroughThe PR expands documentation for the continuous rule encoding process across two files. README.md updates the "Continuous Rule Encoding — the compounding feedback loop" section to detail six encoding disciplines with enforcement tiers. docs/dev-loop.md adds a new "disciplines" subsection that catalogs convention-tier rules and their layered enforcement mechanisms sourced from CLAUDE.md. ChangesEncoding Disciplines Documentation
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)
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: 1
🤖 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 `@docs/dev-loop.md`:
- Around line 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).
🪄 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: 332dca28-6e9c-4112-a804-8e12a82fb014
⛔ Files ignored due to path filters (1)
docs/dev-loop.svgis excluded by!**/*.svg
📒 Files selected for processing (2)
README.mddocs/dev-loop.md
Comment on lines
+135
to
+145
| | 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. | ||
|
|
There was a problem hiding this comment.
🧩 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.mdRepository: 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()}")
PYRepository: 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.mdRepository: 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-specmechanism (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).
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.
Follow-up to #119. The 10 borrowings landed CLAUDE.md disciplines but didn't surface them in the docs/diagrams people read at-a-glance. This closes that gap.
docs/dev-loop.md: new "### The disciplines" subsection cataloging all 6 with layered enforcementREADME.md: Continuous Rule Encoding callout names all 6 disciplines + /feature-spec value gate + hole-testdocs/dev-loop.svg: encoding-loop footer gets a "Disciplines →" row; rect extended; viewBox grown to fitNow a reader of the README sees the disciplines, follows the link to dev-loop.md for the catalog, follows that to CLAUDE.md for canonical text. No silent rules.
Broken-link guard: exit 0.
Summary by CodeRabbit