hotfix

Hotfix Workflow

Apply an urgent fix through a streamlined pipeline that skips the full planning cycle. This skill is for production bugs, security patches, and critical regressions.

Caution

This is NOT a shortcut for feature work. If the change adds new functionality, changes user-facing behavior, or touches more than ~100 lines, use /plan-feature instead. Hotfixes should be small, focused, and clearly scoped.

Caution

Scope boundary: This skill implements the fix, reviews it, creates a PR, and monitors CI. It covers the full lifecycle for urgent fixes so the user does not need to chain multiple skills.

Step 1: Define the Fix

CHECKPOINT: Confirm Hotfix Scope

Ask the user to describe the issue. Gather:

1. What is broken? (symptom, error message, affected users)
2. Where is the bug? (file, endpoint, component — if known)
3. How urgent? (production down, data corruption, security vulnerability, degraded experience)
4. GitHub issue number (if one exists)

If the user provides a GitHub issue number, fetch it:

gh issue view <number> --json title,body,labels,state,number

Present a summary and ask the user to confirm this is appropriate for hotfix (not a feature).

Step 2: Create Branch and Investigate

1. Ensure you are on main and up to date:

   git fetch origin
   git checkout main
   git pull origin main
   

2. Create a fix/ branch:

   git checkout -b fix/<short-description>
   

3. If a GitHub issue exists, add the in-progress label (following AGENTS.md label management rules — remove from any other issue first).

4. Investigate the bug: read relevant files, reproduce the issue if possible, identify the root cause.

Present the root cause analysis to the user before proceeding.

Step 3: Apply the Fix

1. Make the minimal change needed to resolve the issue.

2. Write or update tests to cover the bug (regression test).

3. Run self-checks:

   pnpm type-check
   pnpm lint
   pnpm test
   

4. Fix any failures from the checks above.

CHECKPOINT: Review the Fix

Present:

• Files changed (with a brief description of each change)
• Tests added or modified
• Test results (pass/fail, coverage)

Wait for user approval before committing.

Step 4: Commit

Commit with conventional commit format:

git add <specific-files>
git commit -m "fix(<scope>): <description>"

Step 5: Focused Review

Run a lightweight review (not the full Review Council):

1. Security scan (always): Invoke /security-scanning:security-sast on changed files.
2. Accessibility check (if frontend changes): Invoke /ui-design:accessibility-audit on modified components.

If the security scan finds Critical or High severity issues in the changed files, present them to the user. Fix any legitimate findings before proceeding.

Step 6: Deployment Council (Conditional)

Activate the Deployment Council only if the fix involves:

• Database migrations
• Docker or infrastructure changes
• Environment variable modifications
• Authentication or authorization code

If none of these apply, skip to Step 7.

If activated, run the Deployment Council evaluation from .claude/councils/deployment-council.md with all 3 members (Platform Engineer, Security Engineer, QA Lead).

CHECKPOINT: Deployment Readiness

Present the Deployment Council verdict. Wait for user approval.

Step 7: Create PR and Monitor CI

1. Run pre-push checks:

   pnpm type-check && pnpm lint && pnpm format:check && pnpm test
   

   Auto-fix formatting issues with pnpm format if format:check fails.

2. Push and create PR:

   git push -u origin fix/<short-description>
   

3. Generate PR description. Use the template from .github/PULL_REQUEST_TEMPLATE.md if it exists. Include:

   • Description of the bug and root cause
   • The fix applied
   • Tests added
   • Related issue number (if applicable)

CHECKPOINT: PR Description

Present the PR title and body. Wait for user approval.

4. Create the PR:

   gh pr create --title "<title>" --body "<body>"
   

5. Monitor CI:

   gh run list --branch fix/<short-description> --limit 1 --json databaseId --jq '.[0].databaseId'
   

   Then watch:

   gh run watch <run-id> --exit-status
   

6. If CI fails, diagnose and fix. Present the fix to the user before committing.

Step 8: Hand Off

Present the completed hotfix summary:

• PR URL
• Files changed
• Tests added
• CI status
• Related issue (if applicable)

You completed /hotfix. The PR is ready for merge. If there is a related GitHub issue, it will close automatically when the PR merges (if the PR body includes Closes #N).