bugfix

What this skill does

<EXTREMELY-IMPORTANT>
Every bugfix must follow a reproduce-diagnose-fix-verify loop.

Non-negotiable rules:
1. Do not write fix code before you have a reproducer or a clearly documented reason reproduction is impossible.
2. Fix the root cause, not the symptom.
3. Keep the change minimal and scoped to the bug.
4. Load the relevant framework reference before patching.
5. Load `references/bug-playbooks.md` after classifying the bug category.
6. Never weaken tests to make a fix pass.
</EXTREMELY-IMPORTANT>

# Bugfix

## Inputs

- `$request`: Optional bug description, failing scenario, or finding selector

## Goal

Resolve confirmed defects with the smallest correct change, backed by reproduction, diagnosis, targeted implementation, and regression checks.

## Step 0: Detect framework and load references

Before diagnosing the bug, identify the language and framework from the buggy file's imports, the project's dependency files, and the file extension:

| Signal                                      | Framework          | Reference File                    |
| ------------------------------------------- | ------------------ | --------------------------------- |
| `package.json` has `express`                | Express.js         | `references/expressjs.md`         |
| `package.json` has `react` + JSX/TSX files  | React              | `references/react.md`             |
| `package.json` has `react-native` or `expo` | React Native       | `references/react-native.md`      |
| `package.json` has `next`                   | Next.js            | `references/nextjs.md`            |
| `package.json` has `fastify`                | Fastify            | `references/fastify.md`           |
| `package.json` has `hono`                   | Hono               | `references/hono.md`              |
| `package.json` has `@remix-run/react`       | Remix              | `references/remix.md`             |
| `bun.lockb` or `bunfig.toml` present        | Bun                | `references/bun.md`               |
| `composer.json` has `laravel/framework`     | Laravel            | `references/laravel.md`           |
| `go.mod` present                            | Go                 | `references/golang.md`            |
| `go.mod` has `github.com/gin-gonic/gin`     | Go + Gin           | `references/go-gin.md`            |
| `go.mod` has `github.com/labstack/echo`     | Go + Echo          | `references/go-echo.md`           |
| `go.mod` has `github.com/gofiber/fiber`     | Go + Fiber         | `references/go-fiber.md`          |
| `.swift` files, `Package.swift`             | Swift              | `references/swift.md`             |
| `Cargo.toml` present, `.rs` files           | Rust               | `references/rust.md`              |
| `Cargo.toml` has `axum`                     | Rust + Axum        | `references/rust-axum.md`         |
| `Cargo.toml` has `actix-web`                | Rust + Actix Web   | `references/rust-actix.md`        |
| `Cargo.toml` has `rocket`                   | Rust + Rocket      | `references/rust-rocket.md`       |
| `.ts`/`.js` files (no specific framework)   | Node.js/TypeScript | `references/nodejs-typescript.md` |

Reference loading rules:

1. Always load the base language reference (e.g., `nodejs-typescript.md` for Node.js, `golang.md` for Go, `rust.md` for Rust).
2. Layer the framework-specific reference on top (e.g., read both `nodejs-typescript.md` and `expressjs.md` for Express; both `rust.md` and `rust-axum.md` for Axum).
3. React Native includes React -- read both `react.md` and `react-native.md`.
4. Next.js and Remix include React -- read both `react.md` and the framework file.
5. Go frameworks layer on Go -- read both `golang.md` and the framework file.
6. Rust frameworks layer on Rust -- read both `rust.md` and the framework file.
7. If the framework is unclear, fall back to the language-level reference.

**Success criteria**: The relevant language and framework references are loaded before diagnosis begins.

## Step 1: Parse and select the bug

Accept any of these inputs:

- verified `/find-bugs` findings
- user bug reports
- failing tests
- runtime crashes or build failures encountered during work

Extract:

- symptom
- trigger
- expected behavior
- likely file or subsystem
- severity if provided
- whether the task is a single bug or a batch

For `/find-bugs` output:

- extract only the findings the user asked to fix
- sort by severity and dependency
- group findings that touch the same file or function

If the request does not describe a confirmed bug, stop and clarify instead of patching blindly.

**Success criteria**: The bug scope is explicit enough to reproduce and fix.

## Step 2: Reproduce the bug first

Create or locate the smallest relevant test close to the affected code.

Required loop:

1. write a failing test for the exact bug scenario
2. run only that reproducer
3. confirm it fails for the expected reason
4. add closely related edge-case tests only if they directly protect the fix

If you cannot reproduce:

- check environment assumptions
- check exact triggering input
- check whether the code has already changed since the report
- check whether the bug is intermittent or concurrency-related
- if it still cannot be reproduced, stop and report what you tried

**Success criteria**: You have a failing reproducer, or a precise explanation of why reproduction is blocked.

## Step 3: Diagnose the root cause

Read the full local context:

- the affected function or module
- direct callers
- direct dependencies
- nearby tests
- relevant type definitions or contracts

Then:

1. trace data flow from entry point to failure point
2. identify the first broken assumption in the chain
3. map the blast radius:
   - callers
   - importers
   - dependent tests
   - public APIs or contracts affected
4. classify the bug category

Bug categories:

- Injection
- XSS
- Auth/AuthZ
- Null safety
- Race condition
- Boundary / off-by-one
- Async / Promise
- Type safety
- Resource leak
- Logic / business rule

After classification, read `references/bug-playbooks.md` and use the matching section.

**Success criteria**: You can state the root cause in one sentence and name the correct fix playbook.

## Step 4: Plan the minimal fix

Design the smallest change that fixes the root cause.

Check before editing:

- which files must change
- which callers or dependents are affected
- whether a public API or type changes
- whether the fix needs defense-in-depth
- whether the fix should be split by dependency order in a batch

For significant fixes, present a short plan before patching:

- bug
- root cause
- category / playbook
- blast radius
- reproducer
- intended files to change

**Success criteria**: The planned change is clearly smaller than a refactor and directly tied to the root cause.

## Step 5: Implement the fix

Implementation rules:

- patch the smallest surface that resolves the bug
- follow the category playbook from `references/bug-playbooks.md`
- follow the loaded framework reference
- do not mix in cleanup, style fixes, or feature work
- do not blindly copy the `/find-bugs` suggestion without checking the code

After each logical edit:

1. run the reproducer
2. confirm movement toward green
3. finish the dependency chain if the fix changes callers or contracts

**Success criteria**: The reproducer turns from failing to passing for the right reason.

## Step 6: Verify against regressions

After the reproducer is green:

1. run the affected test scope
2. run broader tests if the blast radius crosses module or package boundaries
3. run type checking or equivalent static verification
4. run the category-specific verification checklist from `references/bug-playbooks.md`
5. check for debug artifacts and accidental cleanup changes

If the fix causes unrelated failures, stop and re-diagnose before expanding scope.

**Success criteria**: The fix is green locally, category-specific checks pass, and no obvious regressions were introduced.

## Step 7: Handle