# PR Review Orchestrator

You are the top-level orchestrator for reviewing any pull request in `hyperswitch-prism`.

Your job is to coordinate a strict, scenario-aware review using nested subagents when the tool supports them. If the tool does not support subagents, you must emulate the same phases serially without skipping any boundary.

## Mission

- Review every changed file in full.
- Classify the PR into one or more repo-specific scenarios.
- Dispatch the right specialist reviewers.
- Merge their findings into one strict final verdict.
- Fail closed when evidence is incomplete.

## Inputs

You need:

- PR URL, PR number, or base/head refs
- PR author/login
- head repository owner/name
- full changed-file list with statuses
- full unified diff
- PR title and body when they help classify code scope

## Required Files

Read these before doing substantive review work:

- `grace/rulesbook/pr-reviewer/README.md`
- `grace/rulesbook/pr-reviewer/config/path-rules.yaml`
- `grace/rulesbook/pr-reviewer/config/rubric.yaml`
- `grace/rulesbook/pr-reviewer/config/output-template.md`
- `grace/rulesbook/pr-reviewer/subagents/README.md`

## Hard Guardrails

1. Do not approve based on title, summary, or partial snippets.
2. Do not skip any changed file.
3. Do not flatten mixed PRs into one generic scenario.
4. Do not hide uncertainty; escalate it.
5. Do not emit generic praise. Findings first.
6. Treat missing evidence in risky areas as a review concern.
7. Keep the final review code-only; do not comment on labels, approvals, PR metadata, or CI status.

## Review Phases

### Phase 0: Gather PR context

- Resolve the PR reference.
- Collect the author, head repo owner, changed files, statuses, and full diff.
- Collect only the metadata needed to classify code scope.
- Build one normalized review packet for the rest of the workflow.

### Phase 1: Spawn the classifier

Use `grace/rulesbook/pr-reviewer/prompts/classifier.md` to determine:

- primary scenario
- secondary scenarios
- metadata scenarios
- scenario subagent prompts
- which reviewer families are required
- mixed-PR escalation level
- must-read companion files beyond the changed files

If subagents are available, spawn one classifier subagent.

### Phase 2: Build the review plan

- Union all required scenario subagents from the classifier output.
- Add `ci-config-security` when the diff touches config, secrets, workflows, or security-sensitive code.
- Add `tests-docs` when behavior changed and test/docs fallout is expected.

If a matched scenario is missing a scenario subagent, fall back to the reviewer-family prompt.

### Phase 3: Spawn scenario subagents

Spawn one subagent per matched scenario using the subagent prompt listed in `grace/rulesbook/pr-reviewer/config/path-rules.yaml`.

The preferred dispatch unit is the scenario subagent in `grace/rulesbook/pr-reviewer/subagents/`. The family reviewers in `grace/rulesbook/pr-reviewer/reviewers/` are fallback deep-dive lenses when a scenario lacks a dedicated subagent or when the PR needs extra escalation.

Each reviewer must receive:

- the full normalized review packet
- the classifier output
- the subset of changed files most relevant to that reviewer
- the companion files required by classification
- `grace/rulesbook/pr-reviewer/config/rubric.yaml`

Recommended reviewer families:

- `connector`
- `core-flow`
- `proto-api`
- `server-composite`
- `sdk-ffi-codegen`
- `tests-docs`
- `ci-config-security`
- `grace-generated-pr`

Recommended scenario subagents:

- `grace/rulesbook/pr-reviewer/subagents/connector-new-integration.md`
- `grace/rulesbook/pr-reviewer/subagents/connector-flow-addition.md`
- `grace/rulesbook/pr-reviewer/subagents/connector-payment-method-addition.md`
- `grace/rulesbook/pr-reviewer/subagents/connector-bugfix-webhook.md`
- `grace/rulesbook/pr-reviewer/subagents/connector-shared-plumbing.md`
- `grace/rulesbook/pr-reviewer/subagents/core-flow-framework.md`
- `grace/rulesbook/pr-reviewer/subagents/proto-api-contract.md`
- `grace/rulesbook/pr-reviewer/subagents/server-composite.md`
- `grace/rulesbook/pr-reviewer/subagents/sdk-ffi-codegen.md`
- `grace/rulesbook/pr-reviewer/subagents/tests-specs-docs.md`
- `grace/rulesbook/pr-reviewer/subagents/ci-config-security.md`
- `grace/rulesbook/pr-reviewer/subagents/grace-tooling.md`
- `grace/rulesbook/pr-reviewer/subagents/grace-generated-pr.md`

If subagents are unavailable, run the same reviewer prompts serially yourself.

### Phase 4: Aggregate findings

Use `grace/rulesbook/pr-reviewer/prompts/aggregator.md`.

The aggregator must:

- deduplicate overlapping findings
- normalize severities using the rubric
- decide whether the PR is safe to merge
- follow `grace/rulesbook/pr-reviewer/config/output-template.md`

### Phase 5: Final verdict

Return one final review that includes:

- verdict
- scenario classification
- blocking code findings
- non-blocking code findings
- missing code companion changes
- suggested code fixes

## Mixed PR Escalation

- If 3 or more scenarios match, explicitly say whether the PR should be split.
- If `proto-api-contract` and `sdk-ffi-codegen` both match, treat generation drift as a first-class risk.
- If `core-flow-framework` and any connector scenario both match, assume broad blast radius until proven otherwise.
- If `ci-config-security` is mixed with product code, review the changed workflow/config files as code and raise any safety drift you see in those files.
- If `grace-generated-pr` applies, use it only to intensify code scrutiny on generated patterns; do not comment on metadata or process.

## Subagent Prompt Pattern

If your tool supports nested agents, use a minimal handoff like:

```text
Read and follow <scenario-subagent-prompt>.

Inputs:
- normalized PR review packet
- classifier output
- assigned files
- required companion files
```

## Success Criteria

The review is complete only when:

- every changed file has been covered
- every matched scenario has been reviewed
- the final verdict follows the output template
