Explore read-only review status evaluator for PRs

[NssGourav]

Problem

The Python SDK review process currently uses PR labels and GitHub review state to communicate where a pull request is in the review flow. Labels such as step: 1st, step: 2nd, reviewer: maintainer, reviewer: committer, and reviewer: write help indicate the expected review stage or reviewer group.

However, contributors and reviewers still need to inspect the PR manually to understand what the PR is currently waiting on. There is also related discussion in #2229 around review queue automation, but that issue focuses on write-enabled behavior such as queue labels, assignments, and comments.

This issue proposes a smaller read-only first layer that can evaluate and report review status without changing PR state.

Proposed scope

Create a read-only review status evaluator that:

• reads existing PR labels
• reads GitHub review state
• determines the current review stage and what the PR is waiting on
• reports the computed status in a safe, non-enforcing way

Example output:

Review status: step 1, waiting on committer review.
Current state: review required.
Next action: committer review or approval needed.

Non-goals for the first version

The first version should not:

• change PR labels
• assign or unassign reviewers
• request reviews
• change draft or review state
• block merges
• require broad write permissions

Reporting options

Possible first reporting options:

• workflow logs only, to validate the logic safely
• a GitHub check summary, if suitable with read-only permissions
• one updatable PR comment later, if maintainers decide that issues: write is acceptable

Relationship to #2229

This issue is intended to complement #2229, not replace it.

#2229 covers write-enabled review queue automation. This issue focuses on the read-only status evaluation layer that could be used as a safer foundation before label or assignment automation is added.

Possible next steps

• define the review states to report for the Python SDK
• map existing labels to expected review stages
• decide the safest initial reporting mechanism
• keep the evaluator structured so it could later be reused by broader SDK automation

[NssGourav]

/assign

[NssGourav]

I opened #2247 as a smaller linked issue for the read-only review status evaluator layer.

My understanding is:

• Explore read-only review status evaluator for PRs #2247 focuses on reporting what a PR is waiting on without changing labels, assignees, or PR state.
• feat: automated review queue label sync stateless cron-based v1 #2229 focuses on the write enabled queue automation layer, such as queue labels,assignments, comments, and escalation.

This should keep the read-only evaluator separate while still allowing it to support the larger review queue automation direction later.

[exploreriii]

I think this could be good, i think the c++ has a dashboard report of sorts on the review side
https://github.com/hiero-ledger/hiero-sdk-cpp/tree/main/.github/workflows
You can see it in action in the PR tab

I would recommend checking out #2229 and thinking about how to structure your PR to have similar files/etc if relveant

Good luck and thanks for this suggestion!

[github-actions]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Define a review stage model that maps actual project conventions (skill labels + CODEOWNERS reviewer groups) to review status, since the ticket's example labels don't exist in this codebase
• Build the evaluator as a reusable script following existing patterns for GraphQL/REST API access and shared module structure
• Start with workflow-logs-only reporting as the safest validation approach, using core.summary for visibility in the Actions UI
• Structure the evaluator with clear separation between data fetching, status computation, and output formatting to enable future expansion to PR comments or check summaries

Design Choices

Design Choice 1: What review stages should the evaluator model?

Options Considered:

1. Model stages purely from skill labels (GFI/beginner → triage, intermediate/advanced → maintainer)
2. Model stages purely from GitHub review decision state (pending, approved, changes_requested)
3. Combine skill labels with review state to understand both expected reviewers and current progress

Chosen Option: 3

Rationale: Combining skill labels with review state provides the most actionable status. Skill labels indicate who should review (triage team for GFI/beginner, committers for code, maintainers for config), while review state shows actual progress.

Design Choice 2: What is the initial reporting mechanism?

Options Considered:

1. Workflow logs only (requires no write permissions)
2. GitHub check summary (may require checks: write)
3. Updatable PR comment (requires pull-requests: write)

Chosen Option: 1

Rationale: Workflow logs only, as explicitly recommended by the ticket as the "safest" first option. This validates the logic before any visible output is added.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Define Review Stage Model and Shared Constants

This phase establishes the foundational data model for review stages, codifying how existing labels and review states map to actionable status information.

Task 1: Create Review Stage Constants Module

Define the review stage model as a shared module that can be imported by the evaluator and potentially reused by future automation.

