Error Interpretation
What This Skill Enables
Agents with this skill can diagnose failures methodically by reading what the system is actually telling them. Without it, agents fall into shotgun debugging -- trying random fixes, changing multiple things at once, and hoping something sticks. A skilled agent reads the error, forms a hypothesis, and verifies it before writing a single line of corrective code.
Core Competencies
1. Read the Actual Error Message First
This sounds obvious but is the most commonly skipped step. Before doing anything:
- Copy the full error output, not just the first line.
- Identify the error type or code (e.g.,
TypeError, ECONNREFUSED, HTTP 403, exit code 137).
- Identify the error message (the human-readable explanation after the type).
- Note any file path and line number referenced.
# Example: Don't just see "TypeError". Read the whole thing.
TypeError: Cannot read properties of undefined (reading 'map')
at renderList (src/components/UserList.tsx:14:22)
at processChild (node_modules/react-dom/cjs/react-dom.development.js:1234:12)
# What to extract:
# Type: TypeError
# Message: Cannot read properties of undefined (reading 'map')
# Where: src/components/UserList.tsx, line 14, column 22
# What: Something is undefined when .map() is called on it
2. Parse Stack Traces Correctly
Stack traces list frames from most recent call to oldest. Your job is to find the boundary between your code and framework/library code.
| Frame Type |
How to Identify |
What to Do |
| Your code |
File path is in src/, app/, lib/, or your project directories. |
This is where the bug lives. Start here. |
| Framework code |
Path is in node_modules/, standard library, or runtime internals. |
Usually not the bug. Tells you what the framework was doing when your code failed. |
| Generated code |
Path references .next/, dist/, build/, __pycache__/. |
Map back to the source file. Don't edit generated code. |
Read from the top. The first frame in your code is almost always the place to investigate.
3. Categorize the Error
Different categories demand different investigation strategies:
| Category |
Examples |
First Move |
| Syntax |
SyntaxError, IndentationError, unexpected token |
Go to the exact line. Look for typos, missing brackets, bad indentation. |
| Type |
TypeError, AttributeError, ClassCastException |
Check what value is actually present vs. what was expected. Add a log or breakpoint one line above. |
| Runtime |
RangeError, IndexError, NullPointerException |
Trace the data flow. Where did the bad value originate? |
| Network |
ECONNREFUSED, TimeoutError, HTTP 4xx/5xx |
Check if the target service is running. Verify URL, port, auth. |
| Permission |
EACCES, PermissionError, HTTP 401/403 |
Check file permissions, API keys, IAM roles, token expiry. |
| Resource |
ENOMEM, exit code 137, OOMKilled |
The process ran out of memory or disk. This is an environment issue, not a code bug. |
4. Avoid Shotgun Debugging
Shotgun debugging is changing things at random until the error disappears. It wastes time and often introduces new bugs. Instead, follow this discipline:
1. Read the error message (competency 1).
2. Locate the failing line (competency 2).
3. Form ONE hypothesis about what is wrong.
4. Identify ONE change that would confirm or refute the hypothesis.
5. Make that change and re-run.
6. If the hypothesis was wrong, revert and form a new one.
Never make two changes at once. If you change two things and the error goes away, you do not know which change fixed it -- and one of them may have introduced a latent bug.
5. Use Error Messages to Form Hypotheses
Translate the error into a plain-language hypothesis before writing any fix:
| Error Message |
Hypothesis |
Cannot read properties of undefined (reading 'map') |
The variable I'm calling .map() on is undefined. It was probably not initialized, or the API returned an unexpected shape. |
ECONNREFUSED 127.0.0.1:5432 |
The PostgreSQL server is not running on localhost, or it is on a different port. |
Module not found: Can't resolve './utils' |
The file utils does not exist at that relative path, or the extension is wrong, or the file was moved. |
403 Forbidden |
The credentials are missing, expired, or lack the required scope for this endpoint. |
A hypothesis is testable. "Something is broken" is not a hypothesis. "The users prop is undefined because the parent component does not pass it" is.
Behavioral Rules
- Never propose a fix without first quoting the exact error message and explaining what it means.
- Never change more than one thing at a time when diagnosing an error.
- Always identify whether the failing line is in your code, framework code, or generated code before investigating.
- Revert any diagnostic change that did not help before trying the next hypothesis.
- If the same error persists after three hypotheses, step back and re-read the full output from scratch -- you likely missed something.
Failure Modes
| Failure |
Symptom |
Correction |
| Shotgun debugging |
Multiple unrelated changes in one attempt; "let me try this" without rationale. |
One hypothesis, one change, one test run. Revert if wrong. |
| Ignoring the message |
Agent says "I see an error" but never quotes or analyzes it. |
Always paste and parse the full error before acting. |
| Fixing the wrong frame |
Agent edits framework or generated code instead of source. |
Trace the stack to the first frame in project source code. |
| Treating symptoms |
Error goes away but root cause remains (e.g., wrapping in try/catch without handling). |
Ensure the fix addresses why the error occurs, not just that it occurs. |
| Stale hypothesis |
Agent keeps pursuing the same theory despite contradicting evidence. |
After two failed attempts on one theory, discard it and re-read the error. |
1---2name: error-interpretation3description: Read error messages, stack traces, and logs systematically rather than guessing at fixes.4---56# Error Interpretation78## What This Skill Enables910Agents with this skill can diagnose failures methodically by reading what the system is actually telling them. Without it, agents fall into shotgun debugging -- trying random fixes, changing multiple things at once, and hoping something sticks. A skilled agent reads the error, forms a hypothesis, and verifies it before writing a single line of corrective code.1112## Core Competencies1314### 1. Read the Actual Error Message First1516This sounds obvious but is the most commonly skipped step. Before doing anything:17181. Copy the **full** error output, not just the first line.192. Identify the **error type or code** (e.g., `TypeError`, `ECONNREFUSED`, `HTTP 403`, exit code 137).203. Identify the **error message** (the human-readable explanation after the type).214. Note any **file path and line number** referenced.2223```24# Example: Don't just see "TypeError". Read the whole thing.2526TypeError: Cannot read properties of undefined (reading 'map')27 at renderList (src/components/UserList.tsx:14:22)28 at processChild (node_modules/react-dom/cjs/react-dom.development.js:1234:12)2930# What to extract:31# Type: TypeError32# Message: Cannot read properties of undefined (reading 'map')33# Where: src/components/UserList.tsx, line 14, column 2234# What: Something is undefined when .map() is called on it35```3637### 2. Parse Stack Traces Correctly3839Stack traces list frames from most recent call to oldest. Your job is to find the boundary between your code and framework/library code.4041| Frame Type | How to Identify | What to Do |42|---|---|---|43| **Your code** | File path is in `src/`, `app/`, `lib/`, or your project directories. | This is where the bug lives. Start here. |44| **Framework code** | Path is in `node_modules/`, standard library, or runtime internals. | Usually not the bug. Tells you what the framework was doing when your code failed. |45| **Generated code** | Path references `.next/`, `dist/`, `build/`, `__pycache__/`. | Map back to the source file. Don't edit generated code. |4647Read from the top. The first frame in **your** code is almost always the place to investigate.4849### 3. Categorize the Error5051Different categories demand different investigation strategies:5253| Category | Examples | First Move |54|---|---|---|55| **Syntax** | `SyntaxError`, `IndentationError`, unexpected token | Go to the exact line. Look for typos, missing brackets, bad indentation. |56| **Type** | `TypeError`, `AttributeError`, `ClassCastException` | Check what value is actually present vs. what was expected. Add a log or breakpoint one line above. |57| **Runtime** | `RangeError`, `IndexError`, `NullPointerException` | Trace the data flow. Where did the bad value originate? |58| **Network** | `ECONNREFUSED`, `TimeoutError`, HTTP 4xx/5xx | Check if the target service is running. Verify URL, port, auth. |59| **Permission** | `EACCES`, `PermissionError`, HTTP 401/403 | Check file permissions, API keys, IAM roles, token expiry. |60| **Resource** | `ENOMEM`, exit code 137, `OOMKilled` | The process ran out of memory or disk. This is an environment issue, not a code bug. |6162### 4. Avoid Shotgun Debugging6364Shotgun debugging is changing things at random until the error disappears. It wastes time and often introduces new bugs. Instead, follow this discipline:6566```671. Read the error message (competency 1).682. Locate the failing line (competency 2).693. Form ONE hypothesis about what is wrong.704. Identify ONE change that would confirm or refute the hypothesis.715. Make that change and re-run.726. If the hypothesis was wrong, revert and form a new one.73```7475Never make two changes at once. If you change two things and the error goes away, you do not know which change fixed it -- and one of them may have introduced a latent bug.7677### 5. Use Error Messages to Form Hypotheses7879Translate the error into a plain-language hypothesis before writing any fix:8081| Error Message | Hypothesis |82|---|---|83| `Cannot read properties of undefined (reading 'map')` | The variable I'm calling `.map()` on is `undefined`. It was probably not initialized, or the API returned an unexpected shape. |84| `ECONNREFUSED 127.0.0.1:5432` | The PostgreSQL server is not running on localhost, or it is on a different port. |85| `Module not found: Can't resolve './utils'` | The file `utils` does not exist at that relative path, or the extension is wrong, or the file was moved. |86| `403 Forbidden` | The credentials are missing, expired, or lack the required scope for this endpoint. |8788A hypothesis is testable. "Something is broken" is not a hypothesis. "The `users` prop is undefined because the parent component does not pass it" is.8990## Behavioral Rules91921. Never propose a fix without first quoting the exact error message and explaining what it means.932. Never change more than one thing at a time when diagnosing an error.943. Always identify whether the failing line is in your code, framework code, or generated code before investigating.954. Revert any diagnostic change that did not help before trying the next hypothesis.965. If the same error persists after three hypotheses, step back and re-read the full output from scratch -- you likely missed something.9798## Failure Modes99100| Failure | Symptom | Correction |101|---|---|---|102| Shotgun debugging | Multiple unrelated changes in one attempt; "let me try this" without rationale. | One hypothesis, one change, one test run. Revert if wrong. |103| Ignoring the message | Agent says "I see an error" but never quotes or analyzes it. | Always paste and parse the full error before acting. |104| Fixing the wrong frame | Agent edits framework or generated code instead of source. | Trace the stack to the first frame in project source code. |105| Treating symptoms | Error goes away but root cause remains (e.g., wrapping in try/catch without handling). | Ensure the fix addresses why the error occurs, not just that it occurs. |106| Stale hypothesis | Agent keeps pursuing the same theory despite contradicting evidence. | After two failed attempts on one theory, discard it and re-read the error. |
varunk130