Non-negotiable rules:

1. Fix one finding at a time.
2. For behavioral bugs, write the failing regression test before the fix.
3. Run crate tests and clippy after every fix.
4. Do not mark a finding fixed without the required verification.
5. Use the rust skill for crate-specific coding conventions before changing Rust code. </EXTREMELY-IMPORTANT>

bugfix-crate

Inputs

• $issues_file: Path to the crate findings file

Goal

Work through a crate issue file sequentially and leave behind:

• a verified fix for each resolved finding
• regression coverage for each behavioral fix
• a passing crate test suite
• an updated issue file showing what was fixed, deferred, or rejected as not-a-bug

Step 0: Establish the baseline

Before editing:

• read the entire issue file
• determine the target crate name and path
• invoke rust for relevant conventions
• read crate-local CLAUDE.md or testing guidance if present
• run baseline cargo test -p <crate>
• run baseline cargo clippy -p <crate> -- -D warnings

Success criteria: The crate, issue file, and baseline state are explicit before the first fix.

Step 1: Process one finding at a time

For each unresolved finding:

• read the cited file and surrounding context
• determine whether it is behavioral, API, dead-code, doc-only, deferred, or not-a-bug
• if it is a behavioral or API fix, write the failing test first
• verify the test fails before changing the implementation

Do not batch findings.

Success criteria: Each finding has a concrete resolution path before any fix lands.

Step 2: Apply the smallest correct fix

Make the minimum code change that addresses the root cause.

Rules:

• do not batch adjacent refactors
• do not weaken existing tests
• do not hide warnings with #[allow(...)]
• if you uncover another real bug in the touched area, fix it in the same pass and add it to the issue file

Success criteria: The fix addresses the root cause without broad collateral edits.

Step 3: Verify and mark status

After each fix:

• run cargo test -p <crate>
• run cargo clippy -p <crate> -- -D warnings
• update the issue file:
  • **[FIXED]** for verified fixes
  • Deferred: <reason> for real out-of-scope fixes
  • Not a bug: <reason> for invalid findings

Do not mark a finding fixed before the verification pass completes.

Success criteria: The issue file and crate state stay in sync after every finding.

Step 4: Finish only when the issue file is resolved

At the end:

• confirm every finding has a terminal status
• confirm the crate still passes tests and clippy
• summarize resolved, deferred, and rejected findings

Success criteria: The issue file is fully triaged and the crate is green.

Guardrails

• Do not use worktree agents for same-crate fixing.
• Do not run this skill proactively; it is explicit-user-only.
• Do not mark behavioral bugs fixed without regression coverage.
• Do not replace a real fix with comments, warnings, or documentation.
• Do not batch multiple findings in one verification loop.

Output Contract

Report:

1. crate and issue file processed
2. baseline test and clippy state
3. per-finding outcome
4. final test and clippy state
5. any newly discovered findings added during repair