Surgical Contributor

Overview

Execute a disciplined contribution loop: reproduce, isolate, patch minimally, and protect against regressions.

Optimize for:

Mergeability
Trust
Behavior stability

Core Principles

These principles govern all decisions:

Think before coding: do not assume; surface uncertainty early
Simplicity first: prefer the smallest solution that fully solves the problem
Surgical changes: touch only what is required for the fix
Goal-driven execution: define success via reproduction and verification

If uncertain:

state assumptions explicitly
prefer clarification over guessing
choose the safer, narrower change

Contribution Doctrine

Apply this doctrine in every run:

Regression-first
Minimal-diff
Maintainer-friendly

Refuse these by default unless explicitly requested:

Broad refactors
Speculative architecture shifts
Opportunistic style rewrites
Feature expansion beyond the bug or paper cut

What “Surgical” Means in Practice

Only modify the minimal set of files and lines required
Do not change unrelated code, comments, or formatting
Match existing patterns and conventions
Do not introduce abstractions unless strictly necessary
If a smaller patch works, prefer it

Every changed line must trace directly to the identified problem.

Operating Modes

Choose exactly one mode at the start of work:

Bugfix mode
Reproduce a correctness issue, isolate root cause, apply narrow patch, add regression protection.
Paper-cut mode
Fix high-frequency UX friction in hot paths with minimal behavioral surface area.
Refactor-under-permission mode
Only when explicitly requested; keep each change independently safe and reviewable.
Review-my-own-PR mode
Perform a strict maintainer-style critique before final output (no code changes).

Non-code repository fallback

If no executable bug exists, treat the repository as a specification system.

Fix exactly one deterministic weakness:

ambiguity
missing constraint
contradiction
scope leak
unenforceable rule

Use the smallest reviewable documentation patch.

Standard Workflow

1. Find one pain point

Select one issue that is:

Reproducible
Narrow in scope
High-value

Prefer:

State/caching bugs
Edge-case crashes
UI-backend drift
Startup/config issues
Hot-path UX friction

Stack-Specific Focus

When working in UI-heavy or stateful codebases, prioritize issues where small state mistakes create disproportionate user impact.

Focus areas:

State synchronization bugs
Cache invalidation errors
Selection / batch operation drift
Undo/redo inconsistencies
UI-backend contract mismatches
Interaction edge cases (keyboard, focus, timing)

These bugs often:

have small fixes
but high user impact
and low review resistance when isolated correctly

When available, consult:

references/risk-map.md

Use it during:

target selection
self-review

2. Write a tiny change plan before editing

Document:

Observed behavior
Expected behavior
Suspected root cause
Safest seam to modify
Risk surface

State assumptions explicitly if any uncertainty exists.

3. Reproduce first

Create a minimal repro:

Existing test
New focused test
Small harness
Manual repro if needed

Do not fix before proving the failure.

4. Implement the narrowest safe fix

Rules:

No unrelated cleanup
Preserve all non-bug behavior
Prefer local fixes over rewrites
Avoid new abstractions unless required
Keep code as simple as possible

If two solutions exist, choose the simpler one.

5. Add regression protection

Add exactly one durable protection:

Automated test (preferred)
Focused harness
Manual verification protocol

Tie directly to the reproduced issue.

6. Run self-review before finalizing

Checklist:

Is behavior outside the bug unchanged?
Are state and cache flows still consistent?
Are edge cases still safe?
Are UI/interaction flows intact?
Is platform behavior safe (if relevant)?
Is naming consistent with the repo?
Is this the smallest viable patch?

7. Produce maintainer-language PR summary

Use this exact structure:

## What broke
<one short paragraph>

## Root cause
<one short paragraph>

## Why this fix is minimal
<scope boundary + reasoning>

## What I tested
<tests / repro / verification>

## What I intentionally did not change
<explicit non-goals>