Repair proven failures with ak:fix

Use ak:fix to carry a concrete bug, error, failing test, CI failure, or UI defect from evidence to a verified repair. The Skill frames the expected behavior, scouts the current project, proves the root cause, selects a workflow from the actual blast radius, and will not treat a symptom patch as complete.

Choose ak:fix for a concrete failure

Use ak:fix when

• You have an exact error, reproduction, failing assertion, or broken behavior.
• A type, lint, test, log, CI, or UI failure needs a code change.
• Several files may share one root cause and need coordinated verification.
• You want diagnosis, implementation, regression protection, and review in one workflow.

Choose another workflow when

• You still need to prove the root cause without committing to a repair. Start with ak:debug.
• You are delivering a feature or refactor rather than repairing a failure. Use ak:cook.
• You only need test execution or an independent review. Use ak:test or ak:code-review.
• A complex diagnosis leaves a material architecture choice. Use ak:brainstorm and ak:plan before implementation.

Prepare the repair contract

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the runtime and scope you are using.
• Provide the exact symptom, minimal reproduction, expected behavior, actual behavior, and relevant environment.
• State constraints, non-goals, acceptance criteria, and the authority boundary for Git, external systems, production data, and publication.
• Preserve unrelated work and make recent commits, affected tests, and project instructions available.

Run the Skill

/ak:fix "POST /api/sessions returns 500 when expiresAt is absent. Reproduce with the focused API test, preserve the response contract, and do not commit or deploy." --review

/ak:fix "POST /api/sessions returns 500 when expiresAt is absent. Reproduce with the focused API test, preserve the response contract, and do not commit or deploy." --review

$ak:fix "POST /api/sessions returns 500 when expiresAt is absent. Reproduce with the focused API test, preserve the response contract, and do not commit or deploy." --review

--auto is the default. Choose another mode when the risk or issue shape requires it:

--ultra runs Steps 0-2 once, then sends the confirmed diagnosis in one immutable evidence packet to exactly five independent, read-only candidates in one parallel wave. A verifier scores their complete fix plans for cause-alignment, blast-radius safety, minimality, and verifiability, then selects one plan unchanged or rejects all. Only a selected plan proceeds through Steps 4-6. The mode stops if parallel read-only dispatch is unavailable.

For multiple unrelated failures, list each symptom and reproduction separately. For one failure with several symptoms, say why you believe they may share a cause, but let the diagnosis prove or reject that grouping.

Understand what happens during a run

1. The Skill frames the repair contract. It captures the outcome, constraints, non-goals, and acceptance criteria before selecting a mode.
2. The Skill scouts the project. It identifies the stack, symptom files, callers and dependents, related tests, recent commits, and existing patterns.
3. The Skill proves the diagnosis. It records the exact error and reproduction, traces the root cause, explains why the issue appears now, and maps every path in the blast radius.
4. The Skill classifies the work. Simple work uses a quick route; moderate work tracks six dependent phases; complex work adds research, a post-diagnosis solution comparison, and a plan. Independent failures can use separate parallel trees. With --ultra, only fix-plan selection fans out; diagnosis and implementation still run once.
5. The Skill implements the selected repair. It changes the root cause with the smallest project-consistent diff and keeps non-goals out of scope.
6. The Skill verifies and prevents recurrence. It repeats the exact pre-fix command, adds a regression test, tests affected callers, checks public contracts, and applies relevant validation layers.
7. The Skill reviews and finalizes. Accepted findings are fixed and re-verified. Plan progress is reconciled, documentation impact is evaluated, and a local journal entry records the technical history.

Optional shadow comparison

The Skill completes its own complexity assessment first and does not call a decision service by default. Only when you request a semantic experiment, or a trusted opt-in from you is already in context, can it run ak eval decision to compare its classification with a shadow result. It sends only a short, non-sensitive summary of the diagnosis, never source files, logs, transcripts, or credentials.

The comparison is shadow-only. The Skill follows its existing complexity workflow, preserves an explicit --parallel, and keeps its own result on disagreement, timeout, or an unavailable provider. The command checks user-scope consent independently. A comparison is experimental evidence, not a measured improvement.

Separately, only when you explicitly ask, the Skill can prepare a bounded, reviewed request for ak eval workflow with workflow fix. The default off mode validates the request locally. --mode shadow also needs user-scope master and provider configuration, your explicit workflow-controller: true consent, and the provider credential; the Skill never infers consent from a key in the environment. Shadow mode may send sanitized facts to an external provider and incur charges.

The experiment never changes what the Skill does. Its effective retry, replan, and escalation decisions stay unchanged, suggestions are recorded only for comparison, and errors, low confidence, or an unavailable provider fall back to the existing workflow. It never executes a recommendation or treats one as permission. Existing caps, your stops, the human checkpoint after three failed repairs, and approval controls remain authoritative. Ordinary use of the Skill makes no call.

Keep the hard gates intact

• --auto removes routine pauses; it does not authorize secrets, production writes, external cost, publication, deployment, or destructive actions.
• A regression or contract change stops the run. You choose whether to revert, narrow the repair, update dependents, or explicitly accept the changed behavior.
• A regression test must demonstrate the repaired scenario, and the original reproduction must pass with fresh output.
• Critical review findings block completion. Automatic review cycles are bounded; repeated failures escalate instead of looping indefinitely.
• After three failed repair attempts, the Skill stops and asks you to question the architecture or scope.
• Commit, push, pull request, CI re-run, external comment, and deployment remain separate actions requiring their own authority.

Verify the result

A complete run should give you:

• The accepted repair contract and exact pre-fix baseline.
• A scout summary covering affected files, dependents, tests, and recent changes.
• A concrete root-cause statement with evidence, exposure condition, and blast radius.
• A minimal implementation diff and regression-prevention measures.
• Before-and-after reproduction results plus focused and blast-radius checks.
• Code-review findings, score, and disposition of every blocker or warning.
• Confirmation that public contracts are unchanged or an explicit decision for each intentional change.
• Updated plan state when applicable, a docs-impact decision, and a concise technical journal.

Do not treat the run as complete while any root-cause field is vague, the original symptom still reproduces, a blast-radius check fails, or an accepted review blocker remains unresolved.

Troubleshoot or continue

Use ak:test for independent validation and ak:code-review for a separate review after the repair.

Know the current limits

• The Skill can only reproduce environments and run checks available in the current session.
• Parallel and advisory modes depend on runtime capabilities and permitted delegation. --ultra additionally requires five parallel read-only candidate runs plus a verifier.
• CI, production, browser-profile, and external-provider work can require credentials and incur operational cost.
• Cursor slash invocation is user-verified evidence, not proof of full runtime parity.
• The installed Kit release determines the available ak:fix modes and workflow references.