Automatic Accept/Decline mechanism for the agentic-review PRWorkflow

[issue-hemingway]

Originates from #243

Quality assessment

The issue intent is clear and feasible, but it is underspecified in a few implementation-critical areas: the exact decision contract returned by the model, whether the formal review action should be posted with or without also posting the existing markdown comment, and provider-scope/behavior when a repository provider does not support review-state changes. Repository context shows the workflow config UI already supports BOOLEAN and TEXT params, and repository clients already expose a provider-agnostic postReviewAction hook, so the feature is implementation-ready with a few assumptions called out.

Summary

Add an optional auto-decision capability to the agentic-review PR workflow so the bot can formally Approve, Request changes, or leave the PR review state unchanged, based on an additional workflow-specific prompt.

This must work for both:

• native tool-calling mode, and
• legacy JSON chat / legacy tool-calling mode.

Default behavior remains unchanged: the workflow only posts a markdown review comment unless the new option is explicitly enabled.

---

Current behavior

The agentic-review workflow reviews the PR diff, may call read-only tools, and posts its findings as a PR comment.

It does not currently change the PR review state (approve / request changes).

---

Desired behavior

In the workflow edit page at:
system-settings/workflow-configurations/[id]/workflows

within the Agentic PR Review section, add two new workflow parameters:

1. Enable formal review decision

   • Type: checkbox / boolean
   • Default: false
   • Meaning: when enabled, the bot may return a formal review decision for the PR.

2. Approval decision prompt

   • Type: multiline text / textarea
   • Default: prefilled with a suitable default instruction
   • Editable only when Enable formal review decision is checked
   • Meaning: operator-provided criteria describing when the bot should:
     • approve,
     • request changes, or
     • leave the review state unchanged.

When the workflow runs and Enable formal review decision is true, the system prompt used for the agentic review must be extended with:

• the configured decision prompt text, and
• an additional non-editable instruction that defines the exact structured return format for the decision.

After the model finishes, the workflow must parse that return value and:

• post Approve when the model returns APPROVE
• post Request changes when the model returns REQUEST_CHANGES
• do nothing to the formal review state when the model returns NONE

The review comment behavior should remain intact unless implementation constraints require otherwise.

---

Scope

In scope

• Workflow configuration UI for agentic-review
• Persisting the new workflow parameters in the existing workflow params JSON
• Extending the runtime prompt for agentic-review
• Parsing a structured approval decision from the model output
• Forwarding the parsed decision to RepositoryApiClient.postReviewAction(...)
• Supporting both native tool-calling and legacy JSON chat / legacy tool-calling flows
• Backward compatibility with existing workflow configurations
• Documentation updates for the agentic review workflow

Out of scope

• Adding write-capable repository tools
• Changing the default behavior of other PR workflows
• Schema/database migration for existing configs

---

Proposed implementation details

New workflow params

Add the following params to AgentReviewWorkflow.paramsSchema():

Key	Type	Default	Description
enableFormalReviewDecision	boolean	false	Allows the workflow to post a formal PR review decision.
formalReviewDecisionPrompt	text	<default prompt text>	Criteria for when to approve, request changes, or leave the PR unchanged.

Notes:

• formalReviewDecisionPrompt should be editable only when enableFormalReviewDecision=true.
• If conditional disabling is not currently supported by the generic workflow form renderer, implement at least a UI-level disable/hide for this workflow field or document the limitation and enforce behavior server-side.

Runtime behavior

When enableFormalReviewDecision=false:

• Preserve current behavior exactly.
• Post the normal markdown review comment only.
• Do not call postReviewAction(...).

When enableFormalReviewDecision=true:

• Extend the system prompt with the operator-configured decision prompt.
• Append a fixed, non-editable instruction describing the required structured decision output.
• Parse the final model output for both:
  • the human-readable review text, and
  • the formal decision (APPROVE, REQUEST_CHANGES, NONE).
• Post the markdown review comment as today.
• Then call repositoryClient.postReviewAction(owner, repo, prNumber, action) when the parsed action is not NONE.

Structured decision contract

The implementation should use a deterministic structured response contract rather than free-text parsing.

Suggested logical decision enum values:

• APPROVE
• REQUEST_CHANGES
• NONE

The exact serialization format can follow the pattern already used elsewhere in the codebase for structured AI responses, but it must be:

