plugin-improve Skill

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

Integration with deep-research:

<handoff_protocol> Trigger: deep-research invokes plugin-improve via Skill tool Detection: Phase 0.45 scans conversation history for research findings (MANDATORY) Action: Extract research findings, skip investigation (Phase 0.5) Benefits: Preserve expensive research context (Opus + extended thinking) </handoff_protocol>

Detection mechanism is implemented in Phase 0.45 below. See references/handoff-protocols.md for additional workflow documentation.

Workflow Overview

Phase 0: Specificity Detection (assess request clarity) ↓ [Specific?] ─NO→ Present menu (brainstorm OR investigate) ↓ YES Phase 0.3: Clarification Questions (4 targeted questions) ↓ Phase 0.4: Decision Gate (confirm understanding) ↓ Phase 0.45: Research Detection (MANDATORY - scan conversation history) ↓ [Research found?] ─YES→ Skip to Phase 0.9 ↓ NO Phase 0.5: Investigation (Tier 1/2/3 auto-detected) ↓ Phase 0.9: Backup Verification (CRITICAL GATE - must pass to proceed) ↓ Phase 1: Pre-Implementation Checks (version, state, commits) ↓ Phase 2: Verify Rollback Path (confirm backup ready) ↓ Phase 3: Implementation (make changes) ↓ Phase 4: CHANGELOG Update (document changes) ↓ Phase 5: Build and Test (delegate to build-automation) ↓ Phase 5.5: Regression Testing (conditional: if plugin-testing + baseline exist) ↓ Phase 6: Git Workflow (stage changes, prepare commit) ↓ Phase 7: Installation (optional, delegate to plugin-lifecycle) ↓ Phase 8: Completion (decision menu)

Key:

• MANDATORY: Always executes (Phase 0.45)

• CRITICAL GATE: Blocks workflow if fails (Phase 0.9)

• CONDITIONAL: Only if conditions met (Phase 5.5, Phase 7)

Progress Checklist

Copy this checklist and check off phases as you complete them:

Improvement Progress:

• Phase 0: Assessed request specificity
• Phase 0.3: Asked clarification questions (if needed)
• Phase 0.4: Confirmed understanding with user
• Phase 0.45: ✓ MANDATORY - Scanned conversation history for research
• Phase 0.5: Investigated root cause (if no handoff)
• Phase 0.9: ✓ CRITICAL - Backup verified (blocks if fails)
• Phase 1: Loaded current state, determined version bump
• Phase 2: Confirmed rollback path ready
• Phase 3: Implemented changes
• Phase 4: Updated CHANGELOG
• Phase 5: Built and tested (delegated to build-automation)
• Phase 5.5: Ran regression tests (if available)
• Phase 6: Staged git changes
• Phase 7: Installed plugin (if requested)
• Phase 8: Presented completion menu

<gate_preconditions enforcement="strict">

Precondition Checking

MUST execute before any other phase. BLOCK if conditions not met.

Before starting, verify:

• Read PLUGINS.md:

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

• Check status:

• If status = ✅ Working or 📦 Installed → OK to proceed

• If status = 🚧 In Development → BLOCK with message: [PluginName] is still in development (Stage [N]). Complete the workflow first with /continue [PluginName]. Cannot use /improve on in-progress plugins.

Note: The workflow now has 3 stages with automatic validation. Stage 1-3 complete = plugin ready for improvement.

• If status = 💡 Ideated → BLOCK with message: [PluginName] is not implemented yet (Status: 💡 Ideated). Use /implement [PluginName] to build it first.

• If not found → BLOCK with message: Plugin [PluginName] not found in PLUGINS.md.

</gate_preconditions>

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.2: Headless Plugin Detection (GUI-Optional Flow)

Purpose: Detect headless plugins and offer "Create custom UI" option before proceeding to normal improvement flow.

Workflow:

• Read .continue-here.md and check gui_type field

• If gui_type: headless OR WebView UI files don't exist → Plugin is headless

• If headless, present 4-option menu: Create UI, Keep headless, Explain headless, Other

• If "Create UI" selected → Invoke ui-mockup skill, then gui-agent subagent

• Update version to v1.1.0 (MINOR bump - new feature)

• Update state files and commit changes

See: references/headless-ui-workflow.md for complete detection logic, menu flows, gui-agent invocation, state updates, and completion protocol.

If NOT headless: Skip to Phase 0.3 (normal flow)

Phase 0.3: Clarification Questions (If Specific)

See: references/clarification-protocol.md for 4 targeted questions (what to change, scope, version bump, testing approach). 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

Phase 0.45: Research Detection

MANDATORY: Scan conversation history for deep-research findings to avoid duplicate investigation.

See: references/research-detection.md for complete detection algorithm, extraction logic, and decision trees.

Decision: If research detected → Skip to Phase 0.9 | If not detected → Continue to Phase 0.5

Phase 0.5: Investigation (Auto-Tiered)

Purpose: Find root causes, prevent band-aid fixes

Workflow:

• Analyze request and auto-detect tier (1/2/3) - never ask user which tier

• Execute tier-appropriate investigation protocol

• For Tier 3 (complex issues), delegate to deep-research skill

• Present findings and wait for approval before implementing

See: references/investigation-tiers.md for complete tier detection algorithm and protocols for each tier (1: Basic Code Inspection, 2: Root Cause Analysis, 3: Deep Research Delegation).

<critical_sequence phase="backup-verification" enforcement="strict">

