Applying Local Fixes

Relevant source files

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

• README.md
• PRODUCT.md
• studio/public/openapi.yaml
• studio/src/lib/api.ts
• examples/commands/triage.md
• skills/marginalia-review/SKILL.md

Local fixes represent the automated code changes generated by Marginalia's triage system in response to peer comments on your own Merge Requests (MRs). When you author an MR, the triage command fetches unresolved discussion threads and applies relevant fixes directly to a dedicated bot worktree. These fixes remain local to your machine until you explicitly review and push them via the Marginalia Studio.

This system ensures that AI-generated code never enters the remote repository without human oversight. The bot commits changes to a local-only branch, allowing you to cherry-pick or push them after verification.
Sources: README.md:122-132, PRODUCT.md:15-20, examples/commands/triage.md:7-10

Triage and Fix Generation

The TRIAGE_COMMAND initiates the process of identifying and applying fixes. The bot polls GitLab for comments left by peers on your MRs. If it detects new activity, it runs the triage command within the bot worktree.

Triage Logic

The triage agent performs the following actions for each unresolved comment:

1. Evaluates the comment against the MR diff and ticket requirements.
2. Assigns a verdict: RELEVANT, NOT RELEVANT, or WRONG.
3. Applies code changes for RELEVANT comments using the Edit tool.
4. Commits these changes locally in the bot worktree.
5. Drafts replies for comments that do not require code changes.

Sources: README.md:122-126, examples/commands/triage.md:7-10, PRODUCT.md:15-20

This diagram illustrates the flow from detecting peer feedback to committing local fixes.
Sources: README.md:122-132, examples/commands/triage.md:7-10

Local Branch Management

Fixes are committed to a local-only branch named marginalia/<branch-slug>. This branch is stored in the git object database shared with your REPO_LOCAL_PATH, making it visible from your primary checkout.

Branch States

The system tracks the relationship between the local fix branch and the remote MR branch.

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

Sources: README.md:133-138, studio/public/openapi.yaml:301-306, studio/src/lib/api.ts:285-292

Superseded Fixes

If a new triage run occurs while the branch has moved or previous fixes exist, the bot moves the older fixes to refs/marginalia/superseded/<branch-slug> to prevent data loss while maintaining a clean current fix branch.
Sources: README.md:138-140

Studio Integration and Pushing

The Marginalia Studio provides the interface for reviewing and pushing local fixes. Pushing is an opt-in feature that requires ALLOW_PUSH=true in the .env configuration.

Pushing Requirements

1. Verification: You must review the "Fixes to push" card in the studio.
2. Fast-Forward Only: The studio only performs fast-forward pushes. It never uses --force.
3. Manual Confirmation: A click is required to move changes from the local marginalia/ branch to the remote origin.

Sources: README.md:133-142, studio/public/openapi.yaml:313-317, PRODUCT.md:38-42

This sequence diagram shows the interaction between the user, the local server, and the remote repository during the fix application process.
Sources: studio/public/openapi.yaml:301-335, studio/src/lib/api.ts:299-310

Configuration and API

The following API endpoints and data structures manage the lifecycle of local fixes.

API Endpoints

• GET /api/fixes/{slug}: Returns the FixesStatus including the local ref, remote SHA, and a list of commits that the push would add.
• POST /api/push: Executes the push of the local fix branch to the origin.

Sources: studio/public/openapi.yaml:301-335

Data Structures

The FixesStatus object is the primary data model for tracking fix readiness:

export interface FixesStatus {
  ref: string;      // e.g., marginalia/feat-branch
  branch: string;   // Remote branch name
  state: 'none' | 'ready' | 'pushed' | 'outdated';
  fixesSha: string | null;
  remoteSha: string | null;
  commits: { sha: string; subject: string }[];
}

Sources: studio/src/lib/api.ts:285-292

The local fixes system in Marginalia balances automation with developer control. By keeping fixes local and requiring explicit push actions, it allows for AI-assisted iteration on peer feedback without compromising repository integrity or bypassing human code review.