• explicit in the prompt,
• machine-parseable,
• supported in both native and legacy modes,
• resilient to malformed output.

Examples of acceptable approaches:

• a JSON object appended to the final answer,
• a dedicated fenced JSON block,
• a clearly delimited sentinel section.

If the model output is invalid or the decision cannot be parsed safely, fail open to:

• keep the markdown review comment if available,
• treat the formal decision as NONE.

---

Legacy mode requirement

This feature must also work when native tool-calling is unavailable and the workflow is running in the existing legacy JSON chat / legacy tool-calling path.

That means:

• the decision instruction must be included in the legacy prompt flow as well,
• the final assistant output must still contain the structured decision payload,
• the parser must work regardless of whether tools were used.

---

Backward compatibility

• No migration is required.
• Existing workflow configurations continue to work unchanged.
• The default for the new feature is disabled.
• If the new params are absent from stored workflow config JSON, runtime behavior must match today's behavior.

---

Error handling / provider behavior

• If the repository provider does not support formal review actions via postReviewAction(...), the workflow should still complete successfully and still post the markdown review comment.
• Unsupported providers should degrade gracefully to comment-only behavior.
• Invalid or malformed model decision output must not fail the whole workflow run.

---

Acceptance criteria

• agentic-review exposes a new boolean workflow parameter to enable/disable formal review decisions.
• The new boolean parameter defaults to false.
• agentic-review exposes a new multiline text parameter for decision criteria.
• The multiline text parameter is only editable when the boolean is enabled.
• A suitable default decision prompt is provided.
• When the feature is disabled, agentic-review behaves exactly as today.
• When enabled, the workflow appends both the configured decision prompt and a fixed structured-output instruction to the runtime prompt.
• The workflow can parse APPROVE, REQUEST_CHANGES, and NONE from the final model output.
• APPROVE results in a formal PR approval.
• REQUEST_CHANGES results in a formal request-changes review.
• NONE leaves the formal review state unchanged.
• The feature works in native tool-calling mode.
• The feature works in legacy JSON chat / legacy tool-calling mode.
• If parsing fails, the workflow does not post a formal review action.
• No DB migration is required.
• Existing workflow configurations remain compatible.
• Documentation for agentic-review is updated.

---

Suggested tests

Unit tests

• Param schema includes the two new fields with correct defaults.
• Missing new params resolve to disabled behavior.
• Final decision parser maps valid outputs to APPROVE, REQUEST_CHANGES, and NONE.
• Malformed/partial outputs fall back to NONE.
• Disabled mode never calls postReviewAction(...).
• Enabled mode calls postReviewAction(...) only for APPROVE and REQUEST_CHANGES.

Integration/service tests

• Native tool-calling path: final output with decision triggers the expected review action.
• Legacy JSON path: final output with decision triggers the expected review action.
• Provider/client without override for postReviewAction(...) degrades without error.
• Review comment is still posted in both enabled and disabled modes.

UI tests

• Workflow configuration page renders the new checkbox and textarea.
• Checkbox defaults to unchecked on a new configuration.
• Textarea is disabled or hidden until checkbox is enabled.
• Saved values round-trip correctly through the workflow configuration form.

---

Notes from repository context

Current code/docs describe agentic-review as read-only and explicitly state that it never posts a formal review action. This issue intentionally changes that behavior, but only when the new workflow option is enabled. Corresponding code comments and docs should be updated to reflect the new conditional behavior.

Assumptions

• The existing workflow params JSON can store the new boolean and text fields without any schema migration.
• The existing workflow configuration UI can render BOOLEAN and TEXT params for this workflow.
• Posting a formal review action should be additive to the existing markdown review comment, not a replacement.
• The formal decision should be parsed from the final model response using a structured contract, but the exact wire format can be chosen during implementation.
• If a provider does not support formal review actions, the default RepositoryApiClient implementation is an acceptable no-op fallback.

Open questions

• Should the final review comment include the chosen formal decision explicitly, or should the formal state change remain separate from the comment body?
• What exact default decision prompt text should product/maintainers prefer for approve vs request-changes thresholds?
• Should the generic workflow form framework support conditional enable/disable behavior for dependent fields, or is a workflow-specific UI handling acceptable here?

---

This issue was automatically drafted by the AI technical-writer agent.

[tmseidel]

verified in 1.14.0