interface:
  display_name: "Team Fix"
  short_description: "Run the compressed bug-fix pipeline"
  default_prompt: "Use $team-fix to run the compressed bug-fix pipeline."

# Bug-fix playbook

## Root-cause correction

Read and apply [Fix Root Causes](../../principle-fix-root-causes/SKILL.md). It owns the debugging invariant: reproduce before fixing, ask why to the changeable cause, resist guards that silence a crash, fix the pattern rather than the instance, instrument instead of guessing, and suspect stale persistent state after a restart. Use the diagnostic and test-driven procedures below for their reproduction, diagnosis, and verification steps. Add an absence guard only when absence is legal; otherwise correct why the value is missing. Search for sibling occurrences: fix only those inside approved scope and record the rest without editing them. Make the smallest scoped correction and verify the reproduction and affected callers.

## Triage

Classify first:

- **Product:** continue with the reproduce-fix-verify discipline below.
- **Test impl:** fix the test separately; never change production for a bad test.
- **Infra:** fix the environment, not product behavior.
- **Tooling:** fix the runner or build system.

Intermittency is not a fifth bucket. Read [diagnosis reference](../references/diagnosis.md) to reproduce it, and its Root Cause Analysis (5 Whys) for non-obvious causes.

## Step 1: Reproduce

Before any code change, reliably reproduce the failure. Record exact inputs, actual and expected behavior, and affected files/functions. Observe; do not hypothesize a fix.

## Step 2: Write a failing test

Write a test that:

- **Reproduces the bug** with the exact scenario;
- asserts correct behavior, not current behavior;
- fails through the intended assertion, not infrastructure;
- names the behavior, not a bug number or method.

Run it and the existing suite. The new test must fail for the right reason and all prior tests must pass. Do not continue without this Red state.

## Step 3: Fix minimally

Change only code causing the defect. Do not refactor, extend scope, alter the test, or fix adjacent bugs. Run tests after each change. Green means the new and existing tests pass.

## Step 4: Verify

1. Run the full suite; undo and investigate any regression.
2. Re-run the original inputs.
3. Search for related instances and file them separately.
4. Mutation-check the regression test: temporarily revert one fix line and require the new test to fail. Restore it. If it stays green, strengthen the assertion or reproduction.

## Commits

Keep two atomic commits:

```text
test: reproduce <bug description> with failing test
fix: <minimal description of the fix>
```

The fix targets the root cause. It is not a refactor, feature, or workaround.

## Input

`$ARGUMENTS` may be:

- A ticket identifier (e.g. `ENG-1234`) — set aside as `ticketId` on
  `1-task.md`.
- An issue URL — fetched through `gh issue view` to extract title and body.
- Free-form text — treated as the bug description.

When `$ARGUMENTS` is empty, **discover, do not demand**: ground in repo
context before asking. Read recent `git log` activity and the repo's
`README` / `CLAUDE.md` to surface the likely failing area, then use
`AskUserQuestion` with labeled options to fill any genuine gap. Never
bare-stop with a plain "describe the bug" demand when context is available.

## When to Use

Use `/team-fix` when:

- The bug is well-understood and the affected code is known
- The fix is likely contained to a small number of files
- No architectural decisions are needed — this is a defect correction

Use `/team` (full QRSPI pipeline) when:

- The root cause is unknown and needs investigation
- The fix requires designing new behavior or APIs
- Multiple subsystems may be involved
- The user wants to align on the approach before code is written

## Pipeline

```
WORKTREE → REPRODUCE → RED (failing test) → GREEN (minimal fix) → VERIFY → SHIP
```

No Question. No Research. No Design. No Structure. No Plan. No approval gate.

## Setup

1. **Resolve the input** to a bug description first. On empty `$ARGUMENTS`,
   ground in repo context, then ask only for genuine gaps, per the
   **"discover, do not demand"** rule in `## Input`. A ticket id or issue
   URL is resolved as `## Input` describes (`gh issue view` for URLs).
2. **Move the ticket to in-progress.** If the input resolved to a ticket id
   or issue, move that ticket to its tracker's in-progress state — this is
   the first action of the fix, before any other work begins. Read
   [tracking rules](../team-pr/references/tracking.md) and
   follow its ticket-lifecycle rules, best-effort —
   skip silently when no tracker mechanism exists. Never block the pipeline
   on a tracker update.
3. **Derive `<id>`** the same way `/team` does (ticket-prefixed or
   date-prefixed kebab slug).
4. **Run the WORKTREE phase** (`## Worktree` below) before anything else
   touches the working tree. It settles which branch the fix commits to, so
   it must finish before the artifact directory is authored.
