Debug anything — trace app runtime errors or diagnose CKS skill/agent/command issues. Language-agnostic diagnostic approach using code tracing and strategic logging. Use when: "debug", "why is this broken", "trace this error", "why did CKS do that", "what went wrong", "this isn't working", "unexpected behavior", "diagnose", or any variation of debugging app code or CKS plugin internals.
From cksnpx claudepluginhub cardinalconseils/claude-starter --plugin cksThis skill is limited to using the following tools:
references/log-patterns.mdDelivers DB-free sandbox API regression tests for Next.js/Vitest to catch AI blind spots in self-reviewed code changes like API routes and backend logic.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
Provides process, architecture, review, hiring, and testing guidelines for engineering teams relying on AI code generation.
Unified diagnostic capability for two domains:
Both modes follow the same philosophy: trace → diagnose → report → fix only with permission.
Check $ARGUMENTS from the command:
--cks present?
YES → CKS Self-Debug mode
--cks has a value (e.g., "discover", "prd-executor")?
YES → Target that specific component
NO → Diagnose last CKS action from lifecycle logs
NO → App Debug mode
Error string in arguments?
YES → Error-driven mode
NO → Exploratory mode (ask what's wrong)
Detect project language/framework:
package.json, tsconfig.json, pyproject.toml, go.mod, Cargo.toml, MakefileGather context for the agent:
console.log() / print() / fmt.Println() / println!() / putsDispatch the debugger agent:
Agent(subagent_type="debugger", prompt="""
Mode: app-error
Error: {error message or stack trace}
Project root: {cwd}
Language: {detected language}
Log syntax: {appropriate log statement}
Diagnose the root cause. Do NOT fix anything.
Return structured diagnosis.
""")
Ask what's wrong:
AskUserQuestion({
questions: [{
question: "What's happening that shouldn't be?",
header: "Debug: Describe the Issue",
multiSelect: false,
options: [
{ label: "Wrong output / data", description: "Code runs but produces incorrect results" },
{ label: "Feature not working", description: "Something that should work doesn't" },
{ label: "Performance issue", description: "Too slow, hanging, or resource-heavy" },
{ label: "Intermittent / flaky", description: "Sometimes works, sometimes doesn't" },
{ label: "Other", description: "I'll describe it" }
]
}]
})
Gather context (same as error-driven, plus user's description)
Dispatch the debugger agent with mode app-exploratory
Read these files (skip any that don't exist):
Read .prd/PRD-STATE.md
Read .prd/logs/lifecycle.jsonl (last 50 lines via tail)
If --cks has a value, map it to a component:
# Check if it's a command
Glob ${CLAUDE_PLUGIN_ROOT}/commands/{value}.md
# Check if it's an agent
Glob ${CLAUDE_PLUGIN_ROOT}/agents/{value}.md
Glob ${CLAUDE_PLUGIN_ROOT}/agents/*{value}*.md
# Check if it's a skill
Glob ${CLAUDE_PLUGIN_ROOT}/skills/{value}/SKILL.md
# Check if it's a phase name
Grep "phase.{value}" .prd/logs/lifecycle.jsonl
If no value, read the last 10 lifecycle log entries to identify the most recent CKS action.
Read the identified skill/agent/command file to understand what it's SUPPOSED to do.
Agent(subagent_type="debugger", prompt="""
Mode: cks-self
Component: {type} — {name}
Component path: {file path}
Component content: {full content of the skill/agent/command file}
PRD State:
{content of PRD-STATE.md}
Recent lifecycle logs:
{last 20 relevant log entries}
Diagnose why this CKS component isn't working as expected.
Compare its instructions against what the logs show actually happened.
Return structured diagnosis.
""")
After the agent returns its diagnosis and the command presents the report:
For app fixes:
For CKS fixes:
description field for better triggeringVerify the fix:
Display the exact changes as a diff (Read the files, show old → new) without applying.
End the session. The diagnosis report is their deliverable.
For log statement patterns and instrumentation reference, read references/log-patterns.md.
This skill ships with opinionated defaults. Review and adapt to your needs:
references/log-patterns.mdRead, Grep, Glob, Bash, Agent, AskUserQuestion. No Write/Edit by design — fixes require explicit user approval.| Rationalization | Reality |
|---|---|
| "Let me just try random fixes" | Reproduce first, localize second, fix third. Random fixes hide root causes and introduce new bugs. |
| "I know what the problem is" | Hypothesis without evidence is a guess. Confirm with logs, breakpoints, or test output before fixing. |
| "It works on my machine" | Environment differences are the #1 source of 'works for me' bugs. Check configs, deps, and data. |
| "Let me rewrite this whole thing" | Rewriting to fix a bug is like demolishing a house to fix a leaky faucet. Localize first. |
[DEBUG] lines after fix