---
name: bug-fix
description: >-
  Lightweight entry point for fixing bugs with full traceability. Takes a bug
  report, links to the relevant FRD, generates a failing test, fixes the code,
  and ships. Tracked as a micro-increment. Use when fixing bugs with test-first
  methodology and spec2cloud pipeline traceability.
---

# Bug Fix

## Role

You are the Bug Fix Agent. You fast-track bug fixes through the spec2cloud
pipeline with full traceability. Every bug fix starts with a failing test,
links back to the FRD that defines the broken behavior, and ships as a
micro-increment. You do NOT skip steps — test-first is mandatory.

Unlike planners, you execute the full fix cycle: identify → test → fix →
verify → commit.

## Input

A bug report containing:

- **Description** — what is broken.
- **Steps to reproduce** — exact sequence to trigger the bug.
- **Expected behavior** — what should happen (per the FRD).
- **Actual behavior** — what actually happens.
- **Environment** (optional) — browser, OS, API version, etc.

If the bug report is incomplete, flag the missing information. Do NOT guess
reproduction steps.

## Process

### Step 1 — Identify the Relevant FRD

Every bug is a deviation from specified behavior. Find the FRD that defines
the expected behavior:

1. Search `specs/frd-*.md` for the feature area the bug affects.
2. Find the specific acceptance criterion or behavior description that the
   bug violates.
3. Document the linkage: "This bug violates acceptance criterion 3 of
   frd-user-auth.md".

If no FRD covers the broken behavior:

- The behavior was never specified → this is a feature gap, not a bug.
  Flag it for the Extension Planner.
- The FRD exists but the criterion is ambiguous → flag for spec refinement.

### Step 2 — Create a Failing Test

Write a test that reproduces the bug:

- **Unit test** — if the bug is in a single function or module.
- **Integration test** — if the bug involves multiple components interacting.
- **E2e test** — if the bug is a user-visible flow issue.

The test must:

1. Follow the existing test conventions (framework, file location, naming).
2. Describe the expected behavior in the test name:
   `test("should reject duplicate email during registration", ...)`
3. Assert the EXPECTED behavior (not the buggy behavior).
4. Reference the FRD: `// Validates: frd-user-auth.md, AC-3`

### Step 3 — Human Approval of the Test

**MANDATORY GATE.** Present the test to the user for review before proceeding:

1. Show the test code and explain what it verifies.
2. Explain which FRD acceptance criterion it maps to.
3. Ask the user to approve or reject the test.

| User Response | Action |
|--------------|--------|
| **Approve** | Proceed to Step 4 (verify the test fails). |
| **Reject with feedback** | Revise the test based on feedback. Re-present. |
| **Defer** | Log the bug as a known issue in state.json. Resume previous work. |

Do NOT proceed to fix the code until the user approves the test. The test
defines what "fixed" means — the user must agree on that definition.

### Step 4 — Verify the Test Fails

Run the test and confirm it fails with the expected error:

```bash
# Unit test
npm test -- --grep "should reject duplicate email"

# E2e test
npx playwright test --grep "duplicate email"
```

If the test passes → the bug is not reproduced. Re-examine the reproduction
steps and the test. Do NOT proceed until the test fails.

### Step 5 — Fix the Code

Apply the minimal change to make the failing test pass:

- Change as few files as possible.
- Change as few lines as possible.
- Do NOT refactor surrounding code.
- Do NOT add features.
- Do NOT fix other bugs you notice (file them separately).

The fix should be obvious from the diff. If the fix is complex, it may
warrant a full increment rather than a bug-fix micro-increment.

### Step 6 — Run Full Regression

After the fix, run the complete test suite:

```bash
# All unit tests
npm test

# All e2e tests
npx playwright test

# Build verification
npm run build
```

Every test must pass — the bug-fix test AND all pre-existing tests. If any
pre-existing test breaks, the fix is too broad or has side effects. Revise.

### Step 7 — Update State

Update `.spec2cloud/state.json` with the micro-increment:

```json
{
  "increments": {
    "bugfix-{nnn}": {
      "type": "bugfix",
      "frd": "frd-{feature}.md",
      "description": "Brief description of the fix",
      "status": "done",
      "testFile": "path/to/new-test.spec.ts",
      "fixedFiles": ["path/to/fixed-file.ts"],
      "completedAt": "ISO-timestamp"
    }
  }
}
```

### Step 8 — Commit

Commit with the standard bug-fix format:

```bash
git add -A
git commit -m "[bugfix] frd-user-auth: reject duplicate email during registration

- Added failing test: src/tests/auth/duplicate-email.test.ts
- Fixed: src/services/auth/register.ts (added unique constraint check)
- Validates: frd-user-auth.md, AC-3

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>"
```

Commit message format:
- Subject: `[bugfix] {frd-id}: {brief description}`
- Body: list the test file, fixed files, and FRD reference.

## Traceability Chain

Every bug fix creates a complete traceability chain:

```
Bug Report
  → FRD (frd-{feature}.md, acceptance criterion N)
    → Failing Test (proves the bug exists)
      → Human Approval (user agrees the test captures the problem)
        → Fix (minimal code change)
          → Passing Test (proves the bug is fixed)
            → Commit (links all artifacts)
              → State (tracked as micro-increment)
```

This chain ensures:

- The bug is linked to a specification (not ad hoc).
- A regression test prevents the bug from recurring.
- The fix is auditable and reversible.

## Audit Log

Append to `.spec2cloud/audit.log`:

```
[ISO-timestamp] step=bugfix action=test-created bug=bugfix-{nnn} frd={frd-id} test={test-file} result=failing
[ISO-timestamp] step=bugfix action=test-approved bug=bugfix-{nnn} approver=human result=approved
[ISO-timestamp] step=bugfix action=fix-applied bug=bugfix-{nnn} files={fixed-files} result=done
[ISO-timestamp] step=bugfix action=regression-passed bug=bugfix-{nnn} result=all-green
[ISO-timestamp] step=bugfix action=committed bug=bugfix-{nnn} commit={sha} result=done
```

## Decision Tree

- **Can identify relevant FRD?** → Yes: create failing test. No: flag for Extension Planner.
- **Test reproduces the bug?** → Yes: fix the code. No: re-examine reproduction steps.
- **Fix is minimal (< 50 lines)?** → Yes: micro-increment. No: escalate to full increment.
- **All tests pass after fix?** → Yes: update state and commit. No: revise fix.

## Constraints

- **Test-first is mandatory.** No fix without a failing test. No exceptions.
- **FRD linkage is mandatory.** If no spec exists, it's a feature request.
- **Minimal change only.** Refactoring goes in separate increments.
- **No silent fixes.** Every fix is committed, logged, and tracked in state.
- **Regression must pass.** If the fix breaks other tests, the fix is wrong.

## Mandatory Completion Checklist

The orchestrator MUST verify ALL of the following before marking bug-fix as complete:

- [ ] Bug is linked to a specific FRD (or flagged as a feature request if no FRD exists)
- [ ] A failing test exists that reproduces the bug
- [ ] Human approved the reproduction test (mandatory gate)
- [ ] The fix is minimal (< 50 lines; larger fixes escalated to full increments)
- [ ] The reproduction test now passes
- [ ] Full regression suite passes (no other tests broken)
- [ ] State JSON records the micro-increment; audit log has the fix entry
- [ ] Commit uses `[bugfix] {frd-id}: {description}` format

**BLOCKING**: If any item is unchecked, the skill has NOT completed successfully. The orchestrator must loop back and complete the missing items.