dx-bug-fix

---
name: dx-bug-fix
description: "Plan, implement, test and open a PR for a bug fix from triage.md / verification.md. Use after /dx-bug-triage or /dx-bug-verify. Not before triage exists, not for the whole workflow (dx-bug-all) or reproduction (dx-bug-verify)."
argument-hint: "<ADO Bug Work Item ID (optional — uses most recent if omitted)>"
allowed-tools: ["read", "edit", "search", "write", "agent"]
---

You are a coordinator. You do NOT implement anything yourself. You delegate each workflow phase to the `subagent` agent via the Task tool, then report progress.

## Flow

```dot
digraph bug_fix {
    "Pre-flight validation" [shape=box];
    "Locate spec dir + read triage/verification" [shape=box];
    "Check verification status" [shape=box];
    "Generate fix plan (opus, 2-5 steps)" [shape=box];
    "Cross-repo gate: all steps in other repo?" [shape=diamond];
    "Hub dispatch fix" [shape=box];
    "STOP: Fix belongs in other repo" [shape=doublecircle];
    "Execute step cycle (step - test - review - fix)" [shape=box];
    "Step blocked (2-strike)?" [shape=diamond];
    "STOP: Human intervention needed" [shape=doublecircle];
    "All steps done?" [shape=diamond];
    "Run build" [shape=box];
    "Run bug-verify (after mode)" [shape=box];
    "Fix verified?" [shape=diamond];
    "Attempt < 2?" [shape=diamond];
    "Revise plan + re-execute steps" [shape=box];
    "Commit + create PR" [shape=box];
    "Final summary" [shape=doublecircle];

    "Pre-flight validation" -> "Locate spec dir + read triage/verification";
    "Locate spec dir + read triage/verification" -> "Check verification status";
    "Check verification status" -> "Generate fix plan (opus, 2-5 steps)";
    "Generate fix plan (opus, 2-5 steps)" -> "Cross-repo gate: all steps in other repo?";
    "Cross-repo gate: all steps in other repo?" -> "Hub dispatch fix" [label="yes + hub mode"];
    "Cross-repo gate: all steps in other repo?" -> "STOP: Fix belongs in other repo" [label="yes + no hub"];
    "Cross-repo gate: all steps in other repo?" -> "Execute step cycle (step - test - review - fix)" [label="no"];
    "Hub dispatch fix" -> "Final summary";
    "Execute step cycle (step - test - review - fix)" -> "Step blocked (2-strike)?";
    "Step blocked (2-strike)?" -> "STOP: Human intervention needed" [label="yes"];
    "Step blocked (2-strike)?" -> "All steps done?" [label="no"];
    "All steps done?" -> "Execute step cycle (step - test - review - fix)" [label="no, next step"];
    "All steps done?" -> "Run build" [label="yes"];
    "Run build" -> "Run bug-verify (after mode)";
    "Run bug-verify (after mode)" -> "Fix verified?";
    "Fix verified?" -> "Commit + create PR" [label="yes or blocked"];
    "Fix verified?" -> "Attempt < 2?" [label="no (partial/failed)"];
    "Attempt < 2?" -> "Revise plan + re-execute steps" [label="yes"];
    "Attempt < 2?" -> "STOP: Human intervention needed" [label="no, 2 attempts"];
    "Revise plan + re-execute steps" -> "Run build";
    "Commit + create PR" -> "Final summary";
}
```

## Node Details

### Pre-flight validation

Before starting the bug fix workflow, validate prerequisites:

1. **Spec directory exists** — run `bash .ai/lib/dx-common.sh find-spec-dir $ARGUMENTS`. If not found, STOP with: "No spec directory found. Run `/dx-bug-triage <id>` first."
2. **Required files exist** — check for `triage.md` in the spec directory. If missing, STOP.
3. **MCP health** — run `bash .ai/lib/mcp-health-check.sh all`. Report any failures as warnings (non-blocking — fix may not need MCP).
4. **Feature branch** — run `bash .ai/lib/ensure-feature-branch.sh <spec-dir>`.

