Fix

Fix the bug described in $ARGUMENTS.

Parse Arguments

The argument can be:

• Bug description: /fix users can't login when password contains special chars
• Issue link: /fix https://github.com/org/repo/issues/42

Branch

Before writing code, ensure you are on a short-lived branch named fix/. If currently on main/master, create the branch now. See the global Trunk-Based Workflow in root CLAUDE.md for branch/worktree conventions.

Steps

1. Understand the bug

• If given an issue link: fetch it with gh issue view and read the full description, comments, and labels.
• If given a description: use it directly.
• Check for existing docs (CLAUDE.md, README.md, docs/) to understand the project context.

1. Reproduce and locate

• Search the codebase for the relevant code paths (use Grep, Glob, read key files).
• Identify the component, module, or layer where the bug lives.
• If there are existing tests, run them to see the current failure state.
• If reproduction requires specific steps, tell the user what you're doing.

1. Diagnose root cause

• Read the relevant code carefully. Trace the data flow from input to failure point.
• Check git log on the affected files for recent changes that may have introduced the bug.
• Identify the root cause — not just the symptom. Explain it to the user in 1-2 sentences before proceeding.

1. Discover test strategy — Before writing the fix, understand the project's test approach:

a. Check for TDD: Read docs/TECHNICAL_DESIGN_DOCUMENT.md — if it has a Testing Strategy section, follow it. b. If no TDD: Infer from the codebase — look for existing test directories, frameworks, patterns, and naming conventions (same discovery as /feature step 3b). c. Determine which test layers the bug touches — a bug in a pure function needs a unit test; a bug in an API endpoint needs an integration test; a bug in a user flow may need an e2e test.

1. Fix

• Make the minimal change that fixes the root cause. Don't refactor surrounding code.
• Add regression tests at the appropriate layer(s):
• Unit test: Always — proves the root cause logic is fixed
• Integration test: If the bug is at a component boundary (API, database, service interaction)
• E2E test: Only if the bug broke a critical user flow and no e2e coverage existed for it
• Each regression test must fail without the fix and pass with it.
• Run the project's test suite and fix any failures.

1. Run quality checks — Run the project's lint, typecheck, and test commands (check CLAUDE.md or Makefile for the right commands). Run ALL test layers, not just unit tests.

Slice-size gate (trunk-based). Before reporting completion, run git diff --stat main...HEAD (or git diff --stat if working changes are unstaged). If the total diff exceeds ~200 lines (tests included), stop and propose a split via AskUserQuestion — a "fix" that balloons into a refactor is two slices, not one. Never silently leave a >200-line fix in the working tree without the user's explicit override.

1. Stack-aware code review — Prefer Anthropic's official code-review skill (from claude-code-plugins) if installed. Otherwise, run /sec-review for security and spawn an architecture-reviewer subagent for architecture, passing the matching language guide from reviews/ as stack-specific criteria.

This is a self-check, not a trust boundary — reviewer subagents have fresh context, but you (the writer) are reading and acting on their findings. A fresh-session /review or a human reviewer is still expected before merge.

1. Address findings — Fix any HIGH severity issues from the review. For MEDIUM issues, use your judgment.

1. Report and stop. Summarize for the user:

• Root cause — 1–2 sentences on what was actually broken.
• Files changed — git diff --stat output, or a short list.
• Regression tests — which layers (unit/integration/e2e) you added, where they live, how to re-run them.
• Verification — lint / typecheck / test commands run and their tail output.
• Self-review verdict — Security: PASS / REVIEW / FAIL from step 7.
• Issue link — if one was provided, so the user can reference it later.

Suggested conventional-commit subject for when the user commits: fix: (describe the bug, not the change). Example: fix: login fails when password contains special characters.

Then stop. The user reviews the working tree and decides next steps (typically /commit then /pr).

Source & license

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

• Author: 0xrafasec
• Source: 0xrafasec/ai-workflow
• License: MIT

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