In short:
ak-debugfinds the root cause of a bug and proves it with evidence instead of fixing by guesswork. Once it has the cause, it hands off toak-fix, or toak-brainstormwhen several fixes are worth weighing. It does not write new tests for code that already works; that belongs toak-test.
Disclosure: I maintain AgentKit and have an affiliate relationship with it: the AgentKit link in this post is an affiliate link; buying through it gets you 30% off.
Summary
Use it when a green test suddenly turns red, CI is red while your machine is green, a server returns errors across the board, the system gets slower, or a flaky bug will not reproduce reliably. You do not need it when nothing is broken and you only want more tests; use ak-test for that.
flowchart LR
S["ak-scout finds the related code"] --> B["ak-debug"]
A["Failing test, error, wrong output"] --> B
B --> C["Root cause with evidence"]
C --> D["ak-fix"]
C --> E["ak-brainstorm when there are several fixes"]
B --> F["Stop: 3 failed fixes, revisit the architecture"]It always keeps 4 principles:
| Principle | Question | Example |
|---|---|---|
| Root cause | Where does the error start, not where does it show up? | The checkout page shows "undefined", but the root is a config reader returning an empty string three call levels up. Fix the config reader, do not patch the checkout page. |
| One hypothesis at a time | Am I testing exactly one thing, and have I said why I think so? | "The cache expires early because the TTL is in seconds but the code passes milliseconds." Change only that one variable to test it. If wrong, form a new hypothesis instead of stacking another fix. |
| Fresh evidence | Which command proves the claim "done", and did I just run it? | Rerun the exact test that failed and see 0 failed. For a regression test: remove the fix and the test must go red, put the fix back and it goes green. |
| The 3-fix mark | How many fixes have I tried that still fail? | The 3rd fix still fails, and each attempt exposes another place that shares state. It stops and asks you whether to revisit the architecture or the scope. |
Code bugs (tests, bugs, builds) go through 4 phases: investigate, find a working pattern to compare against, test a hypothesis, and only then fix. System issues (server, CI, DB, performance) go through 5 steps, from assessing the scope to proposing a fix.
Sample prompt for a test that fails after a merge:
/ak-debug Test <test name> in <project> started failing after the latest merge.
Error: <paste the error message and stack trace>.
Expected: <correct behavior>.
Done when: that test passes and no other test breaks.| Flag | What it is for | Since ak |
|---|---|---|
--ultra | 5 independent diagnoses, keep the best one | 2.13.0 |
Below is the detailed version: the run flow, 6 situations with prompts, each flag explained (when to use it, when you do not need it, what you get, which flags it combines with), the change history by ak release, and common pitfalls. The detailed version and the interactive page are for subscribers. Your agent can also search them through the portal's MCP.
Opens when your account has subscriber access
This guide is for subscribers
Once your account has access, the full piece, the interactive visual and the agent call all open.
- Sign in or create a modernEngineer accountReading access belongs to your account email.
- Choose a plan on the pricing page1, 3 or 12 months, paid by VietQR bank transfer. Access opens about a minute after the money arrives.
- Or redeem a Facebook subscriber codePeople supporting the page on Facebook get an activation code by message each month.
Already a subscriber? Sign in to read.
Use this piece in your agent
Get an API keyCopy the text below and paste it into Claude Code, Codex or whichever agent you use. The agent reads the piece and checks it against the repo you have open.
Read "ak-debug: prove the root cause before fixing a bug" on modernEngineer and apply it to this repo.
1. Call the content_get tool of the modernengineer MCP server with locale "en", slug "ak-debug". If the modernengineer MCP server is not connected, stop and walk me through connecting it from https://modernengineer.dev/en/mcp.
2. Summarize the main steps of the piece and point out which apply to this repo.
3. Propose concrete changes and ask me before editing any file.Connect MCP in Claude Code (once)
claude mcp add --transport http modernengineer \
https://api.modernengineer.dev/mcp \
--header "Authorization: Bearer <API key>"Reading the full piece over MCP needs an API key from a subscriber account or one that bought this guide. Without access, the agent only gets the opening.
- Version
- v1.0.0
- Updated
- 22/10/2026
- Licence
- All rights reserved
- Slug
- ak-debug
