fix

Reproduce-first bug resolution. Capture bug in failing regression test, apply minimal fix, verify via quality stack and review loop.

NOT for:

• CI-only failures with no local traceback — use /develop:debug --ci-run <run-id> first
• production incidents without any CI run or traceback (use /foundry:investigate (requires foundry plugin))
• .claude/ config issues (use /foundry:audit (requires foundry plugin))
• non-Python projects (JS/TS/Go/Rust) — toolchain assumes pytest; use language-native toolchain instead
• CSS/JS-only frontend changes (no Python source touched) — use /develop:feature for new frontend work or direct editing for surgical CSS/JS fixes; this skill's regression-test gate assumes pytest

Agent Resolution

_PATHS=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/develop}/bin/dev_shared_resolve.py" --foundry 2>/dev/null)  # timeout: 5000
_DEV_SHARED=$(echo "$_PATHS" | head -1)
_FOUNDRY_SHARED=$(echo "$_PATHS" | tail -1)

Read $_DEV_SHARED/agent-resolution.md. Contains: foundry check + fallback table. If foundry not installed: use table to substitute each foundry:X with general-purpose. Agents this skill uses: foundry:sw-engineer, foundry:qa-specialist (conditional — outcome C only), foundry:challenger.

Anti-Rationalizations

Read $_DEV_SHARED/task-hygiene.md.

Project Detection

Read $_DEV_SHARED/runner-detection.md — sets $TEST_CMD (full suite) and $PYTEST_CMD (pytest flags). Run at skill start.

Optional --plan <path>: if $ARGUMENTS ends with --plan <path>, read plan file first. Extract Affected files, Risks, Suggested approach — use to populate Step 1 analysis instead of cold codebase exploration. Skip agent feasibility re-check (already done in /develop:plan). Store plan path as PLAN_FILE.

Read $_DEV_SHARED/preflight-helpers.md — execute --plan path extraction; sets $PLAN_FILE.

Checkpoint init: run DEV_DIR=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/develop}/bin/dev_run_dir.py" 2>/dev/null) # timeout: 5000 to create .developments/<TS>/ and capture path. Write checkpoint.md inside $DEV_DIR. After each major step (1, 2, 3, 4), append step: N — completed to $DEV_DIR/checkpoint.md. On skill start, check for existing .developments/*/checkpoint.md — offer resume from last completed step if found.

Fix Mode

Optional --diagnosis <path>: if provided (from preceding /develop:debug session), read diagnosis file first. Skip Step 1 codebase analysis — root cause, suspect files, and evidence pre-populated from diagnosis file. The Challenger gate still applies: proceed from pre-populated root cause through challenger gate, then to Step 2. Do NOT skip the challenger gate — it reviews the fix approach, not just root cause discovery.

DIAG_FILE=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/develop}/bin/diagnosis_parse.py" "$ARGUMENTS" 2>&1) || { echo "$DIAG_FILE"; exit 1; }  # timeout: 5000

Diagnosis file format: see /develop:debug Final Report section for canonical field definitions (Root Cause, Suspect Files, Evidence).

Flag parsing

Parse flags into actual shell variables (not prose) so downstream blocks see correct values. Persist to temp files for cross-block access (bash state lost between Bash() calls):

# timeout: 5000
CHALLENGE_ENABLED=true
ACCEPT_NO_PLAN=false
SEMBLE_ENABLED=false
TEAM_MODE=false
[[ " $ARGUMENTS " == *" --no-challenge "* ]] && CHALLENGE_ENABLED=false
[[ " $ARGUMENTS " == *" --accept-no-plan "* ]] && ACCEPT_NO_PLAN=true
[[ " $ARGUMENTS " == *" --semble "* ]] && SEMBLE_ENABLED=true
[[ " $ARGUMENTS " == *" --team "* ]] && TEAM_MODE=true
echo "$CHALLENGE_ENABLED" > ${TMPDIR:-/tmp}/dev-challenge-enabled
echo "$ACCEPT_NO_PLAN"    > ${TMPDIR:-/tmp}/dev-accept-no-plan
echo "$SEMBLE_ENABLED"    > ${TMPDIR:-/tmp}/dev-semble-enabled
echo "$TEAM_MODE"         > ${TMPDIR:-/tmp}/dev-team-mode

