Mk Fix

---
name: "mk-fix"
description: "Diagnoses and fixes bugs, type/lint errors, CI failures, and runtime errors, root-cause first. NOT for investigation without a fix (mk:investigate) or build-only compile errors (mk:build-fix)."
---

# Fixing

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

## Common Workflow (Authoritative)

```
Bug → Mode Select → [Check Memory: standard/deep] → Scout (MANDATORY) → Diagnose
  → [quick: confirm the known cause directly | standard/deep: investigate → sequential-thinking]
  → root cause? → yes → Root-Cause Proof → Complexity → Fix ROOT CAUSE → Verify + Prevent (MANDATORY)
  → pass → Report + capture only when recurrence/salience warrants it
  → fail <3 → re-diagnose | fail 3+ → STOP
```

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

## Profiles

- **quick** — known cause and one or two files: minimal scout, compact root-cause proof, edit, focused before/after check, and summary. No default plan, report, wiki, memory, commit prompt, or sub-task fan-out.
- **standard** (default) — full evidence chain, root-cause proof, focused regression test, relevant suite, and review.
- **deep** — standard plus an approved plan when a contract or architecture changes.

**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.
`--quick` may use the compact proof, but it never bypasses Scout, Diagnose, root-cause evidence, Verify + Prevent, or the three-failed-attempt stop.

## Arguments

