The bootstrap doc named the right script and the wrong working directory

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

What the doc said

The commands lived in a companion tool that sits in its own project, next to the one most sessions 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.

The doc never accounted for where a session is when it opens it, which is inside the main project, not the companion one. Pasting either command from there hits a file that isn’t at that path. It fails every time.

Why it read as fine

Saying where something lives looks like complete information. It names the thing and its location, so a reader can reasonably conclude they know what to run. The step that framing skips is the one between reading a location and standing in it. The doc had the location right and never asked whether the reader was there.

How it surfaced

No report of a failure turned it up. We went back over the change shortly after committing it and read it as someone about to paste it, rather than as someone who already knew where everything was. The commands were correct. They would have failed for everyone on the first attempt, because the doc never said to change directories first.

The fix

Both commands got a directory change prefixed onto them. The doc now says what to run from the place the reader is already standing. It was one line each, added within the hour of the original commit going in.

What the doc was missing

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

When you write setup or runbook instructions, have someone who doesn’t know the system paste each command from the place a new person would actually be standing. Do it before the document ships. Accurate steps that fail on the first attempt still cost every new reader time.

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/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.