Downstream blocks read back, e.g. TEAM_MODE=$(cat ${TMPDIR:-/tmp}/dev-team-mode 2>/dev/null || echo false).

CODEMAP_ENABLED raw flag — scan $ARGUMENTS: --no-codemap → off; --codemap (without preceding --no-) → strict; else → auto. Substitute value below.

CODEMAP_ENABLED=$("${CLAUDE_PLUGIN_ROOT:-plugins/develop}/bin/codemap-resolve" "<off|strict|auto>") || exit 1  # timeout: 5000; substitute raw flag from rule above
echo "$CODEMAP_ENABLED"   > ${TMPDIR:-/tmp}/dev-codemap-enabled

Unsupported flag check — after all supported flags extracted, scan $ARGUMENTS for remaining --<token> tokens. If found: print ! Unknown flag(s): \--<token>`. Supported: `--plan`, `--team`, `--diagnosis`, `--no-challenge`, `--codemap`, `--no-codemap`, `--accept-no-plan`, `--semble`.then invokeAskUserQuestion` — (a) Abort (stop, re-invoke with correct flags) · (b) Continue ignoring (skip unknown flags, proceed). On Abort: stop.

Preflight — if CODEMAP_ENABLED=true:

Read $_DEV_SHARED/preflight-helpers.md — execute codemap + semble preflight if respective flags set.

Team Mode Branch

If TEAM_MODE=true: execute team workflow now — do not proceed to Step 1.

Root cause unclear after initial triage, OR bug spans 3+ modules and user accepted "Proceed anyway" at scope gate: use this path.

Coordination:

1. Lead broadcasts current evidence: {bug: <description>, traceback: <key lines>}
2. Spawn foundry:sw-engineer x 2-3 (model=opus) — each investigates a distinct root-cause hypothesis independently. Read $_DEV_SHARED/preflight-helpers.md §Team Spawn Template — replace [ROLE_PHRASE] with [bug description], [FILE_SLUG] with fix-hypothesis.
3. Each teammate investigates independently — claims hypothesis; returns full output to file (file-based handoff protocol).
4. Lead facilitates cross-challenge between competing analyses.
5. Lead synthesizes consensus root cause, then proceeds with Steps 2-4 (regression test, fix, review loop) alone.

Compute run directory and create health sentinel:

# timeout: 5000
mapfile -t _run < <(python "${CLAUDE_PLUGIN_ROOT:-plugins/develop}/bin/setup_worktree.py" --sentinel fix-team-check)
TS="${_run[0]}"
FIX_TEAM_DIR="${_run[1]}"
echo "$TS" > ${TMPDIR:-/tmp}/dev-fix-team-ts
trap 'rm -f ${TMPDIR:-/tmp}/fix-team-check-$TS' EXIT

Spawn 2 teammates in parallel using Agent() tool:

IMPORTANT: before building each spawn prompt below, resolve all shell variables to literal values — embed resolved literals, not variable references, in the prompt strings:

# Resolve variables to literals for spawn prompt embedding  # timeout: 5000
_SPAWN_DEV_SHARED="$_DEV_SHARED"
_SPAWN_TS="$TS"
_SPAWN_ARGS="$ARGUMENTS"

Teammate 1 — foundry:sw-engineer (model=opus) — hypothesis A: substitute $_SPAWN_DEV_SHARED, $_SPAWN_TS, and $_SPAWN_ARGS with resolved literals before constructing prompt: "You are a foundry:sw-engineer teammate investigating a bug fix. Read <_DEV_SHARED_LITERAL>/preflight-helpers.md §Team Spawn Template. Bug: <ARGUMENTS_LITERAL>. Evidence: {bug: <description>, traceback: <key lines>}. Your task: investigate hypothesis A — claim one distinct ro