kandev/.agents/skills/debug-instance/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
debug-instance	Debug a running kandev development instance. Use when the user reports a bug, unexpected behavior, or asks to investigate an issue while kandev is running via `make dev`. Fetches backend logs, analyzes errors, and optionally inspects the UI via an existing Playwright browser session.	Bash(curl:*) Bash(jq:*) Bash(playwright-cli:*)

Debug Running Kandev Instance

Diagnose issues in a running kandev development instance by fetching structured logs and optionally inspecting the UI via an existing Playwright browser session.

Immediately: Create Task Pipeline

As soon as this skill is invoked, create a task list to track progress:

1. Detect running instance — probe health endpoint, determine ports
2. Fetch & analyze backend logs — get debug export, summarize errors
3. Browser inspection (if UI-related) — check for existing playwright session, inspect DOM/console
4. Diagnose & report — correlate findings, present root cause hypothesis

Mark each task as in_progress when starting and completed when done. Skip task 3 if the issue is purely backend.

---

Phase 1 — Detect Running Instance

1. Probe the default backend port:

   curl -sf http://localhost:38429/api/v1/system/health
   

2. If that fails, try ports 38430–38435 (kandev auto-assigns nearby ports if default is busy).
3. If still not found, ask the user which port kandev is running on.
4. Derive the web port: typically backend_port - 1000 (e.g., 38429 → 37429).

Phase 2 — Fetch & Analyze Logs

IMPORTANT: The debug export returns raw JSON. If output appears schema-converted (types instead of values), the response is being compressed by a proxy tool — use curl directly or check tool configuration.

1. Fetch the debug export:

   curl -s http://localhost:<backend_port>/api/v1/system/debug/export | jq .
   

2. Summarize findings:
   • Metadata: uptime, version, goroutine count, memory usage
   • Errors: count of error-level entries, most recent errors with stack traces
   • Warnings: count and notable patterns
3. Filter by level if needed:

   curl -s "http://localhost:<backend_port>/api/v1/system/debug/export?level=error" | jq .logs
   

4. Correlate errors with the user's reported issue.

Phase 3 — Browser Interaction (conditional)

Only enter this phase if:

• The issue is UI-related
• The user explicitly asks to inspect the browser
• Log analysis alone is insufficient

Check for existing Playwright session

playwright-cli list

• If a session exists: use it directly. Do NOT open a new browser.
• If no session exists and browser inspection is needed:

  playwright-cli open http://localhost:<web_port> --headed
  

Browser debugging commands

# Page state
playwright-cli snapshot

# Console logs (frontend errors)
playwright-cli console
playwright-cli console error

# Network activity
playwright-cli network

# Execute JS to extract frontend log buffer
playwright-cli eval "JSON.stringify(window.__kandevLogBuffer?.snapshot?.() ?? [])"

# Navigate to a specific page
playwright-cli goto http://localhost:<web_port>/some/path

# Inspect specific elements
playwright-cli snapshot "#main"
playwright-cli snapshot --depth=4

Correlate frontend + backend

After gathering browser console errors or frontend log buffer entries, cross-reference with backend error timestamps to identify the full request lifecycle.

Phase 4 — Diagnose & Report

1. Present a structured summary:
   • Issue: what was reported
   • Evidence: relevant log entries, console errors, DOM state
   • Root cause hypothesis: most likely cause based on evidence
   • Suggested fix: what code to change (with file paths)
2. If the fix is clear, offer to implement it (delegate to /fix or /tdd).

---

Rules

• Always probe health first — never assume ports.
• Always check playwright-cli list before opening a browser — reuse existing sessions.
• Present log summary before browser inspection — logs are faster and often sufficient.
• Don't leave browsers open — if you opened one, close it when done (unless user wants to keep it).
• Filter aggressively — 2000 log entries is a lot; use ?level=error or grep for keywords.
• Create the task pipeline immediately — track progress from the start.