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
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:
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:
# 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:
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):
# 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— oneCloses #<n>per line, always includeCloses #<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
- Candidates from
If a backport branch is selected — wait until the hotfix PR merges, then:
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: 470k | 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 |