fixit

name	fixit
description	Use when the user reports a bug or issue that can be fixed without blocking their current work — backgrounds an agent in a worktree to fix and merge back without breaking stride
tags	["workflow"]

Fixit

One-shot background bug fix. Describe the bug, an agent spins up a worktree, fixes it, merges back, and reports what it did.

Arguments

• $ARGUMENTS — Required. Natural language description of the bug to fix.

If no arguments provided, reply: Usage: /fixit <describe the bug> and stop.

Context

• Current branch: !git branch --show-current 2>/dev/null || echo '(not in a git repo)'
• Project root: !pwd
• Main repo root: !git worktree list --porcelain 2>/dev/null | head -1 | sed 's/^worktree //'
• OpenSpec project: !test -d openspec && echo "yes" || echo "no"
• Active OpenSpec changes: !test -d openspec && openspec list 2>/dev/null || echo '(n/a)'
• Sandbox mode: !~/.claude/bin/repo-writable-check.sh

---

Instructions

1. Triage (≤30 seconds, main thread)

You are a dispatcher, not a debugger. Do NOT read source code or investigate.

• Parse the user's description
• Run up to 3 Glob/Grep calls (paths only, no content reads) to locate likely files
• If the description is ambiguous, echo back a 1-line interpretation and proceed — don't block on clarification

2. Create Worktree

Sandbox-mode branch. Check the Sandbox mode: value from the Context block.

• If sandbox: read skills/agent-driven-development/sandbox-mode.md and follow its dispatch tiers — it auto-selects the highest-capability path available (orchestration-managed, then host task-spawning, then staged-command) — instead of running git worktree add from this session. After dispatching via the sandbox path, skip to step 4 (Confirm to User). The On Agent Completion section below also defers to sandbox-mode.md for the merge and (if OpenSpec) archive paths.
• If ok: continue with the steps below as normal.

Resolve the main repo root first — fixit may be invoked from inside a worktree. Worktrees must be created relative to the main repo, never nested inside another worktree.

MAIN_REPO=$(git worktree list --porcelain 2>/dev/null | head -1 | sed 's/^worktree //')

# Pick a short slug from the bug description
SLUG="fixit-<short-slug>"
git worktree add -b "$SLUG" "$MAIN_REPO/.claude/worktrees/$SLUG" HEAD

If the branch already exists, clean up first:

git worktree remove "$MAIN_REPO/.claude/worktrees/$SLUG" --force 2>/dev/null
git branch -D "$SLUG" 2>/dev/null

3. Dispatch Background Agent

Use the Agent tool with run_in_background: true and mode: "bypassPermissions":

## Bug Fix: <title>

### Context
- Main repo root: <$MAIN_REPO>
- Working directory: <worktree path>
- Branch: <SLUG>

### Bug Description
<user's description>

### Files Likely Involved
<from triage search, or "Explore the codebase to find the relevant code">

### Spec-aware project
<if openspec/ directory exists at the project root>
This project uses OpenSpec.

**Active OpenSpec change:** <from the `Active OpenSpec changes` Context value — name the in-flight change this fix most plausibly belongs to, or "none">. If one is named, add any spec delta to that change's folder rather than scaffolding a new one.

**Classify the bug before writing any code:**

- **Code drift** – the spec is correct; the code diverged from it.
- **Spec gap** – the spec does not cover the case this bug exposes; the expected behavior is new or missing.

**Code drift path:**
1. Identify the relevant base spec at `openspec/specs/<capability>/spec.md`
2. Confirm the spec describes the correct behavior the code should follow
3. Fix the code so it matches the existing base spec
4. Write or update a test that validates the correct behavior
5. Run all tests
6. Commit with `--no-verify` (no delta update is needed; include a note in the commit message explaining this is a drift fix, not a new capability)

**Spec gap path:**
1. Identify the capability name from the description, affected files, or failing test
2. Check for an active change FIRST: run `openspec list`. If an unarchived change already covers this capability/area (and especially if `Active OpenSpec change` was named in the Context above), add your delta to *that* change's folder — do not scaffold a new one. Fragmenting deltas for one body of work across two change folders is wrong. Only if no relevant active change exists, scaffold one: `openspec new change fix-<short-slug>`.
3. Write a delta under the chosen change folder at `specs/<capability>/spec.md` that adds or modifies the relevant requirement and at least one scenario
4. Validate: `openspec validate <change-name> --strict`
5. Write a failing test that captures the new scenario
6. Implement the fix to pass the test
7. Run all tests
8. Commit with the delta file included alongside the code

