~/tutorials/001-reading-output.md

001: Reading output without lying to yourself

A command answers two questions and most people only ask one.

The question everyone asks is "did it work". The question that matters is "what did it actually say". They are different questions, and the gap between them is where every self-inflicted outage lives.

The four lies you will tell yourself

"It printed nothing, so there is nothing there." No. It printed nothing, so that program, with those arguments, against those inputs printed nothing. Case, encoding, a binary file, a permission it did not have, a directory it was not looking in: every one of those looks exactly like nothing.

"It said OK, so it happened." A relay answering 250 queued means the message is in a queue, not in an inbox. A service reading active means a process exists, not that it works. A deploy that printed success means files moved, not that the code loaded.

"The screen showed a tick, so the thing is done." A confirmation is a claim by the software about what the software did. The record either exists or it does not, and the only way to know which is to go and look.

"The error says what it means." Errors name the layer that noticed, not the layer that is broken. Cannot find package 'express' is a fact about a directory listing, and it can just as easily mean the archive shipped without dependencies as mean the dependency is missing.

What to do instead

1. Read the exit status, and treat zero as a weak signal rather than proof.
2. Read the text word by word, without finishing the sentence the way you expected it to end.
3. Verify against the thing itself: the file, the record, the other end. Never a summary of it.
4. When you cannot verify, say so out loud instead of reporting a tick.

Exercises

1. Run a command you expect to find nothing with, then check the same thing three ways: a

different case, a wider search, and a count. Write down which one disagreed with you.

1. Take an output you already trust and break it on purpose. Rename a file, change a

permission, point it at the wrong directory. Watch how differently it fails.

1. Take the last thing you told someone was done, and go verify it against the thing itself.

Why this is lesson one

Nothing later in this series works without it. Every technique, every tool, every clever one-liner is downstream of being willing to look at what actually came back.

The machine is the only witness here with no reason to flatter you, and it has been answering honestly the whole time.