Comment Triage Workflow

Relevant source files

The following files were used as context for generating this wiki page:

• examples/commands/triage.md
• README.md
• PRODUCT.md
• studio/public/openapi.yaml
• studio/src/lib/api.ts
• studio/src/components/ReviewReader.tsx

The Comment Triage Workflow manages feedback received on a developer's own GitLab Merge Requests (MRs). The system polls GitLab for unresolved threads from peers, triggers an automated triage command using Claude Code, and presents the findings in a local studio. This workflow allows developers to efficiently process reviewer comments, apply local fixes, and draft replies before pushing updates back to the project.

Sources: PRODUCT.md:16-20, README.md:154-159

Triage Execution Logic

The marginalia poller triggers the triage workflow when it detects new or updated peer comments on an MR authored by the configured GITLAB_USERNAME. Unlike the standard review workflow, a fresh push without new comments does not re-trigger triage.

1. Detection: The poller identifies unresolved threads where the author is not the current user.
2. Command Invocation: The bot runs the TRIAGE_COMMAND (e.g., /triage) headlessly in a dedicated git worktree.
3. Analysis: The command assesses each comment against the MR diff and ticket requirements, assigning a verdict of RELEVANT, NOT RELEVANT, or WRONG.
4. Action: For RELEVANT comments, the agent applies fixes directly to the working tree. For others, it drafts a short reply.

Sources: examples/commands/triage.md:5-7, README.md:154-160

Local Fixes and Version Control

Fixes applied during triage are committed locally within the bot's worktree but are never automatically pushed to the remote repository.

• Local Branching: Commits land on a local-only branch named marginalia/<branch-slug>.
• Safety: The bot worktree is cleaned (git clean -fdx) and reset (git reset --hard) before every checkout, but the marginalia/ branch preserves the triage work.
• Superseding: If a new triage occurs and no new commits are made, previous fixes are moved to refs/marginalia/superseded/<branch-slug>.

Sources: README.md:165-171

Fix Statuses

The studio tracks the relationship between the local triage fixes and the remote MR branch.

State	Description
none	No local fixes exist for this triage.
ready	Fixes are on top of the current remote head; push will fast-forward.
pushed	The branch on origin already contains these fixes.
outdated	The remote branch moved since the triage; a re-run is required.

Sources: studio/public/openapi.yaml:263-268, studio/src/lib/api.ts:241-246

Studio Triage Interface

The studio serves as the primary interface for reviewing triage results. It presents a report containing the comment, the agent's verdict, rationale, and the resulting action (fix applied or drafted reply).

Components and APIs

• ReviewReader: Displays the triage report. If the MR kind is comments, it renders a FixesPanel. Sources: studio/src/components/ReviewReader.tsx:77-81
• FixesPanel: Provides the interface for pushing local fixes to origin if ALLOW_PUSH=true is set in the environment. Sources: studio/src/components/ReviewReader.tsx:79
• API Endpoints:
  • GET /api/fixes/{slug}: Compares local fixes against the remote branch.
  • POST /api/push: Executes a fast-forward push of the local marginalia/ branch to origin.

Sources: studio/public/openapi.yaml:261-299

Triage Report Data Model

The triage process produces a report categorized as comments (represented by ReviewKind). This report is stored as a Markdown file and normalized into a ReviewShape for the studio.

export interface ReviewItem {
  slug: string;
  kind: 'review' | 'comments' | 'retro';
  title: string;
  iid: string | number | null;
  author: string | null;
  // ... other fields
  postable: number; // Findings with ready-to-post replies
}

Sources: studio/src/lib/api.ts:27-51

Conclusion

The Comment Triage Workflow automates the initial assessment and remediation of reviewer feedback. By integrating automated code analysis with local git management and a controlled push mechanism, it minimizes the manual effort required to resolve peer discussions while ensuring the developer remains in final control of the codebase.

Sources: PRODUCT.md:16-25, README.md:175-180