Investigate failures systematically with ak:debugging

Use ak:debugging for systematic investigation of a bug, failed test, unexpected behavior, performance issue, build failure, or integration problem. The Skill requires root-cause evidence before a correction, traces failures back to their original trigger, adds applicable validation layers, and requires fresh verification before any completion claim.

Inside Marketing Kit, this workflow is most useful for technical failures in a marketing site, analytics path, content pipeline, or automation. It is not a campaign-performance diagnosis Skill.

Choose ak:debugging for evidence-first investigation

Use ak:debugging when

• A failure is reproducible but its source is not yet known.
• An error appears deep in a call stack or across multiple components.
• Several attempted fixes have treated symptoms without resolving the issue.
• You need to compare a broken path with a working example in the same project.
• You are about to claim a correction works and need fresh verification.

Choose another workflow when

• You want an orchestrated correction with explicit auto, review, quick, or parallel routing. Use ak:fix.
• You only need technical architecture advice. Use ak:ask.
• The issue is an unclear marketing objective rather than a technical failure. Use ak:brainstorm or a Marketing domain Skill.
• The technical behavior is already defined and you are implementing new scope. Use ak:cook.

ak:debugging can be used as a read-only diagnosis method, but its full fourth phase includes creating a failing test and implementing a correction. State “stop after diagnosis” when no workspace mutation is authorized.

Prepare the reproduction and boundary

Before invoking the Skill:

• Complete Onboarding and confirm the Marketing Kit target and scope.
• Provide the exact error, failing assertion, log evidence, screenshot, or observed behavior.
• State reproduction steps, expected behavior, actual behavior, environment, and recent relevant changes.
• Identify the paths, tests, components, and live services that may be inspected.
• Decide whether the run may only diagnose or may also add a test and correction.
• Exclude secrets, personal data, credentials, live-account mutations, publication, spend, and destructive actions unless separately authorized.

Run the Skill

Start with a diagnosis-only request when the cause is unknown:

/ak:debugging "The campaign preview drops UTM parameters only after a locale switch. Reproduce it, trace the value backward to the original trigger, and stop after the diagnosis report without editing files"

/ak:debugging "The campaign preview drops UTM parameters only after a locale switch. Reproduce it, trace the value backward to the original trigger, and stop after the diagnosis report without editing files"

$ak:debugging "The campaign preview drops UTM parameters only after a locale switch. Reproduce it, trace the value backward to the original trigger, and stop after the diagnosis report without editing files"

The documented argument is an error or issue description. This Skill has no documented mode flags. Put the diagnosis-only or fix-authorized boundary in the request.

Follow the four techniques

Investigate systematically

1. Read errors and stack traces completely.
2. Reproduce the failure consistently; if it is intermittent, gather more data.
3. Inspect recent changes, dependencies, and configuration.
4. Capture evidence at each component boundary to locate where behavior first diverges.
5. Trace the relevant data flow before proposing a correction.

Compare patterns

Find a working example in the same project, read it completely, list every meaningful difference, and identify its dependencies and environment. A similar-looking implementation is evidence only after its contracts are understood.

Test one hypothesis at a time

Form one specific hypothesis, make the smallest possible diagnostic change or observation, and verify the result before continuing. A failed hypothesis requires a new hypothesis, not a stack of speculative changes.

Implement and verify only when authorized

Create the smallest failing test, implement one cause-aligned correction, rerun the reproduction and affected checks, and stop if it fails. After three failed attempts, question the architecture with the user before another change.

Add defense only where applicable

After finding the root cause, map how the bad value or state travels through the system and consider four layers:

Apply the layers that address the confirmed failure path. Defense in depth is not permission to add unrelated validation, logging, data collection, or tracking.

Keep diagnosis and mutation separate

Instrumentation can expose request content, identifiers, or customer data. Capture the minimum evidence, redact sensitive values, and do not leave verbose debug logging or new tracking in production without review. Network or provider access must be current, available, and separately approved.

Verify the evidence and result

For diagnosis-only work, expect:

• The exact reproduction and captured pre-change evidence.
• A trace from the visible symptom back to the original trigger.
• One confirmed root-cause hypothesis and the evidence that distinguishes it from alternatives.
• The affected scope and a bounded correction path.
• Uncertainty and missing evidence called out explicitly.

For an authorized correction, also require:

• A failing test or minimal reproduction that demonstrates the issue.
• One root-cause-aligned change without adjacent cleanup.
• Fresh output from the original reproduction.
• Relevant regression and blast-radius checks with zero hidden failures.
• Evidence that applicable validation layers work.
• No completion claim before the verification commands run and their output is read.

Troubleshoot the investigation

Know the current limits

• The Skill provides a general technical debugging framework, not specialized campaign, attribution, or conversion analysis.
• Root-cause confidence depends on reproducibility and access to relevant code, logs, tests, configuration, and environment evidence.
• Defense in depth reduces known failure paths but cannot prove that every defect or operational risk is impossible.
• The bundled test-pollution helper applies only where its shell and test-layout assumptions fit the project.
• The workflow cannot guarantee performance, revenue, conversion, provider behavior, compliance, or zero regressions.
• Stable and beta contain identical ak:debugging source content and references.

Continue with ak:fix for an approved correction or return to the Marketing Kit overview for domain analysis.