# PR Review Agent Runbook

## Project Context To Prepare
- Project goal
- Current repository or workflow context
- Diff
- Requirements
- Test output
- Known constraints

## Input Template
Project:

Goal:

Current context:

Constraints:

Available files, notes, or data:

Expected output:
- Findings
- Test gaps
- Verdict
- Open questions

## Starter Inputs
### First useful run
Use this when you know the goal but still need a structured first draft.

Review a pull request that changes agent search filters and includes lint output.

Context:
- Current state:
- Constraints:
- Audience:
- Success criteria:

### Project handoff run
Use this when the output will be pasted into a ticket, PR, document, or project brief.

Goal: produce Findings for a real project.
Source material:
- 
Constraints:
- 
Review needs:
- Go deep on the risks and constraints listed above.
- Mark assumptions.
- Flag missing context.

### Boundary check
Use this when the request may be under-specified and you want the agent to narrow it safely.

Judge whether a large refactor is safe from a prose summary without seeing the diff.

Before producing the final answer, identify missing required context and propose a stronger prompt if needed.

## Setup Context Notes
- Provide the actual diff, requirement, test output, and review focus so findings can be concrete.
- Include the target audience, output destination, and any examples of acceptable or unacceptable work.
- Name what should remain out of scope so the agent does not broaden the task.

## Good Input Example
Diff summary: installable agents now receive generated evaluation metadata.
Requirement: ensure project-ready agents show trustworthy quality signals.
Test output: npm run check:data passed.
Review focus: behavioral regressions, misleading quality claims, missing validation.

## Weak Input Example
Review my PR and tell me if it is good.

## Weak Input Diagnostics
### Help me with PR Review Agent.
- Why it fails: It does not name the project, source material, constraints, audience, or success criteria.
- Stronger input: Review a pull request that changes agent search filters and includes lint output. Include current context, constraints, expected output, and review criteria.

### Make this better.
- Why it fails: The agent cannot tell whether better means clearer, safer, faster, more complete, or easier to hand off.
- Stronger input: Improve the output for Pre-merge review. Optimize for Findings, keep assumptions explicit, and list the changes made.

## Expected Output Shape
- Findings ordered by severity (blocker, major, minor): location, failure case, and the fix as a code change
- Test gaps: the test to add for each finding or changed behavior
- Verdict: merge, merge after fixes, or do not merge, with the deciding findings
- Questions only for what the diff cannot answer
- Style nits kept to one line each under "Nits (optional)"

## Output Checklist
- Every requirement, constraint, and file the user named is checked against the diff, citing lines
- Each finding has severity, location, failure case, and a concrete fix
- Test gaps name the test to add
- Comments only on code that was shown; assumptions are marked [ASSUMPTION]
- Does not approve unseen code or deploys

## Failure Modes
- No diff is provided but the review comments on code anyway
- Style preferences come before correctness issues
- Findings lack severity, location, or a concrete fix
- The review approves a merge or deploy it cannot verify

## Handoff Tips
- Paste relevant project files, notes, or constraints before asking for the final output.
- Ask for a first draft, then request a stricter revision using the checklist.
- Keep the generated output with the project ticket, PR, proposal, or team document.