// Use when debugging errors, test failures, build issues, or blocked tasks — structured triage to fix to learn
| name | kn-debug |
| description | Use when debugging errors, test failures, build issues, or blocked tasks — structured triage to fix to learn |
Systematic debugging: triage → reproduce → diagnose → fix → learn.
Announce: "Using kn-debug for [error/issue]."
Core principle: CLASSIFY FIRST → REPRODUCE → ROOT CAUSE → FIX → CAPTURE LEARNING.
Classify before investigating. Misclassifying wastes time.
| Type | Signals |
|---|---|
| Build failure | Compilation error, type error, missing module, bundler failure |
| Test failure | Assertion mismatch, snapshot diff, timeout, flaky intermittent |
| Runtime error | Crash, uncaught exception, undefined behavior |
| Integration failure | HTTP 4xx/5xx, env variable missing, API schema mismatch |
| Blocked task | Circular dependency, conflicting changes, unclear requirement |
Output: One-line classification: [TYPE] in [component]: [symptom]
Before deep investigation, search for known solutions (unified search includes docs, learnings, and memories):
mcp_knowns_search({ "action": "search", "query": "<keywords from classification>", "type": "doc" })
Also check learnings docs:
mcp_knowns_search({ "action": "search", "query": "<error pattern>", "type": "doc", "tag": "learning" })
Search memories for past debug patterns:
mcp_knowns_search({ "action": "search", "query": "<error pattern>", "type": "memory" })
If a known pattern matches → jump to Step 4 (Fix) using the documented resolution.
Run the exact failing command verbatim:
# Whatever failed — run it exactly
<failing-command> 2>&1
Capture error output verbatim. Exact line numbers and messages matter.
Run twice — if intermittent, classify as flaky (check shared state, race conditions, test ordering).
Read exactly the files mentioned in the error output. Do not read the entire codebase.
git log --oneline -10
git diff HEAD~3 -- <failing-file>
If a recent commit introduced the failure → fix is likely adjusting that change.
mcp_knowns_tasks({ "action": "get", "taskId": "<id>" })
Does the failure indicate the task was implemented against the wrong spec, or correctly but the spec was wrong?
Write a one-sentence root cause:
Root cause:
<file>:<line>—<what is wrong and why>
If you cannot write this sentence, you do not have the root cause yet. Do NOT proceed to Fix.
# Re-run the originally failing command
<failing-command>
mcp_knowns_tasks({ "action": "update", "taskId": "<id>",
"appendNotes": "🐛 Debug: <root cause summary>. Fix: <what was changed>"
})
mcp_knowns_tasks({ "action": "create", "title": "Fix: <root cause summary>",
"description": "Root cause: <detail>\nFix approach: <approach>",
"priority": "high",
"labels": ["bugfix"]
})
Run the exact command that originally failed. It must pass cleanly:
<original-failing-command>
Also run broader checks for regressions:
# Project-specific build/test/lint
go build ./...
go test ./...
If verification fails → return to Step 3 with new information. Do NOT report success.
Ask: would this save ≥15 minutes if a future agent knew it?
Quick pattern (< 5 min to describe): save to memory for fast recall:
mcp_knowns_memory({ "action": "add", "title": "<error pattern>",
"content": "Root cause: <sentence>. Fix: <what resolves it>",
"layer": "project",
"category": "failure",
"tags": ["debug", "<domain>"]
})
Detailed pattern (worth a full writeup): create or update a learning doc:
mcp_knowns_search({ "action": "search", "query": "<failure domain>", "type": "doc", "tag": "learning" })
If existing learning doc found — update it:
mcp_knowns_docs({ "action": "update", "path": "<existing-path>",
"appendContent": "\n\n## <Date> — <Classification>\n\n**Root cause:** <sentence>\n**Signal:** <how to recognize>\n**Fix:** <what resolves it>"
})
If no existing doc — create new:
mcp_knowns_docs({ "action": "create", "title": "Learning: <domain> — <pattern>",
"description": "Debugging pattern for <issue type>",
"folder": "learnings",
"tags": ["learning", "<domain>"],
"content": "## Problem\n\n<what goes wrong>\n\n## Root Cause\n\n<why it happens>\n\n## Signal\n\n<how to recognize this pattern>\n\n## Fix\n\n<what resolves it>\n\n## Source\n\n@task-<id> (if applicable)"
})
If the documented resolution failed or is outdated:
mcp_knowns_docs({ "action": "update", "path": "<learning-path>",
"appendContent": "\n\n⚠️ **Update <date>:** Resolution no longer accurate — <what changed>"
})
Required order for the final user-facing response:
For kn-debug, the key details should cover:
| Situation | First action |
|---|---|
| Build fails | git log --oneline -10 — check recent changes |
| Test fails | Run test verbatim, capture exact assertion output |
| Flaky test | Run 5× — if intermittent, check shared state/ordering |
| Runtime crash | Read stack trace top-to-bottom, find first line in your code |
| Integration error | Check env vars, then API response body (not just status code) |
| Recurring issue | Search learnings docs first |
/kn-implement <id> — resume implementation after fix/kn-extract — extract pattern if fix reveals reusable knowledge/kn-review — review fix before committing/kn-commit — commit the fixUse when working with Knowns documentation - viewing, searching, creating, or updating docs
Use when extracting reusable patterns, decisions, failures, or knowledge into documentation
Use when implementing all tasks from an approved spec in one continuous run without manual review gates
Use when implementing a task - follow the plan, check ACs, track progress
Use at the start of a new session to read project docs, understand context, and see current state
Use when creating an implementation plan for a task