If any blocking check fails, STOP with a clear message listing what's missing.

### Locate spec dir + read triage/verification

```bash
SPEC_DIR=$(bash .ai/lib/dx-common.sh find-spec-dir $ARGUMENTS)
```

Read from `$SPEC_DIR`:
- `raw-bug.md` — **required**. If missing: "Run `/dx-bug-triage` first."
- `triage.md` — **required**. If missing: "Run `/dx-bug-triage` first."
- `verification.md` — **optional**. If missing or result is "Blocked", warn but continue.

Print: `Bug fix starting for ADO #<id> — <title>`

### Check verification status

If `verification.md` exists, read the `**Result:**` line:
- `Reproduced` → proceed normally
- `Partially Reproduced` → proceed with caution note
- `Could Not Reproduce` → warn: "Bug was not reproduced — fix is based on code analysis only."
- `Blocked` → warn: "Verification was blocked — proceeding on triage analysis alone."

If `verification.md` doesn't exist → same warning as "Blocked".

### Generate fix plan (opus, 2-5 steps)

Delegate to a subagent with **model: opus** for deep reasoning:

```
Generate implement.md for bug fix in spec directory <SPEC_DIR>.

Read raw-bug.md, triage.md, and verification.md (if exists).
Use the root cause hypothesis from triage.md and the evidence from verification.md
to generate a concrete fix plan.

Before writing implement.md, load coding standards for the affected file types
(from triage.md's Affected Files table):
- Check .claude/rules/ for rules matching the file types being fixed
- If .github/instructions/ exists, read the relevant instruction file:
  - .js files → .github/instructions/fe.javascript.instructions.md (or fe.javascript.md)
  - .scss/.css files → .github/instructions/fe.css-styles.md (or fe.styles.instructions.md)
  - .html (HTL) files → .github/instructions/be.htl.md
  - .java files → .github/instructions/be.sling-models.md
  - Dialog XML → .github/instructions/be.dialog.md
  - Accessibility-related bugs → .github/instructions/accessibility.instructions.md
- If the bug involves AEM frontend modals, overlays, or focus management,
  also read shared/aem-dom-rules.md from the dx-aem plugin for DOM constraints.
These conventions MUST inform the fix approach — do not generate steps that violate them.

Write implement.md to <SPEC_DIR>/implement.md with:
- Root Cause (1-2 sentences)
- Approach (2-3 sentences)
- If triage.md has a "Cross-Repo Scope" section, add: **Other repos required:** <repo name(s)> — run `/dx-bug-all <id>` there after this fix
- Steps (2-5, each with Status: pending, Files, What, Why, Test)
- Testing Plan (unit tests + manual verification)

Rules for plan generation:
- 2-5 steps maximum (bugs are simpler than features)
- Every file reference must come from triage.md's Affected Files table
- Steps ordered by implementation dependency
- Each step has **Status:** pending
- Include regression test in at least one step
- Root Cause must be grounded in actual code, not speculation
```

Print: `Phase 1 done — implement.md created with <N> steps`

### Cross-repo gate: all steps in other repo?

After implement.md is generated, check if the fix belongs in another repo:

1. Read implement.md for the `**Other repos required:**` line
2. Check if **any step modifies source code** (JS, CSS, Java, etc.) in the current repo — or if steps only touch spec/doc files (triage.md, verification.md, etc.)

**If all steps are doc-only / dead-code cleanup** (no functional fix in this repo) → go to "STOP: Fix belongs in other repo".

**If at least one step modifies functional source code** in this repo → go to "Execute step cycle (step - test - review - fix)". The cross-repo note will appear in the final summary.

### Hub dispatch fix

**Entered when:** Cross-repo gate detected all fix steps belong to another repo AND hub mode is active.

Print: `Hub mode detected. The fix belongs in another repo. Use /dx-hub-dispatch <ticket-id> to dispatch this bug to the correct repo terminal.` STOP.

