Files

T

bastien a117e7ed67 fix(effort): shifts are sent with the step's first tool call (harness pairing rule); challenge shifts under their heading; fence indentation

2026-09-28 19:55:47 +02:00

14 KiB

Raw Blame History

name, effort, description, argument-hint, allowed-tools

name

effort

description

argument-hint

allowed-tools

hotfix

high

Quick fix for superficial bugs: typos, CSS issues, config errors, off-by-one, wrong variable name, missing import, broken link. Use when the root cause is obvious and the fix is 1-2 files max. Trigger: "hotfix", "quick fix", "typo", "fix this small thing", "c'est juste un petit bug", "patch rapide". Do NOT use for bugs requiring investigation — use /bugfix instead.

Read

Edit

Write

Bash

Grep

Glob

Agent

/hotfix — quick-fix orchestrator (reflection inline, execution dispatched)

MODEL GATE (blocking): run $HOME/.claude/lib/model-gate.md BEFORE any step below. Verdict small → STOP — print the gate's remedy, end the turn, dispatch nothing. EFFORT SHIFTS: follow $HOME/.claude/lib/effort-shift.md (BDR-NEXT): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.

REQUEST

$ARGUMENTS

STEP 1 — LOCATE (reflection)

Find the bug. Use the description and any error message to go straight to the source:

git status
git log --oneline -3

