xiduzo/wtf / skills/wtf.hotfix
wtf.hotfix
VerifiedThis skill should be used when something is broken in production and needs an immediate fix that bypasses the normal Epic→Feature→Trace planning flow — for example "production is down", "hotfix needed", "critical bug in prod", "emergency fix for
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.5 KB |
| evals/evals.json | config | 4.4 KB |
| evals/fixtures/narrow-fix.json | config | 1.1 KB |
| evals/fixtures/pr-body-completeness.json | config | 1.1 KB |
| evals/fixtures/scope-gate-fires.json | config | 1.4 KB |
SKILL.md
View on GitHub---
name: wtf.hotfix
description: This skill should be used when something is broken in production and needs an immediate fix that bypasses the normal Epic→Feature→Trace planning flow — for example "production is down", "hotfix needed", "critical bug in prod", "emergency fix for #X", "patch this now", "security patch", or "this can't wait for the normal flow". Cuts a hotfix branch directly from main, implements a narrow fix with TDD, and opens a PR back to main. Not for large or unclear changes — use write-feature + feature-to-traces for those.
---
# Hotfix
Emergency fix path that skips the normal Epic→Feature→Trace 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 the normal Trace workflow (`wtf.write-feature` → `wtf.feature-to-traces`) 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 the normal Trace workflow as the next step: `wtf.write-feature`, then `wtf.feature-to-traces`.
### 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 the normal Trace workflow (`wtf.write-feature` → `wtf.feature-to-traces`) 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-trace` step 9.
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 —
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |