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

Non-negotiable rules:

Do not write fix code before you have a reproducer or a clearly documented reason reproduction is impossible.
Fix the root cause, not the symptom.
Keep the change minimal and scoped to the bug.
Load the relevant framework reference before patching.
Load
```
references/bug-playbooks.md
```
after classifying the bug category.
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:

Always load the base language reference (e.g.,
```
nodejs-typescript.md
```
for Node.js,
```
golang.md
```
for Go,
```
rust.md
```
for Rust).
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).
React Native includes React -- read both
```
react.md
```
and
```
react-native.md
```
.
Next.js and Remix include React -- read both
```
react.md
```
and the framework file.
Go frameworks layer on Go -- read both
```
golang.md
```
and the framework file.
Rust frameworks layer on Rust -- read both
```
rust.md
```
and the framework file.
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:

write a failing test for the exact bug scenario
run only that reproducer
confirm it fails for the expected reason
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:

trace data flow from entry point to failure point
identify the first broken assumption in the chain
map the blast radius:
- callers
- importers
- dependent tests
- public APIs or contracts affected
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:

run the reproducer
confirm movement toward green
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:

run the affected test scope
run broader tests if the blast radius crosses module or package boundaries
run type checking or equivalent static verification
run the category-specific verification checklist from
```
references/bug-playbooks.md
```
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 multi-bug batches carefully

For multiple findings:

group by file, function, and dependency
fix dependent findings in order
fix independent findings by severity
run verification after each group, not only at the end
if one fix resolves another finding, say so explicitly instead of pretending both required separate patches

Success criteria: Batch work remains reviewable and regressions are caught early.

Step 8: Report the result

For each bug fixed, report:

root cause
category / playbook used
files changed
reproducer test
verification completed
any remaining risk or deferred follow-up

Include a summary with:

bugs fixed
tests added or updated
files modified
whether broader verification passed

If a bug was not fixed, say exactly why:

could not reproduce
insufficient information
root cause is upstream
fix requires architectural change beyond bugfix scope

Success criteria: Another engineer can understand what was fixed, why it was fixed that way, and how it was verified.

Guardrails

Do not fix without a reproducer unless you explicitly document why reproduction is impossible.
Do not fix the symptom if the root cause is still present.
Do not weaken or skip tests.
Do not mix refactors with bugfixes.
Do not convert bugfix work into feature work.
Do not leave broad TODOs instead of finishing the actual fix.

When To Load References

Framework references: load the relevant language and framework docs in Step 0.
```
references/bug-playbooks.md
```
: load after classifying the bug in Step 3.

Output Contract

Keep the response focused on execution and proof:

what bug is being fixed
what reproduced it
what root cause was found
what changed
how the fix was verified

bugfix

NPX Install

Tags

SKILL.md Content