docs: update CodeRabbit workflow review instructions to nudge quality (hiero-ledger#1799) (hiero-ledger#1809)

Signed-off-by: Ritesh Patil <riteshsanjaypatil@gmail.com>
Signed-off-by: riteshr19 <riteshrana36@gmail.com>
Signed-off-by: Ritesh Kumar <ritesh@ambicuity.com>
Co-authored-by: Manish Dait <90558243+manishdait@users.noreply.github.com>

Author: ambicuity

.coderabbit.yaml

@@ -1018,178 +1018,128 @@ reviews:
     # --- CUSTOM INSTRUCTIONS FOR .GITHUB DIRECTORY ---
     - path: ".github/workflows/**/*"
       instructions: |
-        Review workflows as security-sensitive infrastructure.
-
-        A good workflow is small, focused, and boring.
-        If a workflow is clever, generic, or overly flexible, it is a risk.
-
-        ---------------------------------------------------------
-        PRIORITY 0 — ABSOLUTE REQUIREMENTS 
-        ---------------------------------------------------------
-        - All third-party actions MUST be pinned to full commit SHAs, similar to other workflows.
-        - `permissions:` MUST be explicitly declared and minimally scoped.
-        - Workflows MUST behave safely when executed from forks.
-        - YAML MUST orchestrate steps, not implement business logic.
-        - Any workflow that mutates GitHub state MUST support dry-run mode.
-        - Dry-run behavior must be explicit and visible in logs.
-        - Workflows MUST NOT modify repository source code outside `.github/`.
-
-        ---------------------------------------------------------
-        PRIORITY 1 — SCOPE, FOCUS & RESTRAINT
-        ---------------------------------------------------------
-        - The title of each workflow must be relevant, match similar naming schemes, and match its script filename.
-        - Each workflow MUST have a single, clearly defined objective and SHOULD document this in a top-level comment.
-        - Flag workflows that:
-          - Attempt to be generic “frameworks”
-          - Include speculative or future-facing logic
-          - Perform actions unrelated to the stated goal
-        - Over-abstraction and excess flexibility are maintenance risks.
+        You are reviewing GitHub Actions workflows as a thoughtful senior
+        engineer. Your goal is to nudge contributors toward higher-quality,
+        maintainable workflows — not to impose a rigid checklist.
 
         ---------------------------------------------------------
-        PRIORITY 2 — INPUT HARDENING
+        SECURITY ESSENTIALS
         ---------------------------------------------------------
-        - Treat ALL GitHub event data as potentially hostile input, including:
-          - issue titles, bodies, and comments
-          - labels, usernames, branch names
-        - Free-form user input MUST NOT be passed directly into:
-          - shell commands
-          - gh CLI arguments
-          - Node.js exec / spawn calls
-        - Require strict allowlists or exact string matches.
-        - Flag any use of:
-          - eval or bash -c
-          - backticks or $(...) with user-controlled input
+        These are firm expectations for every workflow:
+
+        - All third-party actions must be pinned to full commit SHAs,
+          consistent with other workflows in this repository.
+        - `permissions:` must be explicitly declared and scoped to the
+          minimum needed. Flag over-permissioned or under-permissioned
+          workflows, and any reliance on broad default permissions.
+        - Workflows must not request `contents: write` unless strictly
+          required.
+        - Workflows must behave safely when executed from forks.
+        - Treat all GitHub event data as potentially untrusted input:
+          issue titles, bodies, comments, labels, usernames, branch
+          names. Prefer strict allowlists or exact string matches.
+          Free-form user input must not flow directly into shell
+          commands, `gh` CLI arguments, or Node.js exec/spawn calls.
 
         ---------------------------------------------------------
-        PRIORITY 3 — DRY-RUN & SAFE OPERATION
+        CLARITY & CODE ORGANIZATION
         ---------------------------------------------------------
-        - Workflows that mutate state MUST expose:
-          workflow_dispatch:
-            inputs:
-              dry_run:
-                default: "true"
-        - When dry_run=true, workflows MUST:
-          - Log dry mode is active
-          - Function on dry run: never post, comment, label, assign or edit
-          - Be easy to expand in the future
-          - Exit successfully
+        Each workflow should have a single, clearly defined objective.
+        YAML should orchestrate execution — not implement business
+        logic.
+
+        - Non-trivial logic belongs in dedicated scripts under
+          `.github/scripts/`, keeping the workflow YAML focused on
+          orchestration.
+        - Environment variables should be defined in the YAML and
+          passed to scripts, not hardcoded inside scripts.
+        - Flag large `run: |` blocks, inline loops or conditionals,
+          and API calls embedded directly in YAML steps.
 
         ---------------------------------------------------------
-        PRIORITY 4 — SCRIPT EXTRACTION & CODE TRIM
+        DRY-RUN
         ---------------------------------------------------------
-        - YAML should orchestrate execution only.
-        - All non-trivial logic MUST live in:
-          - `.github/scripts/*.sh`
-          - `.github/scripts/*.js`
-        - Workflow filenames and their primary scripts SHOULD share a clear, matching name.
-        - Scripts MUST remain:
-          - Purpose-built
-          - Trim and readable
-          - Easy to maintain
-        - Flag:
-          - Large `run: |` blocks
-          - Inline loops, conditionals, or API calls in YAML
-          - Overly generic helper scripts for narrow tasks
+        If used, dry-run should be clear, well-logged, and default
+        to true on `workflow_dispatch`. It should have a reasonable
+        use case and be easy to maintain. Do not flag missing dry-run
+        as a blocker.
 
         ---------------------------------------------------------
-        PRIORITY 5 — API EFFICIENCY & DISCIPLINE
+        OPERATIONAL QUALITY
         ---------------------------------------------------------
-        - GitHub API usage must be intentional and minimal.
-        - Prefer:
-          - Aggregated queries over per-entity loops
-          - Server-side filtering over client-side iteration
-          - Reusing data already present in the event payload
-        - Pagination MUST:
-          - Be considered and justified
-          - Enforce hard upper bounds
-        - Flag:
-          - Repeated API calls inside loops
-          - Unbounded pagination
-          - Fetching data already available in context
+        - Log key decisions and early exits — avoid silent skips.
+        - Avoid raw payload dumps and any secret or token leakage.
+        - Workflows that mutate state should use concurrency groups
+          and duplicate prevention patterns (marker-based comments,
+          check-before-create for labels).
+        - Assume workflows may run multiple times or be retried.
 
         ---------------------------------------------------------
-        PRIORITY 6 — CONCURRENCY & IDEMPOTENCY
+        API DISCIPLINE
         ---------------------------------------------------------
-        - Workflows that mutate state MUST:
-          - Define a deterministic concurrency group
-          - Be safe under retries and parallel execution
-        - Duplicate prevention is REQUIRED:
-          - Marker-based comment detection
-          - Check-before-create logic for labels and assignments
-        - Assume workflows may:
-          - Run multiple times
-          - Be retried automatically
-          - Execute concurrently with other automations
-        - Workflows should avoid logic that duplicates or causes conflicts.
+        - Prefer reusing data already in the event payload over
+          making additional API calls.
+        - Prefer aggregated queries and server-side filtering over
+          per-entity loops and client-side iteration.
+        - Pagination should have reasonable upper bounds.
 
         ---------------------------------------------------------
-        PRIORITY 7 — PERMISSION CORRECTNESS
+        REVIEW SCOPE
         ---------------------------------------------------------
-        - Requested permissions MUST exactly match behavior.
-        - Explicitly validate common cases:
-          - issues: write → comments, labels, assignments
-          - contents: read → repository checkout
-          - pull-requests: write → PR mutations
-        - Flag:
-          - Over-permissioned workflows
-          - Under-permissioned workflows that would fail at runtime
-          - Reliance on default permissions
+        - Focus feedback on the PR's stated scope.
+        - Flag out-of-scope issues as irrelevant and suggest opening
+          a separate PR — do not block for them.
+        - Do not propose major refactors unless correctness or
+          security is affected.
 
         ---------------------------------------------------------
-        PRIORITY 8 — LOGGING & OPERABILITY
+        BLOCKERS vs SUGGESTIONS
         ---------------------------------------------------------
-        - Logs should include, where applicable:
-          - repository
-          - workflow name
-          - issue or PR number
-          - triggering actor
-          - dry-run status
-          - decisions made (performed vs skipped)
-        - Avoid:
-          - Silent success or silent skips
-          - Raw payload dumps
-          - Any secret or token leakage
+        - Block only for security, correctness, or firm expectation
+          violations.
+        - Style and maintainability improvements should be
+          non-blocking suggestions.
+        - When in doubt, suggest — don't block.
 
     # ============================================================
     # SHELL SCRIPTS
     # ============================================================
     - path: ".github/scripts/**/*.sh"
       instructions: |
-        Treat shell scripts as production-grade automation.
+        Review shell scripts as production-grade CI automation.
 
-        Scripts should be small, focused, and explicit.
-        Avoid “do-everything” or overly generic scripts.
+        Firm expectations:
+        - Use `set -euo pipefail` to fail fast on errors.
+        - Environment variables should be passed from the YAML,
+          validated early, and defensively quoted.
+        - No `eval`, `bash -c`, backticks, or `$(...)` with untrusted content.
 
-        - MUST use: `set -euo pipefail`
-        - MUST validate all required environment variables
-        - MUST defensively quote variables
-        - MUST validate all untrusted input
-        - MUST have bounded loops and pagination
-        - MUST support dry-run mode if state is mutated
-        - MUST log key decisions and early exits
+        Good practices:
+        - Log key decisions and early exits.
+        - Keep scripts purpose-built — flag overly generic helpers.
 
     # ============================================================
     # JAVASCRIPT SCRIPTS
     # ============================================================
     - path: ".github/scripts/**/*.js"
       instructions: |
-        Review JavaScript scripts as long-lived automation code.
-
-        Scripts must remain:
-        - Focused
-        - Readable
-        - Purpose-built
-
-        - All `context.payload` fields MUST be validated
-        - Free-form text MUST NOT be trusted
-        - Dynamic code execution is prohibited
-        - Avoid `child_process.exec`; prefer `execFile` if needed
-        - All async operations MUST be wrapped in try/catch
-        - Errors MUST include contextual metadata
-        - Duplicate API calls MUST be avoided
-        - Marker-based deduplication is required
-        - Scripts MUST NOT assume write access
-        - Permission failures MUST be handled gracefully
+        Review JavaScript scripts as production-grade CI automation.
+
+        Firm expectations:
+        - Validate `context.payload` fields before use.
+        - Do not trust free-form text from issues, PRs, or comments.
+        - No `eval`, `new Function`, or dynamic code execution.
+        - Use top-level constants for configuration — avoid
+          hardcoded values scattered through the script.
+        - Environment variables should be passed from the workflow
+          YAML, not hardcoded in the script.
+
+        Good practices:
+        - Wrap async operations in try/catch with contextual errors.
+        - Reuse event context data instead of making redundant API
+          calls.
+        - Use marker-based patterns to prevent duplicate actions.
+        - Handle permission failures gracefully.
 
     - path: "src/hiero_sdk_python/query/**/*.py"
       instructions: *query_review_instructions

CHANGELOG.md

@@ -36,6 +36,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - chore: update step-security/harden-runner from 2.14.1 to 2.14.2 in a workflow
 - Redesigned beginner issue template with readiness self-check, exploration-based task structure, compact workflow reference, and common pitfalls guidance to improve completion rates (#1651)
 - Added workflow documentation guide (`docs/github/04_workflow_documentation.md`) with best practices for documenting GitHub workflows and automation scripts (#1745)
+- Updated CodeRabbit workflow and script review instructions to nudge higher-quality patterns without imposing rigid rules (`#1799`)
 
 ## [0.2.0] - 2026-11-02