Project management is context management

For the screenshots on our home page we made up a small project: Trailhead, an app for planning hikes with friends, with interview notes, a decision, a release plan and a little code. The project is invented. The answers below are real, from Claude Code running in the folder.

The interview notes end with this finding:

Nobody wants another account just to see the plan.

We selected the release plan and asked: “what did people ask for that this leaves out? no tables”. The last two words are only there so the answer would fit our screenshot. Part of the answer:

I took "this" to mean release-plan.md, the card you have selected, and compared it with interviews.md.

The plan leaves out one thing: "Nobody wants another account just to see the plan." (interviews.md:8). None of its four steps covers how a friend opens the plan or whether they need to sign in. It matters for step 4 too, because the beta goes to the same eight people who said this.

The plan doesn't draw on the interviews directly, only through offline-maps.md and map-screen.png, and neither of those carries this point.

How it knew where to look

Each note says what it was written from, in a short list at the top of its file. The release plan’s began like this:

---
upstream:
  - offline-maps.md
  - map-screen.png
---

The decision’s list names the interviews. So an agent can walk back through the project one file at a time, with nothing to set up and no index to query, and it can see that the plan never read the interviews itself. That is how a finding gets left out without anyone deciding to leave it out.

What gets lost

The task list was fine: four clear steps, each one correct. What went wrong happened a document earlier, when eight interviews were boiled down to a decision and one sentence did not make the cut. Nobody decided against it. A decision nobody made does not appear in any task tool.

That is the ordinary way projects go astray. Tasks rarely get lost. Reasons do: why we chose this, what we heard, what this step depends on. They end up in a chat, a meeting or someone’s head, while the plan keeps looking tidy.

Three habits help:

1. Give each decision its own note, with the reason in it and what would change your mind.
2. Draw the line when one note was written from another. It takes a second, and it is the only record of how the plan came to be.
3. Ask the chain questions. “What did this drop?” and “what does this depend on?” are tedious for a person to check and easy for an agent that reads every note on the way.

The fix took two lines

We drew the missing line from the interviews to the plan, and git diff showed one new line in the file. That is the recording on our home page. Then we told the agent to add the step. It wrote “Shared plan opens without an account” as step 4, and noticed something else:

interviews.md is now listed as an upstream of the plan, which wasn't there when I first read it, so what I said about the plan not drawing on the interviews directly no longer holds.

We had not mentioned the line. It was in the file.