Fix

Fix

Diagnose and fix the issue: $ARGUMENTS

Step 0 — Load Extensions

Check for optional overrides. Use Glob to verify each path exists before reading. Do NOT call Read on files that may not exist — skip missing files silently (no output).

1. Global: ~/.claude/skills/fix/SKILL.md + reference.md
2. Project: {project}/.claude/skills/fix/SKILL.md + reference.md
3. Merge: project > global > plugin defaults

Project extensions define framework-specific log paths (e.g., Electron logs in %APPDATA%//logs/, Angular dev server console, etc.).

1. Codex context: Read {PLUGIN_ROOT}/deep-knowledge/codex-integration.md — this skill auto-invokes Codex on unclear root cause (§2 in that doc). Codex MUST be called via {PLUGIN_ROOT}/scripts/codex-safe.sh (5-min hard timeout, see "Hard Timeout & Failure-Tolerance" section), NEVER via the /codex:rescue Agent tool. Detect Codex availability now so Step 6 can act on it.

Step 1 — Triage: what broke?

If $ARGUMENTS is empty or vague, ask ONE focused question via AskUserQuestion:

• "Was ist passiert?" with options like: "Error in console", "Blank screen", "Crash on startup", "Wrong behavior"
• Do NOT ask multiple questions — get the symptom, then investigate.

Step 2 — Check recent changes first

The most common cause of bugs is recent code changes. Before reading logs:

git log --oneline -5
git diff HEAD~1 --stat

If the symptom appeared after a specific commit, focus investigation there.

Step 3 — Discover and read logs

Search for logs automatically — don't assume fixed paths:

1. Glob for **/*.log and **/logs/** in the project root
2. Check project extension for framework-specific log locations
3. Read the most recent log file first — don't read all unless needed

Step 4 — Locate the failure point

Search for the error string via Grep. Follow the stack trace to the originating file and line.

Step 5 — Root cause analysis

Find the actual broken invariant — not just the symptom. Ask:

• What assumption is violated?
• What changed that broke this assumption?
• Is this a data issue, a logic issue, or a configuration issue?

Step 6 — Decision: fix or propose?

| Situation | Action | |-----------|--------| | Trivial fix (typo, missing import, off-by-one) | Fix immediately, report what was wrong | | Clear root cause, low risk (single file) | Fix immediately, explain root cause | | Clear root cause, medium risk (multiple files) | Propose fix via AskUserQuestion | | Unclear root cause | Present findings, propose 2-3 hypotheses, ask user. Automatically invoke Codex via Bash: bash "${CLAUDE_PLUGIN_ROOT}/scripts/codex-safe.sh" "" for parallel independent investigation. Handle exit codes per codex-integration.md "Hard Timeout" section: rc=124 → continue without Codex findings, note "Codex timed out"; rc=126/127 → skip silently. Never use the /codex:rescue Agent tool. | | Architectural issue | Report root cause, do NOT fix — recommend planned approach |

Step 7 — Implement fix (if appropriate)

Before writing the fix, run the inline pre-mortem from {PLUGIN_ROOT}/deep-knowledge/pre-mortem.md — with special focus on the question: "How could this fix break something else?" A fix that resolves the reported symptom while regressing a sibling path is a net loss. Cover:

• Which other callers rely on the behaviour I'm about to change?
• Does this fix paper over a deeper invariant violation?
• Could the root cause reappear in a different branch of the same code path?

Apply the fix. Then verify:

1. The specific error no longer occurs
2. Related functionality still works
3. Run tests if available

Step 8 — Report

Always report:

• Root cause: the exact file:line where the failure originates
• What was wrong: the broken assumption or logic error
• What was fixed: the change made (or proposed)
• Confidence level: "Sicher behoben" vs. "Hypothese — braucht Verifizierung"

Step 9 — Completion Card

Call mcp__plugin_devops_dotclaude-completion__render_completion_card with the variant that matches the outcome — variant is NOT fixed for this skill:

| Outcome | Variant | |---------|---------| | Fix applied + app/service can be tested | test (prefer — include userTest steps) | | Fix applied, no user-visible testing needed | ready | | Diagnosed only, no fix made (proposal/architectural) | analysis | | Could not reproduce / infeasible / aborted | aborted (include cta.reason) |

Pass: variant, summary, lang, session_id, changes (file:line of root cause → what was fixed), and state when files changed.

Output the returned markdown VERBATIM as the LAST thing in the response — nothing after the closing ---.

Rules

• Root-cause first — never propose symptom-only workarounds unless explicitly asked.
• No fallbacks by default — propose as alternatives if relevant.
• Report the exact file:line where the failure originates.
• If git bisect would help, offer it as an option.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Jerry0022
• Source: Jerry0022/dotclaude
• License: MIT

Install and usage instructions live in the source repository linked above.