hotfix

Hotfix — emergency fix workflow

Apply a minimal, targeted fix fast. No brainstorm document, no plan document — but tests and review are still non-negotiable.

Bug Description

<bug_description>$ARGUMENTS</bug_description>

If the bug description above is empty, ask the user: "What's the bug? Paste a description, issue link, or error message."

DO NOT proceed until you have a bug description.

Phase 0 — Triage

Summarize the bug in one sentence. Identify:

• Symptom: what the user sees or what is broken
• Suspected area: which layer or component is likely involved (based on the description alone — do not read code yet)

Phase 1 — Locate

Run a focused codebase exploration to find the problem area:

• Task @codebase-review-agent("Locate the code responsible for this bug. Focus narrowly on the symptom described — do not survey the entire codebase. Bug: <bug_description>")

After the agent returns:

1. Read the identified files and their immediate neighbors to understand the context.
2. Identify the root cause (or the most likely candidate).
3. Summarize the root cause to the user in 2-3 sentences.

If the root cause is unclear after exploration, use AskUserQuestion to ask the user for additional context before proceeding.

Phase 2 — Branch

Set up a hotfix branch. Unlike normal feature branches, hotfix branches use the hotfix/ prefix.

Run:

git rev-parse --abbrev-ref HEAD

If already on a hotfix/ branch: skip silently.

Otherwise: infer a branch name in the format hotfix/<kebab-slug> where the slug is derived from the bug description (max 60 characters total). Use AskUserQuestion to confirm:

1. Create branch (Recommended) — git checkout -b hotfix/<slug>
2. Skip — stay on the current branch

Phase 3 — Fix

Blast Radius Check

Before writing any code, outline which files and layers the fix touches.

If >5 files, multiple layers, or new abstractions needed: warn the user and use AskUserQuestion: (1) Proceed with hotfix, (2) Switch to /plan.

If contained (≤5 files, single layer): proceed directly.

Step 1: Implement

Write the minimal change that addresses the root cause. Change only what is necessary — no drive-by refactors. If you touch unrelated code, stop and flag scope creep. Leave // TODO(hotfix): <description> comments for out-of-scope issues. Match surrounding code style.

Step 2: Test

Tests are non-negotiable, even for hotfixes:

• Add or update tests that reproduce the bug (the test should fail without the fix).
• Cover the fix path and any closely related edge cases.
• Do not write tests for unrelated code.

Step 3: Validate

Follow the validation and fix procedure.

Execution Rules

• Never skip tests. Every fix gets a regression test.
• Never add features not related to the bug (YAGNI).
• If the fix grows beyond the original scope, stop and flag it.
• Acceptable tradeoffs: a hotfix may intentionally introduce a lesser issue (e.g., fixing a P0 while accepting a P2 side effect). When this happens, document the tradeoff clearly with a // TODO(hotfix): <description of known limitation and its severity> comment in the code and note it in the PR description. The goal is to stop the bleeding, not achieve perfection.
• Ask the user only when genuinely stuck: ambiguous root cause, 3 failed fix attempts, or a missing dependency.

Phase 4 — Review

Run review agents in parallel to validate the fix. Use a reduced set — speed matters, but quality is non-negotiable.

Agent instructions

Each agent prompt must include the review agent instructions with REPORT_DIR set to docs/hotfix-review/.

The 2 agents and their report filenames:

Agent	Report file
@vgv-review-agent	docs/hotfix-review/vgv-review.md
@test-quality-review-agent	docs/hotfix-review/test-quality-review.md

After reviews complete

Follow the review consolidation procedure: fix critical issues, present important issues to the user, and record suggestions.

Cleanup

Remove review reports after findings are addressed:

rm -rf docs/hotfix-review/

Phase 5 — Ship

Final Validation

Run the project's formatter, linter, and test runner one last time. Fix any failures before proceeding.

Ship

Create a single, cherry-pick-friendly commit. Stage only fix-related files (no unrelated changes). Use this commit format:

fix: <concise description of what was fixed>

<Root cause explanation in 1-2 sentences>

Bug: <original bug description or issue link, truncated if long>

Push the branch and create a PR. Title: fix: <concise description> (under 70 chars). Body: Use the PR template.

Post-Ship

Use AskUserQuestion to present options:

1. Done: end the session

Gotchas

• If the bug is in a shared dependency or utility, the fix may affect callers you did not expect. Grep for all usages before changing shared code.
• If the fix requires a migration (database, config, schema), this is likely too large for a hotfix. Recommend switching to /plan → /build.
• Hotfix branches use the hotfix/ prefix, not fix/. Other skills use fix/ — do not mix them.
• If docs/hotfix-review/ already exists from a previous interrupted hotfix, delete it before running Phase 4 to avoid stale reports contaminating the review.
• The blast radius check (Phase 3) uses a threshold of 5 files. A fix that touches exactly 5 files is within threshold; 6 triggers the warning.

Important

• This skill is for emergency fixes. It trades planning depth for speed, but never trades away quality.
• No brainstorm or plan documents are generated.
• Tests and review are non-negotiable — fast doesn't mean sloppy.
• Keep the diff minimal. A hotfix that grows into a feature rewrite belongs in /plan → /build.
• The commit must be cherry-pick-friendly: one commit, one concern, no unrelated changes.