Either path: include all delta or spec files (if any) in the commit.
</if openspec/ directory exists>
<if no openspec/ directory>
No spec management required. Implement the fix directly.
</if>

### Debugging References
Read these before investigating:
- `skills/debug/root-cause-tracing.md` — systematic hypothesis-driven debugging
- `skills/debug/defense-in-depth.md` — making fixes robust against related failures

### Instructions
Implementation follows agent-driven-development pattern for a single task. Read `skills/agent-driven-development/SKILL.md`.

1. Explore the codebase to understand the problem (use root-cause-tracing approach)
2. If this is a spec-aware project (see above), follow spec-first order
3. Otherwise: implement the fix directly
4. Follow TDD discipline per `skills/test-driven-development/SKILL.md`
5. Self-review per `skills/verification-before-completion/SKILL.md`
6. Run tests if test infrastructure exists (check Makefile, README, package.json, etc.)
7. Commit with message: "Fix: <short description>"
8. If you can't figure it out, commit nothing and report what you tried
9. Report status: DONE | DONE_WITH_CONCERNS | BLOCKED

### Constraints
- Work ONLY in your worktree directory
- Follow existing codebase patterns
- Keep the fix minimal — don't refactor surrounding code
- If tests fail after your fix, investigate and resolve
- Apply defense-in-depth: make the fix robust, not just sufficient

4. Confirm to User

Print one line and move on:

Fixit dispatched — agent working on "<short title>" in background.

Do NOT wait for the agent. Return control to the user immediately.

---

On Agent Completion

Sandbox-mode branch. If dispatch ran in sandbox mode (per step 2), the worker is either a host-spawned task or a user-driven shell session. The calling session cannot merge into MAIN_REPO's default branch — but if it is itself on a feature branch, it CAN land the fix by merging the worker's branch into that branch locally (the worktree is writable). Follow Tier 3 of skills/agent-driven-development/sandbox-mode.md, which handles both the local-merge and staged-merge cases, and for OpenSpec projects the async verify-then-archive section. The two-stage review below still runs (read against the worker's pushed branch); only the landing and archive steps change.

When the background agent reports back:

Success Path — Two-Stage Review

Before merging, run both reviews from agent-driven-development (see prompt templates in skills/agent-driven-development/):

1. Spec reviewer — dispatch with spec-reviewer-prompt.md. Checks the fix matches spec intent. If issues found, implementer fixes, reviewer re-reviews until clean.
2. Code quality reviewer — dispatch with code-quality-reviewer-prompt.md. Checks code quality. Same fix/re-review loop.

Spec compliance must pass before code quality review begins.

Once both reviews pass:

git checkout <original-branch>
git merge <SLUG> --no-edit

If merge succeeds:

git worktree remove "$MAIN_REPO/.claude/worktrees/$SLUG" --force
git branch -D "$SLUG"

Report to user:

✅ Fixit merged: <short title>
  <1-2 line summary of what the agent changed>
  📋 Specs: <Updated (openspec/changes/<name>/specs/<cap>/spec.md) | No behavioral changes | Code drift fixed | Skipped (no openspec/ dir)>

If merge conflicts:

git merge --abort

Report to user:

⚠️ Fixit conflict: <short title>
  Worktree preserved at $MAIN_REPO/.claude/worktrees/<SLUG> for manual resolution.

Failure Path

If the agent couldn't fix it:

git worktree remove "$MAIN_REPO/.claude/worktrees/$SLUG" --force
git branch -D "$SLUG"

Report to user:

❌ Fixit failed: <short title>
  <brief reason from agent>

---

Rules

• Never read source code in the main thread — agents do that
• Never investigate root causes — agents do that
• Never block the user — dispatch and return immediately
• One bug, one agent, one worktree — no queues, no sessions
• Triage search budget: max 3 Glob/Grep calls, zero file reads