Findings & Verdicts
Relevant source files
The following files were used as context for generating this wiki page:
Findings and Verdicts constitute the core analytical output of the Marginalia review process. A Finding represents a specific, atomic observation regarding a code change, typically anchored to a file and line number. A Verdict is the high-level decision rendered by the review agent, summarizing the overall state of the merge request (MR).
The Marginalia studio consumes these data points to provide a structured, interactive reading experience. This system allows you to verify machine-generated suggestions, edit comments, and post them as GitLab draft notes for final submission.
Sources: README.md:68-83, studio/src/lib/api.ts:4, studio/src/lib/api.ts:89-97
Data Structures
The system relies on a normalized data shape for findings and verdicts, regardless of which skill or command generated the review.
Finding Schema
Each finding contains metadata for identification, location, and communication.
| Field | Type | Description |
|---|---|---|
id | string | A stable identifier derived from the file and point, used for tracking across re-runs. |
severity | enum | The priority level: critical, important, suggestion, or info. |
title | string | A short descriptive title for the observation. |
path | string | null | Repo-relative path to the affected file. |
line | number | null | The specific line number in the new version of the file. |
body | string | The full technical explanation and evidence for the finding. |
comment | string | null | A pre-written comment ready for posting to GitLab. |
Sources: studio/src/lib/api.ts:89-97, studio/public/openapi.yaml:396-405
Verdicts
A verdict summarizes the bot's final assessment of the MR. The system supports three primary states:
APPROVE: The changes meet project standards and are ready for merging.REQUEST_CHANGES: The changes contain critical or important issues that must be addressed.OTHER: A non-standard or inconclusive result.null: No verdict has been rendered (unrated).
Sources: studio/src/lib/api.ts:4, studio/public/openapi.yaml:370-372
Severity Definitions
Severity levels determine how findings are prioritized in the UI and how they influence the final verdict.
- critical: Represents wrong behavior, data loss, security vulnerabilities, or broken builds. These findings typically block the merge and lead to a
REQUEST_CHANGESverdict. - important: Indicates a likely bug, missing tests on risky logic, or a breach of repository-specific rules.
- suggestion: Points to improvements the author may choose to skip; non-blocking.
- info: Used for questions or highlighting something done well.
The diagram above illustrates how the severity of findings influences the high-level verdict and subsequent UI representation.
Sources: skills/marginalia-review/SKILL.md:65-78, studio/src/components/FindingsPanel.tsx:13-14
Review Processing and Extraction
The system extracts findings from two primary sources: structured JSON files or raw Markdown reports.
Extraction Logic
- JSON Source: If the command writes a
.marginalia-findings.jsonfile, the studio uses it as the source of truth. - Markdown Source: If no JSON exists, the system parses the report. It looks for sections titled
## Critical,## Important, or## Suggestions. Bullets within these sections become individual findings. The firstpath[:line]found in a bullet serves as the anchor. - Meta Extraction: The system extracts metadata such as Branch, Ticket, and MR IID from standard Markdown lines using regex patterns.
Sources: README.md:73-88, studio/src/lib/reviewSections.ts:41-52, studio/src/lib/reviewSections.ts:58-67
The Posting Workflow
The studio facilitates the transition from bot-generated findings to human-verified GitLab comments.
Adding to Review
When ALLOW_POSTING=true is set, the FindingsPanel provides an Add to review button. Clicking this:
- Creates a GitLab Draft Note.
- Anchors the note to a specific
pathandlinein the MR. - If the line anchor is refused by GitLab (e.g., outside the diff), the system adds it as a general note prefixed with the path/line.
Sources: studio/src/components/FindingsPanel.tsx:90-100, studio/public/openapi.yaml:189-192
Submitting the Review
Once individual findings are added as drafts, you must submit the full review. The ConfirmSubmit component manages this final step.
This sequence shows the progression from individual finding selection to the bulk publishing of a review.
Sources: studio/src/components/ConfirmSubmit.tsx:55-75, studio/public/openapi.yaml:227-240
Findings Panel Interface
The FindingsPanel and FindingCard components manage the display and editing of findings.
Interactive Features
- Editing: You can edit the
commentfield of a finding directly in the studio before posting. - Focus & Scroll: Selecting a finding in the sidebar or diff list triggers a scroll-into-view action (
scrollInPane) and a visual flash to highlight the item. - Compact Mode: Beside a diff pane, findings appear as single-line titles that expand on click.
Sources: studio/src/components/FindingsPanel.tsx:43-52, studio/src/components/FindingsPanel.tsx:78-85, studio/src/components/FindingsPanel.tsx:115-125
Visual Categorization
Findings are visually distinguished by color-coded badges based on their severity.
| Severity | Color | CSS Class |
|---|---|---|
| Critical | Red | bg-red-500 |
| Important | Amber | bg-amber-500 |
| Suggestion | Blue | bg-blue-500 |
| Info | Zinc | bg-zinc-400 |
Sources: studio/src/components/FindingsPanel.tsx:13-14, DESIGN.md:57-60
Summary
Findings and Verdicts bridge the gap between automated code analysis and human code review. By normalizing findings into a standard schema—regardless of their origin—Marginalia ensures that you can efficiently triage machine observations, refine them into high-quality feedback, and maintain full control over the final review submitted to GitLab.