5. **Create `docs/plans/<id>/`** inside the resolved worktree, and write a
   minimal `docs/plans/<id>/1-task.md` with the standard frontmatter
   (`topic`, `date`, `phase: task`, `ticketId`) plus a brief description
   of the bug. The `topic` value is the kebab portion of `<id>` — i.e.
   `<id>` minus the `<TICKET>-` or `<YYYY-MM-DD>-` prefix. Never use the
   ticket id, the date, or a re-worded description as the topic.
   `ticketId` lives only on `1-task.md`. This is the single durable record
   for the fix and lets any `/team-*` command pick it up if interrupted.
6. **Seed the TodoWrite ledger** with the bug-fix phases:
   `Worktree → Reproduce → Red (failing test) → Green (minimal fix) → Verify → Ship`.
   Mark `Worktree` as `in_progress`.
   See [execution rules](../team/references/execution.md) for the per-step tracking convention agents follow within each phase.

## Worktree

This is the **leading** phase, and the one hard gate in the pipeline. A fix
never commits to the default branch. Everything after this phase runs in the
checkout this phase resolves.

### Branch gate

Run this block first. It prints `on-default` when HEAD is the repository's
default branch, and `ok <branch>` otherwise:

```sh
# Branch gate — a fix never commits to the default branch.
default="$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null)"
default="${default#origin/}"
if [ -z "$default" ]; then
  # No origin/HEAD (no remote, or an unset remote head): fall back to whichever
  # conventional default-branch name actually exists locally.
  for candidate in main master; do
    if git show-ref --verify --quiet "refs/heads/$candidate"; then
      default="$candidate"; break
    fi
  done
fi
head="$(git rev-parse --abbrev-ref HEAD)"
if [ -n "$default" ] && [ "$head" = "$default" ]; then
  echo "on-default"
else
  echo "ok $head"
fi
```

- **`ok <branch>`** — HEAD is already on a non-default branch. Check
  whether it is the head of an open pull request:
  `gh pr view --json number,title --jq '"#\(.number) \(.title)"' 2>/dev/null`.
  No open PR, or one whose title names this bug → reuse the branch in
  place: create no worktree and no new branch, and announce the reuse
  once: "Continuing on branch `<branch>`." This is also the linked-worktree
  reuse case in `skills/team-worktree/SKILL.md` → "Detect existing
  worktree". An open PR for other work → treat it as `on-default`: a fix
  never rides on another PR's branch, so isolate per **Isolate** below.
- **`on-default`** — isolate before the first commit, per **Isolate** below.

### Isolate

Create the home worktree on branch `<id>` off `origin/HEAD`, exactly as
`/team`'s leading WORKTREE phase does. Call the Skill tool with
`team-worktree` for the single-repo
"Create the worktree(s)" procedure, and read the
[worktree playbook](../team-worktree/playbooks/worktree.md) for the topology:

```sh
git fetch origin --quiet
git worktree add .claude/worktrees/<id> -b <id> origin/HEAD
```

Then continue the fix inside that worktree.

**Edge — branch `<id>` already exists** (re-invocation): reuse the worktree
that holds it. Do not recreate either one.

**Edge — worktree creation fails**, on a shallow clone, certain CI systems,
or permissions. Isolation is best-effort; **the branch is not.** Report the
failure loudly, then branch in place and keep going:

```sh
git switch -c <id>
```

Re-run the branch gate afterward. It must print `ok <id>`. If the run cannot
get off the default branch at all, stop and report — that is the one
condition that aborts before any work, because the alternative is committing
a fix to the default branch.

## Execution

Read [bug-fix playbook](playbooks/bug-fix.md) before proceeding, and follow its
reproduce-red-green-verify discipline.

When the failure is non-obvious, read the [diagnosis reference](references/diagnosis.md) and drill its
**Root Cause Analysis (5 Whys)** causal chain to the root before proposing a
fix. The fix lands at the root, never at the symptom, per
[bug fix rules](playbooks/bug-fix.md).

When the buggy behavior looks deliberate — a guard, a threshold, a
workaround, anything an author plausibly wrote on purpose — call the
Skill tool with `why` on that code before changing it. A "bug" that was a
deliberate trade-off needs its constraint preserved, not deleted; the
rationale findings become inputs to the minimal fix.

Mark each TodoWrite item `in_progress` when you begin and `completed`
when it finishes.

**Mechanical gate between Red and Green:** the new test must fail with an
assertion failure, not a crash, and the project's static checks (typecheck,
lint, build) must pass. Do not proceed to the fix until both are confirmed. A
runner that executes tests without type-checking them leaves a red type checker
behind a green suite.

