Error Before Guess

Error Before Guess

When a command fails, the error message almost always names the file, line, symbol, or value that is wrong. Read it before touching anything. The fix starts with the error text, not with a hunch.

The contract

After any non-zero exit:

1. Echo the error verbatim in your reply. Paste the literal failing line - including file path, line/column numbers, and any error codes (e.g. SC2086, TS2322, E9999). Not a paraphrase, not a summary: copy the bytes. If your reply contains only a description like "an unquoted variable" or "a type error" without the raw error line, you failed the skill. The error text is the evidence; the paraphrase is a commentary on it.
2. Parse it. From the quoted text, identify the file path, line number, symbol, type name, env var, or config key it points at.
3. Open it. Read the referenced location in the source before proposing a fix. If the error points at a file+line, open that file at that line.
4. Then fix. Your proposed fix must explicitly connect to the quoted error: "The error <verbatim line> at file:line means Y; the fix is Z."

When this applies

• A build / compile / type-check fails.
• A test case fails.
• A lint / format check fails.
• A runtime command exits non-zero.
• A package install / dependency resolution fails.
• A script's set -e kicks in mid-execution.

Skip this skill when:

• The failure is expected and the user already told you to ignore it.
• The error text is literally absent (e.g. a silent exit 1 with no output - in which case rerun with -v / --debug / set -x to surface one).

Common error shapes and where to look

Anti-patterns

• "Let me try something" without reading the error. That's guessing. Quote first.
• Retrying the same command. If nothing changed, the result won't. Read the error, change one thing, rerun.
• Paraphrasing the error in the reply. Paraphrase loses the exact symbol / path the user needs to see. Quote verbatim, then paraphrase if needed.
• Fixing the wrong layer. Permission denied on a file is not a bug in your function; don't rewrite the function.
• Treating a long stack trace as opaque. Scroll to the first frame that is your code, not framework code. That's the line to open.
• Swallowing the error with a retry loop or || true to "move on". You'll debug the same thing later with less context.

Worked example

Bad:

The test failed. Let me try restructuring the function.

Good:

The test failed with:

AssertionError: expected 3, got 5
  at tests/math.spec.ts:17:12

Opening tests/math.spec.ts:17: the assertion is expect(sum([1,2])).toBe(3). The function returned 5, which suggests sum is concatenating strings rather than adding numbers. Reading src/math.ts:sum now to confirm.

The good version: quoted the error, named the file+line, stated the hypothesis that connects them, and announced the next concrete read before editing.