Feedback Modes

Supported public path: GitLab artifact-first

Start with artifact-first delivery, then layer MR feedback on top only after the baseline path is working.

Artifact-first baseline

The public onboarding baseline is the artifact-first workflow:

• The review job writes ai-review.html, ai-review.md, and ai-review.json.
• Developers inspect the results from the job artifacts first.
• The team validates the review path before adding more delivery noise to merge requests.

This keeps the first successful run narrow, observable, and easy to debug.

What each surface owns

• The GitLab Review Summary is the persistent PatchPatrol-owned merge request note. It carries the current reviewer decision and cross-run Active Finding Set.
• ai-review.json, ai-review.md, and ai-review.html are Run Reports for one execution. They preserve that run's structured evidence, readable detail, and printable presentation.
• Inline Findings are separate GitLab discussions anchored to changed lines. They keep actionable code context beside the diff.

The Run Reports do not replace the GitLab Review Summary, and a Run Report from one execution does not own the merge request's cross-run finding lifecycle.

Optional MR feedback

MR feedback is a follow-on capability, not the primary onboarding path.

• Use it after the artifact-first workflow is already working for the team.
• Treat MR feedback as an enhancement to the same review run, not a replacement for understanding the artifacts.
• When MR feedback is enabled, PatchPatrol-owned summary state lets later reruns use incremental provider review by default. The first run reviews the full MR; later safe reruns can review only the delta since the prior PatchPatrol-reviewed head SHA while preserving full MR line anchoring.
• The GitLab Review Summary leads with Review Outcome, risk, Review Coverage, reviewed commit, and active-finding counts.
• The first run omits Review Delta because there is no prior PatchPatrol state to compare. Safe reruns can add a compact Review Delta for new, updated, resolved, unchanged, or not-re-evaluated findings.
• Use the job console and linked Run Report for usage statistics, routing reasons, skipped-inline diagnostics, and other operational details. They stay out of the merge request summary so the review decision remains easy to scan.
• Medium, high, and blocker findings appear as Inline Findings when placement is safe. PatchPatrol does not cap the number of eligible Inline Findings. Inline Findings are not duplicated in the GitLab Review Summary.
• Non-inline Priority Findings remain actionable in the summary: at most three are expanded, with every fallback finding retained in collapsed detail. Low and informational Review Suggestions use a separate collapsed section and do not create new threads.
• If an eligible finding cannot be placed safely, or GitLab rejects discussion creation, PatchPatrol preserves it as Summary Fallback without changing the Review Outcome.
• ai-review.html is enabled by default, so the latest Run Report link opens the HTML artifact. An explicit HTML opt-out changes that link to ai-review.md.
• The JSON artifact remains the canonical machine-readable contract.
• Keep deeper operator, self-hosted, and private-rollout delivery variants outside this public guide.

Sanitized example: compact GitLab Review Summary

This public-safe example shows a rerun. Names, paths, commit IDs, and counts are illustrative:

PatchPatrol · GitLab Review Summary
Review Outcome: Attention needed
Risk: High
Review Coverage: Full (4/4 validated chunks)
Reviewed commit: 7e31b2a
Active Findings: blocker=0 high=1 medium=2 suggestions=0
**Review Delta:** 1 new · 1 resolved · 2 unchanged

Summary Fallback
- HIGH · Request validation gap · src/api/orders.py:42

Inline discussion (separate): 2 findings beside changed lines
HTML Run Report (separate): latest run artifact
Job console: Operational Diagnostics

The compact note answers the merge decision first. Inline discussions carry line-specific prose, while the HTML Run Report and job console retain deeper run evidence and diagnostics.

If MR delivery disappears, is suppressed, or fails after artifact writing, use Troubleshooting instead of switching modes blindly.

How to choose the next step

• Stay on the artifact-first path when you are still proving the workflow or onboarding a new team.
• Move to MR feedback when you want the review result to appear directly in merge request collaboration.
• Return to First review output if you still need to confirm the artifacts before changing delivery mode.
• Use Troubleshooting if feedback delivery and artifact output no longer agree.

Next step: Reference

Also continue with:

• First review output
• Troubleshooting