Read the relevant file(s). Confirm the root cause is obvious and superficial (typo, wrong value, missing import, etc.).
If the bug turns out to be deeper than expected (unclear cause, multiple files involved, logic error): STOP and say: "This looks deeper than a hotfix — it needs investigation. Re-run this as /bugfix (root-cause investigation, then a scoped fix)."
Settle the proposed fix HERE — the executor cannot ask questions, so the exact edit (what changes, in which file(s)) must be closed before dispatch.
Then run pass B of $HOME/.claude/lib/contract-interview.md against that edit: a VISIBLE / PUBLIC NAME / SCOPE choice the bug description leaves open (which way the icon aligns, the label's wording) → ask before dispatch. A typo or a wrong value asks nothing.

OPTIONAL — memory check (exempt by default; hotfix = obvious fix, mirror of its capitalize skip). For a RECURRING or urgent bug only, a quick blockers-only glance may save time:

  [ -d .claude/memory ] && grep -nE '^## BLK-' .claude/memory/blockers.md   # "déjà vu ?"

If a prior BLK names this bug, jump to its solution. Not mandatory; no RELATED MEMORY disposition required at hotfix weight.

STEP 1.5 — DESIGN GATE

Follow $HOME/.claude/lib/design-gate.md:

Scan $ARGUMENTS and target files for design/UI/style signals (CSS, component, styling, animation).
Signals found → a hotfix is the trivial tier by definition (≤2 files, one cosmetic value — design-gate.md §1): skip the gate, no toolchain. If the signals reveal real UI work (new component, layout, motion), this is not a hotfix → route to /feat or /bugfix instead of running design-tool-gate.sh.
If no signals → skip (zero overhead).

STEP 1.7 — CONTRACT (silent autofill)

Run $HOME/.claude/lib/contract-interview.md at hotfix weight: pass A is a silent autofill (a hotfix is an obvious fix by definition); pass B already ran at STEP 1, ask nothing more here. Autofill the contract — REQUEST verbatim = the bug description as given; ACCEPTANCE CRITERIA = "symptom gone; build/tests green"; FILE SCOPE = the 1-2 target files from STEP 1. It writes .claude/tasks/contracts/<date>-<slug>-<HHMM>.md. This is the reference the executor reads first, and the scope for STEP 4's security gate and the escalation report if a gate fails. No verifier is dispatched at hotfix weight — STEP 4's smoke result already verifies these trivial criteria; the gate hotfix adds is security (STEP 4).

STEP 1.8 — CHALLENGE THE FIX (logic fixes only)

GUARD — this is the one place the plan-challenge phase is kept proportionate to hotfix's speed. SKIP entirely for a purely cosmetic fix (CSS value, copy/typo, a broken link): there is nothing for three lenses to bite on, and speed is the point. Run it ONLY when the settled fix touches control flow or behaviour — an off-by-one, a wrong operator/variable, a behaviour-changing config value, or a missing import that alters execution. In doubt → it is probably a /bugfix.

Skill(effort-high) first (effort-shift: reflection resumes; send it in the same message as the challenger dispatch). For a logic fix: persist the STEP 1 located fix (root cause + the exact edit) to .claude/tasks/plans/<date>-<slug>-<HHMM>.md, then run $HOME/.claude/lib/challenge-plan.md with PLAN = that file, KIND = build-plan, SCOPE = the 1-2 target files, CONSTRAINTS = the STEP 1.7 contract's acceptance criteria. Three blind challengers attack the fix; the main loop RE-THINKS any aspect a BLOCKER lands (a named change to the fix, or [deferred]) and re-challenges once if it materially changed. Print a CHALLENGE SUMMARY (BLOCKERs addressed / deferred / lenses returned). A BLOCKER that shows the fix is wrong or incomplete means this was never a hotfix — escalate to /bugfix (its STEP 3b runs the same phase under the full verify+secure loop).

STEP 2 — PRE-FLIGHT

Gitflow aiguillage (before dispatch): follow $HOME/.claude/lib/gitflow-aiguillage.md — your type follows the base: on main → hotfix (prod incident; finish fans out to main + develop); on develop → bugfix (the fix forks from develop — a hotfix/* off main would miss develop's code and later merge to prod). Either protected base branches first; on a working branch it's a no-op (commit in place). The /hotfix size rules and the hotfixer executor are unchanged either way. Never finish.

Snapshot current state so revert is possible:

git diff HEAD --stat   # confirm working tree is clean OR carries only the
                       # in-progress hotfix area; if unrelated dirty files are
                       # present, ask user whether to stash them first
# Snapshot the TREE STATE (incl. tolerated uncommitted edits) without touching it.
# A bare SHA is not enough: restoring to HEAD would wipe the user's own
# in-progress edits in the hotfix area.
PRE=$(git stash create "hotfix-preflight"); [ -n "$PRE" ] || PRE=$(git rev-parse HEAD)
echo "PRE=$PRE"       # the revert source for every failure branch below

If the working tree contains unrelated uncommitted changes the user has not mentioned: STOP and ask "working tree dirty: stash and continue, or abort?".

STEP 3 — DISPATCH EXECUTOR

Dispatch the executor — sonnet by frontmatter pin, do not override:

Skill(effort-medium)   # effort-shift: dispatch span starts; send with the Agent call below in ONE message
Agent(subagent_type="hotfixer")
prompt: "CONTRACT: <path from STEP 1.7>
LOCATED: <file(s) found in STEP 1 + the confirmed root cause>
FIX: <the proposed minimal fix, closed in STEP 1>
BRANCH: <current branch — verify with git branch --show-current, never switch>
Apply the minimal fix. No refactoring, no commit, no branch ops, no
security dispatch, no revert. Finish with the HOTFIX-EXEC REPORT."

Parse the HOTFIX-EXEC REPORT:

STATUS : DONE → STEP 4 (the SMOKE line in the report decides pass/fail there; DONE here means execution completed, not that it verified clean).
STATUS : BLOCKED with CLASS: visible | public-name | scope in NOTES → the executor halted at an open choice before editing (nothing to revert): ask the user per MID-RUN CLARIFICATION in $HOME/.claude/lib/contract-interview.md, append the answer to the contract [gated], re-dispatch ONCE with the closed choice. This is the one re-dispatch hotfix allows; it is not a retry of a failed attempt.
STATUS : BLOCKED otherwise → if any edits were made, revert ONLY the executor's files: git restore --source=$PRE -- <FILE(S) from the report> and delete any NEW file the report lists (untracked, absent from $PRE). Never git restore . — it would wipe the tolerated pre-existing edits too. Surface the blocker to the user; STOP. One attempt only — hotfix never re-dispatches (escalate to /bugfix for deeper work).

STEP 4 — VERIFY + SECURE + COMMIT (main loop, LRN-083)

Read the SMOKE line from the executor's report. Failure branch — if it reports a failing test/build result:
- Print the failure output verbatim (under 30 lines).
- Revert ONLY the executor's files: git restore --source=$PRE -- <FILE(S) from the report> + delete report-listed NEW files. Never git restore . (wipes tolerated pre-existing edits).
- STOP and tell user: "Hotfix introduced a regression. Reverted. Escalate to /bugfix or /analyze for deeper investigation."
- Do NOT commit a broken fix.
Security gate (fresh auditor) — failure REVERTS, never loops. Dispatch a FRESH security-auditor (subagent_type: security-auditor — always a fresh dispatch, never inline-load: the repo convention and the FRESH requirement both forbid it) with MODE: gate, SCOPE: the working-tree diff vs $PRE. Parse its SECURITY — VERDICT: line:
- PASS (or DEGRADED with no BLOCK) → proceed to commit.
- BLOCK(n) → this is hotfix: do NOT loop. Revert ONLY the executor's files (git restore --source=$PRE -- <FILE(S)> + delete report-listed NEW files), print the BLOCKING list, and STOP: "Hotfix introduced a security finding. Reverted. Escalate to /bugfix for a fix under the full verify+security loop." The hotfix model is one attempt; any gate failure (smoke OR security) reverts and escalates.
- Structural failure (mute / unparsable / no VERDICT line) → treat as a failed gate: retry ONCE fresh; a 2nd structural failure → revert + escalate. A mute auditor is never a PASS.
Commit using conventional format (only after smoke AND security pass):
```
fix(<scope>): <what was wrong>
```

Print summary:

HOTFIX APPLIED
FILE(S) : <changed files>
FIX     : <one-line description>
VERIFIED: <test name or smoke check that passed>
SECURITY: <PASS | DEGRADED (checklist only)>

STEP 5 — DOC SYNC (automatic)

Dispatch the doc pipeline (BDR-077 — audit judgment on opus, patch on the sonnet pin, gate HERE):

Agent(subagent_type="doc-syncer", model="opus") — MODE: audit + auto-mode scope: <list of files modified during this session>.
Silence (NONE) → done. [MINOR] PATCH PLAN → re-dispatch Agent(subagent_type="doc-syncer") with MODE: patch + the plan verbatim (no gate — auto behavior preserved; a SHAPE ESCALATION in its report comes back here, gated as SIGNIFICANT).
SIGNIFICANT → gate here (Apply? yes / no / select), then MODE: patch with the approved subset.

Then commit the docs — follow $HOME/.claude/lib/doc-commit.md: it surgically commits ONLY the files doc-syncer patched (its PATCHED_FILES output), never git add -A, never .claude//CLAUDE.md (rc 4 = a loud BDR-022 anomaly, not a silent skip), and no-ops when nothing was patched — the common case for a trivial hotfix. No FINISH in an inline flow, so it just commits the docs on the current branch (no ordering concern).

STEP 6 — CAPITALIZE (memory registries, lightweight)

Hotfixes are often trivial (typo, config, import) — skip by default. But if the fix revealed something non-obvious:

Wrong default that should never have been merged → propose LRN-XXX in .claude/memory/learnings.md.
Bug that cost real time to locate despite being "superficial" → propose BLK-XXX in .claude/memory/blockers.md (status: resolved).

Default behaviour: CAPITALIZE: hotfix trivial, skip (no prompt, no output). Ask the user only when there is an actual candidate to propose.

Always append a 1-line entry to today's heading in .claude/memory/journal.md (even trivial hotfix — journal is timeline, not signal).

Language rule: the journal line and any proposed BLK/LRN entries are ALWAYS written English AND caveman — fragments, articles dropped, code/IDs/quoted errors verbatim — per CLAUDE.md "Memory registries" (Always English, always caveman).

Skill(effort-low) first (effort-shift: bookkeeping tail; send it in the same message as the memory-commit command).

Then commit the memory — follow $HOME/.claude/lib/capitalize-commit.md: it surgically commits what capitalize just wrote (.claude/memory + .claude/tasks only, never git add -A) as one chore(memory) commit, reports the memory-commit hash, and no-ops if nothing was written. The always-on journal line means a trivial hotfix still produces a chore(memory): journal — … commit (Frame 2 / F3).

RULES

Max 2 files changed. If more needed → /bugfix.
Reflection (LOCATE, contract, gate decisions) NEVER leaves this main loop; execution NEVER stays in it — the executor is the sonnet-pinned hotfixer subagent (BDR-066). A skill-mandated executor is exempt from the doctrine's "don't delegate few-tool-call work" rule (CLAUDE.md "Workflow" names that exception: skill-mandated dispatches run as written).
The executor is dispatched FRESH, once — hotfix never re-dispatches after a failed or blocked attempt (it reverts and escalates to /bugfix, it does not retry). Sole exception: a class-tagged BLOCKED answered by the user (STEP 3), re-dispatched once with the closed choice.
Design gate only if CSS/style signals detected. See STEP 1.5.
Revert-not-loop preserved: smoke FAIL or security BLOCK → file-scoped revert from $PRE (STEP 4's protocol — never git restore .) + STOP + escalate to /bugfix; hotfix never loops. No verifier is dispatched at hotfix weight.
If root cause is unclear → escalate to /bugfix (STEP 1).
If fix touches >5 lines of logic → reconsider if this is truly a hotfix.

14 KiB Raw Blame History