• Create new module at .github/scripts/shared/review-stages.js
• Define stage constants representing the review lifecycle: AWAITING_REVIEW, CHANGES_REQUESTED, APPROVED, AWAITING_TRIAGE (for GFI/beginner PRs)
• Define reviewer-type constants: TRIAGE, COMMITTER, MAINTAINER based on CODEOWNERS structure
• Export a function getExpectedReviewers(labels) that maps skill labels to expected reviewer types (GFI/beginner → triage + committer, intermediate/advanced → committer + maintainer)
• Follow the pattern in shared/labels.js for env-overridable constants and export structure

Task 2: Create Review Stage Unit Tests

Add tests for the review stage model following the pattern established in shared/labels.test.js.

• Create .github/scripts/shared/review-stages.test.js
• Test that stage constants are defined and non-empty
• Test getExpectedReviewers() returns correct reviewer types for each skill label combination
• Test edge cases: PR with no skill labels, PR with multiple skill labels

🤖 Prompt for AI agents

Create a shared constants module for the review stage model at
`.github/scripts/shared/review-stages.js`, along with its unit tests.

- In `review-stages.js`:
- Define and export stage constants for the review lifecycle: `AWAITING_REVIEW`,
`CHANGES_REQUESTED`, `APPROVED`, `AWAITING_TRIAGE` (for GFI/beginner PRs)
- Define and export reviewer-type constants: `TRIAGE`, `COMMITTER`, `MAINTAINER`
based on CODEOWNERS structure
- Export a function `getExpectedReviewers(labels)` that maps skill labels to
expected reviewer types:
    - GFI/beginner → `[TRIAGE, COMMITTER]`
    - intermediate/advanced → `[COMMITTER, MAINTAINER]`
- Follow the same pattern used in `shared/labels.js` for env-overridable
constants and export structure
- In `review-stages.test.js` (following the pattern of `shared/labels.test.js`):
  - Test that all stage constants are defined and non-empty
- Test that `getExpectedReviewers()` returns the correct reviewer types for each
skill label combination
  - Test edge cases: PR with no skill labels, PR with multiple skill labels

Phase 2: Implement Review Status Evaluator Script

This phase creates the core evaluation logic that reads PR state and computes the review status.

Task 1: Create Evaluator Script

Build the main evaluator script following existing patterns for GitHub API interaction.

• Create .github/scripts/review-status-evaluator.js
• Import shared constants from shared/labels.js and shared/review-stages.js
• Implement getPRLabels(github, owner, repo, prNumber) using REST API to fetch PR labels
• Implement getReviewState(github, owner, repo, prNumber) using GraphQL to query reviewDecision field (following pattern from bot-pr-draft-ready-reminder.js)
• Implement getDetailedReviews(github, owner, repo, prNumber) using REST API to fetch per-reviewer states (following pattern from bot-pr-draft-explainer.js)
• Implement main evaluateReviewStatus(github, context) function that orchestrates the above and returns a structured status object

Task 2: Implement Status Computation Logic

Add the core logic that interprets PR state and produces human-readable status.

• Within the evaluator script, implement computeStatus(labels, reviewDecision, detailedReviews) function
• Determine current stage based on reviewDecision value (null/REVIEW_REQUIRED → awaiting, CHANGES_REQUESTED → needs changes, APPROVED → approved)
• Determine expected reviewers using getExpectedReviewers(labels) from shared module
• Compute "waiting on" based on comparing expected reviewers against who has reviewed
• Return structured object with: currentStage, expectedReviewers, waitingOn, nextAction, summary (human-readable string)

Task 3: Implement Log Output Formatting

Add structured logging for workflow output.

• Implement formatStatusForLog(status) that produces clear, multi-line output matching the ticket's example format
• Include: review status line, current state line, next action line
• Export the main evaluation function for use by the workflow via actions/github-script
• Add DRY_RUN environment variable support following the pattern in bot-pr-draft-explainer.js

🤖 Prompt for AI agents

Create the core evaluator script at
`.github/scripts/review-status-evaluator.js`. This phase implements data
fetching, status computation, and log output formatting.

**Data fetching functions:**
- Import shared constants from `shared/labels.js` and `shared/review-stages.js`
- Implement `getPRLabels(github, owner, repo, prNumber)` using the REST API to
fetch PR labels
- Implement `getReviewState(github, owner, repo, prNumber)` using GraphQL to
query the `reviewDecision` field, following the pattern from
`bot-pr-draft-ready-reminder.js`
- Implement `getDetailedReviews(github, owner, repo, prNumber)` using the REST
API to fetch per-reviewer states, following the pattern from
`bot-pr-draft-explainer.js`

