--- name: fix description: Debug and fix a reported defect, such as a failing build or tests, runtime or console errors, regressions, merge conflicts, red PR checks. Triggers "fix", "broken", "not working", "merge conflict", "fix CI". context: fork --- # Bug Fix Workflow ## Standalone Codex Skip Claude's `!command` interpolation below. Run `git branch --show-current`, `git log --oneline -5`, and `git status --porcelain` explicitly. Create each new agent with `spawn_agent`, continue a live agent with `send_message`, trigger another turn for an idle existing agent with `followup_task`, wait with `wait_agent`, and stop a current turn with `interrupt_agent` only when necessary. Never spawn `codex-verifier` and never run `codex-run.ts` from inside Codex. Writers share the working tree unless the live host explicitly offers isolation. Give every writer non-overlapping ownership and serialize the test-writer, implementer, and verification writer phases. Only read-only reviewers may overlap. Wait until the explorer finishes before starting a test writer; wait until that writer finishes before implementation. Codex implementers are not promised Claude worktree isolation. Use Context7 only when the user configured it. Otherwise use official library docs through native browsing or inspect the pinned local package and state the fallback. This package does not auto-run unpinned registry MCP packages. You are in **Maestro orchestration mode**. Delegate immediately to specialized agents. ## Current State - Branch: !`git branch --show-current 2>/dev/null || echo "unknown"` - Recent commits: !`git log --oneline -5 2>/dev/null || echo "no commits"` - Uncommitted changes: !`git status --porcelain 2>/dev/null | head -10` ## Workflow 0. **Clarify** - If the report admits more than one reading (which surface, which environment, what "fixed" looks like), run clarifying rounds through the host's question tool until no fork is left, before exploring; a report that names the file, the symptom, and the expected behaviour skips this 1. **Explore** - Spawn `explore` agent to understand the affected codebase area 2. **Reproduce** - Spawn `tester` agent to create a failing test if possible 3. **Diagnose** - Analyze findings to identify root cause. Commits named in the bug report are hypotheses, not conclusions — blame the actually-affected file's history before fixing; regressions often ride in earlier on the same branch as the change that got blamed. Before blaming, fetch the team-knowledge index and read any note whose title matches the error's nouns; the fetch command is in docs/knowledge-system.md (fail-open — skip if `gh` is unavailable) 4. **Implement** - Spawn `implementer` agent to fix the issue 5. **Verify** - Spawn `tester` agent to confirm the fix 6. **Learn** - If this was a non-obvious fix, the auto-memory system in `~/.claude/CLAUDE.md` captures it; for team-wide gotchas use `/share-learning` to post to the team-knowledge repo ## Scope Rules Follow CLAUDE.md Guardrails (scope constraint, 2-iteration limit). Only modify files directly related to the bug. **Build after every fix**: Run the build after each individual fix attempt. Never stack multiple untested fixes -- verify green before moving on. If the build breaks, fix *that* before continuing. **Autonomous fix-verify loop**: once the reproducer exists, set `/goal the reproducer test passes and the full suite is green, or stop after 5 attempts` to keep iterating without re-prompting. Keep the 2-iteration scope rule in mind when choosing the stop clause. ## Agent Delegation Spawn explore and tester first — these accept thin prompts because they discover what they need from the codebase: ``` Agent(explore, "Investigate the bug: $ARGUMENTS. Find relevant files, trace the issue.") Agent(tester, "Create a failing test that reproduces: $ARGUMENTS") ``` **Claude: then assemble the implementer prompt from the actual outputs.** The Claude implementer runs in an isolated worktree with no access to prior agent results, so paste real content — not placeholders, not references: - The user's original ask (`$ARGUMENTS`) verbatim - The exact file paths + line ranges `explore` reported (copy them in) - The recommended fix `explore` identified, quoted line-by-line — **not** "based on findings" - The build/test command the tester wrote (or repro steps) - Scope: "only the files listed above; do not refactor adjacent code" Now spawn: ``` Agent(implementer, "") Agent(reviewer, "Quick review of the fix for quality and edge cases") ``` **Standalone Codex branch:** follow the lifecycle and serialization rules at the top. After implementation and verification finish, a fresh read-only `reviewer` supplies the independent pass. Skip the Claude bridge branch below. Any fix that produced a diff gets a cross-model review in parallel with the reviewer, when the Codex bridge is available — a non-Claude family is the cheapest insurance against a logic error you just wrote: ``` Agent(codex-verifier, "Cross-model review of the fix diff. Focus on correctness and security. Report findings by severity.") ``` The bridge fails open: if Codex is unavailable, the reviewer agent alone is fine. If the `codex-verifier` spawn fails, or it reports that Bash was stripped (forked skill contexts), run `bun "$HOME/.claude/src/scripts/codex-run.ts" review` directly instead — never skip the cross-model pass. Skip the implementer step if `explore` reports the bug is non-reproducible or already fixed in current HEAD. ## Output Return a concise summary: - **Root cause**: What was wrong - **Fix applied**: What changed - **Files modified**: List of files - **Verification**: How it was tested - **Learning stored**: If applicable ## Remember - If the fix involves a library API, fetch current docs first using the host-specific path above - Always store non-obvious bug fixes as learnings - Check if similar bugs were fixed before (recall learnings) - Run tests after fixing - On an OS, device, vendor, or network blocker, apply the AGENTS.md stop-loss: about 20 minutes or 30 tool calls, then a written diagnosis (ruled out with evidence, likely cause, ranked next options) instead of another attempt --- ## Variant: Merge Conflicts If the failure is unresolved git merge conflicts (not a code bug), skip the explore/tester loop: 1. Detect conflicts: `git diff --name-only --diff-filter=U` lists conflicted paths. 2. Resolve each conflict with minimal, correctness-first edits. Prefer preserving both sides when safe; otherwise choose the variant that compiles and keeps public behavior stable. 3. Regenerate lockfiles with the package manager (`bun install`, `npm install`, etc.) rather than hand-editing. 4. Run compile, lint, and relevant tests. 5. Stage resolved files and summarize key decisions in the commit message. Guardrails: - Avoid broad refactors while resolving conflicts — separate PR for cleanup. ## Variant: Failing PR CI If the failure is on a pushed branch with an open PR (not a local bug), use `gh pr checks` as the source of truth — it covers all PR-attached checks, not just GitHub Actions: 1. Resolve the PR: `gh pr view --json number,url,headRefName`. 2. Inspect attached checks: `gh pr checks --json name,bucket,state,workflow,link`. 3. For each failed check, fetch logs: - GitHub Actions: `gh run view RUN_ID --log-failed`. - External services: follow the check `link` to the provider. 4. Extract the first actionable error. Apply the smallest safe fix. 5. Push and re-check. The check set can change between runs — re-read `gh pr checks` after every push. Guardrails: - Fix one actionable failure at a time. - If the failure is clearly unrelated to the PR and already fixed on main, merge main into the branch instead of bloating the PR with unrelated fixes. - For flaky checks, retry once and report flake evidence rather than chasing a phantom fix.