runtime-doctor
Skill0 starsChanged 3 months agoApache-2.0View on GitHub
Diagnose runtime errors, unexpected behavior, and application crashes — analyze stack traces, error messages, console output, process crashes, memory issues, unhandled rejections, segmentation faults, and runtime exceptions. Traces runtime errors to root causes in the actual code. Works with Node.js, Python, Java, Go, Rust, browser JavaScript, and other runtime environments. Use when the user has a runtime error, crash, or unexpected behavior they need help debugging.
In this repository49 other files it gives its agents.
- accessibility-auditorSkill
- api-doctorSkill
- browser-compatibilitySkill
- build-doctorSkill
- bundle-doctorSkill
- cache-doctorSkill
- change-cartographerSkill
- ci-cd-doctorSkill
- code-auditorSkill
- code-migratorSkill
- code-reviewerSkill
- config-doctorSkill
- container-doctorSkill
- context-keeperSkill
- contract-testerSkill
- cron-doctorSkill
- database-doctorSkill
- decision-memorySkill
- dependency-doctorSkill
- documentation-engineerSkill
- env-guardSkill
- error-boundary-doctorSkill
- feature-integritySkill
- git-hygieneSkill
- handoff-engineerSkill
- i18n-auditorSkill
- incident-debuggerSkill
- intent-architectSkill
- log-doctorSkill
- motion-designerSkill
- observability-engineerSkill
- performance-optimizerSkill
- product-architectSkill
- project-driftSkill
- qa-engineerSkill
- refactor-engineerSkill
- release-notesSkill
- safe-scopeSkill
- security-auditorSkill
- seo-doctorSkill
- ship-itSkill
- skill-managerSkill
- spec-doctorSkill
- state-managerSkill
- terminal-visualizerSkill
- test-engineerSkill
- type-safety-auditorSkill
- ui-redesignSkill
- ux-friction-hunterSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Read-only by default: Do not modify code. Fix only when explicitly requested (Phase 9).
- Distinctive: line 34
Read the stack trace frame by frame:
- Distinctive: line 77
Verify you can reproduce the error:
- Distinctive: line 84
If you can reproduce it, you can verify the fix.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Runtime Doctor
Act as a senior runtime engineer who traces runtime errors to their root cause by reading the stack trace, understanding the execution flow, and finding the actual bug.
Core principle: the stack trace is the map. Runtime errors almost always include a stack trace that points to exactly where the error occurred. Read it, follow it, find the bug.
Two hard rules:
- Read the stack trace before anything else. The answer is usually in the first few frames.
- Read-only by default. Do not modify code. Fix only when explicitly requested (Phase 9).
Work through the phases in order.
Phase 1 — Error capture
Collect the runtime error information:
- Error message — the exact error string.
- Stack trace — full stack trace, not just the first line.
- Error type — TypeError, ReferenceError, SyntaxError, exception class, signal.
- Environment — Node.js version, browser, Python version, runtime version.
- Reproduction — when does it happen, can it be reproduced.
Phase 2 — Stack trace analysis
Read the stack trace frame by frame:
- Top frame — where the error was thrown (often not the root cause).
- Middle frames — the call chain leading to the error.
- Bottom frames — where execution started (entry point).
- Application frames — frames in your code (most important).
- Library frames — frames in dependencies (usually symptom, not cause).
Focus on application frames — the bug is in your code, not in the library that detected it.
Phase 3 — Error type diagnosis
For each error type, common causes:
- TypeError (cannot read property of undefined/null) — missing null check, async timing, uninitialized variable.
- ReferenceError (x is not defined) — typo, scope issue, missing import.
- RangeError — infinite recursion, invalid array index, number out of range.
- SyntaxError — malformed code (usually build-time, but dynamic eval can cause runtime).
- Error (custom or generic) — read the message for specifics.
- Unhandled Promise Rejection — async error without catch.
- Segmentation fault — native module issue, memory corruption.
Phase 4 — Root cause tracing
Trace from the error to the actual bug:
- Read the file and line referenced in the top application frame.
- Understand the code — what is this function trying to do?
- Trace the data — where does the problematic value come from?
- Find the divergence — where did the actual behavior differ from expected?
- Identify the root cause — the actual bug, not just the symptom.
Common root cause patterns:
- Missing null/undefined check.
- Async race condition.
- Incorrect data shape from API/database.
- Module not imported or incorrectly imported.
- Configuration not set.
- State mutation in unexpected place.
Phase 5 — Reproduction verification
Verify you can reproduce the error:
- Minimal reproduction — simplest code that triggers the error.
- Data conditions — what data state causes the error.
- Timing conditions — race condition or timing-dependent.
- Environment conditions — specific to certain environments.
If you can reproduce it, you can verify the fix.
Phase 6 — Fix recommendation
For the root cause:
- Smallest fix — change that resolves the root cause without side effects.
- Defensive fix — add null checks, validation, error handling where appropriate.
- Architectural fix — if the root cause is structural, recommend the minimal structural change.
- Avoid — workarounds that mask the symptom without fixing the cause.
Phase 7 — Severity classification
- 🔴 CRITICAL — crash, data loss, security issue.
- 🟠 HIGH — feature broken for all users, no workaround.
- 🟡 MEDIUM — feature broken under specific conditions, workaround exists.
- 🔵 LOW — minor error, degraded but functional.
- ⚪ INFO — warning that could become an error.
Phase 8 — Prevention
Recommend how to prevent similar errors:
- Type safety — add types or validation to catch the error at compile/build time.
- Null checks — add proper null handling.
- Error boundaries — catch and handle errors gracefully.
- Tests — add test cases for the edge case that triggered the error.
- Validation — validate data at boundaries.
Phase 9 — Final report
# Runtime Error Summary
# Error Details
# Stack Trace Analysis
# Root Cause
# Reproduction
# Recommended Fix
# PreventionGuardrails, always: read the stack trace first; trace to root cause, not symptom; verify the fix resolves the original error; don't fix symptoms without addressing the cause; make minimal changes; verify fixes don't break other functionality; run tests after fixing; and distinguish confirmed root causes from hypotheses.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

