Prove the root cause with ak:debug

Use ak:debug to turn a failure symptom into a reproducible, evidence-backed root cause. The Skill can trace code paths, correlate logs and CI events, diagnose database or performance problems, and verify a cause-aligned correction without hiding failed hypotheses.

Choose ak:debug when the cause is unknown

Use ak:debug when

• A bug, failing test, build error, or unexpected behavior needs diagnosis.
• A stack trace shows the symptom far from the original bad input or state.
• CI, server logs, database behavior, or several components must be correlated.
• Latency, resource exhaustion, or query performance has degraded.
• You need fresh evidence before saying an issue is fixed.

Choose another workflow when

• The root cause is already proven and you want the complete guarded repair pipeline. Use ak:fix.
• You only need to execute a known validation suite. Use ak:test.
• You want an independent review of a diff, commit, or pull request. Use ak:code-review.
• The behavior is not failing, but the delivery direction is unclear. Use ak:brainstorm or ak:plan.

Run a bug-repair workflow

Separate diagnosis from mutation. The chain is ak:debug → ak:fix → ak:test → ak:code-review; each stage consumes the prior stage's evidence and has its own stop condition.

Use this handoff between diagnosis and repair:

Observed failure:
Minimal reproduction:
Root cause and supporting evidence:
Affected and unaffected boundaries:
Required regression test:
Allowed mutation scope:
Known uncertainty:

Stop when the failure cannot be reproduced, evidence supports multiple causes, or the proposed repair exceeds the approved boundary. Gather the missing evidence instead of asking ak:fix to guess. A failed regression returns to the repair stage; it does not authorize changing or deleting the test.

Prepare the evidence and runtime

Before you start:

• Complete Onboarding, and confirm Marketing Kit is installed for the runtime and scope you are using.
• Provide the exact error, failing assertion, or observed behavior, plus the expected behavior and the smallest known reproduction.
• Keep the relevant project, tests, recent changes, and repository instructions available.
• For CI or server investigations, make the relevant logs and time window available. Authenticated gh access is needed to inspect GitHub Actions.
• For database or production diagnostics, grant only the credentials and environment access you intend the run to use.

See Runtime adapters for target-level differences.

Describe the failure

The Skill accepts an error or issue description. Add --ultra when an ambiguous or high-stakes diagnosis justifies a best-of-5 verifier pass. Without that flag, the evidence determines which investigation technique is loaded.

/ak:debug "pnpm test fails in session-cache.test.ts with 'expected 1 write, received 2'. It started after the cache invalidation change. Reproduce with the single test and do not modify production data."

/ak:debug "pnpm test fails in session-cache.test.ts with 'expected 1 write, received 2'. It started after the cache invalidation change. Reproduce with the single test and do not modify production data."

$ak:debug "pnpm test fails in session-cache.test.ts with 'expected 1 write, received 2'. It started after the cache invalidation change. Reproduce with the single test and do not modify production data."

A useful input names the exact symptom, reproduction command, expected and actual behavior, when the failure began, affected environment, and authority boundary. For an incident, also include timestamps, request or run IDs, impact, and the systems that may be involved.

Escalate diagnosis with --ultra

In --ultra mode, the controller gathers the symptom, reproduction, logs, stack traces, and scouted code paths once into an immutable evidence packet and sets a rubric. It dispatches exactly five independent, read-only candidate diagnoses in one parallel wave. Each candidate must provide a root-cause hypothesis with file:line evidence, eliminate rival hypotheses, define the blast radius, and propose a verification plan. Candidates cannot fix code, edit files, or mutate system state.

All five diagnoses must be usable. After one bounded retry for failed slots, a smaller pool causes a hard stop. A runtime without parallel, read-only multi-candidate dispatch also stops instead of simulating the mode sequentially. A verifier then scores the anonymized candidates against the rubric and either selects one diagnosis unchanged or rejects all. The controller must verify the selected root cause with fresh evidence before any fix.

This is prompt-orchestrated best-of-5 verification inspired by LLM-as-a-Verifier, not the full framework. It costs several times more than a normal run, so keep the default path for routine failures.

Understand what happens during a run

1. The Skill establishes the failing state. It reads complete errors and stack traces, reproduces the issue when possible, checks recent changes, and records the baseline that later verification must repeat.
2. The Skill gathers bounded evidence. It inspects relevant code, callers, tests, configuration, logs, metrics, database state, or browser behavior. Multi-component incidents receive a timeline and boundary-by-boundary data checks.
3. The Skill traces the root cause. It follows bad state backward through the call chain, compares working patterns, and identifies the original trigger rather than the line where the symptom finally appears.
4. The Skill tests one hypothesis at a time. Each hypothesis gets the smallest useful experiment. Refuted hypotheses remain recorded; several failed attempts trigger a return to evidence gathering, not stacked fixes.
5. The Skill develops a cause-aligned response. When correction belongs in the run, it changes the source of the defect, adds relevant validation layers, and avoids unrelated cleanup. Otherwise, it hands the proven diagnosis to ak:fix.
6. The Skill verifies and reports. It repeats the original reproduction, checks the affected test and system surface, and reports only claims backed by fresh command output, logs, metrics, or visual evidence.

For frontend work, the final gate can include a screenshot, interaction check, console inspection, and responsive verification. Real Chrome login or cookie state requires the profile-aware browser path; generic pages can use an isolated browser or project-native tests.

Optional workflow shadow experiment

Only when you explicitly ask, the Skill can prepare a bounded, reviewed request for ak eval workflow with workflow debug. 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 investigation authority bounded

• Reading local source and logs does not authorize unrelated private-file access.
• Inspecting a CI run is different from re-running it. A new CI run, deployment, rollback, or external mutation needs separate approval.
• Database queries require the intended credentials and environment. Do not run a write, expensive analysis, or production experiment merely because a diagnostic command is available.
• Temporary instrumentation changes the workspace and must be identified, reviewed, and removed or retained deliberately.
• After three failed correction cycles, the workflow stops and asks you to reassess the architecture or scope before another attempt.
• A passing narrow test does not prove the blast radius is safe. Completion still requires the original reproduction and relevant broader checks.

Verify the result

A useful debugging result should give you:

• The exact symptom, reproduction, expected behavior, and actual behavior.
• A timeline or call-chain evidence trail from trigger to visible failure.
• The confirmed root cause, the condition that exposed it, and the blast radius.
• Hypotheses tested, including evidence that rejected alternatives.
• The smallest cause-aligned correction or a clear handoff to ak:fix.
• Fresh before-and-after verification evidence when a correction was made.
• A concise diagnostic report with impact, findings, recommendations, and unresolved questions.
• Frontend screenshots and console findings when visual verification applies.

Treat the diagnosis as complete only when the root-cause statement names a specific defect and the evidence chain explains both the trigger and the symptom. Treat a correction as complete only when the original reproduction and the affected wider surface pass fresh verification.

Troubleshoot or continue

Continue with ak:fix when the root cause is proven and a guarded repair is needed, or use ak:test and ak:code-review for independent verification.

Know the current limits

• The Skill can only inspect the code, logs, metrics, tools, credentials, and environments available in the current session.
• Log correlation and performance analysis show only what the captured window and instrumentation can support.
• Browser, CI, database, and production evidence depend on external access and may have operational or provider cost.
• Cursor slash invocation is user-verified evidence, not proof of full runtime parity.