Hub dispatch is handled by the dedicated `/dx-hub-dispatch` skill, which opens independent VS Code terminals for each repo.

> **Note:** If hub mode is NOT active, the existing "STOP: Fix belongs in other repo" behavior applies unchanged.

### STOP: Fix belongs in other repo

Print a prominent warning and STOP:

```markdown
## Cross-Repo Bug: Fix belongs in <other repo(s)>

**ADO #<id> — <title>**

The root cause is in **<other repo(s)>**, not in this repo. No functional fix can be applied here.

**Root cause:** <1-line from implement.md>

**What's needed in <other repo>:**
<Extract the specific fix description from implement.md's "Other repos required" line or approach section>

### Next steps:
1. `cd <path-to-other-repo>` (from `.ai/config.yaml` repos section)
2. Run `/dx-bug-triage <id>` → `/dx-bug-fix <id>` there
3. _(Optional)_ Come back here to clean up dead code after the upstream fix ships

### Dead code in this repo (optional cleanup):
<List any dead-code steps from implement.md, e.g., "Remove unused fix from brand.js">
Run `/dx-bug-fix <id>` again with `--cleanup` intent if you want to proceed with just the cleanup steps.
```

Do not proceed to any further sections. The user must fix the other repo first.

> **Note:** If hub mode is active, the "Hub dispatch fix" node directs the user to `/dx-hub-dispatch` instead of reaching this node.

### Execute step cycle (step - test - review - fix)

For each pending step in implement.md, run the step-test-review-fix cycle. Before the first step, mark the step loop active, so the workers drop their "run X next" hints addressed to a human (`shared/orchestration-check.md` § Step-loop marker). Remove it at "All steps done?" → yes and at "STOP: Human intervention needed":

```bash
mkdir -p .ai/run-context && echo "$SPEC_DIR" > .ai/run-context/step-loop.flag   # rm -f on exit
```

**Execute Step:**

```
Invoke /dx-step for spec directory <SPEC_DIR>
```

`/dx-step` handles implementation, testing, review, and commit in one pass. It runs forked and ends with a `## Return` block — a checkpoint, not the end of this skill. `verdict: fail` (step `blocked`) → go to fix sub-cycle; otherwise continue to "All steps done?".

**Fix (if needed):**

```
Invoke /dx-step-fix for spec directory <SPEC_DIR>
```

Track fix attempts per step. If fix succeeds → re-run tests (loop back to Run Tests above).

**Progress Report:** After each step cycle: `Step <N>/<total> done — <step title>`

### Step blocked (2-strike)?

Track consecutive fix failures per step. **2-strike rule:** If 2nd consecutive fix on the same step fails:

- **yes** → go to "STOP: Human intervention needed"
- **no** → go to "All steps done?"

### STOP: Human intervention needed

Print error details and: "Step <N> blocked after 2 fix attempts. Human intervention needed."

STOP the entire workflow.

### All steps done?

Check implement.md for remaining pending steps (`bash .ai/lib/plan-metadata.sh $SPEC_DIR`), never from memory:

- **no, next step** → go back to "Execute step cycle (step - test - review - fix)" with the next pending step
- **yes** → go to "Run build"

### Run build

After all steps complete:

```
Invoke /dx-step-build for spec directory <SPEC_DIR>
```

If build fails, delegate to step-fix. 2-strike rule applies.

### Run bug-verify (after mode)

Run local verification to confirm the fix resolved the issue:

```
Invoke /dx-bug-verify <id> after
```

This runs `dx-bug-verify` in `after` mode — swaps the repro URL to local AEM, re-runs the repro steps, and confirms the bug is no longer present. Output goes to `verification-local.md`.

Read `verification-local.md` for the result.

Print: `Local verification: <result>`

### Fix verified?

Read the result from `verification-local.md`:

- **yes (Fix Verified)** → go to "Commit + create PR"
- **blocked** → go to "Commit + create PR" (warn but proceed — local verification is best-effort, e.g., Playwright unavailable)
- **no (partial/failed)** → go to "Attempt < 2?"

