---
title: "The bootstrap doc named the right script and the wrong working directory"
canonical: https://dxdev.com/blog/told-where-it-lived-not-how-to-run-it/
datePublished: 2026-08-02
---
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.