Patch Design Skill
Create minimal, surgical patch plans for targeted fixes.
When to Use
- Fixing specific issues from review
- Creating focused bug fixes
- Addressing blockers without scope creep
- Making targeted improvements
Core Principle
"This is a PATCH - keep the scope minimal. Only fix what's described in the issue and nothing more."
Design Workflow
Step 1: Understand the Specific Issue
Parse the issue clearly:
- What is broken? (specific behavior)
- How should it work? (expected behavior)
- What evidence exists? (screenshots, errors)
Do NOT expand scope beyond the reported issue.
Step 2: Analyze Current State
Review the relevant code:
# Find relevant files
git diff --stat
grep -r "related_function" src/
# Read the specific code
cat src/component/file.tsStep 3: Determine Minimum Fix
Ask: "What is the smallest change that fixes this?"
| Approach | Lines | Risk |
|---|---|---|
| Surgical fix | 1-10 | Low |
| Targeted fix | 10-50 | Medium |
| Refactor | 50+ | High |
Always prefer surgical fixes for patches.
Step 4: Create Patch Plan
Document the precise fix:
# Patch: [Concise title]
## Issue Summary
**Problem**: [What's broken]
**Solution**: [Minimal fix]
## Files to Modify
- `path/to/file.ts`: [Specific change]
## Implementation Steps
### Step 1: [Specific action]
[Exact code change]
### Step 2: [Specific action]
[Exact code change]
## Validation
- [Command to verify fix]
- [How to confirm success]
## Patch Scope
- Lines of code: ~X
- Risk level: low
- Testing: [minimal/standard]Step 5: Define Validation
Every patch needs verification:
## Validation
1. Run specific test: `npm test path/to/test`
2. Manual verification: [steps]
3. Visual check: [if applicable]Patch Plan Template
# Patch: [Brief description]
## Metadata
- Issue: [Source of this patch request]
- Severity: [blocker/tech_debt]
## Issue Summary
**Original Spec**: [Link if available]
**Problem**: [Brief description of what's wrong]
**Solution**: [Brief description of the fix]
## Files to Modify
[Only files that need changes - be specific]
- `src/component/Button.tsx`: Fix disabled state
## Implementation Steps
IMPORTANT: Execute every step in order.
### Step 1: [Specific change]
<!-- markdownlint-disable MD033 -->
// Before <button onClick={handleClick}>
// After <button onClick={handleClick} disabled={isLoading}>
### Step 2: [Next change if needed]
[Details]
## Validation
Execute to confirm patch is complete:
- `npm test src/component/Button.test.tsx`
- Manual: Click button, verify disabled during load
## Patch Scope
- **Lines changed**: ~5
- **Risk level**: low
- **Testing**: Run component tests
## Anti-Patterns to Avoid
### Scope Creep
BAD: Expanding scope
While fixing the button, I noticed the form could use refactoring, so I'll also update the validation logic, improve the error messages, and add loading states to all other buttons too.
### Vague Changes
BAD: Vague plan
Implementation
- Fix the button issue
- Make it work correctly
- Test to confirm
### No Validation
BAD: No verification
Implementation
- Change the code
- Done
## Best Practices
1. **One issue, one patch**: Don't bundle fixes
2. **Minimal scope**: Only change what's needed
3. **Specific steps**: Exact code changes
4. **Clear validation**: How to verify success
5. **Risk assessment**: Lines changed, testing needed
## Integration with Review
Patches typically come from review issues:
/review → Identifies blocker ↓ /patch → Creates surgical fix plan ↓ /implement → Executes patch ↓ /review → Verifies fix (re-review)
## Memory References
- @issue-severity-classification.md - What triggers patches
- @review-vs-test.md - Review identifies patch needs
- @one-agent-one-purpose.md - Patches are focused by nature
## Version History
- **v1.0.0** (2025-12-26): Initial release
---
## Last Updated
**Date:** 2025-12-26 **Model:** claude-opus-4-5-20251101