**Status computation:**
- Implement `computeStatus(labels, reviewDecision, detailedReviews)` function:
- Determine the current stage from `reviewDecision`: `null`/`REVIEW_REQUIRED` →
awaiting, `CHANGES_REQUESTED` → needs changes, `APPROVED` → approved
- Determine expected reviewers via `getExpectedReviewers(labels)` from the
shared module
- Compute "waiting on" by comparing expected reviewers against who has already
reviewed
- Return a structured object with: `currentStage`, `expectedReviewers`,
`waitingOn`, `nextAction`, `summary` (human-readable string)

**Orchestration and output:**
- Implement main `evaluateReviewStatus(github, context)` function that calls the
data fetching functions and passes results to `computeStatus`
- Implement `formatStatusForLog(status)` producing clear multi-line output
including: review status line, current state line, next action line
- Export the main evaluation function for use by the workflow via
`actions/github-script`
- Add `DRY_RUN` environment variable support following the pattern in
`bot-pr-draft-explainer.js`

Phase 3: Create Workflow to Run Evaluator

This phase creates the GitHub Actions workflow that triggers the evaluator on PR events.

Task 1: Create Evaluator Workflow

Define the workflow file with minimal, read-only permissions.

• Create .github/workflows/pr-review-status-evaluator.yml
• Set trigger on pull_request events: opened, synchronize, reopened, labeled, unlabeled, ready_for_review
• Also trigger on pull_request_review events: submitted, dismissed to catch review state changes
• Set minimal permissions: contents: read, pull-requests: read (no write permissions)
• Add concurrency group keyed on PR number to avoid parallel runs for same PR
• Include step-security/harden-runner with egress-policy: audit following existing patterns

Task 2: Implement Workflow Job

Define the job that runs the evaluator and logs output.

• Create single job evaluate-status running on ubuntu-latest
• Use actions/checkout to access the scripts
• Use actions/github-script to run the evaluator, importing from .github/scripts/review-status-evaluator.js
• Log the computed status using core.info() for structured output
• Set outputs via core.setOutput() for potential future workflow chaining
• Add job summary output using core.summary to make status visible in Actions UI without requiring PR write access

🤖 Prompt for AI agents

Create the GitHub Actions workflow file at
`.github/workflows/pr-review-status-evaluator.yml` to trigger and run the
evaluator.

**Workflow triggers and permissions:**
- Trigger on `pull_request` events: `opened`, `synchronize`, `reopened`,
`labeled`, `unlabeled`, `ready_for_review`
- Also trigger on `pull_request_review` events: `submitted`, `dismissed`
- Set minimal read-only permissions: `contents: read`, `pull-requests: read`
- Add a concurrency group keyed on PR number to prevent parallel runs for the
same PR
- Include `step-security/harden-runner` with `egress-policy: audit`, following
existing workflow patterns

**Job definition (`evaluate-status`):**
- Run on `ubuntu-latest`
- Use `actions/checkout` to access the scripts
- Use `actions/github-script` to import and run the evaluator from
`.github/scripts/review-status-evaluator.js`
- Log the computed status using `core.info()` for structured output
- Set outputs via `core.setOutput()` for potential future workflow chaining
- Add job summary output using `core.summary` to make status visible in Actions
UI without requiring PR write access

Research

The Python SDK repository has extensive GitHub automation in .github/workflows/ and .github/scripts/. Existing patterns include GraphQL queries for aggregate reviewDecision state (bot-pr-draft-ready-reminder.js), REST API calls for per-reviewer review details (bot-pr-draft-explainer.js), shared label constants in .github/scripts/shared/labels.js, and a consistent workflow structure with step-security/harden-runner and actions/github-script. The codebase uses skill-based labels (Good First Issue, skill: beginner/intermediate/advanced) rather than explicit review-stage labels, and CODEOWNERS defines a committer/maintainer split for reviewer assignment.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Create a shared constants module for the review stage model at
`.github/scripts/shared/review-stages.js`, along with its unit tests.

- In `review-stages.js`:
- Define and export stage constants for the review lifecycle: `AWAITING_REVIEW`,
`CHANGES_REQUESTED`, `APPROVED`, `AWAITING_TRIAGE` (for GFI/beginner PRs)
- Define and export reviewer-type constants: `TRIAGE`, `COMMITTER`, `MAINTAINER`
based on CODEOWNERS structure
- Export a function `getExpectedReviewers(labels)` that maps skill labels to
expected reviewer types:
    - GFI/beginner → `[TRIAGE, COMMITTER]`
    - intermediate/advanced → `[COMMITTER, MAINTAINER]`
