Mk Fix

Fixing

Unified skill for fixing issues of any complexity with intelligent routing.

Arguments

• --auto - Activate autonomous mode (default); high-risk fixes stop for human approval before finalize/commit/ship
• --review - Activate human-in-the-loop review mode
• --quick - Activate quick mode
• --parallel - Activate parallel mode: route to parallel fullstack-developer agents per issue
• --advice - Run under kongming advisory supervision (see Advisory supervision)

Advisory supervision (--advice)

When --advice is present, run this skill under kongming supervision. kongming is an advisory-only supervisor: it returns counsel, never code, and the main agent stays responsible for every decision, edit, and gate.

Spawn kongming at these checkpoints:

• After each phase or step completes (Steps 1-6) - pass the goal, what changed, and the evidence; ask for a go/no-go and the next risk to watch.
• When stuck - the 3+ failed-attempt gate, a blocked step, or contradictory evidence; pass everything already tried and the exact obstacle before questioning the architecture.
• Before a high-stakes decision - a design fork, a public-contract or security-sensitive change, or an irreversible action; get counsel first.

Invoke with the runtime's live agent-delegation capability using subagent_type="kongming" and a prompt containing the task, evidence, approaches tried, and the exact question. Give it enough context to answer in one reply; it does not interview.

When the workflow reaches a PR such as a CI-failure fix shipped for review, carry the advice context forward and watch/fix CI until every required check is green. Then spawn kongming to review the whole implementation and post its assessment plus concrete next steps as a comment directly on the PR and the source issue when one exists.

--advice adds supervision; it never bypasses this skill's approval gates, tests, review blockers, branch protections, or security policy.

State a 3-6 bullet codebase-context summary to the user before asking questions.

1. Exact symptom: precise error message / failing assertion / observed behavior (copy verbatim, not paraphrased).
2. Reproduction steps: minimal sequence that triggers it (commands, inputs, environment).
3. Expected vs actual: what SHOULD happen vs what DOES happen.
4. Root cause (not symptom): the underlying defect — a specific line, missing check, race condition, contract violation, or design flaw. Cite file:line evidence.
5. Why now: what change/condition exposed it (recent commit, data shape, env, dep upgrade).
6. Blast radius: every code path that depends on the broken behavior or shares the same root cause.

If ANY item is vague ("probably", "I think", "something with…"), use AskUserQuestion to gather missing facts (logs, repro, env) OR run more scout/debug — never guess.

Use AskUserQuestion with options grounded in scout findings (specific files, specific commits, specific functions) — never abstract.

1. Original symptom no longer reproduces (re-run exact pre-fix repro from Step 2).
2. All tests in modified files + transitively-affected modules pass.
3. No business logic / workflow regression in the blast radius identified above (run those tests too, or manually walk the affected flows).
4. No new lint/type/build errors introduced anywhere.
5. Public API contracts (function signatures, exported types, response shapes, DB schemas, env vars) unchanged — OR change is intentional and called out.

If verification reveals a side effect, regression, or broken workflow, STOP. Do NOT silently patch around it. Use AskUserQuestion to present:

• What broke (file, test, workflow)
• Why the fix caused it (1-line cause)
• 2-4 concrete options to choose from, e.g.:
  • "Revert the fix and try a different root-cause angle"
  • "Keep the fix and update the dependent code at to match the new contract"
  • "Narrow the fix scope to so the regression goes away"
  • "Accept the regression — it was buggy behavior the test was locking in"

Let the user decide. Do not assume.

Anti-Rationalization

Process Flow (Authoritative)

flowchart TD
    A[Issue Input] --> B[Step 0: Mode Selection]
    B --> C[Step 1: Scout - Understand Context]
    C --> D[Step 2: Diagnose - Structured Root Cause Analysis]
    D --> E[Step 3: Complexity Assessment + Task Orchestration]
    E -->|Simple| F[Quick Workflow]
    E -->|Moderate| G[Standard Workflow]
    E -->|Complex| H[Deep Workflow]
    E -->|Parallel| I[Multi-Agent Fix]
    F --> J[Step 4: Fix Implementation]
    G --> J
    H --> J
    I --> J
    J --> K[Step 5: Verify + Prevent]
    K -->|Pass + Prevention in place| L[Step 6: Finalize]
    K -->|Fail, <3 attempts| D
    K -->|Fail, 3+ attempts| M[Question Architecture]
    M --> N[Discuss with User]
    L --> O[Report + Docs + Journal]

