| name | explain-error |
| description | Diagnose an error message or traceback, find the root cause, and explain it clearly. |
| trigger | User pastes a traceback, says "explain error", "why does this fail", "diagnose", or asks about an exception |
| route | explain-error |
| output-contract | Structured diagnosis with Error, Location, Root Cause, and Fix sections; no code modifications |
Explaining Errors
Workflow
- Reproduce — run the command that produces the error:
result = await self.shell.run("uv run pytest tests/ -x -q", timeout=60)
print(result.stderr or result.stdout)
-
Locate — identify the file, line number, and exception type from the traceback.
-
Read context — inspect the failing code and its callers:
match = await self.shell.read("src/module.py", lines=(40, 80))
print(match.text)
- Trace dependencies — check imports, configuration, and recent changes:
await self.shell.run("git log --oneline -5 -- src/module.py")
await self.shell.run("git diff HEAD -- src/module.py")
- Explain — produce a structured diagnosis:
- What happened (exception + message)
- Where (file:line + call chain)
- Why (root cause reasoning)
- How to fix (concrete next steps)
Output format
Structure your answer as:
## Error
<exception type and message>
## Location
<file:line, function name>
## Root Cause
<1-3 sentences explaining why this happens>
## Fix
<numbered steps or code suggestion>
Rules
- Always reproduce before explaining — do not guess from the message alone.
- Cite exact file paths and line numbers in your explanation.
- If the error is environment-related (missing dep, wrong version), say so explicitly.
- Do not modify code in inspect mode — only diagnose and explain.
