Hotfix Dispatcher

Create an emergency hotfix branch from production with fast-track merge and tagging workflow.

When to Use This Command

Run this command when you need to:

• Fix a critical production bug immediately without waiting for the next release cycle
• Create a hotfix branch from the latest production tag on main
• Deploy a targeted patch that merges into both main and develop to keep branches synchronized

Consider alternatives when:

• The bug is low-severity and can wait for the next scheduled release branch
• You need to backport a fix to multiple older release versions simultaneously

Quick Start

Configuration

Copy
name: hotfix-dispatcher
type: command
category: git

Example Invocation

Copy
claude command:run hotfix-dispatcher --name "fix-payment-timeout" --severity critical

Example Output

Creating hotfix branch...
  Latest production tag: v3.8.2
  Base commit: f29c4a1 (tag: v3.8.2, origin/main)
  Branch: hotfix/fix-payment-timeout

Hotfix workspace ready:
  Branch: hotfix/fix-payment-timeout
  Tracking: origin/hotfix/fix-payment-timeout
  Suggested tag: v3.8.3

Next steps:
  1. Apply your fix on this branch
  2. Run: claude command:run power-finish
  3. Deploys to production via CI/CD pipeline

Core Concepts

Hotfix Lifecycle Overview

Aspect	Details
Origin	Branches from the latest tag on main representing current production
Naming	hotfix/descriptive-name following kebab-case convention
Scope	Minimal changes only: the fix itself plus any required test additions
Merge Targets	Merges into both main (for deployment) and develop (for continuity)
Tagging	Creates a patch-level semver tag on main after merge completes

Hotfix Workflow

main:    --*---[v3.8.2]---*---[v3.8.3]-->
               |         /
hotfix:        *---fix--*
               |         \
develop: --*---+-----------*--*--------->
           (hotfix merged to both targets)

Configuration

Parameter	Type	Default	Description
name	string	(required)	Descriptive name for the hotfix in kebab-case
severity	string	normal	Severity level: normal, high, critical for prioritization
base-tag	string	latest	Specific tag to branch from instead of the latest
auto-push	boolean	true	Push hotfix branch to origin immediately
notify	string	(none)	Slack channel or email to notify about the hotfix creation

Best Practices

1. Keep hotfixes minimal - A hotfix should contain only the code necessary to resolve the production issue. Resist the temptation to include nearby refactors or improvements that increase risk.

2. Write a regression test first - Before fixing the bug, write a test that reproduces it. This ensures the fix actually resolves the issue and prevents the same bug from recurring in the future.

3. Document the incident - Include the incident report or ticket number in the hotfix commit message so future developers understand why this emergency change was made outside normal flow.

4. Verify on staging first - Even though hotfixes are urgent, deploy to a staging environment that mirrors production before going live. A broken hotfix is worse than the original bug.

5. Communicate with your team - Use the notify parameter to alert your team about the hotfix. Others may be mid-release and need to incorporate the fix into their current work.

Common Issues

1. No tags found on main - If your project has never been tagged the command cannot determine the production baseline. Create an initial tag with git tag v1.0.0 on main first.

2. Develop has diverged significantly - When merging the hotfix into develop conflicts with recent changes, resolve conflicts carefully to ensure the fix is preserved without overwriting develop work.

3. CI pipeline not configured for hotfix branches - Ensure your CI configuration includes hotfix/* branch patterns so automated tests and deployments trigger for hotfix branches. Without this, hotfixes may bypass your automated quality gates entirely.

4. Hotfix branch accidentally based on develop - If you created the hotfix from develop instead of main, it may include unreleased features. Reset the branch to the correct production tag with git reset --hard v3.8.2 before applying your fix to ensure only the patch reaches production.