sakura-fix

name	sakura-fix
description	Use a reproducible failure record to identify the root cause, implement the smallest correction, and return to the original verification path. Use after test, build, runtime, or review failure; do not make random evidence-free changes, expand feature scope, or bypass validation.

Sakura Fix

Role

Convert an observed failure into an explained root cause and a minimal repair, then return the change to verification.

Use When

• sakura-verify produced a reproducible failure record.
• sakura-review found a blocking issue.
• A regression can be traced to the current change.

Do Not Use When

• Only a vague error description exists and no project or reproduction is available.
• The user requested diagnosis only and did not authorize modification.
• The expected behavior changed and requires a new specification.

Inputs

• The failed command, exit status, relevant output, and reproduction steps.
• Expected behavior, actual behavior, and affected acceptance items.
• The current diff, related code, and previous attempts.

Outputs

• An evidence-supported root-cause statement.
• The smallest repair and necessary test changes.
• The original failed check and required regression checks.
• A repair handoff to sakura-verify.

Workflow

1. Reproduce the failure and confirm that the record is current.
2. Trace the first divergence to the smallest root cause.
3. Check adjacent paths affected by the same cause.
4. Apply the smallest correction without unrelated refactoring or dependency upgrades.
5. Do not disable checks, swallow errors, or weaken assertions.
6. Increment the repair count and record new evidence.
7. Return to sakura-verify for the original failed check.

Read fix-loop.md for complex or repeated failures.

Quality Gate

• The root cause explains the observed failure.
• The repair scope matches that root cause.
• The original behavior failed before the repair and passes after it.
• Related regression paths are identified.
• The attempt produced new evidence instead of repeating the same guess.

Failure and Fallback

• Return to sakura-spec when the expected product behavior is wrong.
• Return to sakura-plan when a technical assumption is wrong, and use sakura-research first when needed.
• Block and request user direction when three attempts against the same root cause produce no new evidence.
• Pause when repair requires destructive operations, real credentials, or external permissions.

Upstream and Downstream

• Upstream: a failure record from sakura-verify or a blocking finding from sakura-review.
• Downstream: sakura-verify. Never jump directly from repair to Done.

Handoff

Include the root cause, changed files, repair, remaining risks, the original check that must run again, and required regression checks.