# Bug Fix Workflow

> See the full workflow at [AIFLOW.md](../../AIFLOW.md)
> **Gates must pass in order: 1 → 2 → 3 → 4 → 5**

---

## Step 1: Load ticket & AI analyzes (Gate 1)

```bash
aiflow use PROJ-33 --with-comments    # get both comments — important for bugs
claude                                # AI auto-starts Gate 1
```

AI will **automatically**:
1. Load ticket info + comments from Backlog/Jira
2. Read source code — trace data flow related to the bug
3. Use `superpowers:systematic-debugging` to form root cause hypothesis
4. Ask clarifying questions if reproduction steps are unclear
5. Output `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` containing:
   - Bug analysis (current vs expected behavior)
   - **Root cause hypothesis** with evidence from source code
   - **Proposed fix approach** (with alternatives if applicable)
   - **Impact analysis** — will the fix break anything else?
   - **Effort estimate** (S/M/L/XL)
   - Testing plan (reproduce bug + verify fix)

**PM needs to prepare on the ticket:**
```markdown
## Description
Bug description: current behavior vs expected.

## Acceptance Criteria
- [ ] Bug no longer occurs
- [ ] [Other specific conditions]

## Reproduction Steps
1. [Step 1]
2. [Step 2]
3. Actual result: [what error, what screen]
4. Expected result: [...]

## Context
Error log (if any), environment (browser, OS, app version).
```

**If reproduction steps are unclear:** AI will ask based on what it found in the code.

**When satisfied with the requirement document, type:**
```
APPROVED
```

---

## Step 2: Review Implementation Plan (Gate 2)

AI generates:
- TDD plan: write test to reproduce bug → implement fix → verify
- Minimal fix approach (only edit the bug location)

**When agreed, type:**
```
APPROVED
```

---

## Step 3: AI Fix Code (Gate 3)

AI performs in the following order:
1. `superpowers:systematic-debugging` — confirm root cause
2. `investigate-bug` skill — trace Controller→Service→Repository to identify the bug layer
3. Write test to reproduce bug → run → confirm FAIL
4. Implement fix → tests PASS
5. Commit

**Principle:** Minimal fix — only edit the bug location, no extra changes.

---

## Step 4: Review Summary (Gate 4)

AI runs:
1. `superpowers:verification-before-completion` — all tests PASS (including old tests)
2. `impact-analysis` — fix doesn't cause new bugs elsewhere
3. Create `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md`

**If OK, type:**
```
APPROVED
```

**If the fix is incorrect:**
```
BUG: [describe specifically what is wrong]
```

---

## Step 5: Peer Review & PR (Gate 5)

```bash
git push origin fix/PROJ-33-description
# PR title: fix: [PROJ-33] Short description
```

Commit message format:
```
fix: [PROJ-33] Payment processing timeout

Root cause: API timeout too short (5s), needs at least 10s
Fix: Increase timeout + add retry logic

Closes PROJ-33
```

---

## Completion Checklist

- [ ] Gate 1 APPROVED — requirement doc with root cause, fix approach, impact, estimate
- [ ] Gate 2 APPROVED — implementation plan confirmed
- [ ] Gate 3 done — test reproduce bug + fix → green
- [ ] Gate 4 APPROVED — no regression
- [ ] Gate 5 done — PR merged