This diagram is the authoritative workflow. If prose conflicts with this flow, follow the diagram.

Workflow

Step 0: Mode Selection

First action: If there is no "auto" keyword in the request, use AskUserQuestion to determine workflow mode:

See references/mode-selection.md for AskUserQuestion format.

Step 1: Scout (MANDATORY — never skip)

Purpose: Understand the affected codebase BEFORE forming any hypotheses.

Mandatory skill chain:

1. Activate mk-scout skill OR launch 2-3 parallel Explore subagents
2. Discover: affected files, dependencies, related tests, recent changes (git log)
3. Read ./docs for project context if unfamiliar

Quick mode: Minimal scout — locate affected file(s) and their direct dependencies only. Standard/Deep mode: Full scout — map module boundaries, test coverage, call chains.

Output: ✓ Step 1: Scouted - [N] files mapped, [M] dependencies, [K] tests found

Step 2: Diagnose (MANDATORY — never skip)

Purpose: Structured root cause analysis. NO guessing. Evidence-based only.

Mandatory skill chain:

1. Capture pre-fix state: Record exact error messages, failing test output, stack traces, log snippets. This becomes the baseline for Step 5 verification.
2. Activate mk-debug skill (systematic-debugging + root-cause-tracing techniques).
3. Activate mk-sequential-thinking skill — form hypotheses through structured reasoning, NOT guessing.
4. Spawn parallel Explore subagents to test each hypothesis against codebase evidence.
5. If 2+ hypotheses fail → auto-activate mk-problem-solving skill for alternative approaches.
6. Create diagnosis report: confirmed root cause, evidence chain, affected scope.

See references/diagnosis-protocol.md for full methodology.

Output: ✓ Step 2: Diagnosed - Root cause: [summary], Evidence: [brief], Scope: [N files]

Step 3: Complexity Assessment & Task Orchestration

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

Task Orchestration (Moderate+ only): After classifying, create native Claude Tasks for all phases upfront with dependencies. See references/task-orchestration.md.

• Skip for Quick workflow (< 3 steps, overhead exceeds benefit)
• Use TaskCreate with addBlockedBy for dependency chains
• Update via TaskUpdate as each phase completes
• For Parallel: create separate task trees per independent issue
• Fallback: Task tools (TaskCreate/TaskUpdate/TaskGet/TaskList) are CLI-only — unavailable in VSCode extension. If they error, use TodoWrite for progress tracking. Fix workflow remains fully functional without them.

Step 4: Fix Implementation

• Implement fix per selected workflow, updating Tasks as phases complete.
• Follow diagnosis findings — fix the ROOT CAUSE, not symptoms.
• Minimal changes only. Follow existing patterns.

Step 5: Verify + Prevent (MANDATORY — never skip)

Purpose: Prove the fix works, has NO side effects, and prevents the same bug class from recurring. See HARD-GATE-NO-SIDE-EFFECTS.

Mandatory skill chain:

1. Verify (iron-law): Run the EXACT commands from pre-fix state capture. Compare output. NO claims without fresh evidence.
2. Regression test: Add or update test(s) that specifically cover the fixed issue. The test MUST fail without the fix and pass with it.
3. Side-effect sweep (NEW): Run tests across the full blast radius identified in Step 2 (not just the modified file). Walk each dependent code path. Confirm public contracts unchanged (signatures, response shapes, DB schemas, env vars).
4. Code review (delegate): Spawn code-reviewer subagent with explicit instructions to check: (a) root cause actually addressed (not symptom-patched), (b) no broken business logic in blast radius, (c) no new failure modes, (d) follows existing patterns from scout. Pass scout summary + diagnosis report as context.
5. Artifact gate: Write review artifacts from ../_shared/references/workflow-artifacts.md, then run node claude/hooks/workflow-artifact-gate.cjs --stage finalize --artifact-dir <artifact-dir>.
6. Prevention gate: Apply defense-in-depth validation where applicable. See references/prevention-gate.md.
7. Parallel verification: Launch Bash agents for typecheck + lint + build + test.

