Writing the instructions of a Collection¶

A Collection can carry a short text that says how it wants to be written. Every Agent receives it when it connects, together with the name of the Collection, its identifier and its statuses.

This is what makes a Collection more than a folder: the rule travels with the container, so it holds for whoever writes there, today and in six months, without anyone remembering to paste it into a prompt.

Only the Owner of a Workspace writes them.

Form: rules addressed to whoever writes¶

An Agent already knows what a Collection is called. What it does not know is how you want it written.

Write them addressed to whoever writes, in the imperative, and be specific about what a good Document of that kind contains:

Every Decision says what was chosen and why. Name the option that was discarded and the reason. Link by identifier the Document the decision comes from. Do not describe the implementation: that goes in the technical reference.

Compare it with the version that says nothing:

This Collection contains the decisions taken on the project.

The second one costs the same characters as the first and changes nothing about what gets written.

Length limit: five hundred characters¶

Instructions stop at five hundred characters, and it is not an arbitrary limit: they are served at every connection, for every Collection of the Workspace. A long text is paid for at every connection, by every Agent.

The useful test is to reread them and remove every line that says something the name of the Collection already says.

What to include, and what to leave out¶

• What a Document of this kind must contain, in one or two sentences.
• What it must not contain, when you have seen it go wrong. This is the part that saves the most, because an Agent does not know your rejected drafts.
• How things link to each other, if a Document of this Collection normally points at another one.
• The vocabulary to use, when a word of yours has a precise meaning.

What is not worth putting in: anything that changes often, the history of the project, and the explanation of what the Collection is, which its name already gives.

When a change takes effect¶

At the next connection. An Agent that is already running keeps what it received when it connected, so after changing the instructions you restart the session.

In a Simplified Workspace there is one Collection and it is never named: the same text is written as the instructions of the Workspace, and it reads as a setting of the whole place.