mk:fix

Fixing

Unified skill for fixing issues of any complexity with structured diagnosis.

Process Flow (Authoritative)

Bug → Mode Select → Check Memory → Scout (MANDATORY) → Diagnose
  → [investigate → sequential-thinking → root cause?]
  → yes → Root-Cause Proof (6 fields, HARD GATE) → Complexity → Fix ROOT CAUSE → Verify+Prevent (MANDATORY)
  → pass → Finalize + Write to Memory
  → fail <3 → re-diagnose | fail 3+ → STOP

This flow is authoritative. If prose conflicts, follow the flow.

HARD GATE

Do NOT propose or implement fixes before completing Steps 1-2 (Scout + Diagnose). Symptom fixes are failure. Find the cause first through structured analysis, NEVER guessing. If 3+ fix attempts fail, STOP and question the architecture — discuss with user. Override: --quick allows fast scout→diagnose→fix for trivial issues (lint, type errors).

Arguments

• --auto — Autonomous mode (default). Auto-fixes blocking issues up to the cycle limit, then stops at ready for user approval. Never self-approves; score is advisory display only.
• --review — Human-in-the-loop. Pause at each step.
• --quick — Fast cycle for trivial bugs.
• --parallel — Parallel developer agents per independent issue.
• --tdd — Force regression test BEFORE the fix (writes the .claude/session-state/tdd-mode sentinel). Without --tdd, regression tests are recommended but not gated. Useful for security-sensitive fixes where you want to prove the bug first.

Plan-First Gate

For moderate/complex bugs:

1. Run mk:investigate to confirm root cause
2. If fix affects > 2 files → mk:plan-creator --type bugfix
3. Wait for Gate 1 approval

Skip: --quick mode (single file, clear cause).

Step 0 — Mode Selection

If no mode flag: use AskUserQuestion (Autonomous / HITL / Quick). See references/mode-selection.md.

Step 0.5 — Check Fix Memory (before scouting)

Read .claude/memory/fixes.json first — it is the canonical, schema-validated store of prior fix patterns. Fall back to .claude/memory/fixes.md only when the JSON is absent. If both exist and describe different bug classes, prefer the JSON and emit a one-line conflict warning (⚠ fixes.md has entries not in fixes.json — JSON is authoritative; run 'mewkit memory seed-from-md'). See the source-of-truth rule in .claude/rules/memory-read-rules.md.

• Search for similar symptoms, error messages, or affected modules
• If a matching fix pattern exists → use it as starting hypothesis in Step 2
• If a matching success pattern exists → apply the known fix approach directly

This turns repeated bugs into instant fixes. Skip only if .claude/memory/ doesn't exist.

Step 1 — Scout (MANDATORY — never skip)

Activate mk:scout to map affected codebase BEFORE any diagnosis:

• Affected files, dependencies, related tests, recent changes (git log)
• Quick mode: minimal scout (affected file + direct deps only)
• Standard/Deep: full scout (module boundaries, test coverage, call chains)
• Risk flags: match the task against .claude/rules/risk-checklist.md (the 9 IDs only — do not invent flags) and hold matchedFlags for the evidence index. If any of AUTH / AUTHZ / DATA_MODEL / AUDIT_SEC / EXT_SYSTEM / PUBLIC_CONTRACT / WEAK_PROOF matches, set risk.requiresHumanApproval = true — auto mode cannot finalize silently (see references/review-cycle.md).

Why mandatory: Without codebase context, diagnosis guesses instead of reasons from evidence.

Step 2 — Diagnose (MANDATORY — never skip)

Capture pre-fix state first: exact error messages, failing test output, stack traces.

Then structured diagnosis using two skills:

1. mk:investigate — collect symptoms, traces, reproduction steps
2. mk:sequential-thinking — generate hypotheses from evidence, test each, eliminate, conclude

Load references/diagnosis-protocol.md for the 5-phase protocol: Observe → Hypothesize → Test → Trace → Escalate.

Output: confirmed root cause (not symptom) with evidence chain + confidence level.

BLOCK: If confidence < medium → gather more evidence before fixing. Never fix a "maybe."

Step 2.5 — Root-Cause Proof Checkpoint (HARD GATE)

Operationalizes .claude/rules/core-behaviors.md Rule 6 ("Verify, Don't Assume"). The six fields are the named output of the Step 2 diagnosis (references/diagnosis-protocol.md Phase 4). Do NOT start Step 4 (Fix) until all six are populated — empty fields mean the diagnosis is not yet proven.

Standard/Complex/Parallel — all six required:

1. Exact symptom — copy-pasted error/message/behavior, not paraphrased.
2. Deterministic reproduction — exact command(s) or steps that trigger it every time.
3. Expected vs actual — what should happen vs what does.
4. Root cause with file:line — the specific source location, traced backward from the symptom (never the symptom site).
5. Why now — what changed / what condition makes it surface (regression commit, data state, env, version).
6. Blast radius — other callers, modules, or behaviors the same root cause touches.

--quick compact form (still non-empty — one phrase each): exact compiler/lint error · file · direct cause · command-before · command-after · impacted area.

If any field cannot be filled, return to Step 2 and gather more evidence. Do not substitute a guess.

Write evidence (init): emit workflow-evidence.json with skill: mk:fix, mode, task, planPath (if the fix escalated to a plan), phase, risk (from Step 1), and fixDiagnosis (the six fields above; compact form for --quick). See the Workflow Evidence Index section below for path + schema.

Step 3 — Complexity Assessment

Classify before routing. See references/complexity-assessment.md.

| Level | Indicators | Workflow | | ------------ | --------------------------------- | --------------------------------- | | Simple | Single file, clear error | references/workflow-quick.md | | Moderate | Multi-file, root cause multi-step | references/workflow-standard.md | | Complex | System-wide, architecture impact | references/workflow-deep.md | | Parallel | 2+ independent issues | Parallel agents per issue |

Task orchestration (Moderate+): references/task-orchestration.md.

Step 4 — Fix Implementation

• Fix must address ROOT CAUSE from Step 2 — never symptoms only
• Minimal changes, follow existing patterns
• If fix deviates from diagnosis → re-diagnose first

Step 5 — Verify + Prevent (MANDATORY)

1. Iron-law verify: Re-run exact pre-fix commands. Compare before/after.
2. Regression test: Test that fails WITHOUT fix, passes WITH fix.
3. Defense-in-depth: Load references/prevention-gate.md — consider entry validation, business logic guards, error handling, type safety.
4. BLOCK: No regression test = fix is incomplete.

If verify fails: loop to Step 2. After 3 failures → STOP, question architecture.

Update evidence: write verification.commands (the re-run commands) and verification.overall (pass/fail) to workflow-evidence.json.

Step 6 — Finalize + Learn (MANDATORY for Standard/Complex/Parallel; opt-in for Simple)

1. Report: confidence, root cause, changes, files, prevention measures.

1. Write to memory via direct Edit calls — capture the fix pattern for future sessions. Read both files first to match the live schema, then append.

• .claude/memory/fixes.md — append:

``` ## <YYYY-MM-DD> — <bug-class slug> (severity: low|medium|high|critical)

• Symptom: <one line>
• Root cause: <one line>
• Fix: <one line + file paths>
• Prevention: <regression test path OR guard added>

```

• .claude/memory/fixes.json — under patterns, add or update:

```json { "id": "<kebab-slug>", "type": "failure", "category": "bug-class", "severity": "low|medium|high|critical",