### Attempt < 2?

Check how many fix-verify iterations have been attempted:

- **yes (first attempt)** → go to "Revise plan + re-execute steps"
- **no, 2 attempts** → STOP. Write diagnostic to `<spec-dir>/fix-loop-report.md`:

```
## Bug Fix Loop — Blocked After 2 Attempts

**Original issue:** <from triage.md>
**Attempt 1 result:** <from verification-local.md>
**Attempt 2 result:** <from verification-local.md>
**Diagnosis:** <what changed between attempts, what's still failing>

Human intervention needed. The verification output suggests: <actionable next step>
```

Go to "STOP: Human intervention needed".

**Cap:** 2 fix-verify iterations maximum. Never loop more than twice.

### Revise plan + re-execute steps

1. Read the verification failure details from `verification-local.md`
2. Append failure context to `triage.md` under a new `## Fix Attempt 1 — Failure Analysis` heading
3. Re-read the original triage + failure context
4. Generate a revised fix plan — update `implement.md` with new steps (mark old steps as `done` or `superseded`)
5. Execute the revised steps via `/dx-step` (same 2-strike rule per step)

After revised steps complete → go to "Run build".

### Commit + create PR

```
Invoke /dx-pr-commit for spec directory <SPEC_DIR>.
Commit message format: #<id> Fix <short description from bug title>
```

Print: `PR created: <PR URL>`

### Final summary

```markdown
## Bug Fix Complete: ADO #<id>

**<Title>**
**Root Cause:** <1-line from implement.md>
**Branch:** `bugfix/<id>-<slug>`
**PR:** <PR URL>

| Phase | Status | Details |
|-------|--------|---------|
| Triage | Done | <N> files identified, layer: <layer> |
| Verification | <result> | <N> screenshots |
| Fix Plan | <N> steps | All pending → done |
| Execution | <N>/<N> done | <N> fix attempts |
| Build | Passed | |
| Local Verify | <result> | <N> post-fix screenshots |
| PR | Created | <PR URL> |

### Files Changed:
<list from git diff --name-only>

### Cross-Repo Note:
<If implement.md has "Other repos required", print:>
> This fix covers **<current repo>** only. Switch to **<other repo(s)>** and run `/dx-bug-all <id>` there.
<Otherwise omit this section.>
```

## Error Handling

| Scenario | Action |
|----------|--------|
| triage.md missing | STOP — "Run `/dx-bug-triage` first." |
| triage.md has no affected files | STOP — "Cannot generate fix plan without affected files." |
| implement.md generation fails | Retry once. If still fails, suggest: "Run `/dx-plan` manually." |
| All fix steps are in another repo | STOP — print cross-repo gate message (section "STOP: Fix belongs in other repo"). Advise user to `cd` to that repo and run `/dx-bug-triage` + `/dx-bug-fix` there. |
| Step blocked (2-strike) | STOP loop. Report which step blocked. |
| Build fails after all steps | Delegate to step-fix loop (max 6 attempts per build pattern). |
| Local verification Fix Failed (attempt 1) | Revise fix plan, re-execute steps, retry once (attempt 2). |
| Local verification Fix Failed (attempt 2) | STOP. Write `fix-loop-report.md`. Human intervention needed. |
| Local verification Blocked | WARN and continue to commit. Playwright may be unavailable. |
| commit fails | Report error. Suggest: "Run `/dx-pr-commit` manually." |

## Rules

- **Coordinator only** — never implement code yourself. Always delegate via Task tool.
- **Sequential phases** — plan → execute → build → commit. Never skip.
- **2-strike rule** — stop after 2 consecutive fix failures. Don't brute-force.
- **Re-read implement.md** — re-read between steps to get latest status.
- **Bugfix branch required** — never execute on a protected branch. Check `.branch` file.
- **Progress reporting** — print status after each phase and step.
- **Commit message format** — `#<id> Fix <description>` (not `#<id> Add` or `#<id> Update`).