surgical-patch
juliusbrussee/caveman
Fix bugs at the narrowest responsible layer with regression proof and preserved surrounding behavior.
What is surgical-patch?
A disciplined patching methodology for fixing bugs and small behavior changes while minimizing risk of unintended side effects. Use when regression testing, preserving existing functionality, and task-relevant test coverage are critical to the fix.
- Trace symptoms to the responsible mechanism before making changes
- Modify only the narrowest layer that owns the incorrect behavior
- Preserve unrelated behavior and existing user changes
- Avoid cleanup, renaming, and abstraction outside the immediate fix
- Add only regression tests relevant to the specific task
- Run focused proof plus nearest affected gate to verify the fix
How to install surgical-patch
npx skills add https://github.com/juliusbrussee/caveman --skill surgical-patchHow to use surgical-patch
- 1.Reproduce the failure first if economical, or capture the strongest available evidence of the bug
- 2.Trace the symptom to identify the responsible mechanism or layer
- 3.Identify the narrowest layer of code that owns the incorrect behavior
- 4.Make the minimal change needed to fix that behavior
- 5.Verify that unrelated behavior and user changes are preserved
- 6.Add regression tests relevant to the specific task and fix
- 7.Run focused proof tests plus the nearest affected test gate
- 8.Stop when the failure is fixed and regression proof passes
Use cases
- Fixing a critical bug in production code where side effects must be minimized
- Patching a small behavior change in a core module while maintaining backward compatibility
- Addressing a regression in a complex system where the fix scope must be tightly controlled
- Debugging and fixing issues in legacy code where broader refactoring is not feasible
- Implementing targeted fixes in systems with extensive test suites that catch regressions
- Backend engineers working on production systems
- Developers maintaining legacy or complex codebases
- QA engineers verifying bug fixes don't introduce regressions
- Teams with strict change-control requirements
- Engineers working on safety-critical or high-reliability systems
surgical-patch FAQ
Use surgical patch when regression proof, preserved surrounding behavior, and task-relevant tests are critical. Use broader refactoring when the codebase needs structural improvement and you have time to validate extensively.
Capture the strongest available evidence of the bug—logs, stack traces, user reports, or behavioral descriptions—and proceed with fixing the responsible mechanism based on that evidence.
No. Avoid cleanup, renaming, and abstraction outside the immediate fix. Keep changes focused on the bug itself to minimize risk and keep the patch reviewable.
The narrowest responsible layer is the one that directly owns the incorrect behavior. Trace the symptom to its root cause, then change only that layer. Test that unrelated behavior is preserved.
Add only tests relevant to the specific task and bug fix. These should verify the failure is fixed and that the nearest affected functionality still works correctly.
Full instructions (SKILL.md)
Source of truth, from juliusbrussee/caveman.
name: surgical-patch description: Fix bugs and small behavior changes at the narrowest responsible layer. Use when regression proof, preserved surrounding behavior, and task-relevant tests matter.
Surgical patch
Reproduce failure first when economical; otherwise capture strongest available evidence.
- Trace symptom to responsible mechanism.
- Change narrowest layer that owns incorrect behavior.
- Preserve unrelated behavior and user changes.
- Avoid cleanup, renaming, and abstraction outside fix.
- Add only regression proof relevant to task.
Run focused proof plus nearest affected gate. Stop when failure is fixed and regression proof passes.
Related skills
More from juliusbrussee/caveman and the wider catalog.
verify-and-stop
Prove existing work meets acceptance conditions without expanding scope.
cavecrew
Three compressed-output subagents for code location, surgical edits, and diff review—save context tokens across delegations.
caveman
Ultra-compressed communication mode that cuts output tokens while keeping technical accuracy.
caveman-commit
Write terse, Conventional Commits messages focused on intent, not description.
context-canary
Install a per-turn canary signal to detect silent context degradation and trigger recovery when it fails.
fuck-slop
Strip AI writing fingerprints and rewrite text into its target register—academic, tweet, email, blog, anything.