# Wtf.hotfix

> This skill should be used when something is broken in production and needs an immediate fix that bypasses the normal Epic→Feature→Task planning flow — for example "production is down", "hotfix needed", "critical bug in prod", "emergency fix for

- Skill: `xiduzo/wtf-hotfix` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add xiduzo/wtf-hotfix`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xiduzo/wtf-hotfix/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: xiduzo (https://skillmd.com/u/xiduzo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xiduzo/wtf-hotfix

---


# Hotfix

Emergency fix path that skips the normal Epic→Feature→Task hierarchy.

This skill moves a narrow, well-understood fix into production as fast as possible.
It still keeps a test, a commit trail, and a PR review.

## When to use vs. when not to use

**Use when:** something is broken in production, the fix is narrow and well-understood, and waiting for the full workflow is not acceptable.

**Do not use when:** the fix is large, the scope is unclear, or the change needs design review — use `wtf.write-epic` + `wtf.write-task` instead.

## Process

### 0. GitHub CLI setup

Run steps 1–2 of `../references/gh-setup.md`.
Stop if `gh` is not installed or not authenticated.

### 1. Identify the bug

If a bug issue number was passed in, fetch it:

```bash
gh issue view <bug_number>
```

If no issue exists yet, ask in a single message:

- "What is broken? (one sentence)"
- "What is the user impact? (e.g. data loss, revenue impact, all users blocked, subset of users)"
- "Is there an existing bug issue, or should I create one?"

If no issue exists, follow the **Fast path** section of `wtf.report-bug`.
Skip Gherkin derivation and Ubiquitous Language mapping.
The goal is to file the issue fast.

### 2. Confirm hotfix scope

A hotfix must be:
- **Narrow**: changes the minimum files necessary to fix the specific breakage
- **Non-breaking**: no API contract changes, no schema migrations unless strictly required
- **Testable**: at least one automated test can verify the fix

Call `AskUserQuestion` (per `../references/questioning-style.md`):
- question: "Does this fix meet the hotfix criteria? (narrow, non-breaking, testable)"
- header: "Scope check"
- options:
  - **Yes — proceed** → create the hotfix branch and start the fix
  - **Not sure — it may be larger than that** → use the normal workflow instead

If "Not sure" → exit.
Suggest `wtf.write-task` as the next step.

### 3. Load the technical steering document

Load `docs/steering/TECH.md` per the **best-effort consumer-side load** in `../references/steering-doc-process.md`.
If present, apply its stack constraints, coding patterns, and test commands silently throughout this session.

### 4. Set up the hotfix branch

Set up the hotfix branch per `../references/branch-setup.md` ("Hotfix branch — direct from main" section).
Print the branch name.

### 5. Explore the codebase

Use the Agent tool to find:

- The specific file(s) responsible for the breakage
- Existing tests covering the broken behavior (or noting their absence)
- Contracts or interfaces the fix must preserve without changing

Do not expand scope from what you find.
If the fix turns out larger than expected, report it as a gate in step 6.

### 6. Scope gate

If exploration shows the fix changes more than 3–4 files, report it before writing any code.
Also report it if the fix requires an API contract change or a schema migration:

Call `AskUserQuestion` (per `../references/questioning-style.md`):
- question: "This fix is larger than a typical hotfix — [describe what was found]. How do you want to proceed?"
- header: "Scope gate"
- options:
  - **Proceed as hotfix** → accept the larger scope. The user understands the risk.
  - **Switch to normal flow** → exit and use `write-epic` + `write-task` instead

### 7. Implement the fix

Write the failing test first (one test per broken behavior).
Then implement the minimum fix to make it pass.
Follow the TDD cycle from `wtf.implement-task` step 8.

Run the full test suite after the fix:

```bash
# Run project test command (from TECH.md or package.json scripts)
```

If unrelated tests fail: do not block — record them in the PR body as pre-existing failures.

Commit per `../references/commit-conventions.md`.
The commit message uses a `Bug:` trailer.
The `Closes #<n>` keyword lives in the PR body, not the commit:

```bash
git add <changed files>
git commit -m "fix(<scope>): <description>

Bug: #<bug_number>"
```

### 8. Open the PR

Apply strict STE per `../references/ste-writing.md` before writing any durable body (PR body and commit subject/body prose).

Write the body to a temp file (`$BODY`) with the Write tool.
Then create the PR targeting `main` via the gh body helper (`../references/gh-body-helper.md`):

```bash
# Ensure the hotfix label exists
gh label create hotfix --color e11d48 --description "Emergency fix targeting main directly" 2>/dev/null || true

# $BODY is the temp file you wrote the PR body to with the Write tool.
python3 .wtf/gh-body.py create --pr \
  --title "fix(<scope>): <description>" \
  --body-file "$BODY" \
  --base main \
  --label "hotfix"
```

PR body must include:

- **Related**: closure keywords per `../references/commit-conventions.md` — one `Closes #<n>` per line, always include `Closes #<bug_number>`.
- **Impact**: what was broken and who was affected.
- **Root cause**: what caused it.
- **Fix**: what was changed and why it is safe.
- **Risk**: what could be affected by this change.
- **Pre-existing failures** (if any): unrelated tests that were already failing before this change.

Print the PR URL.

### 9. Offer backport

If the project uses release branches, offer to backport:

Call `AskUserQuestion` (per `../references/questioning-style.md`):
- question: "Should this fix be backported to a release branch?"
- header: "Backport"
- options:
  - Candidates from `git branch -r | grep -iE 'release|v[0-9]'` (limit 5)
  - **No backport needed** — main only

If a backport branch is selected — wait until the hotfix PR merges, then:

```bash
git checkout <release-branch>
git pull --rebase origin <release-branch>
git cherry-pick <hotfix-commit-sha>
git push origin <release-branch>
```

### 10. Report status

Print:

```
Hotfix
──────────────────────────────────
Branch:   hotfix/<slug>
PR:       <url>
Closes:   #<bug_number>
Target:   main
Backport: <branch> or —
```