Skip to content
Skills Library
Programming · Building & coding

surgical-patch

/surgical-patch

Fix a bug or make a small behaviour change at the narrowest layer that owns the wrong behaviour, with regression proof and nothing else touched. Use for bug fixes and small tweaks where preserving surrounding behaviour matters. Not for new features (use lean-build) or restructuring (use safe-refactor).

Licence
MIT
Last repository change
12.11.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Fix a bug or make a small behaviour change at the narrowest layer that owns the wrong behaviour, with regression proof and nothing else touched. Use for bug fixes and small tweaks where preserving surrounding behaviour matters. Not for new features (use lean-build) or restructuring (use safe-refactor).

Original author description

Fix a bug or make a small behaviour change at the narrowest layer that owns the wrong behaviour, with regression proof and nothing else touched. Use for bug fixes and small tweaks where preserving surrounding behaviour matters. Not for new features (use lean-build) or restructuring (use safe-refactor).

How it works

  1. When to use
  2. Steps
  3. Rules
  4. Red flags
  5. Output
Original SKILL.md headings · 45 lines, 464 words
SKILL.md preview
---
name: surgical-patch
description: Fix a bug or make a small behaviour change at the narrowest layer that owns the wrong behaviour, with regression proof and nothing else touched. Use for bug fixes and small tweaks where preserving surrounding behaviour matters. Not for new features (use lean-build) or restructuring (use safe-refactor).
metadata:
  kind: skill
  castes: [coder]
  tags: [bugfix, minimal-diff, regression]
  version: 1
  status: vetted
  sources:
    - repo: juliusbrussee/caveman
      path: skills/surgical-patch/SKILL.md
      license: Apache-2.0
---

# Surgical Patch

Fix the fault where it lives, prove it is fixed, and leave everything else exactly as it was.

## When to use

- A bug fix, or a small change to existing behaviour.
- The surrounding code must keep working as before.

Not for: new features (`lean-build`), structural cleanup (`safe-refactor`), build or type errors (`build-error-resolution`), data or schema changes (`reversible-migration`).

## Steps

1. **Capture the failure.** Reproduce it first, ideally as a failing automated test. If a test is too costly, capture the strongest evidence you can: exact error, log line, input that triggers it, steps to reproduce.
2. **Trace the symptom to the mechanism.** Follow the failure from where it shows up back to the code that actually decides the wrong thing. The place where the error appears is often not the place that is wrong.
3. **Pick the narrowest responsible layer.** Change the layer that *owns* the incorrect behaviour, not a caller that hides it. Patching the symptom downstream (an extra null check, a special case in the UI) leaves the real fault for the next caller to hit.
4. **Make the smallest change that fixes it.** Match the existing style. Remove only what your change made unused.
5. **Add regression proof.** One test (or the reproduction from step 1) that fails without the fix and passes with it. Only proof relevant to this fault.
6. **Run the proof, then the nearest gate.** Run the focused test first, then the closest wider check that could be affected (the module's test suite, the type check, the build).
7. **Stop and report.** Stop as soon as the failure is fixed and the regression proof passes.

## Rules

- Preserve unrelated behaviour, including odd behaviour other code may depend on.
- Preserve user or teammate changes already in the working tree. Never overwrite or revert them.
- No cleanup, renaming, reformatting or new abstractions outside the fix. Note them in your result instead.
- If the true fix needs a wider change (interface change, several modules, data migration), stop and report back with your findings rather than widening scope on your own.
- If you cannot reproduce the failure, say so. Do not ship a speculative fix as if it were proven.

## Red flags

- The diff touches files that have nothing to do with the fault.
- You fixed it without ever seeing it fail.
- The fix is a broad try/catch, a default value or a suppressed warning that hides the error.
- "While I'm here…" changes.

## Output

In the task card result:
- Root cause in one or two sentences (file and line).
- What changed and why that layer.
- The regression proof and the checks run, with results.
- Anything noticed but deliberately left alone.

Versions

The database has no other skills named surgical-patch.

Database snapshot: 13.11.2026 · package version 59093fd5329a (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90lean-build
    Build new behaviour as one complete, narrow, end-to-end slice that fits the existing system, with explicit non-goals and a clear stop condition. Use for new features, product slices or integrations where overbuilding is a risk. Not for bug fixes (surgical-patch) or restructuring (safe-refactor).
  • 100fix-bug
    Use when the user asks to fix a known bug, after a regression trace or from a clear report. Triggers include "fix this bug", "patch this", "apply the fix", "repair this crash", "the tracer found the commit, fix it", "make the failing test pass".
  • 90task
    Make a small change to a shipped product — a bug fix, behavior tweak, micro-feature, refactor, or perf fix — as one verified slice, syncing the affected feature spec on the way out. Use for day-to-day requests like "fix X", "change Y to do Z", or a single small feature that…
  • 90duck-patch
    Surgical implementation for small, bounded code edits after direction is clear. Use when: "apply this fix", "make a targeted edit", "patch this", "implement the agreed change".
  • 100surgical-code-refactoring
    Token-efficient, dependency-aware methodology for modifying large existing codebases without breaking working functionality. Patch over rewrite, validate BEFORE integrating, regression-check after every change. ALWAYS use when editing a large single-file app, adding features to…
  • 100bug-fix
    Bug fix workflow. Use when: fixing bugs, resolving issues, regression fixes. Not for: new features (use feature-dev), understanding code (use code-explore). Output: fix + regression test + review gate.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.