fix

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

1. 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. When a round runs and the user named no Linear issue, add one question: create one now (recommended: yes)? Create it per the ship skill's "Linear issue" step and put its ID in the branch name. Never open a round only for this: /ship creates the issue anyway
2. Explore - Spawn explore agent to understand the affected codebase area
3. Reproduce - Spawn tester agent to create a failing test if possible
4. 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)
   • A prediction must name something not yet looked at (another code path, an observable the first hypothesis did not touch). One that restates the symptom or only re-reads the suspect line is rejected.
   • The user's own uncommitted edits are hypothesis 1. Test them: git stash push -u -m <unique-tag>, rerun the reproducer, then restore only the entry this run created, found by its tag (git stash apply --index it so staged state comes back too, and drop it only after the apply succeeds). Never pop other entries. If the push reports nothing to save, restore nothing.
   • No fix until the causal chain from trigger to symptom is complete, with file:line evidence at each link. "Somehow X leads to Y" is a gap.
5. Implement - Spawn implementer agent to fix the issue
6. Verify - Spawn tester agent to confirm the fix
7. 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