@haposoft/cafekit 0.16.0-rc.8 → 0.16.0

package/src/claude/skills/hotfix/SKILL.md

@@ -1,6 +1,6 @@
 ---
-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."
+name: cf:fix
+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 cf: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
@@ -8,33 +8,65 @@ 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
+# Fix — root-cause repair 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 `cf:debug` report and validate its contract before accepting it
 
-Default: deterministic scout-first hotfix. There is no initial mode selection step.
+Default: deterministic scout-first fix. There is no initial mode selection step.
+
+## Proportional depth
+
+Choose the smallest adequate depth from the diagnosed evidence. Depth vocabulary
+follows `cf: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.
+
+## Bounded repair frame
+
+Quick/local does not add a separate framing ceremony when the issue and diagnosis
+already establish the repaired behavior and proof. For Standard or Incident/deep,
+or whenever scope or risk remains ambiguous after diagnosis, record four short
+fields before choosing an implementation:
+
+- **Outcome:** the observable repaired behavior.
+- **Constraints:** compatibility, safety, ownership, rollout, and time boundaries.
+- **Non-goals:** adjacent behavior the repair must not absorb.
+- **Acceptance:** the exact reproduction plus broader evidence that proves completion.
+
+Derive repository-owned facts from scout and diagnosis. Ask the user only for a
+missing user-owned decision that could materially change the repair. This frame
+does not select a solution, widen the issue into feature work, or run before the
+root cause is proven.
 
 <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.
+Fix 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.
@@ -42,6 +74,7 @@ Collect these scout outputs first:
 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>
@@ -52,7 +85,7 @@ The fix is not done until Step 5 proves:
 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
@@ -60,192 +93,166 @@ If verification reveals a side effect or regression, STOP and present 2-4 concre
 Do not silently patch around the regression.
 </HARD-GATE-NO-SIDE-EFFECTS>
 
-## Anti-Rationalization
+## Delegation Gate
+
+Dispatch subagents (parallel scouts, hypothesis tests, deep research, or
+`--parallel` fix trees) only when all three conditions hold:
 
-| 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. |
+- 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:inspect]
-    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]
+    A[Issue Input] --> B[Step 1: Scout via cf:scout]
+    B --> C[Step 2: Diagnose via cf:debug]
+    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.
+## Step 1: Scout
 
-**Action:** Activate `hapo:inspect` skill to map the blast radius.
+Understand the affected codebase before forming any hypotheses. Activate
+`cf:scout` or perform an equivalent focused local scout (`rg` plus targeted
+reads) to map the blast radius.
 
-Do not ask generic questions before this step unless there is no repo, no error text, and no observable artifact to inspect.
-
-| 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 `cf:debug`
 
-**Purpose:** Evidence-based root cause analysis. NO guessing.
+Evidence-based root cause analysis; no guessing. Use `cf:debug`, or validate
+an existing debug report when `--from-debug` is provided. See
+`references/diagnosis-protocol.md` for the Fix-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 (`cf: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
+## Step 3: Select Depth + Bound Repair
 
-| 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 |
+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.
 
-**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.
+For Standard and Incident/deep, complete the bounded repair frame above. Quick
+records no separate frame unless scope or risk is still ambiguous.
 
-**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, gather evidence in parallel — Scout (`hapo:inspect`), Diagnose (`hapo:debug`), and Research (`researcher` subagent) can run concurrently. 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:** after diagnosis, research only unresolved external facts. If
+  multiple cause-aligned remedies or an architecture decision remain, use
+  `cf:brainstorm` to compare 2-3 options against the bounded repair frame, then
+  write a concise staged implementation plan with dependencies and proof per
+  stage. When diagnosis leaves one safe direct repair, skip research and
+  brainstorm, record why it satisfies the frame, and implement it. Delegated
+  research follows the Delegation Gate; implementation starts only after the
+  direction is resolved.
+- **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 `cf: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 `cf: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]`
 
@@ -257,44 +264,26 @@ 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 a progressively disclosed overlay
+after Step 1 scout for CI/CD failures, test suite failures, TypeScript type
+errors, UI/visual issues, and application log errors. Load only the matching
+section. Specialized paths add category-specific evidence and proof; they do
+not replace the six-step flow, weaken diagnosis, or broaden the repair scope.
 
 ## 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

package/src/claude/skills/hotfix/references/diagnosis-protocol.md

@@ -1,14 +1,14 @@
 # Diagnosis Protocol
 
-Structured root cause analysis methodology. Replaces ad-hoc guessing with evidence-based investigation. Prefer running `hapo:debug` directly; use this file as the hotfix-local checklist.
+Structured root cause analysis methodology. Replaces ad-hoc guessing with evidence-based investigation. Prefer running `cf:debug` directly; use this file as the Fix-local checklist.
 
 ## Core Principle
 
-**NEVER guess root causes.** Form hypotheses through structured reasoning and test them against evidence.
+Do not guess root causes. Form hypotheses through structured reasoning and test them against evidence.
 
-**NO FIXES IN DIAGNOSIS.** Product-code changes start only after the exact root-cause contract is complete.
+No fixes during diagnosis: product-code changes start only after the exact root-cause contract is complete.
 
-## Pre-Diagnosis: Capture State (MANDATORY)
+## Pre-Diagnosis: Capture State
 
 Before any investigation, capture the current broken state as baseline:
 
@@ -56,13 +56,14 @@ For each hypothesis:
 
 ### Phase 3: Test — Verify hypotheses against evidence
 
-Spawn parallel `Explore` subagents to test each hypothesis simultaneously:
+Test each hypothesis with focused local evidence (`rg`, targeted reads, exact
+commands). Spawn parallel `Explore` subagents only when the Delegation Gate in
+`../SKILL.md` is open:
 
 ```
