# Debug Runtime

> Root-causes runtime errors, crashes, and unexpected behavior from stack traces, logs, and live app output. Use when the app crashes, throws an unhandled error, misbehaves, or the user pastes a stack trace/error/log needing root cause.

- Skill: `rockclaver/debug-runtime` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rockclaver/debug-runtime`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rockclaver/debug-runtime/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: rockclaver (https://skillmd.com/u/rockclaver)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rockclaver/debug-runtime

---


# Debug Runtime

Root-cause fast: evidence → origin → hypothesis → confirm → fix or escalate.

## Workflow

### 1. Evidence
Stack trace/error (`file:line`), what happened, environment, recent changes. If unavailable, tail the logs:
```bash
tail -100 logs/app.log | grep -i "error\|fatal\|exception"
journalctl -u <service> -n 100 --no-pager
docker logs <container> --tail 100
```

### 2. Origin
Deepest frame in YOUR code (skip framework frames — Express/Rails/Django/Next.js). Read it and its caller. Sparse? `grep -rn "error text" src/`

### 3. Hypothesis
*"This occurs because [condition] when [state is X]."* Check error type, call path, recent changes.

### 4. Confirm

| Method | When to use |
|---|---|
| Targeted failing test | Root cause clear, want a regression guard |
| One-line debug log + re-run | Need to observe live state |
| Call function in REPL/scratch file | Input known, fastest to isolate |

### 5. Fix or escalate
Fix inline when ≤10 lines, root cause unambiguous. Escalate to `/triage-issue` when:
- fix needs a design decision or touches multiple callers
- it's a symptom of a deeper structural problem
- you want a tracked issue + TDD plan before changing code

## Edge cases

| Situation | Action |
|---|---|
| No stack trace | Verbose logging/`DEBUG=*`; check error page |
| Prod-only | Diff env/config across envs; read config-loading code |
| Race condition | Shared mutable state, missing locks, non-atomic ops |
| External dependency | Read library source; check its GitHub issues |
| Minified trace | Ask for source map; rebuild with `NODE_ENV=development` |
| No repro | Ask for a verbose-logged repro; check load/input correlation |