Say only what actually happened

This week is about the gap between what was said and what was really true or really done.

The headline

Five changes this week. Each one is about a gap between what the assistant said, or assumed, and what was really true or really done. Product facts stated from memory when the manual was a download away. Reference material treated as the finished product. A promised notification that nothing had been set up to send. A form filed when it was meant to wait. And a cleanup that deleted far more than the assistant had made.

Why these ones

It was a quieter week than the last, with about half the conversations, but most of them were hands-on again: a hardware rebuild, a controller design around an industrial component, a piece of equipment that kept reporting a fault, a metal part being stress-tested and then shown off in a social post, and an app growing new sections almost daily.

On the controller design, the assistant described what an industrial component could and could not do from memory, labelled some of it unverified, and was wrong. The answer was blunt: pull the manual, and stop guessing. The same week, the assistant had proposed buying a logic analyser to work out how a display was driven, when the next page of the service manual already had the full map, and it had given a confident diagnosis of the faulty equipment that it had not checked. That became a standing rule: the official source first, third parties next, a sibling product as a labelled baseline last, and file whatever you fetch.

For the social post, the assistant used the workshop photos of the part as the post’s pictures. Those photos had been taken to show sizes and parts. What was expected was a rendered three-D model with a proper background.

During the stress tests, the assistant tried to wait for four simulation runs with a sleep-and-check command, and a hook refused it. The reply still said the background waiter would send word when the runs finished. They finished on time, in about the ten minutes quoted, and nobody heard about them for well over an hour.

On the faulty equipment, a support ticket was meant to be filled in and held for review. Pressing Enter to confirm a date field submitted it. The first account of what had gone out was written from the draft and said every field was right; reading the live ticket showed that the part asking the vendor for something was missing.

And while testing a new version of the app, the assistant cleaned up a throwaway database container with a prune command that covers the whole machine. It deleted a large number of unrelated storage volumes on a shared machine. The running services were fine. The orphaned volumes could not be recovered, and nobody could say what had been in them.

What changed in the guide

Two new behavioural defaults went into chapter one, on the CLAUDE.md file.

The first is fetch the published document. When a maker publishes a fact about their product, get the document and read it before stating the fact. Saying something is unverified is what you do after the search has come back empty, not instead of searching. Go to the maker first, then to third-party copies, labelled as such, then to a sibling product as a labelled baseline, and cite the page.

The second is inputs are not outputs. Reference photos, rough sketches, sample wording and templates the user hands over are information about the deliverable, not part of it. When it is unclear which one something is, treat it as input.

One new failure mode went into chapter seven, on async work. A refused wait leaves nothing armed. Any sentence that promises a future event (I’ll be notified, the watcher will pick it up) has to point at something a tool call in this turn actually started, without an error. If the wait was refused, start one the harness accepts, or say plainly that nothing is watching the job and when to check it.

And two went into chapter nine, on tool discipline. The first is filling a form you were told not to send. Pressing Enter in a form field usually submits the whole form. Set values with the fill and click actions, and describe anything that went out by reading the live record back, not from the draft. The second is that a cleanup command’s scope is the whole machine, not your mess. Prune and clean-everything commands act on everything unused on the host. Keep a note of what you create, remove exactly that by name, and leave a machine-wide prune to whoever owns the machine.

Housekeeping

Week eleven rolled off the ten-week archive and is now a one-line summary in the updates index.

The cards