## Ship

1. Commit in two commits:
   - `test:` commit with the failing test
   - `fix:` commit with the minimal fix
2. **Open a draft PR automatically — do not stop to ask.** The WORKTREE
   phase already put the run on a non-default branch. Re-assert the branch gate
   first — `git rev-parse --abbrev-ref HEAD` must not name the default branch.
   If it does, push nothing and report: the commits are local and recoverable;
   a push to the default branch is not. Otherwise push that branch and open the
   PR as a **draft** (`gh pr create --draft`).
3. **Screenshots for a UI-impacting fix.** Read the
   [ux reviewer brief](../code-review/references/ux-reviewer.md) and apply its
   `## Screenshot Capture (UI projects)` UI-impact gate to the full branch
   diff. A backend fix that changes the interface counts. When UI impact is
   uncertain, capture. Only a fix that does not change the interface attaches
   nothing. When it does, run the brief's capture procedure into
   `docs/plans/<id>/screenshots/`, then call
   the Skill tool with `pr-screenshots` and attach the PNGs. Build the entries
   file and read `result.json` per
   [Screenshot Upload](../team-pr/references/04-screenshot-upload.md), with the
   run's `docs/plans/<id>/` directory as the `$ARGUMENTS` that reference names.
   A capture that cannot run degrades to the note; it never blocks the PR.
4. **Ticket — link now, in-review when ready.** If `ticketId` is non-null in
   `1-task.md`'s frontmatter, read [tracking rules](../team-pr/references/tracking.md) and
   apply its ticket-lifecycle rules: link the PR to the ticket through the
   conditional closing footer, keep the ticket in-progress while the PR is a
   draft and move it to in-review only once the PR is marked ready for
   review, and never close the ticket by hand — the link auto-closes it on
   merge. Best-effort. Never block. Surface the `ticketId` in the completion
   report.
5. Mark all TodoWrite items complete.

## Aborting

If reproduction fails: report "Bug could not be reproduced with the
given description." and stop. Do not write a test for an unconfirmed bug.

If the fix is larger than expected (touching many files, requiring new
APIs, or revealing an architectural problem): stop, report the scope,
and recommend switching to the full `/team` pipeline.

# Bug diagnosis reference

Read this when a failure is non-obvious, intermittent, or whose first fix would be a guess. Never skip to fixing: understand the cause first.

## 4-phase investigation

### Phase 1: OBSERVE

Gather evidence before forming any theory.

- Read error messages and stack traces completely.
- Reproduce the failure and record exact steps.
- Collect multiple data points: logs, stack traces, test output, runtime state.
- Note what still works — the boundary between working and broken narrows the search.
- Record timestamps and sequence: what changed just before, in git, deploys, or dependencies. When the trail leads to code that looks deliberate and the question becomes "why was it written this way" rather than "what broke", that is design-rationale archaeology — `skills/why/SKILL.md` owns it.
- Treat intermittency as evidence, not noise. Record the failure rate, environment variance, and the timing, concurrency, resources, and shared state in the path.

Do not hypothesize during OBSERVE.

### Phase 2: HYPOTHESIZE

List at least two explanations that explain ALL the observed evidence. Rank common causes before exotic ones; configuration before code; environment before logic. State what each hypothesis predicts, so a discriminating test can prove it wrong.

### Phase 3: TEST

Run a discriminating experiment that eliminates a hypothesis under either outcome. Change one variable at a time. Record expected and actual results immediately. Keep disproved theories closed unless new evidence appears. With a working baseline and failing tip, use `git bisect`; apply the same binary search to config, dependency, or feature-flag ranges.

### Phase 4: CONCLUDE

Identify the root cause, not the proximate symptom. Make the original reproduction pass without changing unrelated behavior. Search for related instances and document evidence and eliminated theories.

#### Root Cause Analysis (5 Whys)

Ask why from symptom to a cause you can change. Anchor every link in OBSERVE evidence; branch when a link has multiple causes; stop at a cause you can change. The chain can be length one — five is the technique's name, not its quota. Fix the root link, not a proximate link above it. The mutation check proves the regression test depends on the fix. Blame the process, not the person.

## Escalation rules

### After 3 failed hypotheses

Widen to adjacent systems, environment differences, questioned evidence, and component interactions.

### When to escalate to the user

Escalate only after plausible hypotheses are exhausted, required environment is inaccessible, reproduction remains unreliable, or the cause is external. Give observed evidence, tested hypotheses, eliminated explanations, and remaining possibilities. Never return only "I do not know."