If verification fails OR a side effect is detected: Use AskUserQuestion per HARD-GATE-NO-SIDE-EFFECTS — present what broke, why, and 2-4 concrete options (revert, narrow scope, update dependents, accept). Never silently patch.

If verification fails: Loop back to Step 2 (re-diagnose). After 3 failures → question architecture, discuss with user.

See references/prevention-gate.md for prevention requirements.

Output: ✓ Step 5: Verified + Prevented - [before/after comparison], [N] tests added, [M] guards added

Step 6: Finalize (MANDATORY — never skip)

1. Report summary: confidence score, root cause, changes, files, prevention measures, side-effect sweep results
2. Activate /mk-project-management skill (MANDATORY) → sync plan/task status (if fix is part of a plan), update progress, hydrate Claude Tasks, generate status report
3. docs-manager subagent → update ./docs if changes warrant (NON-OPTIONAL)
4. TaskUpdate → mark ALL Claude Tasks completed (skip if Task tools unavailable)
5. Ask user if they want to commit via git-manager subagent

IMPORTANT: Skill/Subagent Activation Matrix

See references/skill-activation-matrix.md for complete matrix.

Always activate (ALL workflows):

• mk-scout (Step 1) — understand before diagnosing
• mk-debug (Step 2) — systematic root cause investigation
• mk-sequential-thinking (Step 2) — structured hypothesis formation

Always activate (Step 6 Finalize):

• mk-project-management — MANDATORY for sync-back and progress tracking, every fix

Conditional:

• mk-problem-solving — auto-triggers when 2+ hypotheses fail in Step 2
• mk-brainstorm — multiple valid approaches, architecture decision (Deep only)
• mk-context-engineering — fixing AI/LLM/agent code

Subagents: debugger, researcher, planner, code-reviewer, tester, Bash Parallel: Multiple Explore agents for scouting, Bash agents for verification

Output Format

Unified step markers:

✓ Step 0: [Mode] selected
✓ Step 1: Scouted - [N] files, [M] deps
✓ Step 2: Diagnosed - Root cause: [summary]
✓ Step 3: [Complexity] detected - [workflow] selected
✓ Step 4: Fixed - [N] files changed
✓ Step 5: Verified + Prevented - [tests added], [guards added]
✓ Step 6: Complete - [action taken]

References

Load as needed:

• references/mode-selection.md - AskUserQuestion format for mode
• references/diagnosis-protocol.md - Structured diagnosis methodology (NEW)
• references/prevention-gate.md - Prevention requirements after fix (NEW)
• references/complexity-assessment.md - Classification criteria
• references/task-orchestration.md - Native Claude Task patterns for moderate+ workflows
• references/workflow-quick.md - Quick: scout → diagnose → fix → verify+prevent → review
• references/workflow-standard.md - Standard: full pipeline with Tasks
• references/workflow-deep.md - Deep: research + brainstorm + plan with Tasks
• ../_shared/references/workflow-artifacts.md - Review artifact schema and validator contract
• references/review-cycle.md - Review logic (autonomous vs HITL)
• references/skill-activation-matrix.md - When to activate each skill
• references/parallel-exploration.md - Parallel Explore/Bash/Task coordination patterns

Specialized Workflows:

• references/workflow-ci.md - GitHub Actions/CI failures
• references/workflow-logs.md - Application log analysis
• references/workflow-test.md - Test suite failures
• references/workflow-types.md - TypeScript type errors
• references/workflow-ui.md - Visual/UI issues (requires design skills)

Workflow Position

Typically follows: /mk-debug (after root cause analysis), /mk-scout (after locating affected code) Typically precedes: /mk-code-review (review the fix), /mk-test (validate the fix) Related: /mk-cook (alternative for feature work), /mk-debug (diagnose before fixing)