- `--auto` — Standard profile with automatic progress through diagnosis and verification. It stops at any required human gate and never self-approves.
- `--review` — Human-in-the-loop. Pause at each step.
- `--quick` — Quick profile for a known cause and ≤2 files.
- `--parallel` — Parallel `developer` agents per independent issue.
- `--tdd` — Force regression test BEFORE the fix (writes the `.codex/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.
- `--advice` — Opt-in strategic supervision for one run. At named checkpoints (`GUIDE → RESCUE* → REVIEW → RECHECK*`, hard cap 5) the workflow asks the `athena` agent to assess the situation, recommend an operational path inside the locked scope, and — after the work — review it against the evidence, with the power to return it for correction. Standard and deep profiles only. Supervision is evidence, never approval: it clears no gate, counts as no verification, and the three-failed-attempt human STOP below still fires on its own schedule. Without the flag, zero calls happen and no state is written. Contract: `.agents/skills/rule-advice-supervision/SKILL.md` (load it only when the flag is present). Checkpoints: the Advice Checkpoints section in `references/workflow-standard.md` / `references/workflow-deep.md`.

## Plan-First Gate

For moderate/complex bugs:

1. Run `mk:investigate` to confirm root cause. A supplied diagnostic report is evidence to validate and extend, never a substitute for investigation.
2. If fix affects > 2 files → request an approved plan with `mk:plan-creator "bug fix: {symptom and affected area}"`
3. Wait for Gate 1 approval

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

## Step 0 — Mode Selection

Without a mode flag, use the standard profile. Use quick only when its boundary is already proven; otherwise use standard. See `references/mode-selection.md` for escalation.

## Step 0.5 — Check Fix Memory (standard/deep only)

Read `.meowkit/memory/fixes.json` — it is the canonical, schema-validated store of prior fix patterns. See the source-of-truth rule in AGENTS.md (Memory).

- 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 for quick, or if `.meowkit/memory/` does not 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 the risk checklist (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 choose the evidence path that matches the profile:

1. **Quick** — validate the supplied known cause against the error and affected code directly. Do not delegate to `mk:investigate`; if the cause is no longer clear, escalate to standard before editing.
2. **Standard/Deep** — use **mk:investigate** to collect and validate symptoms, traces, and reproduction steps, then **mk:sequential-thinking** to generate hypotheses from evidence, test each, eliminate, and conclude. A supplied diagnostic report is evidence to validate and extend, never a bypass.

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 AGENTS.md (Core behaviors) 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. **Reproduction evidence** — either exact command(s) or steps that trigger it every time, or, for an intermittent failure, the observed attempts, failure rate, conditions, and supporting trace/log correlation.
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 / uncertainty record** — what changed or condition makes it surface (regression commit, data state, env, version); if unknown, state that explicitly with eliminated hypotheses and the monitoring or next observation needed. Never invent a cause for timing.
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. Intermittent failures may use bounded probabilistic evidence; a documented unknown is valid only for the uncertainty record, never as a substitute for the root cause.

**Write evidence (init):** standard/deep runs emit `workflow-evidence.json` with `skill: mk:fix`, `mode`, `task`, `planPath` (if the fix escalated to a plan), `phase`, `risk`, and `fixDiagnosis`. Quick runs keep evidence in the response only.

## 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:** Follow AGENTS.md (Development / TDD); when required, the test fails WITHOUT the fix and passes WITH it.
3. **Defense-in-depth:** Load `references/prevention-gate.md` — consider entry validation, business logic guards, error handling, type safety.
4. **BLOCK:** Missing a required regression test is incomplete; record the allowed omission rationale for lint/format/config-only changes.

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

**Update evidence:** standard/deep runs write `verification.commands` and `verification.overall` to `workflow-evidence.json`; quick runs report the same focused before/after check inline.

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

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

2. **Write to memory only for recurrence or durable salience** — read `.meowkit/memory/fixes.json` first, then add/update the canonical JSON store only when the pattern is likely to help a future run. Quick runs never write memory.
   - **`.meowkit/memory/fixes.json`** — under `patterns`, add or update:

     ```json
     {
      "id": "<kebab-slug>",
      "type": "failure",
      "category": "bug-class",
      "severity": "low|medium|high|critical",
      "domain": ["<area1>", "<area2>"],
      "applicable_when": "<one line>",
      "context": "<one line>",
      "pattern": "<one line — what to do or avoid>",
      "frequency": 1,
      "lastSeen": "<YYYY-MM-DD>"
     }
     ```

   - **If the same `id` already exists**, increment `frequency` and update `lastSeen`. Do not duplicate entries.

   - **DO NOT use `##pattern:bug-class` prefixes.** That is a user-typed keyboard shortcut; the handler (`hooks/handlers/immediate-capture-handler.cjs`) only fires on `UserPromptSubmit` — the human typing the prefix at the start of a message. Agent-emitted `##pattern:` text is invisible to the handler. Always call `Edit` directly. See `.agents/skills/memory/references/capture-architecture.md`.

   - **Scrub secrets / tokens / PII before writing.** `Edit` is not secret-scrubbed; you are responsible.

   - **Inside `the cook skill` full pipeline**: Phase 6 / `mk:memory session-capture` covers this — do NOT double-write here. Standalone `the fix skill` runs OWN the write themselves.

   - Skip when `the fix skill --no-capture` was passed, the run is quick, or the result is a one-off with no durable lesson.

3. **Delegate to `project-manager`** (Moderate/Complex/Parallel ONLY) per the post-phase-delegation conventions Rule 1 (background — include "Run in the background" in the prompt). Skip for Simple complexity — Gate 1 bypass path means no plan to track. Also skipped when `MEOWKIT_PM_AUTO=off`.

4. `documenter` agent → update `./docs`.

5. Ask user about commit.

6. **Terminal wiki handoff (standalone runs only; advisory, fail-open):** Inside `the cook skill`, SKIP — cook's Phase 6 owns the handoff. For a standalone `the fix skill` of Standard/Complex/Parallel complexity, first write a short, durable fix summary (NEVER raw `workflow-evidence.json`) to `tasks/reports/fix-<YYMMDD-HHMM>-<slug>.md` with only: symptom, root cause, files changed, verification result, recurrence/friction note, and links to the evidence path. Then hand it to the wiki per `.agents/skills/wiki/references/terminal-handoff-advisory.md` — resolve the slug (env `MEOWKIT_WIKI_SLUG` → the sole `tasks/wikis/<slug>/wiki.json` → else skip + print), fail-open, never `wiki approve`, no `wiki reindex`:

   ```bash
   npx mewkit wiki handoff propose \
     --skill mk:fix \
     --from tasks/reports/fix-<YYMMDD-HHMM>-<slug>.md \
     --slug <resolved-wiki-slug> \
     --verified-outcome --recurring-friction
   ```

   Omit `--recurring-friction` for a one-off bug. Skip entirely for Simple complexity or when `--no-capture` was passed.

## Workflow Evidence Index

Contract: the workflow-evidence conventions. The index records pointers + summaries of this run; it **never approves anything** (Gate 2 / ship stay human authority) and carries **no score**. Generated for standalone Standard/Complex/Parallel fixes; quick and simple fixes keep focused evidence in their response.

**Storage path:** `.codex/session-state/evidence/<YYMMDD-HHMM-slug>/workflow-evidence.json` (framework-internal state per `skill-authoring-rules.md` Rule 2). For a fix that escalated to a plan, use `tasks/plans/<plan>/reports/evidence/workflow-evidence.json` instead.

**Write points (standard/deep only):** Step 2.5 (init: skill, mode, task, planPath, phase, risk, fixDiagnosis) → Step 5 (verification) → Step 6 finalize (`approvals.gate2`/`ship` as `required|not_applicable`, `memory.fixPatternWritten`).

**Validate before approval:** run `node .codex/scripts/validate-workflow-evidence.cjs <path> --phase fix` before the user-approval prompt (Step 6 item 5). Surface any `EVIDENCE_BLOCKED:<reasons>` and fill the missing fields — do not present for approval on a blocked index. A high-risk flag (`risk.requiresHumanApproval`) forces explicit human approval before finalize regardless of mode.

**Evidence ≠ memory:** the evidence file is one-run proof; `.meowkit/memory/fixes.json` is the durable pattern store. Keep them separate — standalone `the fix skill` owns its evidence write; inside `the cook skill` the pipeline (Phase 6) owns the evidence write, so do NOT double-write. Scrub secrets / tokens / PII and store pointers/summaries only — never raw command logs.

## Skill Activation

**Always:** `mk:scout` (Step 1) + direct diagnosis (Step 2). **Standard/Deep:** `mk:investigate` + `mk:sequential-thinking` for the full evidence chain. A supplied diagnostic report informs investigation; it never bypasses it.
**Conditional:** `mk:brainstorming` (complex, multiple approaches) | `mk:docs-finder` (unfamiliar APIs)

## Gotchas

- **Guessing root causes**: "I think it's X" without evidence → use mk:sequential-thinking to generate + test hypotheses from evidence
- **Fixing symptoms**: test passes but underlying issue remains → always trace backward: symptom → cause → ROOT cause
- **Skipping scout**: fixing without codebase context → mandatory scout maps what you're touching
- **Missing required regression test**: bug resurfaces next sprint → follow `tdd-rules.md` and record any allowed omission rationale
- **3+ failed attempts without stopping**: insanity loop → STOP, question architecture, discuss with user

Full list: `references/gotchas.md` (update when Codex produces wrong fix patterns)

## References

- `references/mode-selection.md` — stop and ask the user in chat format
- `references/diagnosis-protocol.md` — 5-phase structured diagnosis
- `references/prevention-gate.md` — defense-in-depth + verification checklist
- `references/complexity-assessment.md` — Simple/Moderate/Complex/Parallel
- `references/task-orchestration.md` — Task patterns for moderate+
- `references/workflow-quick.md` | `workflow-standard.md` | `workflow-deep.md`
- `references/review-cycle.md` — Autonomous/HITL/Quick review
- `references/skill-activation-matrix.md` — When to activate each skill
- `references/workflow-ci.md` | `workflow-logs.md` | `workflow-test.md` | `workflow-types.md` | `workflow-ui.md`
- `references/parallel-exploration.md` — Parallel investigation strategy for multi-hypothesis diagnosis