Phase 0.9: Backup Verification

CRITICAL INVARIANT: Phase 1 MUST NOT execute until backup verified. ENFORCEMENT: Block execution, halt workflow if backup fails. VIOLATION CONSEQUENCE: Data loss, no rollback path.

Goal: Ensure rollback is possible if improvement fails

Process:

• Check if backup exists at backups/[PluginName]/v[CurrentVersion]/

• If missing, create backup using rsync (exclude build/ and build.log)

• Verify backup integrity: ./scripts/verify-backup.sh [PluginName] [CurrentVersion]

• If verification fails, HALT workflow with error message

• If verification succeeds, present confirmation and proceed

See: assets/backup-template.sh for complete backup creation script.

</critical_sequence>

DEPENDENCY: MUST NOT execute until Phase 0.9 (Backup Verification) completes.

Load current state (parallelize file reads):

Read these files in parallel using multiple Read tool calls:

• CHANGELOG.md - Extract current version (e.g., v1.2.3)

• PLUGINS.md - Get plugin entry for additional context

• Git log - Check recent commits: git log --oneline plugins/[PluginName]/ -10

Determine version bump:

Present choice:

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): _

If Major version selected, warn:

⚠️ 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): _

Calculate new version based on selection.

Breaking Change Detection

Check for breaking changes BEFORE confirming version bump:

Breaking if:

• ❌ Parameter ID renamed (automation breaks)

• ❌ Parameter range changed (saved values invalid)

• ❌ Parameter removed (automation breaks)

• ❌ Parameter type changed (e.g., float → choice)

• ❌ State format changed (old presets won't load)

• ❌ Feature removed (users lose functionality)

• ❌ Public API signature changed

If breaking changes detected: Force MAJOR version bump, warn user, require confirmation.

See: references/breaking-changes.md for detailed detection criteria and edge cases.

<critical_sequence phase="backup-creation" enforcement="strict">

Phase 2: Verify Rollback Path

Baseline backup verified in Phase 0.9. Confirm ready to proceed:

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

</critical_sequence>

DEPENDENCY: MUST NOT execute until Phase 2 (Backup Creation) completes. SAFETY: If implementation fails, rollback path guaranteed by Phase 2 backup.

Execute the change:

• Modify source files according to investigation findings

• Update build configuration if needed (CMakeLists.txt)

• Adjust UI if required (PluginEditor.cpp)

• Update parameter definitions if needed (PluginProcessor.cpp)

Follow best practices:

• Real-time safety in processBlock

• No allocations in audio thread

• Thread-safe parameter access

• JUCE API correctness

Log changes as you go for CHANGELOG.

Phase 4: CHANGELOG Update

Add version entry at top of CHANGELOG.md with technical details:

Required fields:

• Date in ISO format (YYYY-MM-DD)

• Root cause for fixes (from Phase 0.5 investigation)

• Testing notes (regression test results if Phase 5.5 ran)

Sections by version type:

• PATCH (0.0.X): Use "Fixed" section primarily

• MINOR (0.X.0): Use "Added" and/or "Changed" sections

• MAJOR (X.0.0): Include "Breaking Changes" and "Migration Notes"

See: references/changelog-format.md for complete template structure, section usage guide, and examples by version type (PATCH/MINOR/MAJOR).

<delegation_rule target="build-automation" required="true">

Phase 5: Build and Test

DELEGATION: MUST invoke build-automation skill for all build operations. REASON: Centralized build logic, 7-phase pipeline with verification.

1. Build: Invoke build-automation skill - handles full build pipeline, installation, cache clearing, and failure protocol.

2. Test: After build succeeds, invoke plugin-testing skill - present 4-option menu (automated tests, pluginval, manual DAW testing, skip).

</delegation_rule>

<validation_gate gate="regression-tests" required="conditional">

Phase 5.5: Regression Testing

GATE CONDITION: Conditional - only runs if both conditions met GATE FAILURE: Present rollback options, require user decision

Conditions required:

• plugin-testing skill exists

• Baseline backup exists at backups/[Plugin]/v[baseline]/

If conditions not met: Skip regression tests, warn user, add note to CHANGELOG, continue to Phase 6.

If conditions met:

• Build baseline version from backup

• Run plugin-testing on baseline (capture results)

• Run plugin-testing on current version (capture results)

• Compare results and present findings with decision menu

See: references/regression-testing.md for complete RegressionReport interface, comparison logic, and rollback decision trees.

</validation_gate>

Phase 6: Git Workflow

Stage changes: git add plugins/[PluginName]/ backups/[PluginName]-v[X.Y.Z]-[timestamp]/

Commit format: improve: [PluginName] v[X.Y.Z] - [description]

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

Note: Display git commands for user to run manually. Do not execute git commit or git push.

<delegation_rule target="plugin-lifecycle" required="false">

Phase 7: Installation (Optional)

If user requested installation: Invoke plugin-lifecycle skill, then update PLUGINS.md and NOTES.md (version, status, timeline entry).

</delegation_rule>

<checkpoint_protocol>

Phase 8: Completion

Present numbered decision menu (inline format, NOT AskUserQuestion tool):

Options: Test in DAW, Make another improvement, Create new plugin, Document this change, Other

</checkpoint_protocol>

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 (table row: version, last updated, status)

• plugins/[Name]/NOTES.md (status, version, timeline entries, known issues)

• 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 table row updated (version, status, last updated)

• NOTES.md updated (status, version, timeline entry)

• User knows how to rollback if needed