cf:fix · diff
v1.0.0 to v2.0.0
127 added, 167 removed. Audit A to A.
---
name: hapo:hotfix
- description: "ALWAYS activate this skill when you are asked to FIX a bug, error, test failure, CI/CD issue, type error, lint error, log error, UI issue, or code problem. Uses hapo:debug for evidence-first diagnosis before any code change."
+ description: "Use when asked to FIX a bug, error, test failure, CI/CD issue, type error, lint error, log error, UI issue, or code problem. Uses hapo:debug for evidence-first diagnosis before any code change."
user-invocable: true
when_to_use: "Invoke to fix a bug or failure with scout-first diagnosis before change."
category: dev-tools
keywords: [hotfix, fix, bug, diagnosis]
argument-hint: "[issue] --quick|--parallel|--from-debug"
metadata:
author: haposoft
- version: "1.0.0"
+ version: "2.0.0"
---
- # Hotfix - Structured Bug Elimination
+ # Hotfix — root-cause fix workflow
- Kill bugs systematically. No guessing. Evidence first, fix second.
+ Fix the diagnosed root cause, prove the fix with fresh evidence, and leave no
+ side effects. Evidence first, fix second.
## Arguments
- `--quick` - Reduced-depth path for trivial issues (lint, type errors, syntax); still scout-first
- - `--parallel` - Spawn multiple `implementer` agents for independent issues
- - `--from-debug` - Start from an existing `hapo:debug` report and validate its root-cause contract
+ - `--parallel` - Fix independent issues concurrently, only through the Delegation Gate below
+ - `--from-debug` - Start from an existing `hapo:debug` report and validate its contract before accepting it
Default: deterministic scout-first hotfix. There is no initial mode selection step.
+ ## Proportional depth
+
+ Choose the smallest adequate depth from the diagnosed evidence. Depth vocabulary
+ follows `hapo:debug`:
+
+ - **Quick/local:** one deterministic syntax, lint, type, or isolated-test failure
+ with obvious local scope. Quick mode only reduces depth; it never skips scout, pre-fix evidence, diagnosis, or before/after verification.
+ - **Standard:** a diagnosed root cause inside one bounded area. Fix plus a
+ regression test that fails without the fix and passes with it.
+ - **Incident/deep:** production impact, multiple components, intermittent
+ behavior, data/security risk, or concurrency. Consume the full Incident/deep
+ debug handoff (timeline, elimination path, recurrence candidates), implement in
+ stages, and verify each stage.
+
+ Depth changes evidence breadth, never the gates: scout, diagnosis, before/after
+ proof, and the side-effect gate apply at every depth.
+
<HARD-GATE>
- Do NOT propose or implement fixes before completing Steps 1-2 (Scout + `hapo:debug` diagnosis).
- Symptom fixes are FAILURE. Find the root cause first.
- The exact root-cause contract is mandatory: symptom, reproduction, expected/actual, root cause file:line or config/env source, why now, evidence chain, blast radius.
- Answer each item in one concrete sentence.
- If any answer contains 'probably', 'I think', 'something with', or 'maybe' — it is not an answer; gather evidence instead.
- The side-effect gate is mandatory before completion.
- If 3+ fix attempts fail → STOP. Question the architecture. Discuss with user.
- Exception: `--quick` mode only abbreviates depth; it never skips scout, pre-fix evidence, diagnosis, or before/after verification.
+ Do not propose or implement a fix before Steps 1-2 (scout + diagnosis) complete.
+ A symptom patch without a diagnosed root cause is a failed fix.
+ The exact root-cause contract in Step 2 is mandatory; answer each field in one concrete sentence.
+ An answer containing 'probably', 'I think', 'something with', or 'maybe' is not an answer; gather evidence instead.
+ If 3+ fix attempts fail, stop, question the architecture, and discuss with the user.
</HARD-GATE>
<HARD-GATE-SCOUT-FIRST>
- Hotfix ALWAYS scouts before asking broad clarification questions, forming hypotheses, or changing files.
+ Hotfix always scouts before asking broad clarification questions, forming hypotheses, or changing files.
Collect these scout outputs first:
1. Project type, language(s), framework(s), and package/test runner from repo files.
2. Exact file(s) where the symptom surfaces and their direct callers/dependents.
3. Related tests covering the affected area.
4. Recent commits touching affected files: `git log --oneline -10 -- <affected-files>`.
5. Existing patterns/conventions for this kind of fix.
Then state a concise 3-6 bullet codebase-context summary before Step 2.
+ Do not ask generic questions before this step unless there is no repo, no error text, and no observable artifact to inspect.
</HARD-GATE-SCOUT-FIRST>
<HARD-GATE-NO-SIDE-EFFECTS>
The fix is not done until Step 5 proves:
1. The original symptom no longer reproduces with the exact pre-fix command/user flow.
2. Modified files and transitively affected modules still pass relevant tests.
3. Blast-radius workflows have no business-logic regression.
4. No new lint/type/build errors were introduced.
5. Public contracts are unchanged unless intentionally called out: function signatures, exported types, response shapes, DB schemas, env vars.
- If verification reveals a side effect or regression, STOP and present 2-4 concrete options to the user:
+ If verification reveals a side effect or regression, stop and present 2-4 concrete options to the user:
- Revert this fix and try a different root-cause angle
- Keep the fix and update <dependent files> to match the new contract
- Narrow the fix to <subset> so the regression disappears
- Accept the change — the old behavior was itself a bug
Do not silently patch around the regression.
</HARD-GATE-NO-SIDE-EFFECTS>
- ## Anti-Rationalization
+ ## Delegation Gate
- | Thought | Reality |
- |---------|---------|
- | "I can see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. Scout first. |
- | "Quick fix for now, investigate later" | "Later" never comes. Fix properly now. |
- | "Just try changing X" | Random fixes waste time and create new bugs. Diagnose first. |
- | "It's probably X" | "Probably" = guessing. Use structured diagnosis. |
- | "One more fix attempt" (after 2+) | 3+ failures = wrong approach. Question architecture. |
- | "Quick mode means skip process" | Quick mode only reduces depth. Scout, diagnosis, and before/after proof remain mandatory. |
+ Dispatch subagents (parallel scouts, hypothesis tests, deep research, or
+ `--parallel` fix trees) only when all three conditions hold:
+ - The user explicitly requested or permitted delegation or parallel agents.
+ - The active runtime exposes an Explore/delegation capability.
+ - The work splits into at least two distinct, non-overlapping scopes with useful independent work.
+
+ Otherwise continue sequentially in the main agent with focused local evidence.
+ Task-tracking tools are an optional visibility fallback, never a required step;
+ a concise markdown checklist is always sufficient.
+
## Process Flow
```mermaid
flowchart TD
A[Issue Input] --> B[Step 1: Scout via hapo:scout]
B --> C[Step 2: Diagnose via hapo:debug]
- C --> D[Step 3: Classify Complexity]
- D -->|Trivial| E[Quick Fix after scout+diagnose]
- D -->|Standard| F[Standard Fix]
- D -->|Complex| G[Deep Fix + Subagents]
- D -->|Multiple Issues| H[Parallel Fix]
- E --> I[Step 4: Implement Fix]
- F --> I
- G --> I
- H --> I
- I --> J[Step 5: Verify + Prevent]
- J --> N[Side-Effect Gate]
- N -->|Pass| K[Step 6: Finalize]
- N -->|Regression Risk| C
- J -->|Fail, <3 attempts| C
- J -->|Fail, 3+ attempts| L[Question Architecture → Discuss with User]
- K --> M[Report + Commit]
+ C --> D[Step 3: Select Depth]
+ D --> E[Step 4: Implement Fix]
+ E --> F[Step 5: Verify + Prevent]
+ F --> G[Side-Effect Gate]
+ G -->|Pass| H[Step 6: Finalize]
+ G -->|Regression risk| C
+ F -->|Fail, <3 attempts| C
+ F -->|Fail, 3+ attempts| I[Question architecture with user]
+ H --> J[Report]
```
- **This diagram is the authoritative workflow.** If prose conflicts with this flow, follow the diagram.
+ If prose conflicts with this flow, follow the diagram.
---
- ## Step 1: Scout (MANDATORY — never skip)
-
- **Purpose:** Understand the affected codebase BEFORE forming any hypotheses.
-
- **Action:** Activate `hapo:scout` skill to map the blast radius.
+ ## Step 1: Scout
- Do not ask generic questions before this step unless there is no repo, no error text, and no observable artifact to inspect.
+ Understand the affected codebase before forming any hypotheses. Activate
+ `hapo:scout` or perform an equivalent focused local scout (`rg` plus targeted
+ reads) to map the blast radius.
- | Path | Scout Depth |
+ | Path | Scout depth |
|------|-------------|
- | `--quick` | Minimal — project type, affected file(s), direct callers/dependents, related tests, recent commits |
- | Standard | Full — project type, module boundaries, test coverage, call chains, recent changes, existing patterns |
- | `--parallel` | Per-issue independent scouts |
-
- **Checklist:**
- - [ ] Project type, language, framework, package manager, and test runner identified
- - [ ] Affected files identified
- - [ ] Direct callers/dependents mapped (imports/exports, route registrations, provider wiring, consumers)
- - [ ] Related tests located
- - [ ] Recent git changes checked: `git log --oneline -10 -- <affected-files>`
- - [ ] Existing local patterns for this code path identified
- - [ ] 3-6 bullet codebase-context summary reported before diagnosis
+ | Quick/local | Minimal - project type, affected file(s), direct callers/dependents, related tests, recent commits |
+ | Standard and deeper | Full - module boundaries, test coverage, call chains, recent changes, existing patterns |
+ | `--parallel` | Per-issue independent scouts, one scope each, only through the Delegation Gate |
**Output:** `✓ Step 1: Scouted — [N] files mapped, [M] dependencies, [K] tests found`
---
- ## Step 2: Diagnose via `hapo:debug` (MANDATORY — never skip)
+ ## Step 2: Diagnose via `hapo:debug`
- **Purpose:** Evidence-based root cause analysis. NO guessing.
+ Evidence-based root cause analysis; no guessing. Use `hapo:debug`, or validate
+ an existing debug report when `--from-debug` is provided. See
+ `references/diagnosis-protocol.md` for the hotfix-local checklist.
- Use `hapo:debug` or validate an existing debug report when `--from-debug` is provided. See `references/diagnosis-protocol.md` for full methodology.
+ Diagnosis chain:
- **Mandatory chain:**
- 1. **Capture pre-fix state:** Record exact error messages, failing test output, stack traces. This is your baseline for Step 5.
- 2. **Observe:** Read the actual error. Where does it occur? When did it start? (`git log -p`)
- 3. **Hypothesize:** Form 2-3 hypotheses through structured reasoning:
- ```
- Hypothesis: [statement]
- Confirm if: [what evidence would prove it]
- Refute if: [what evidence would disprove it]
- Quick test: [how to verify fast]
- ```
- 4. **Test:** Use `Grep`, `Read`, or spawn parallel `Explore` subagents to validate each hypothesis against codebase evidence.
- 5. **Trace root cause:** Follow the chain backward — symptom → immediate cause → contributing factor → **ROOT CAUSE**.
- 6. **Escalate:** If 2+ hypotheses fail, apply Inversion Thinking (see `references/escalation-tactics.md`).
+ 1. **Capture pre-fix state:** exact error messages, failing test output, stack traces. This is the baseline for Step 5.
+ 2. **Observe:** read the actual error; locate where it occurs and when it started (`git log -p`).
+ 3. **Hypothesize:** form 2-3 hypotheses, each with confirm/refute evidence and a quick test.
+ 4. **Test:** validate each hypothesis against codebase evidence with focused local reads; test hypotheses in parallel only through the Delegation Gate.
+ 5. **Trace root cause:** symptom → immediate cause → contributing factor → root cause.
+ 6. **Escalate:** if 2+ hypotheses fail, apply `references/escalation-tactics.md`.
**Exact root-cause contract:**
- Symptom: exact observable failure
- Reproduction: command, user flow, CI job, log trigger, or route
- Expected vs actual behavior
+ - Trigger: event or input that activated the failure, or `unknown`
- Root cause: file:line, config, environment, dependency, or data source
+ - Contributing factors: conditions that raised likelihood or impact but are not sufficient causes, or `none evidenced`
- Why now: recent change, dependency drift, data state, environment, timing, or load
- Evidence chain: observations proving the cause
- Blast radius: affected files, modules, tests, users, workflows, or release paths
- If any field is vague (`probably`, `maybe`, `I think`, or missing file:line/config/env evidence), keep diagnosing or ask the user for the specific missing artifact. Do not implement.
+ With `--from-debug`, validate the report before accepting it:
+ - the exact root-cause contract above is complete;
+ - `Evidence Timeline` is present — a skipped timeline is valid in either producer form (`Timeline: skipped - <reason>` or `- skipped: <reason>`);
+ - `Elimination Path` records the decisive observation for each removed or retained candidate;
+ - `Recurrence-Prevention Handoff`, when present, carries evidence-backed candidates only.
+
+ A report missing required fields routes back to diagnosis (`hapo:debug`); it
+ does not enter implementation.
+
+ If any contract field is vague or missing file:line/config/env evidence, keep
+ diagnosing or ask the user for the specific missing artifact. Do not implement.
+
**Output:** `✓ Step 2: Diagnosed — Root cause: [summary], Evidence: [brief], Scope: [N files]`
---
- ## Step 3: Classify Complexity
-
- | Level | Indicators | Workflow |
- |-------|------------|----------|
- | **Trivial** | Single file, clear error, type/lint/syntax | Quick: straight to fix |
- | **Standard** | Multi-file, root cause identified via diagnosis | Standard: fix + regression test |
- | **Complex** | System-wide, architecture impact, unclear boundaries | Deep: research + plan + fix |
- | **Parallel** | 2+ independent issues OR `--parallel` flag | Spawn `implementer` agents per issue |
+ ## Step 3: Select Depth
- **Task Orchestration (Standard+ only):**
- - Use `TaskCreate` with dependencies to track fix phases
- - Skip for Trivial (overhead exceeds benefit)
- - If `TaskCreate` / `TaskUpdate` are unavailable, use a concise markdown checklist or `TodoWrite` fallback. Do not block the hotfix because structured task tools are missing.
+ Apply the Proportional depth rule above. For 2+ independent issues (or
+ `--parallel`), evaluate the Delegation Gate; when it is closed, fix the issues
+ sequentially. Track progress with the runtime's task surface when available, or
+ a markdown checklist otherwise.
- **Output:** `✓ Step 3: [Complexity] detected — [workflow] selected`
+ **Output:** `✓ Step 3: [Depth] selected — [workflow]`
---
## Step 4: Implement Fix
- **Rules:**
- - Fix the ROOT CAUSE, not the symptom. Follow diagnosis findings.
- - Minimal changes only. Follow existing code patterns.
+ Rules:
+ - Fix the root cause, not the symptom. Follow diagnosis findings.
+ - Minimal changes only; follow existing code patterns.
- One logical change per commit boundary.
- ### Quick Workflow
- 1. Apply the minimal fix directly from completed scout + diagnosis
- 2. Run exact pre-fix command plus typecheck/lint immediately
- 3. Report before/after proof
-
- ### Standard Workflow
- 1. Implement fix targeting root cause
- 2. Add/update regression test that fails without fix, passes with it
- 3. Run full test suite
-
- ### Deep Workflow
- 1. **Parallel investigation:** After initial scope is known, Scout (`hapo:scout`), Diagnose (`hapo:debug`), and Research (`researcher` subagent) may run concurrently only when their permission, runtime-capability, and independent-scope gates pass; otherwise gather the same evidence locally and sequentially. See `references/parallel-patterns.md` Pattern E.
- 2. Synthesize findings from all three into a unified fix approach
- 3. Plan the fix (consider writing to `references/` for future use)
- 4. Implement in stages, verifying each stage
- 5. Comprehensive regression tests
-
- ### Parallel Workflow
- 1. Create separate `TaskCreate` per independent issue
- 2. Spawn `implementer` subagents — one per issue
- 3. Each agent follows Steps 1-5 independently
- 4. Aggregate results upon completion
+ Workflows by depth:
+ - **Quick:** apply the minimal fix from completed scout + diagnosis, run the exact pre-fix command plus typecheck/lint immediately, report before/after proof.
+ - **Standard:** implement the fix, add or update a regression test that fails without the fix and passes with it, run the relevant suite.
+ - **Incident/deep:** investigate with `hapo:scout`/`hapo:debug` (and `researcher` for external facts) — concurrently only through the Delegation Gate, otherwise sequentially; synthesize one fix approach; implement in stages and verify each stage.
+ - **Parallel:** one independent issue per agent, each following Steps 1-5, dispatched only through the Delegation Gate; aggregate results on completion.
**Output:** `✓ Step 4: Fixed — [N] files changed`
---
- ## Step 5: Verify + Prevent (MANDATORY — never skip)
-
- **Purpose:** Prove the fix works AND prevent the same bug class from recurring.
+ ## Step 5: Verify + Prevent
- **Mandatory chain:**
- 1. **Iron-law verification:** Run the EXACT commands from pre-fix state capture (Step 2). Compare output. NO claims without fresh terminal evidence.
- 2. **Regression test:** The test MUST fail without the fix and pass with it.
- 3. **Parallel verification:** Run typecheck + lint + build + test simultaneously via `Bash`. See `references/parallel-patterns.md` Pattern C.
- 4. **Prevention guard (Standard+ only):** See `references/prevention-gate.md`.
- 5. **Side-effect gate:** Sweep the full blast radius identified in Step 2:
- - Modified files and direct dependents pass relevant tests
- - Affected user/API/CLI workflows still work
- - Public contracts unchanged unless intentionally called out
- - No new lint/type/build errors
- 6. **Code review:** Trigger `hapo:code-review`; never auto-approve blocking security, auth, data-loss, resource-exhaustion, or public-contract issues.
+ 1. **Iron-law verification:** run the exact commands from the pre-fix state capture and compare output. No claims without fresh command output from the current run.
+ 2. **Regression test:** must fail without the fix and pass with it.
+ 3. **Full check:** typecheck + lint + build + test (see `references/parallel-patterns.md` Pattern C).
+ 4. **Prevention guard (Standard+):** see `references/prevention-gate.md`; consume the debug report's recurrence candidates when present.
+ 5. **Side-effect gate:** sweep the full blast radius from Step 2 against the five checks in the gate above.
+ 6. **Review:** trigger `hapo:code-review`; see `references/review-cycle.md`.
- **If verification fails:**
- - < 3 attempts → Loop back to Step 2 (re-diagnose with new evidence)
- - 3+ attempts → STOP. Question architecture. Discuss with user.
+ Verification and review report `PASS | PASS_WITH_WARNINGS | FAIL | BLOCKED`.
+ The definition of `PASS` defers to `hapo:code-review`. `PASS_WITH_WARNINGS`
+ routes through the same remediation or user-pause path as `FAIL` and never
+ auto-accepts. `BLOCKED` is terminal for the cycle; resolve the blocker instead
+ of retrying. A review-only result is not execution proof; completion claims
+ require fresh command output.
- **If a side effect appears:**
- - STOP and present concrete options to the user. Do not silently broaden the fix.
+ If verification fails: under 3 attempts, loop back to Step 2 and re-diagnose
+ with the new evidence; at 3+ attempts, stop and discuss with the user. Never
+ weaken, delete, or mock a failing assertion to obtain green.
**Output:** `✓ Step 5: Verified + Prevented — [before/after comparison], [N] tests added`
---
- ## Step 6: Finalize (MANDATORY — never skip)
+ ## Step 6: Finalize
- 1. **Report:** Confidence score, root cause, changes made, files affected, prevention measures, side-effect sweep result
- 2. **Docs update:** If API/behavior changed → delegate to `docs-keeper` subagent
- 3. **Task cleanup:** `TaskUpdate` → mark all tasks `completed` (skip if no tasks created)
- 4. **Commit:** Ask user if ready to commit via `git-ops` subagent
+ 1. **Report:** root cause, changes made, files affected, prevention measures, side-effect sweep result, and any remaining limitations.
+ 2. **Docs update:** if API or behavior changed, update only the affected existing docs through the docs flow.
+ 3. **Commit:** ask the user before committing; use conventional commits.
**Output:** `✓ Step 6: Complete — [action taken]`
---
## Output Format
Unified step markers (emit after each step):
```
✓ Step 1: Scouted — [N] files, [M] deps
✓ Step 2: Diagnosed — Root cause: [summary]
- ✓ Step 3: [Complexity] detected — [workflow] selected
+ ✓ Step 3: [Depth] selected — [workflow]
✓ Step 4: Fixed — [N] files changed
✓ Step 5: Verified + Prevented — [tests added], [guards added]
✓ Step 6: Complete — [action taken]
```
- ## Subagent Usage
-
- | Subagent | When |
- |----------|------|
- | `hapo:debug` | Mandatory diagnosis gate before code edits (Step 2) |
- | `debugger` | Root cause unclear, need deep systematic investigation (Step 2) |
- | `Explore` (parallel) | Scout multiple areas (Step 1), test hypotheses (Step 2) |
- | `Bash` (parallel) | Verify: typecheck + lint + build + test (Step 5) |
- | `researcher` | External docs needed (Deep workflow only) |
- | `test-runner` | After fix, verify correctness (Step 5) |
- | `hapo:code-review` | After fix, quality check (Step 5) |
- | `git-ops` | Commit changes (Step 6) |
- | `docs-keeper` | Update docs if behavior changed (Step 6) |
- | `implementer` | Parallel independent issues (each gets own agent) |
-
## Specialized Paths
- Use `references/workflow-specialized.md` as an overlay after Step 1 scout:
- - CI/CD failures
- - Test suite failures
- - TypeScript type errors
- - UI / visual issues
- - Application log errors
-
- Specialized paths do not replace the 6-step hotfix process.
+ Use `references/workflow-specialized.md` as an overlay after Step 1 scout for
+ CI/CD failures, test suite failures, TypeScript type errors, UI/visual issues,
+ and application log errors. Specialized paths do not replace the six-step flow.
## References
Load as needed:
- - `references/diagnosis-protocol.md` — Structured root cause analysis methodology
+ - `references/diagnosis-protocol.md` — Structured root cause analysis and the exact root-cause contract
- `references/escalation-tactics.md` — What to do when hypotheses fail (Inversion, Scale Game)
- `references/prevention-gate.md` — Defense-in-depth validation after fix
- - `references/review-cycle.md` — Review handling and required user-pause conditions
- - `references/parallel-patterns.md` — Parallel Explore/Bash/Task coordination with code templates
+ - `references/review-cycle.md` — Review verdict handling and required user-pause conditions
+ - `references/parallel-patterns.md` — Delegation Gate patterns for parallel work
- `references/workflow-specialized.md` — CI/CD, test, TypeScript, UI-specific workflows