Told Where the Commands Lived, Not How to Run Them

Two commands went into a shared bootstrap document, the one every new working session on a project reads before doing anything else. Both were correct, in the sense that they were the right commands, calling the right script, doing the right thing. Neither one would have run for the first person who copied it and hit enter.

What the doc actually said

The commands lived in a companion tool that sits in its own project, next to the one most sessions actually start in. The doc named that tool, said where it lived, and gave the two commands exactly as you’d type them from inside it. What it didn’t do was account for where a session actually is when it opens that doc: inside the main project, not the companion one. Pasting either command from there hits a file that isn’t at that path, because it isn’t. Not sometimes. Every time.

Why it read as fine

Saying where something lives reads as complete information. It names the thing, it names its location, a reader can reasonably conclude they now know what they need to run it. What that framing skips is the one step between reading a location and actually being at it: getting there first. The doc had the location right and never asked whether the reader was standing in it.

How it surfaced

Not from a report of it failing. It surfaced from going back over the change shortly after committing it, reading it as someone about to paste it rather than someone who already knew where everything was. The commands were correct, and they would have failed for every single person who tried them on the first attempt, because the doc never told them to change directories first.

The fix

Both commands got a directory change prefixed onto them, so the doc now says exactly what to run from exactly where the reader already is, not what to run from somewhere else. One line each, added within the hour of the original commit going in.

The lesson underneath it

Documentation that’s accurate about a fact and unusable in practice fails the reader either way. “Here’s what it is and where it lives” and “here’s what to actually type from where you’re sitting” are different claims, and only the second one is something a reader can act on without already knowing the answer. Writing the first one and believing it covers the second is exactly how instructions ship that are true and still don’t work.

dxdev LESSON · paste into your AI coding agent
LESSON: Naming Where Something Lives Is Not the Same as Saying How to Reach It
SOURCE: dxdev.com/blog/2026-08-02_told-where-it-lived-not-how-to-run-it
WHAT HAPPENED: A shared bootstrap document, the kind every new working session reads first, gave two commands for a companion tool that lives in its own project next to the one most sessions actually start in. The doc named the tool and said where it lived, then gave the commands exactly as you'd type them from inside it. It never accounted for where a session actually is when reading that doc: a different project entirely. Pasting either command from there would fail every time, not intermittently, because the file the command pointed at simply wasn't at that relative path from where the reader was standing. It was caught and fixed within the hour, by adding the one missing step (change into the right directory first) directly onto both commands.
THE RULE: "Here is what it is and where it lives" and "here is exactly what to type from where you're already sitting" are different claims. Documentation, onboarding steps, and setup instructions should be checked by literally starting from the reader's actual position (a fresh checkout, a default working directory) and following the steps as written, not by confirming the facts in them are true.
CHECK MY CODE, then report PASS or FAIL with file:line for each:
  1. Any setup or onboarding doc that gives a command assuming a working directory it never states or verifies.
  2. Any instruction that names a tool's location as prose ("it lives in X") without also giving the exact runnable command from the reader's actual starting point.
  3. Any cross-project or cross-repo instruction not tested by literally starting from the reader's default location and running it as written.
THEN PRINT: a table (check, PASS/FAIL, evidence, fix) + a verdict (applies / partially / OUT_OF_SCOPE / no) + the single most important next action.