Diagnose and correct technical defects with ak:fix

Use ak:fix for a concrete technical defect in a marketing site, automation, integration, test suite, or CI workflow. The Skill captures the expected repaired behavior, scouts the affected code, proves a root cause, selects a cause-aligned correction, changes the workspace, and verifies the original reproduction and its blast radius.

This is a code-fixing workflow inside Marketing Kit. It does not diagnose poor campaign performance, revise positioning, or optimize a funnel unless the problem is a reproducible technical defect in the project.

Choose ak:fix for a reproducible defect

Use ak:fix when

• You have an exact error, failing test, type or lint failure, UI defect, log failure, or broken CI run.
• You can provide or collect reproduction steps and expected versus actual behavior.
• You authorize a minimal workspace correction after diagnosis.
• You need fresh verification, regression coverage, a side-effect sweep, and code review.

Choose another workflow when

• You need diagnosis only and no mutation. Use ak:debugging with an explicit stop-after-diagnosis boundary.
• The issue is a strategy or performance question without a reproducible technical failure. Use the relevant Marketing analysis or optimization Skill.
• Several product or marketing directions are viable after diagnosis. Use ak:brainstorm before choosing a correction.
• You are implementing known feature scope rather than repairing a defect. Use ak:cook.
• You only need technical consultation. Use ak:ask.

Prepare the failure evidence

Before starting:

• Complete Onboarding and confirm the Marketing Kit target and scope.
• Provide the exact error message, failing assertion, log excerpt, screenshot, or observable behavior without exposing secrets or personal data.
• State minimal reproduction steps, expected behavior, actual behavior, and the environment where the issue appears.
• Preserve unrelated work and identify sensitive paths, live services, and public contracts that must not change.
• Decide whether the assistant may edit files, add tests, and run the relevant validation commands.

Run the Skill

/ak:fix "Signup submits the lead event twice after a failed first request. Reproduce with the existing integration test, preserve consent behavior, fix the root cause, and do not commit or deploy" --review

/ak:fix "Signup submits the lead event twice after a failed first request. Reproduce with the existing integration test, preserve consent behavior, fix the root cause, and do not commit or deploy" --review

$ak:fix "Signup submits the lead event twice after a failed first request. Reproduce with the existing integration test, preserve consent behavior, fix the root cause, and do not commit or deploy" --review

Select the fix mode

--advice composes with the selected base mode. Do not choose --quick merely because a symptom looks obvious; the root cause still must be confirmed.

Require exact root-cause evidence

Before proposing a correction, the workflow requires concrete answers for:

1. The exact symptom or error.
2. Minimal reproduction steps.
3. Expected versus actual behavior.
4. The root cause at a specific code or contract boundary.
5. The change or condition that exposed it.
6. Every path in the blast radius that shares the cause or broken behavior.

If any answer remains speculative, gather more logs, tests, source evidence, or environment detail. Three failed correction attempts are a stop condition: the workflow should question the architecture and discuss it with you before trying again.

Understand the fix stages

1. Frame intent. Capture outcome, constraints, non-goals, and acceptance criteria without choosing a fix.
2. Scout. Map affected files, direct callers and dependents, related tests, recent changes, and existing patterns.
3. Diagnose. Preserve the pre-fix output, trace the data and call path, test hypotheses, and prove the root cause.
4. Assess complexity. Route a simple, moderate, complex, or independent multi-issue workflow only after diagnosis.
5. Choose a cause-aligned correction. Use a direct minimal repair when one safe option exists; brainstorm and plan only when meaningful alternatives remain.
6. Implement. Change the smallest scope that addresses the confirmed cause.
7. Verify and prevent recurrence. Re-run the exact reproduction, add or update a regression test, sweep the blast radius, confirm public contracts, and run relevant type, lint, build, and test checks.
8. Review and finalize. Review correctness and side effects, reconcile plan and documentation impact, report evidence, and ask before a Git workflow.

Keep mutation and external effects controlled

For CI diagnosis, gh access and network connectivity may be required to read GitHub Actions logs. Reading a run does not authorize pushing a correction or rerunning external workflows. For UI defects, browser or screenshot access is evidence collection; it does not authorize publishing the page.

If verification reveals a side effect, stop and choose whether to revert, narrow the correction, update explicit dependents, preserve compatibility, or accept a documented contract change. The Skill must not silently patch around the failure.

Verify the result and evidence

A complete fix report should contain:

• The exact root cause and its evidence chain.
• The files changed and why each change is cause-aligned.
• Before-and-after output from the original reproduction.
• A regression test that covers the defect, plus blast-radius checks.
• Fresh type, lint, build, and test evidence relevant to the project.
• Review findings, side-effect assessment, public-contract status, and any remaining risk.
• Plan and documentation impact plus actions still awaiting approval.

Do not accept “seems fixed.” The original failure must no longer reproduce and the broader affected behavior must remain valid.

Troubleshoot the fix

Know the current limits

• ak:fix is technical and code-oriented; it does not repair marketing strategy or guarantee campaign performance.
• Its source references several Engineer-oriented or shared workflow names that are not separate Marketing exports. Runtime availability must be checked rather than assumed.
• Verification is limited by reproducibility, project checks, tools, test data, and environment access available in the session.
• The workflow cannot guarantee zero risk, provider behavior, conversion, revenue, deployment success, or compliance.
• Stable and beta contain identical ak:fix source content and flags.

Continue with ak:debugging for investigation, ak:cook for known feature scope, or the Marketing Kit overview for domain workflows.