docs: update CodeRabbit workflow review instructions to nudge quality (#1799)

[ambicuity]

Description

Rewrites the CodeRabbit review instructions for .github/workflows/**/*, .github/scripts/**/*.sh, and .github/scripts/**/*.js from a prescriptive MUST/PRIORITY style to a balanced, quality-nudging approach that encourages better practices without causing scope creep.

What changed

Area	Before	After
Structure	PRIORITY 0–8 numbered tiers	Natural section headers (Security Essentials, Input Safety, Clarity & Purpose, etc.)
Tone	MUST, REQUIRED, ABSOLUTE REQUIREMENTS	should, prefer, consider, good practice
Dry-run	Mandatory for all state-mutating workflows	Contextual: "consider where it genuinely helps"
Scope control	None	New REVIEW SCOPE section: focus on PR's stated scope, don't block for out-of-scope issues
Shell scripts	7 × MUST bullet list	Firm expectations + good practices tiers
JS scripts	10 × MUST bullet list	Firm expectations + good practices tiers

Why

The V1 prompt was overly prescriptive, which led to:

• CodeRabbit flagging dry-run as critical for every workflow, even read-only ones
• Contributors implementing feedback to-the-letter, causing scope drift and bloated workflows
• Workflows becoming long, unclear, and hard to maintain

The V2 prompt keeps security essentials firm while providing quality signals rather than rigid rules.

Security essentials retained

• SHA-pinned third-party actions ✅
• Explicit minimal permissions ✅
• Fork safety ✅
• Input hardening (no eval, strict allowlists) ✅

Files changed

• .coderabbit.yaml — Rewritten workflow/script review sections
• CHANGELOG.md — Added entry under [Unreleased] > .github

Testing

• yaml.safe_load() — YAML syntax valid ✓
• ruff check — No new lint issues ✓
• pytest tests/unit/ — 1495 passed ✓

Closes #1799

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Rewrites CodeRabbit review guidance in .coderabbit.yaml, replacing rigid PRIORITY blocks with thematic, role-focused sections (e.g., SECURITY ESSENTIALS, CLARITY & CODE ORGANIZATION, OPERATIONAL QUALITY), clarifies expectations for shell/JS scripts, reframes dry-run guidance, and adds an Unreleased changelog entry.

Changes

Cohort / File(s)	Summary
CodeRabbit review prompt \.coderabbit\.yaml	Major rewrite: replaces numbered PRIORITY blocks with thematic guidance (SECURITY ESSENTIALS, CLARITY & CODE ORGANIZATION, DRY-RUN/OPERATIONAL QUALITY, API DISCIPLINE, BLOCKERS vs SUGGESTIONS). Emphasizes pinning actions, scoped permissions, fork-safety, input hardening, logging, idempotency, safe API use, and pushes non-trivial logic into .github/scripts/. Updates shell script expectations (set -euo pipefail discipline, quoting, logging) and JS script expectations (validate event context, avoid dynamic exec, robust error handling).
Changelog CHANGELOG.md	Adds an Unreleased entry documenting the updated CodeRabbit workflow/script review guidance (#1799).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: updating CodeRabbit workflow review instructions to nudge quality without imposing rigid rules, matching the primary objective of the PR.
Description check	✅ Passed	The description is thorough and directly related to the changeset, detailing structural changes, tone shifts, security essentials retained, files modified, and testing performed.
Linked Issues check	✅ Passed	The PR fully addresses issue #1799 by rewriting the CodeRabbit prompt from prescriptive PRIORITY tiers to natural section headers with advisory tone, adding a REVIEW SCOPE section, retaining security essentials, and including a valid changelog entry with passing CI checks.
Out of Scope Changes check	✅ Passed	All changes are in-scope: updates to .coderabbit.yaml workflow review instructions and a related CHANGELOG.md entry directly address the PR's stated objectives and issue #1799 requirements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

[Copilot]

Pull request overview

Updates the CodeRabbit configuration to shift GitHub workflow/script review guidance from rigid “MUST”-style rules to a more balanced, scope-aware set of quality nudges, and records the change in the changelog.

Changes:

• Rewrote .github/workflows/**/* review instructions into sectioned guidance (security essentials, input safety, dry-run, operational quality, API discipline, review scope).
• Rewrote .github/scripts/**/*.sh and .github/scripts/**/*.js guidance into “firm expectations” vs “good practices”.
• Added an [Unreleased] changelog entry for the updated CodeRabbit guidance.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
.coderabbit.yaml	Replaces priority-tiered workflow/script review rules with sectioned, quality-nudging guidance and explicit review-scope constraints.
CHANGELOG.md	Adds an Unreleased entry documenting the CodeRabbit review-instructions update.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Mounil2005]

Thanks @ambicuity for improving this....this should meaningfully reduce noisy, scope-creeping bot feedback while keeping quality high.

Some suggestions :

1. Add an explicit “Blockers vs Suggestions” rubric
   Please add a short section that clearly distinguishes what should block approval (security/correctness) vs what should be a non-blocking suggestion (style/maintainability). This will help keep CodeRabbit feedback consistent and prevent scope creep.

2. Keep “Security Essentials” explicitly non-negotiable
   Even with the softer tone overall, I’d recommend making “Security Essentials” unambiguous (e.g., “must/block if violated”), especially for SHA-pinning third-party actions, minimal permissions, fork safety, and input hardening.

3. Tighten dry-run guidance with concrete criteria
   The new dry-run wording is good, could we make it more actionable with 2–3 bullets (e.g., prefer dry-run for deploy/publish/release/state-mutating workflows; usually unnecessary for read-only CI)? This should reduce subjective/flip-floppy reviews.

[ambicuity]

Addressed all review feedback — thanks @Mounil2005 for the thorough suggestions!

Changes in this push:

1. Security Essentials — should → must for SHA-pinning, permissions, fork safety, source code modification (Mounil2005 + Copilot)
2. Blockers vs Suggestions rubric — new section: block only for security/correctness, suggest for style/maintainability (Mounil2005)
3. Dry-run concrete criteria — prefer for deploy/publish/release; unnecessary for read-only/validation workflows (Mounil2005)
4. Script-level DRY_RUN — allowed as defense-in-depth alongside YAML-level orchestration (Copilot)
5. Shell injection caution — added eval/bash -c/backticks warning to shell script firm expectations (CodeRabbit)
6. CHANGELOG — hyphenated 'higher-quality' (Copilot)

[github-actions]

Hi, this is MergeConflictBot.
Your pull request cannot be merged because it contains merge conflicts.

Please resolve these conflicts locally and push the changes.

Quick Fix for CHANGELOG.md Conflicts

If your conflict is only in CHANGELOG.md, you can resolve it easily using the GitHub web editor:

1. Click on the "Resolve conflicts" button in the PR
2. Accept both changes (keep both changelog entries)
3. Click "Mark as resolved"
4. Commit the merge

For all other merge conflicts, please read:

• Resolving Merge Conflicts
• Rebasing Guide

Thank you for contributing!

[exploreriii]

Hi @ambicuity
Good start but we should work to make this a lot more concise
Harcoding should be avoided in the .js, and variables should be added there at the top level, but passed down from the yml where possible as env

[ambicuity]

Addressed all review feedback — thanks @exploreriii for the detailed comments!

Changes in this push

Feedback	What changed
Delete motto lines 730-732	✅ Removed
contents: write instead of "must not modify source"	✅ Replaced line 745
Delete naming lines 771-774 (unclear)	✅ Removed
Hardcoding guidance belongs in .js, not .yml	✅ Moved to JS script section; YAML section now says "env vars should be defined in YAML and passed to scripts"
Dry-run is way too long	✅ Reduced from 14 lines to 4: "clear, well-logged, default to true on workflow_dispatch, reasonable use case, maintainable"
Delete repeated pagination line	✅ Removed duplicate
Out-of-scope: flag as irrelevant, suggest new PR	✅ Reworded: "Flag out-of-scope issues as irrelevant and suggest opening a separate PR"
Env vars should be extracted in yml	✅ Added to both YAML and JS sections
Shell script repetition near top	✅ Removed duplicate input validation — moved input safety into Security Essentials
Good practices too repetitive / generic	✅ Collapsed shell and JS good practices to essentials only, removed cross-section repetition

Net change: −74 lines in .coderabbit.yaml (from ~200 lines of guidance to ~126).

Also rebased onto main and fixed CHANGELOG merge conflict.

[exploreriii]

Hi @ambicuity I think this is a very good improvement, i expect it will help a lot
Thank you

[exploreriii]

@ambicuity rebase please and ready to go 👍

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@           Coverage Diff           @@
##             main    #1809   +/-   ##
=======================================
  Coverage   93.29%   93.29%           
=======================================
  Files         141      141           
  Lines        9119     9119           
=======================================
  Hits         8508     8508           
  Misses        611      611           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

[commit-verification-bot]
Hi, this is VerificationBot.
Your pull request cannot be merged as it has 3 unverified commit(s):

• bd25444 docs: update CodeRabbit workflow review instructio
• cc49d3c docs: address review feedback on CodeRabbit instru
• 905145e docs: address exploreriii review feedback on CodeR

View your commit verification status: Commits Tab.

To achieve verified status, please read:

• Signing guide
• README
• Discord

Remember, you require a GPG key and each commit must be signed with:
git commit -S -s -m "Your message here"

Thank you for contributing!

From the Hiero Python SDK Team

[coderabbitai]

Actionable comments posted: 1

[manishdait]

Hi i @ambiguity, after attempting a GitHub UI rebase, the last three commits were rewritten. This is causing the DCO check to fail. Since the branch is from your fork, could you please rebase locally and re-sign the last three commits, then push the updates?

You can run something like:

git rebase -f --gpg-sign --signoff HEAD~3
git push --force-with-lease

After that, rebasing onto the latest main should work cleanly.
Thanks, and sorry for the inconvenience

[ambicuity]

Hi @manishdait, I have rebased and signed off on the last three commits to fix the DCO check! I also explicitly included $(...) alongside backticks in the shell script untrusted content instructions as suggested. Everything is pushed! Let me know if anything else is needed.

[exploreriii]

@manishdait please merge if suitable, else please request explicitly second opinions