plugin-improve Skill

Purpose: Make changes to completed plugins with versioning, backups, changelog automation, and root cause investigation.

Integration with deep-research:

See references/handoff-protocols.md for complete workflow and detection mechanism.

grep "^### $PLUGIN_NAME$" PLUGINS.md

Phase 0: Specificity Detection

Check if request is specific:

Request IS specific if it has:

• Feature name (e.g., "resonance parameter", "bypass switch")
• Action (e.g., "add", "remove", "fix", "change from X to Y")
• Acceptance criteria (e.g., "range 0-1", "increase to 500px", "reduce by 3dB")

Request IS vague if lacking above:

• "improve the filters"
• "better presets"
• "UI feels cramped"
• "make it sound warmer"

Assess specificity:

• Specific enough (1-2 clarification questions max): Proceed to Phase 0.3 (4-question clarification batch)
• Vague: Present inline decision menu:

Your request needs more detail. How should I proceed?

1. Brainstorm approaches together - I'll ask questions to explore options
2. Implement something reasonable - I'll investigate and propose a solution
3. Other

Choose (1-3): _

Handle responses:

• Option 1 → Invoke plugin-ideation skill in improvement mode
• Option 2 → Proceed to Phase 0.45 (Research Detection)
• Option 3 → Collect free-form text, reassess

Phase 0.3: Clarification Questions (If Specific)

If request is specific enough, ask targeted questions using inline menus:

Question 1 - What to change:

What needs to change?

1. Fix a bug - Something is broken or behaving incorrectly
2. Add a feature - New capability or enhancement
3. Improve existing behavior - Refine how something works
4. Other

Choose (1-4): _

Question 2 - Scope:

How extensive is this change?

1. Single function/method - Localized change in one place
2. Multiple related components - Changes across a few files
3. System-wide change - Affects architecture or many components
4. Other

Choose (1-4): _

Question 3 - Priority:

Version bump priority?

1. PATCH (bug fix) - Backward compatible fix, increment 0.0.X
2. MINOR (feature) - New feature, backward compatible, increment 0.X.0
3. MAJOR (breaking) - Breaking change, incompatible API, increment X.0.0
4. Other

Choose (1-4): _

Question 4 - Testing:

Should I run regression tests?

1. Yes, full regression suite - Compare new behavior vs baseline backup
2. Yes, but manual review if failures - Show me what changed and let me decide
3. No, skip regression tests - Just build and verify compilation
4. Other

Choose (1-4): _

Collect all responses before proceeding to Phase 0.4

Phase 0.4: Decision Gate

Show user what you understand, ask for confirmation:

I understand you want to:
- [Summary of change from Question 1]
- Scope: [Answer from Question 2]
- Version bump: [Answer from Question 3]
- Regression testing: [Answer from Question 4]

Is this correct?

1. Yes, proceed - Continue to Phase 0.45 (Research Detection)
2. No, refine - Ask me follow-up questions
3. No, cancel - Stop the workflow
4. Other

Choose (1-4): _

Handle responses:

• Option 1 → Proceed to Phase 0.45
• Option 2 → Return to Phase 0.3, ask follow-up questions
• Option 3 → Stop workflow, wait for new instruction
• Option 4 → Collect free-form text, reassess

✓ Research already completed (deep-research Level N)

**Problem:** [Extracted from research]
**Root Cause:** [Extracted from research]
**Recommended Solution:** [Extracted from research]
**Implementation Steps:** [Extracted from research]

Skipping Phase 0.5 investigation (research already done).

Ready to implement? (y/n): _

Phase 0.5: Investigation (3-Tier)

Purpose: Find root causes, prevent band-aid fixes

Tier Selection Decision Tree:

Request analysis:
├─ Known pattern match? → Tier 1
├─ Single component issue? → Tier 2
├─ Multi-component / Performance / Architecture? → Tier 3
└─ Unclear? → Start Tier 1, escalate if needed

Tier 1 (5-10 min): File read + pattern match

• Cosmetic changes, simple fixes, obvious issues
• Known patterns from troubleshooting/

Tier 2 (15-30 min): Logic trace + integration check

• Logic errors, parameter issues, integration bugs
• Single component, requires code analysis

