Docs/dev loop tooling#20
Merged
Merged
Conversation
…analysis Three new files in docs/: - dev-loop.md (markdown inventory) — every tool, hook, agent, skill, and config that shapes how code lands in this repo, organized by *when* in the dev loop it fires (5 stages: Edit-time, Build-time, Test-time, PR-time, Merge/Runtime). For each tool: file path so a reader can verify it actually exists. - dev-loop.svg (visual companion) — the same 5-stage flow as a left-to-right diagram with per-stage tool detail and a dotted-loop arrow showing review iteration. Hand-written SVG (not generated via Playwright — the excalidraw render script hit a 30s+ timeout loading the esm.sh ES module repeatedly in this environment). - dev-loop.excalidraw (editable source) — the highway skeleton in Excalidraw format. Open in Excalidraw web/desktop or the VS Code Excalidraw extension to extend; export as SVG to refresh dev-loop.svg. Gap analysis is the load-bearing part of the doc. Each gap (10 total — cross-service E2E, perf baselines, settings.json cruft, SHA-pinning, coverage gate, smoke-run automation, secret scanning, prod migrations, agent-vs-CodeRabbit overlap, AI-commit-tagging) is paired with a sized pragmatic fix — explicitly not "build a whole new system." The signal this doc tries to send is: knowing when to stop adding tooling is more pragmatic than maximum theoretical coverage. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
PR #17 (fix/orderservice-integration-test-hang) merged 2026-05-23 17:56 UTC. The STATUS.md text I added in that PR had forward-looking phrasing ("this PR, in flight", "will reflect ... after the next successful CI run", "CI confirmation pending the fix PR merge") that goes stale the moment the PR lands. Rewording to describe present state: - OrderService integration test bullet: cite the merge (PR #17) and the first-green CI timestamp + per-step durations (Catalog 58s, Order 40s). - Codecov sub-bullet: cite the measured delta (18.28% → 56.14%) instead of the expected aggregate. - Build/test state: drop "Local run / CI pending" duality — both pass now. - Coverage line: state the current badge value, not a future expectation. Also catches one older stale entry: the EF Core review + fixes bullet still said "(this session, uncommitted)" — that work landed in 825d6bd already. Replaced with the commit hash for findability. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
WalkthroughThis PR updates project documentation: it records verified CI/integration-test results and EF Core follow-ups in ChangesProject Status & Verification
Development Loop Documentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 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: 2
🤖 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`:
- Line 158: The placeholder link `[docs/perf-baselines.md](#)` should be
resolved: either add the new perf-baselines document (docs/perf-baselines.md)
with the baseline template and the two endpoints (`GET /api/v1/products/{id}`,
`POST /api/v1/orders`) and commit it in this PR, or change the markdown in
docs/dev-loop.md to remove the broken link and indicate the work is planned
(e.g., "docs/perf-baselines.md (planned)") so the link no longer points to `#`;
update the reference near the k6/`dotnet-counters`/HybridCache guidance
accordingly.
- Line 176: Replace the placeholder link "[codecov.yml](#)" with a real target:
either add the actual codecov.yml file at repo root in this PR and update the
markdown link to point to it, or change the link text to a non-linked note such
as "codecov.yml (to be added at repo root)" so it no longer points to "#";
ensure you update the markdown occurrence of "[codecov.yml](#)" 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: 88cf18bf-2035-4623-9da0-5b386cd3af0b
⛔ Files ignored due to path filters (1)
docs/dev-loop.svgis excluded by!**/*.svg
📒 Files selected for processing (3)
docs/STATUS.mddocs/dev-loop.excalidrawdocs/dev-loop.md
CodeRabbit (PR #20) flagged two empty markdown links — perf-baselines.md and codecov.yml — both rendered as [text](#) because the referenced files don't exist yet (they're future-work suggestions in the gap analysis). MD042 (no-empty-links) violation. Fix is dropping the link syntax and calling out parenthetically that the file isn't yet created — keeps the prose readable without producing a clickable "#" link that goes nowhere. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
emeraldleaf
added a commit
that referenced
this pull request
May 23, 2026
…erlap The Gaps section had ten items in two 840px-wide columns (left at x=60, right at x=900). Each gap's "fix" line is 130-170 chars at 14px monospace — wider than the column — so left-column fix text was bleeding into the right-column title/fix text. See screenshot in PR #20 discussion. Refactor: stack all ten gaps vertically in a single full-width column. Each gap title at x=60 + fix on the next line. ~60px vertical spacing per gap. Fix lines now have 1700px to render in — plenty of room for the longest one. Side effects: - viewBox grows: height 1500 → 1750 to fit the now-taller gaps section. - Dashed border around gaps grows: 490 → 710 tall. - Background rect grows to match new height. - Bottom footer position bumped from y=1410 → y=1715. No content lost. Order changed from interleaved (1-6, 2-7, 3-8, 4-9, 5-10 left-right pairs) to sequential (1, 2, 3, 4, 5, 6, 7, 8, 9, 10 top-down). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2 tasks
emeraldleaf
added a commit
that referenced
this pull request
May 23, 2026
All eight CodeRabbit findings on the initial commit were Quick-Win / Nit /
Minor severity — addressing each:
rebuild-diagrams.sh (4):
1. Add `uv` PATH check up front (was discovered at first render attempt,
hiding the real error in a redirect)
2. Drop `-maxdepth 2` from the find — discovers diagrams at any depth
under docs/ now (e.g., docs/a/b/c/diagram.excalidraw)
3. Quote $REPO_ROOT in parameter expansion: `${src#"$REPO_ROOT"/}` —
shellcheck SC2295, prevents accidental glob interpretation
4. Capture render output to a temp file instead of `>/dev/null 2>&1` —
on failure, print the last 20 lines of the actual error so the user
doesn't need to re-run manually to see what went wrong
render_excalidraw.py (1):
5. Guard `svg_markup` non-empty before writing the .svg sibling. Earlier
query_selector already proved the element exists, so this is defensive
— warn-and-continue on the unexpected empty-outerHTML case rather than
silently writing a broken SVG.
SKILL.md (3):
6. Add (PR #20) citation to the "Caught-in-the-wild example" so the
reference is concrete and grep-able
7. MD031 blank-lines-around-fences — added blank lines before/after the
three ```xml fences in "SVG Output for GitHub Embedding"
8. Restart ordered-list numbering at 1 in every Quality Checklist
subsection (was continuous 1-31 across all subsections — confused some
markdown parsers). Plus MD047 trailing newline on the file.
Not addressed: IDE's separate SonarLint warning about render() function
having cognitive complexity 19/15 — pre-existing on the function, not
flagged by CodeRabbit, and refactoring is scope creep.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
emeraldleaf
added a commit
that referenced
this pull request
May 23, 2026
#21) * chore(excalidraw-skill): encode text-overlap + GitHub-SVG lessons; add rebuild script The recent dev-loop diagram exposed two failure modes the skill didn't guide against. Both got fixed twice (PR #20) instead of being prevented up front. This commit encodes the lessons so future diagrams ship right the first time. SKILL.md additions: Text Width Validation (Prevent Overlap) — new subsection in Layout Principles. Quantifies the issue: SVG <text> doesn't wrap; 150-char line at 14px = ~1260px wide and bleeds into adjacent columns if column width is ~840px. Includes a per-character-width table and the four ways out (shorten, multi-element wrap, single-column restructure, foreignObject). Cites the caught-in-the-wild example from PR #20's Gaps section. SVG Output for GitHub Embedding — new top-level section. Three rules for hand-written SVG to render correctly on GitHub: 1. explicit width + height (without it, GitHub downscales to ~50% and text becomes illegible) 2. white background <rect> as first child (without it, transparent background = invisible text on GitHub dark theme) 3. single-column for any text >80 chars (SVG has no auto-wrap) Plus guidance on when the .excalidraw and .svg drift (document it inline). Quality Checklist — bumped from 27 to 31 items, adding four explicit checks for the GitHub-SVG scenario. render_excalidraw.py changes: Path A (Playwright render) now writes a sibling .svg alongside the .png. New `_make_github_friendly()` helper post-processes Excalidraw's exportToSvg output to add the width/height attributes and white background rect — so Playwright-rendered SVGs land with the same GitHub-friendly shape that hand-written ones now require. Docstring + main() print line updated. .claude/scripts/rebuild-diagrams.sh (new): Walks docs/*.excalidraw, regenerates .png + .svg outputs for any source newer than its outputs. Skips up-to-date files unless --force. Single-file mode for targeted rebuilds. CI-friendly exit code on failure. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * chore(excalidraw-skill): address CodeRabbit findings on PR #21 (8/8) All eight CodeRabbit findings on the initial commit were Quick-Win / Nit / Minor severity — addressing each: rebuild-diagrams.sh (4): 1. Add `uv` PATH check up front (was discovered at first render attempt, hiding the real error in a redirect) 2. Drop `-maxdepth 2` from the find — discovers diagrams at any depth under docs/ now (e.g., docs/a/b/c/diagram.excalidraw) 3. Quote $REPO_ROOT in parameter expansion: `${src#"$REPO_ROOT"/}` — shellcheck SC2295, prevents accidental glob interpretation 4. Capture render output to a temp file instead of `>/dev/null 2>&1` — on failure, print the last 20 lines of the actual error so the user doesn't need to re-run manually to see what went wrong render_excalidraw.py (1): 5. Guard `svg_markup` non-empty before writing the .svg sibling. Earlier query_selector already proved the element exists, so this is defensive — warn-and-continue on the unexpected empty-outerHTML case rather than silently writing a broken SVG. SKILL.md (3): 6. Add (PR #20) citation to the "Caught-in-the-wild example" so the reference is concrete and grep-able 7. MD031 blank-lines-around-fences — added blank lines before/after the three ```xml fences in "SVG Output for GitHub Embedding" 8. Restart ordered-list numbering at 1 in every Quality Checklist subsection (was continuous 1-31 across all subsections — confused some markdown parsers). Plus MD047 trailing newline on the file. Not addressed: IDE's separate SonarLint warning about render() function having cognitive complexity 19/15 — pre-existing on the function, not flagged by CodeRabbit, and refactoring is scope creep. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2 tasks
emeraldleaf
added a commit
that referenced
this pull request
May 24, 2026
… timing (#22) PR #20 was squash-merged at 16:31 with only the placeholder-link fix as its tip. The visual readability fixes — white background, explicit width/height, and single-column gaps to eliminate text overlap — were pushed to the same branch at 16:34, 16:37, and 16:41 (after the merge). Those commits sit on the orphaned docs/dev-loop-tooling branch but never landed on main. This commit recovers them by copying the final dev-loop.svg from the orphan branch directly onto main, collapsing the four follow-up commits into one. Same content as origin/docs/dev-loop-tooling tip: - viewBox 1500 → 1750 (taller, single-column gaps section) - Added explicit width="1800" height="1750" so GitHub renders at natural size with horizontal scroll instead of downscaling text below readable - Added <rect fill="#ffffff"/> as first child so text is readable on GitHub's dark theme - Bumped fonts: title 32→36, body 13→16, etc. - Gaps refactored to single column so the long fix descriptions don't bleed across columns The companion skill update (encoding these as rules so it doesn't happen again) is on chore/excalidraw-skill-text-overlap-fix. Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
This was referenced May 30, 2026
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 changed
added dev loop tolling documentation and diagram
How it was built
AI-assisted,
Summary by CodeRabbit