On 15 June a session could not find a design handoff, and I was not gracious about it:
"the new session can’t find the design handoff, aren’t those in the git repo under docs? if not please put on git, this should not have happened"
The mockup existed. Somebody, meaning me, had it. It was not in the repository, it was not attached to the ticket, and so as far as the work was concerned it did not exist.
That is the whole argument for this piece and I could stop there, but the useful part is what I do now.
Docs that describe the code live in the repo. A /docs folder, markdown, committed like everything else. This is the one people resist and it is the one that pays. If the documentation is in the repository, it moves with the branch, it is visible to anything reading the code, it gets reviewed in the pull request, and it cannot drift out of sync without somebody seeing the diff. Documentation in a separate tool drifts silently, and silent drift is worse than no documentation because you trust it.
Decisions live on the ticket. Covered in an earlier piece. The reasoning belongs where the work is tracked.
Handover documents live in the repo and are written at the end of a session, not the start of the next one. This is the specific adaptation for working with AI and it is the one I would tell people to steal. When a session is getting long, before it degrades, you write the state of things down: what was done, what is half done, what the next session needs to know, what the open questions are. On 14 June I asked for exactly this: update the docs, write a handover, and then decide whether to deploy now or wait for the next session.
Everything else can live wherever your team already lives. Confluence, Notion, Google Docs. I am not precious about this. The question is not which tool, it is whether the document is reachable from the work. A brilliant specification in a Drive folder nobody links to is a private diary.
The test I use is blunt. If a new session started right now with no memory, could it find this by looking at the repository and the tracker? If no, it is not documentation. It is a note you wrote to yourself.
That test sounds like it is about AI. It is not really. It is the same test as a new hire on their first Monday, and we have all failed it for years. What changed is that with AI you now run the experiment several times a day, so you find out immediately.
Next: getting a design out of a design tool and into working code.