-// Launch in SINGLE message — max 3 parallel agents
+// Only through the Delegation Gate — single message, max 3 parallel agents
 Agent(subagent_type="Explore", prompt="Test hypothesis A: [specific search/check]")
 Agent(subagent_type="Explore", prompt="Test hypothesis B: [specific search/check]")
-Agent(subagent_type="Explore", prompt="Test hypothesis C: [specific search/check]")
 ```
 
 **For each hypothesis result:**
@@ -83,15 +84,17 @@ Symptom (where error appears)
 
 **Rule:** NEVER fix where the error appears. Trace back to the source.
 
-## Exact Root-Cause Contract (MANDATORY)
+## Exact Root-Cause Contract
 
-Before Step 4 implementation in `hapo:hotfix`, record:
+Before Step 4 implementation in `cf:fix`, record:
 
 - Symptom: exact observable failure
 - Reproduction: command, user flow, CI job, log trigger, or route
 - Expected: intended behavior
 - Actual: observed 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, data state, dependency drift, environment, timing, or load factor
 - Evidence chain: observations proving this cause
 - Blast radius: affected files, modules, tests, users, workflows, or release paths
@@ -116,7 +119,9 @@ If 2+ hypotheses are REFUTED → see `escalation-tactics.md`.
 - Reproduction:
 - Expected:
 - Actual:
+- Trigger:
 - Root cause:
+- Contributing factors:
 - Why now:
 - Blast radius:
 

package/src/claude/skills/hotfix/references/parallel-patterns.md

@@ -1,6 +1,17 @@
 # Parallel Patterns & Task Coordination
 
-How to effectively leverage multiple subagents (the `Agent` tool) and native task tracking (`TaskCreate`/`TaskUpdate`) during fix workflows.
+How to leverage multiple subagents (the `Agent` tool) and optional task tracking during fix workflows.
+
+## Delegation Gate (applies to every subagent pattern)
+
+Patterns A, B, D, and E dispatch subagents 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.
+Pattern C runs shell commands in the main agent and needs no gate.
 
 ## When to Go Parallel
 
@@ -10,7 +21,7 @@ How to effectively leverage multiple subagents (the `Agent` tool) and native tas
 | Testing 2-3 diagnostic hypotheses simultaneously | Parallel hypothesis test | `Explore` × 2-3 |
 | Verifying fix (typecheck + lint + build + test) | Parallel verification | `Bash` × 3-4 |
 | Fixing 2+ independent bugs in one session | Parallel issue trees | `implementer` × N |
-| Deep workflow: scout + diagnose + research together | Parallel investigation | Mixed |
+| Deep workflow: parallel scout, then diagnose, then optional research | Staged investigation | Mixed |
 
 ## Pattern A: Parallel Scouting
 
@@ -52,7 +63,8 @@ All four must pass. If any fails, investigate that specific failure before re-at
 
 ## Pattern D: Task-Coordinated Issue Trees
 
-For 2+ independent bugs, create separate dependency chains per issue:
+For 2+ independent bugs, optionally create separate dependency chains per issue
+(task tools add visibility, never a required step):
 
 ```
 // Issue A — payment processing error
@@ -73,21 +85,23 @@ TaskCreate(subject="Integration verification",              addBlockedBy=[A4, B4
 
 Spawn one `implementer` agent per issue tree. Each agent claims tasks via `TaskUpdate(status="in_progress")` and completes via `TaskUpdate(status="completed")`.
 
-## Pattern E: Deep Workflow — Parallel Investigation Phase
+## Pattern E: Deep Workflow — Parallel Evidence Gathering
 
-In complex bugs (Deep workflow), Steps 1+2+3 should run **concurrently** to save time:
+In complex bugs, independent scout scopes may run concurrently when the
+Delegation Gate is open. Diagnosis still starts only after the required scout
+outputs are synthesized:
 
 ```
-// All three launch simultaneously:
-Agent(subagent_type="Explore", prompt="Scout: map affected files, dependencies, and test coverage")
-// Meanwhile, main agent starts diagnosis using available error context
-// Meanwhile:
-Agent(subagent_type="researcher", prompt="Research: find latest docs and known issues for [library/framework]")
+// Both read-only scout scopes launch simultaneously:
+Agent(subagent_type="Explore", prompt="Scout scope A: map affected files, dependencies, and test coverage")
+Agent(subagent_type="Explore", prompt="Scout scope B: map runtime/config paths and recent changes")
 ```
 
-The main agent begins hypothesis formation (Step 2) immediately using the error message and stack trace. Scout results enrich the diagnosis when they arrive. Research results inform the fix approach.
-
-**Key insight:** You don't need to wait for scouting to finish before starting diagnosis — the error message itself is often enough to form initial hypotheses.
+Wait for the scout evidence, synthesize the required codebase-context summary,
+then begin hypotheses and diagnosis. Research begins only after Step 2 diagnosis
+proves the root cause and identifies one unresolved external fact. It may inform
+a post-diagnosis remedy decision; it never substitutes for repository evidence
+or selects a fix early.
 
 ## Resource Constraints
 

package/src/claude/skills/hotfix/references/prevention-gate.md

@@ -2,6 +2,11 @@
 
 After a fix is verified, apply defense-in-depth to prevent the same bug class from recurring. Prevention is not the same as side-effect safety; run the Step 5 side-effect sweep in `../SKILL.md` before claiming completion.
 
+When the debug report carries a `Recurrence-Prevention Handoff`, consume its
+evidence-backed candidates (missing invariant or validation layer,
+observability/alerting gap, regression scenario) as guard inputs below instead
+of inventing new ones.
+
 ## Mandatory Prevention Checklist
 
 For every fix (Standard+ complexity), evaluate and apply at least ONE: