Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

debug

Root cause analysis for bugs and unexpected behavior. Traces errors through code, uses structured reasoning, and hands off to fix when cause is found. Core of the debug↔fix mesh. When the diagnosed cause is a memory leak in a long-running process, escalates to perf for cost-impact framing (leaks drive OOM-restart → cold-start → autoscaler spend, often 20-40% bill inflation).

Rune-kit · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add Rune-kit/rune --skill debug

About this skill


name: debug description: "Root cause analysis for bugs and unexpected behavior. Traces errors through code, uses structured reasoning, and hands off to fix when cause is found. Core of the debug↔fix mesh. When the diagnosed cause is a memory leak in a long-running process, escalates to perf for cost-impact framing (leaks drive OOM-restart → cold-start → autoscaler spend, often 20-40% bill inflation)." metadata: author: runedev version: "1.4.0" layer: L2 model: opus group: development tools: "Read, Bash, Glob, Grep" emit: bug.diagnosed, agent.stuck listen: tests.failed, oracle.response

debug

Purpose

Root cause analysis ONLY. Debug investigates — it does NOT fix. It traces errors through code, analyzes stack traces, forms and tests hypotheses, and identifies the exact cause before handing off to rune:fix.

Triggers

  • Called by cook when implementation hits unexpected errors
  • Called by test when a test fails with unclear reason
  • Called by fix when root cause is unclear before fixing
  • /rune debug <issue> — manual debugging
  • Auto-trigger: when error output contains stack trace or error code

Calls (outbound)

  • scout (L2): find related code, trace imports, identify affected modules
  • fix (L2): when root cause found, hand off with diagnosis for fix application
  • brainstorm (L2): 3-Fix Escalation when root cause is "wrong approach" — invoke with mode="rescue" for category-diverse alternatives
  • plan (L2): 3-Fix Escalation when root cause is "wrong module design" — invoke for redesign
  • docs-seeker (L3): lookup API docs for unclear errors or deprecated APIs
  • problem-solver (L3): structured reasoning (5 Whys, Fishbone) for complex bugs
  • browser-pilot (L3): capture browser console errors, network failures, visual bugs
  • sequential-thinking (L3): multi-variable root cause analysis
  • neural-memory (L3): after root cause found — capture error pattern for future recognition
  • adversary (L2): on agent.stuck — oracle-mode dispatches stateless second-model pass to break confirmation-bias loop (parallel with scout zoom-out)

Called By (inbound)

  • cook (L1): implementation hits bug during Phase 4
  • fix (L2): root cause unclear, can't fix blindly — needs diagnosis first
  • test (L2): test fails unexpectedly, unclear why
  • surgeon (L2): diagnose issues in legacy modules

Cross-Hub Connections

  • debug ↔ fix — bidirectional: debug finds cause → fix applies, fix can't determine cause → debug investigates
  • debug ← test — test fails → debug investigates

Execution

Step 0: Build a Feedback Loop (the actual skill)

The loop is the speed limit. A fast, deterministic, agent-runnable pass/fail signal turns debugging into mechanical bisection. Without one, hypotheses just consume noise.

Skip Step 0 only if the existing repro is already one command, deterministic, and runs in < 5s.

Otherwise, before Step 1: pick the highest viable rung from references/feedback-loop-ladder.md (10-rank ladder: failing test → curl → CLI snapshot → headless browser → trace replay → throwaway harness → fuzz → bisection → differential → HITL script). Construct it. Verify it currently FAILS (proves it measures the bug, not noise). Only then proceed.

If loop construction takes > 10 minutes, that itself is the diagnosis: the bug surface is too large or the system too coupled. Trigger the 3-Fix Escalation Rule (Step 6) — architecture is the problem, not the bug.

Step 1: Reproduce

Understand and confirm the error described in the request.

  • Read the error message, stack trace, and reproduction steps
  • Identify which environment it occurs in (dev/prod, browser/server)
  • Confirm the error is consistent and reproducible before proceeding
  • If no reproduction steps provided, ask for them or attempt the most likely path

Step 1.5: Scope Lock (Edit Boundary)

After reproducing the error, lock edits to the narrowest affected directory to prevent debug-driven scope creep — the #1 source of "while I'm here, let me also fix..." violations.

  1. Identify the narrowest directory containing the affected files (from stack trace or error location)
  2. Announce to user: "Debug scope locked to <dir>/. Changes will be restricted to this area."
  3. Any fix recommendation in the Debug Report MUST reference only files within this boundary
  4. If root cause traces outside the boundary → expand scope with user confirmation first

Skip conditions (do NOT lock):

  • Bug spans the entire repo (3+ unrelated directories in stack trace)
  • Cannot determine affected area from initial evidence
  • User explicitly says "investigate everything"

Why: Debugging naturally expands scope as you trace root causes. Without a boundary, rune:fix receives recommendations touching 10+ files across unrelated modules. The scope lock forces discipline: fix at the source, not at every symptom site.

Step 2: Gather Evidence

Use tools to collect facts — do NOT guess yet.

  • Use Grep to search codebase for the exact e
Read the complete source ↗