Tier 3 (30-60 min): Invoke deep-research skill (uses Opus)

• Complex bugs, performance issues, architectural problems
• Multi-component, requires deep investigation

Tier 1: Basic Code Inspection

Read relevant source files:

• PluginProcessor.cpp/h
• PluginEditor.cpp/h
• Relevant JUCE modules

Check for:

• Obvious typos or errors
• Known pattern matches
• Simple logic issues

Tier 2: Root Cause Analysis

Deeper investigation:

• Trace logic flow from symptom to cause
• Check integration points between components
• Review parameter definitions and usage
• Examine state management
• Check threading issues (processBlock vs GUI)

Tier 3: Deep Research

Invoke deep-research skill for complex issues:

Complex issue detected. Invoking deep-research skill...

Use Skill tool to invoke deep-research:

• Provide problem context, plugin name, stage
• deep-research performs graduated investigation (Levels 1-3)
• Returns structured findings with recommendations
• Continue with Phase 0.5 "Present findings" using research output

Present findings:

## Investigation Findings

### Problem Analysis

[What's actually wrong and why it's happening]

### Root Cause

[Technical explanation of the underlying issue]

### Affected Files

- plugins/[Name]/Source/[File]:[Line]
- plugins/[Name]/Source/[File]:[Line]

### Recommended Approach

[How to fix it properly - not a workaround]

### Alternative Approaches

[Other valid options with trade-offs explained]

### Backward Compatibility

[Will this break existing presets/sessions?]

Proceed with recommended approach? (y/n): \_

Wait for approval before implementing.

If user says no, ask which alternative or if they want different approach.

BACKUP_PATH="backups/${PLUGIN_NAME}/v${CURRENT_VERSION}/"
if [[ ! -d "$BACKUP_PATH" ]]; then
  echo "⚠️ No backup found for v${CURRENT_VERSION}"
  CREATE_BACKUP=true
fi

# See assets/backup-template.sh for complete script
mkdir -p "backups/${PLUGIN_NAME}/v${CURRENT_VERSION}/"
rsync -a --exclude='build/' --exclude='build.log' \
  "plugins/${PLUGIN_NAME}/" "backups/${PLUGIN_NAME}/v${CURRENT_VERSION}/"

# Use verify-backup.sh script
./scripts/verify-backup.sh "${PLUGIN_NAME}" "${CURRENT_VERSION}"

✓ Backup verified: backups/[PluginName]/v[CurrentVersion]/

- All source files present
- CMakeLists.txt valid
- Dry-run build successful

Rollback available if needed.

cat plugins/[PluginName]/CHANGELOG.md

git log --oneline plugins/[PluginName]/ -10

Current version: v[X.Y.Z]

