---
name: ayf:fix
description: |
  Investigate and fix a bug under the Iron Law: reproduce, isolate, hypothesize, fix, verify — touching nothing unrelated.
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Agent
  - AskUserQuestion
---

# /fix -- Investigate and Fix (Iron Law)

Takes a bug report (error message, broken behavior, failing test) and runs the full
cycle: reproduce, isolate the root cause, form a hypothesis, apply the minimal fix,
and verify it. Replaces the need for separate debug, fix-bug, investigate, and
troubleshoot commands.

## THE IRON LAW — read before touching anything

A bug fix that breaks something else is not a fix. These rules are absolute. If a rule
is in your way, stop and ask the human — do not work around it.

1. **Never delete or weaken a passing test.** A test that fails after your change is
   evidence, not an obstacle. If a test now fails, either your fix is wrong or the test
   encodes a requirement you are breaking. Never `skip`, `xfail`, comment out, or loosen
   an assertion to make the suite green.
2. **Never widen an error handler to hide the symptom.** Do not broaden a `catch`, add a
   bare `except:`, swallow an error, add `|| true`, or bump a timeout to mask the bug.
   Fix the cause, not the alarm.
3. **Never change unrelated code.** No drive-by refactors, renames, reformatting, or
   "while I'm here" cleanups. The diff must contain only lines required to fix this bug.
4. **The smallest change that fixes the root cause wins.** If your diff is large, you are
   probably treating a symptom.

## Input

The human describes the bug:
- Error message or stack trace
- What was expected vs what actually happened
- Steps to reproduce (if known)

If invoked proactively (see the trigger section at the end), the "bug report" is the
tool output that tripped the trigger — quote it back and confirm before proceeding.

## Phase 1: REPRODUCE  *(directory freeze — READ ONLY)*

From this phase until you enter Phase 4, you are under a **directory freeze**: you may
Read, Glob, Grep, and run read-only/observational commands, but you write **no files**.
Investigation never edits code. Announce the freeze so the human knows you are looking,
not touching.

1. Run the failing command/test to confirm the bug is real and observable **now**.
2. Capture the exact failure: message, stack trace, exit code. Copy it verbatim.
3. If you cannot reproduce it, say so and ask the human for the missing conditions
   (env, data, steps). Do not guess-fix a bug you have not seen fail.

Output:
```
Reproduced: yes/no
Command: [what you ran]
Observed failure: [message + exit code]
```

## Phase 2: ISOLATE  *(directory freeze still in effect)*

1. **Locate:** search for the error message / failing assertion in the codebase.
2. **Trace:** follow the call chain from the failure back toward its origin.
3. **Narrow:** find the smallest unit (function, line, condition) that, when exercised,
   produces the failure. Use logging/prints in a scratch run only — never commit them.
4. **Read the neighborhood** to understand intended behavior before deciding what "correct"
   means. A fix that contradicts the surrounding contract is a new bug.

For a hard-to-pin bug, spawn an independent subagent (Agent) with only the observable
failure and no theory of yours — an unbiased tracer finds what you rationalized away.

Output:
```
Root cause: [one sentence]
Location: [file:line]
Why it happens: [mechanism, not just the symptom]
```

## Phase 3: HYPOTHESIZE  *(directory freeze still in effect)*

1. State the fix as a falsifiable hypothesis: "The bug is X; changing Y at `file:line`
   will make the reproduction pass because Z."
2. **Declare the affected directories/files** — the exact, minimal set you intend to edit.
   This declaration ends the read-only freeze and scopes what Phase 4 may touch. If the
   fix would reach outside your agent's declared scope, stop and ask the human first.
3. Present the root cause + hypothesis + intended file set to the human and wait for
   "go" or an alternative direction. Do not edit before approval.

## Phase 4: FIX  *(freeze lifted — only within the declared set)*

1. **Apply** the minimal change — fix the bug, do not refactor the neighborhood (Iron
   Law 3 + 4). Every edited line must be within the file set declared in Phase 3.
2. **Verify:** run the exact reproduction from Phase 1. It must now pass.
3. **Check regressions:** run the related test group, then the full suite. Nothing that
   passed before may fail now (Iron Law 1).
4. If the fix did not work, return to Phase 2 with what you learned. After 3 failed
   fix attempts, stop and escalate to the human with everything you have found.
5. **Commit** atomically once green: `fix: [what was fixed]`.

## Phase 5: PREVENT

After the fix is verified, briefly assess:
- Should a regression test lock this in? If yes, add it and commit separately:
  `test: prevent regression for [bug]`.
- If the bug came from a missing validation, add the validation (still minimal, still
  scoped).
- Capture any non-obvious gotcha in `.ay/tracking/HANDOFFS.md` for the next agent.

## Proactive Trigger

`/fix` should fire **automatically**, without waiting for the human to type it, whenever
tool output shows a failure signal. If any of these patterns appears in a Bash result,
test run, or build output, stop the current line of work and suggest `/fix`:

| Pattern (case-insensitive) | Typical source |
|----------------------------|----------------|
| `Error:`                   | thrown/logged errors |
| `Cannot read`              | JS null/undefined access |
| `undefined is not`         | JS type errors |
| `FAILED`                   | test runners |
| `exit code 1` (any non-zero exit) | failed commands |
| `Traceback (most recent call last)` | Python |
| `panic:` / `thread '...' panicked` | Go / Rust |

When a trigger fires:
```
⚠ Failure signal detected: "[matched text]"
Recommend running /fix now — reproduce → isolate → fix, under the Iron Law.
Continue with /fix? (or say "keep going" to ignore)
```

Do not silently push past a red signal to finish the happy path. Surface it, then let
the reproduce-first protocol take over.

## Rules

- The Iron Law overrides convenience, speed, and a green-looking suite. When in doubt, ask.
- No edits during Phases 1–3 (directory freeze). Investigation is read-only.
- Never apply a fix without showing root cause + hypothesis to the human first.
- Never refactor surrounding code — fix the bug only.
- Always reproduce before fixing and always verify + regression-check after.
- If you can't find the root cause in 3 attempts, escalate with your findings instead of
  guessing.