- Follow the same pattern used in `shared/labels.js` for env-overridable
constants and export structure
- In `review-stages.test.js` (following the pattern of `shared/labels.test.js`):
  - Test that all stage constants are defined and non-empty
- Test that `getExpectedReviewers()` returns the correct reviewer types for each
skill label combination
  - Test edge cases: PR with no skill labels, PR with multiple skill labels
===============================================================================

Task: 2

Create the core evaluator script at
`.github/scripts/review-status-evaluator.js`. This phase implements data
fetching, status computation, and log output formatting.

**Data fetching functions:**
- Import shared constants from `shared/labels.js` and `shared/review-stages.js`
- Implement `getPRLabels(github, owner, repo, prNumber)` using the REST API to
fetch PR labels
- Implement `getReviewState(github, owner, repo, prNumber)` using GraphQL to
query the `reviewDecision` field, following the pattern from
`bot-pr-draft-ready-reminder.js`
- Implement `getDetailedReviews(github, owner, repo, prNumber)` using the REST
API to fetch per-reviewer states, following the pattern from
`bot-pr-draft-explainer.js`

**Status computation:**
- Implement `computeStatus(labels, reviewDecision, detailedReviews)` function:
- Determine the current stage from `reviewDecision`: `null`/`REVIEW_REQUIRED` →
awaiting, `CHANGES_REQUESTED` → needs changes, `APPROVED` → approved
- Determine expected reviewers via `getExpectedReviewers(labels)` from the
shared module
- Compute "waiting on" by comparing expected reviewers against who has already
reviewed
- Return a structured object with: `currentStage`, `expectedReviewers`,
`waitingOn`, `nextAction`, `summary` (human-readable string)

**Orchestration and output:**
- Implement main `evaluateReviewStatus(github, context)` function that calls the
data fetching functions and passes results to `computeStatus`
- Implement `formatStatusForLog(status)` producing clear multi-line output
including: review status line, current state line, next action line
- Export the main evaluation function for use by the workflow via
`actions/github-script`
- Add `DRY_RUN` environment variable support following the pattern in
`bot-pr-draft-explainer.js`
===============================================================================

Task: 3

Create the GitHub Actions workflow file at
`.github/workflows/pr-review-status-evaluator.yml` to trigger and run the
evaluator.

**Workflow triggers and permissions:**
- Trigger on `pull_request` events: `opened`, `synchronize`, `reopened`,
`labeled`, `unlabeled`, `ready_for_review`
- Also trigger on `pull_request_review` events: `submitted`, `dismissed`
- Set minimal read-only permissions: `contents: read`, `pull-requests: read`
- Add a concurrency group keyed on PR number to prevent parallel runs for the
same PR
- Include `step-security/harden-runner` with `egress-policy: audit`, following
existing workflow patterns

**Job definition (`evaluate-status`):**
- Run on `ubuntu-latest`
- Use `actions/checkout` to access the scripts
- Use `actions/github-script` to import and run the evaluator from
`.github/scripts/review-status-evaluator.js`
- Log the computed status using `core.info()` for structured output
- Set outputs via `core.setOutput()` for potential future workflow chaining
- Add job summary output using `core.summary` to make status visible in Actions
UI without requiring PR write access

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[github-actions]

Hello, this is CommunityCallBot.

This is a reminder that the Hiero Python SDK Community Call will begin in approximately 3 hours and 3 minutes (14:00 UTC).

The call is an open forum where contributors and users can discuss topics, raise issues, and influence the direction of the Python SDK.

Details:

• Time: 14:00 UTC
• Join Link: Zoom Meeting

Disclaimer: This is an automated reminder. Please verify the schedule here for any changes.

[github-actions]

Hi @NssGourav 👋

This issue has been assigned but no pull request has been created yet.
Are you still planning on working on it?
If you are, please create a draft PR linked to this issue or comment /working to let us know.
If you’re no longer able to work on this issue, you can comment /unassign to release it.

From the Python SDK Team

[NssGourav]

/working

[github-actions]

Hi @NssGourav, this is CronInactivityBot 👋

You were assigned to this issue 50 days ago, and there is currently no open pull request linked to it.
To keep the backlog available for active contributors, I'm unassigning you for now.

If you're no longer interested, no action is needed.

Tip: You can comment /unassign on any issue to proactively step away before this bot kicks in.

If you'd like to continue working on this later, feel free to comment /assign on the issue to get re-assigned, and open a new PR when you're ready. 🚀