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 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Rune-kit/rune --skill debug技能说明
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
cookwhen implementation hits unexpected errors - Called by
testwhen a test fails with unclear reason - Called by
fixwhen 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 modulesfix(L2): when root cause found, hand off with diagnosis for fix applicationbrainstorm(L2): 3-Fix Escalation when root cause is "wrong approach" — invoke with mode="rescue" for category-diverse alternativesplan(L2): 3-Fix Escalation when root cause is "wrong module design" — invoke for redesigndocs-seeker(L3): lookup API docs for unclear errors or deprecated APIsproblem-solver(L3): structured reasoning (5 Whys, Fishbone) for complex bugsbrowser-pilot(L3): capture browser console errors, network failures, visual bugssequential-thinking(L3): multi-variable root cause analysisneural-memory(L3): after root cause found — capture error pattern for future recognitionadversary(L2): onagent.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 4fix(L2): root cause unclear, can't fix blindly — needs diagnosis firsttest(L2): test fails unexpectedly, unclear whysurgeon(L2): diagnose issues in legacy modules
Cross-Hub Connections
debug↔fix— bidirectional: debug finds cause → fix applies, fix can't determine cause → debug investigatesdebug←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.
- Identify the narrowest directory containing the affected files (from stack trace or error location)
- Announce to user: "Debug scope locked to
<dir>/. Changes will be restricted to this area." - Any fix recommendation in the Debug Report MUST reference only files within this boundary
- 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
Grepto search codebase for the exact e