What type of change is this?
1. PATCH (v[X.Y.Z] → v[X.Y.Z+1]) - Bug fixes, cosmetic changes
2. MINOR (v[X.Y] → v[X.Y+1]) - New features, enhancements
3. MAJOR (v[X] → v[X+1]) - Breaking changes (presets won't load, parameters changed)

Choose (1-3): _

⚠️ Major version bump will break compatibility.

Breaking changes include:
- Changed parameter IDs (presets won't load)
- Removed parameters (sessions will have missing automation)
- Changed state format (existing sessions corrupted)

Are you sure? This should be rare. (y/n): _

✓ Backup verified: backups/[PluginName]/v[CurrentVersion]/
Ready to implement changes for v[NewVersion]

Phase 4: Enhanced CHANGELOG Update

Update CHANGELOG.md with enhanced format:

See references/changelog-format.md for complete template structure and section usage guide.

Quick reference:

• PATCH (0.0.X): Use "Fixed" section primarily
• MINOR (0.X.0): Use "Added"/"Changed" sections
• MAJOR (X.0.0): Include "Breaking Changes" and "Migration Notes" sections

Always include:

• Date in ISO format (YYYY-MM-DD)
• Technical details (root cause, solution, affected components)
• User impact (what changes in behavior)
• Testing notes (regression test results if available)

Invoking build-automation skill to build and install updated plugin...

Build successful. How would you like to test?

1. Automated stability tests (if Tests/ exists)
2. Build and run pluginval (recommended)
3. Manual DAW testing checklist
4. Skip testing (not recommended)

Choose (1-4): _

# Temporarily checkout baseline
cd backups/[Plugin]/v[baseline]/
../../scripts/build-and-install.sh --no-install

Phase 6: Git Workflow

Stage changes:

git add plugins/[PluginName]/
git add backups/[PluginName]-v[X.Y.Z]-[timestamp]/  # Include backup in git

Commit with conventional format:

# Format: improve: [PluginName] v[X.Y.Z] - [brief description]
# Example: improve: MicroGlitch v1.3.0 - add preset system

git commit -m "improve: [PluginName] v[X.Y.Z] - [description]"

Tag release:

git tag -a "v[X.Y.Z]" -m "[PluginName] v[X.Y.Z]"

Note: User handles actual git operations, we stage only.

Confirm git ready:

✓ Changes staged for commit
✓ Tag ready: v[X.Y.Z]

Git commit message:
  improve: [PluginName] v[X.Y.Z] - [description]

You can commit these changes when ready.

Installing [PluginName] v[X.Y.Z]...

**Version:** [X.Y.Z]
**Last Updated:** [YYYY-MM-DD]

✓ [PluginName] v[X.Y.Z] complete

What's next?
1. Test in DAW (recommended)
2. Make another improvement
3. Create new plugin
4. Document this change
5. Other

Choose (1-5): _

Breaking Change Detection

Check for breaking changes:

See references/breaking-changes.md for complete detection criteria.

Quick check:

• Parameter IDs changed? → Breaking
• Parameter ranges changed? → Breaking
• State format changed? → Breaking
• Features removed? → Breaking
• API signatures changed? → Breaking

If breaking changes detected, warn user and require MAJOR version bump.

Rollback Support

If anything goes wrong:

Provide rollback instructions:

To restore backup:

1. Remove modified version:
   rm -rf plugins/[PluginName]

2. Restore backup:
   cp -r backups/[PluginName]-v[X.Y.Z]-[timestamp] plugins/[PluginName]

3. Rebuild:
   cmake --build build

Backup location: backups/[PluginName]-v[X.Y.Z]-[timestamp]

Version Bump Logic

Determine version bump using decision tree:

See references/versioning.md for complete versioning logic.

Quick reference:

• Breaking change detected? → MAJOR (X.0.0)
• New feature added? → MINOR (0.X.0)
• Bug fix only? → PATCH (0.0.X)

If unsure, prefer MINOR over MAJOR (conservative approach).

Version History

Phase 7 enhancements (2025-11):

• Regression testing integration (Phase 5.5)
• Enhanced changelog format (Phase 4)
• Backup verification protocol (Phase 0.9)
• One-command rollback mechanism
• Breaking change detection

See: architecture/17-testing-strategy.md, scripts/verify-backup.sh, references/regression-testing.md

Integration Points

Invoked by:

• /improve command
• Natural language: "Fix [plugin]", "Add [feature] to [plugin]"
• plugin-ideation skill (after improvement brief)

Invokes:

• plugin-ideation skill (if vague request, user chooses brainstorm)
• deep-research skill (Tier 3 investigation) - Phase 7
• build-automation skill (building) - Phase 4
• plugin-testing skill (validation)
• plugin-lifecycle skill (installation)

Updates:

• CHANGELOG.md (adds version entry)
• PLUGINS.md (version number, last updated)
• Source files (implementation changes)

Creates:

• Backup in backups/[PluginName]-v[X.Y.Z]-[timestamp]/
• Git tag v[X.Y.Z]

Error Handling

Build failure: Present investigation menu, wait for user decision.

Test failure: Present investigation menu, don't proceed to installation.

Breaking change detected: Warn user, require confirmation, force MAJOR version.

Backup creation fails: STOP immediately, don't proceed with changes.

Git operations fail: Log warning, continue (non-critical).

Success Criteria

Improvement is successful when:

• Root cause investigated (not band-aid fix)
• Backup created before changes
• Changes implemented correctly
• CHANGELOG updated with version entry
• Build succeeds without errors
• Tests pass
• Git staged with conventional commit message
• PLUGINS.md updated
• User knows how to rollback if needed