debug

name	debug
description	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.
allowed-tools	Read, Grep, Glob, Bash, Agent, AskUserQuestion

Debug Skill

Purpose

Unified diagnostic capability for two domains:

1. App debugging — Runtime errors, unexpected behavior, data flow issues in the user's project
2. CKS self-debugging — When CKS skills, agents, or commands misbehave

Both modes follow the same philosophy: trace → diagnose → report → fix only with permission.

Mode Detection

Check $ARGUMENTS from the command:

Pattern	Mode	Workflow
--issue N	issue-driven — debug a specific GitHub issue	workflows/mode-issue-driven.md
--issues N1,N2,...	multi-issue — parallel debug of multiple issues (wave-ordered)	workflows/mode-multi-issue.md
--all	multi-issue — debug all open cks:blocking issues from this repo	workflows/mode-multi-issue.md
--cks [value]	cks-self — CKS plugin introspection; value targets a specific component	(inline below)
Error string (no flags)	app-error — trace a specific error message or stack trace	(inline below)
No args	app-exploratory — ask user what's wrong before diagnosing	(inline below)

Wave is a sub-feature of multi-issue: issues are topologically sorted into dependency waves and executed sequentially. It is not a separate top-level mode. See workflows/mode-multi-issue.md for wave assignment and execution details.

---

App Debug Workflow

Error-Driven (error string provided)

1. Detect project language/framework:

   • Glob for package.json, tsconfig.json, pyproject.toml, go.mod, Cargo.toml, Makefile
   • This determines log statement syntax for strategic instrumentation

2. Gather context for the agent:

   • The error message itself
   • The project root path
   • The detected language/framework
   • Log statement syntax: console.log() / print() / fmt.Println() / println!() / puts

3. Dispatch the debugger agent:

   Agent(subagent_type="cks: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.
   """)
   

Exploratory (no error string)

1. 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" }
       ]
     }]
   })
   

2. Gather context (same as error-driven, plus user's description)

3. Dispatch the debugger agent with mode app-exploratory

---

CKS Self-Debug Workflow

Step 1: Gather CKS State

Read these files (skip any that don't exist):

Read .prd/PRD-STATE.md
Read .prd/logs/lifecycle.jsonl (last 50 lines via tail)

Step 2: Identify Target Component

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.

Step 3: Read the Component

Read the identified skill/agent/command file to understand what it's SUPPOSED to do.

Step 4: Dispatch Debugger Agent

Agent(subagent_type="cks: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.
""")

---

Post-Diagnosis: Fix Flow

After the agent returns its diagnosis and the command presents the report:

If user says "Apply fix"

1. For app fixes:

   • Edit the files identified in the diagnosis
   • Fix the ROOT CAUSE, not the symptom
   • Re-run the relevant command (build, test, or manual repro) to verify
   • Report: fixed / partially fixed / failed

2. For CKS fixes:

   • If state corrupted: repair PRD-STATE.md or .prd/ files to match reality
   • If skill description mismatch: update the skill's description field for better triggering
   • If agent off-rails: tighten the agent's constraints or adjust its tools list
   • If skipped steps: check workflow file for conditional logic that may have short-circuited
   • If wrong output: adjust the agent's prompt or the skill's instructions

3. Verify the fix:

   • App: re-run build/test
   • CKS: re-run the command that failed and confirm it works

If user says "Show me the fix first"

Display the exact changes as a diff (Read the files, show old → new) without applying.

If user says "I'll fix it myself"

End the session. The diagnosis report is their deliverable.

---

Strategic Logging Reference

For log statement patterns and instrumentation reference, read references/log-patterns.md.

---

Customization

This skill ships with opinionated defaults. Review and adapt to your needs:

• Log patterns: Suggested instrumentation patterns — edit references/log-patterns.md
• Fix approval flow: How fixes are proposed and approved — edit SKILL.md
• CKS failure patterns: Diagnostic patterns for CKS self-debug — edit SKILL.md
• allowed-tools: Currently Read, Grep, Glob, Bash, Agent, AskUserQuestion. No Write/Edit by design — fixes require explicit user approval.

Common Rationalizations

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.

Constraints

• Diagnose first, always — never jump to fixing without showing the report
• Trace, don't guess — every diagnosis must cite file:line or log evidence
• Language-agnostic — use strategic logging, not language-specific debuggers
• Clean up after — if strategic logging was injected, offer to remove [DEBUG] lines after fix
• Log the session — every debug session gets a lifecycle.jsonl entry via cks-log.sh