Repair proven failures with ak:fix

Scout and diagnose a concrete failure, implement the smallest cause-aligned repair, and prove it has no hidden side effects.

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.

Runtime	Invocation	Availability boundary
Claude Code	`/ak:fix ...`	Native delivery is the default; explicit plugin delivery is also supported.
Cursor	`/ak:fix ...`	Slash invocation is user-verified. This does not establish full runtime parity.
Codex	`$ak:fix ...`	The Skill uses native Codex discovery; broader Engineer Hook and statusline parity is not implied.

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:

Option	Behavior	Important boundary
`--auto`	Runs autonomously and auto-approves a review only at score 9.5 or higher with no Critical finding	Unresolved blockers, regressions, and authority decisions still escalate
`--review`	Pauses for human review at each major step	Best for production, security-sensitive, or public-contract work
`--quick`	Uses a short scout, diagnosis, repair, verification, and review cycle	Only for trivial type, lint, syntax, or direct single-file defects; root-cause evidence remains mandatory
`--parallel`	Routes independent issues into separate owned workstreams	Issues must be independent, ownership must not overlap, and runtime delegation must be available and permitted
`--advice`	Adds advisory checkpoints after phases, when stuck, and before high-stakes decisions	The adviser returns counsel only; it cannot edit, approve, or widen authority

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

The Skill frames the repair contract. It captures the outcome, constraints, non-goals, and acceptance criteria before selecting a mode.
The Skill scouts the project. It identifies the stack, symptom files, callers and dependents, related tests, recent commits, and existing patterns.
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.
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.
The Skill implements the selected repair. It changes the root cause with the smallest project-consistent diff and keeps non-goals out of scope.
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.
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.

Keep the hard gates intact

Automation does not permit guessing

No mode may propose or implement a repair before scouting and diagnosis. The root-cause record must name the exact symptom, reproduction, expected versus actual behavior, specific defect, why it surfaced now, and blast radius.

--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

Symptom	Safe next step
The Skill asks for logs or reproduction details	Supply the exact output, command, inputs, environment, and expected behavior. Do not replace evidence with a probable cause.
`--quick` discovers multiple files or design choices	Escalate to the standard or deep route before implementation.
Several fixes fail	Preserve the rejected hypotheses and stop after the third cycle to reassess architecture or scope.
A test passes but a dependent workflow breaks	Keep the regression visible and choose revert, narrower scope, dependent updates, or explicit acceptance.
Parallel work overlaps files	Stop the affected workstreams, redefine exclusive ownership, and re-check the shared integration point.
Review stays below the automatic threshold	Resolve Critical findings, review warnings, or switch to an explicit human decision; do not manufacture a passing score.
The runtime does not recognize the Skill	Confirm target and scope, restart the runtime session, then follow Runtime cannot find a Skill or Agent.

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.
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.
Stable and beta package the same ak:fix modes, hard gates, and workflow references.

Repair proven failures with ak:fix

On this page