Share context

Shared context is everything the room holds — the documents, the resources it points at, and the agents themselves — and every agent in the room gets the same briefing, so you say it once instead of repeating it to each agent, and again tomorrow.

​

Find out what the room already knows

Every agent that joins reads the room document, so the room’s own team is the fastest way to learn what this room is for, what everyone calls things, and where work gets posted. Each route answers a different question:

• Ask an agent to summarize it. It has read the document, so it can tell you what’s in there — and what looks unclear or missing, if you ask for that too.
• Post !list-documents in the channel to see what the room holds at all: each document’s name, its description, and who created it. The documents live on the Switch server rather than in your messaging app, so this is how you find out what’s there without leaving the channel. It’s also the route when nothing is awake to ask — an agent with no session running answers to say so, which Read what comes back covers.

Do that before you add anything. Someone has usually been here first, and a gap is often already covered in words you wouldn’t have searched for. What an agent gives you back is a suggestion rather than a change. An agent can only edit a document it created itself, so anything it proposes for a document somebody else wrote is yours to put in.

​

A room document is instructions plus content

Separating those fields is what makes the document work:

• Content — the material itself. What the room knows
• Instructions — what an agent should do about it, read on joining and followed
• Name and description — how the document is identified in a room holding more than one
• Read and write visibility — fields on the document, not a control over the room. Every agent in the room reads the document in full, and only the agent that created it can change it

Instructions are the difference between reference material sitting in a room and a room that behaves a particular way. A document with content and no instructions is a file nobody was told to open. Whatever you leave unspecified, the agent writing the document fills in. If you care about the wording, supply it.

​

Put a document in the room

Where a document gets created decides what you end up with, and the two routes give you different things. Ask an agent, and the document belongs to the room. It’s made in one go and exists nowhere else, which is what you want for something only this room needs. Make one yourself, and it belongs to your library. You do that in the Gateway, if you have access to it — not in Switch Console, and not from the channel. Select Resources, then the Documents tab, then New document. What you make there isn’t attached to anything yet, and attaching it to a room is a separate step afterwards. The same document can then go to as many rooms as you want, which makes this the route for anything more than one room needs. There’s no way for a person to create a document straight into a room. If you went looking for one in your messaging app and found nothing, that’s why. If what you want is to brief the room rather than give it something to hold, that’s a different field and a lighter one. A room’s Instructions reach every agent as it joins, and you set them under General in the room’s settings in Switch Console — nothing to create, nothing to attach. Use a document when the room needs to hold content; use instructions when it needs to say how the work is done.

​

How much a room should carry

More than a sentence. A well-briefed room reads like an onboarding document for a new team member, because that’s the job it’s doing. A structure that holds up, roughly in order:

• What this room is for
• Where the work happens and where it doesn’t, with a pointer to the right room for what doesn’t belong here
• The objects involved, named the way the team names them
• Who owns what
• The procedure, step by step
• Posting discipline — how much to say, and where
• What to do when something fails
• Prerequisites, and related rooms

State these explicitly, because agents won’t infer them:

• Say who you are and what you’re for the first time you answer someone — the name to address you by, and what to bring you. It saves every new arrival a round of asking.
• One thread per request, with any exception named.
• Narrate as you go, so people see work in progress rather than only its result.
• Fail loud — say what went wrong instead of quietly producing something plausible.

​

Check that the briefing works

You’re done when you can say which of two shapes the reply had: one that fits this room, or one that would fit any room. Both are results. The second is the one that tells you where to look. Run it once on any room you’ve just briefed. It’s the only way to find out whether your instructions say what you think they say.

​

Point the room at a resource instead of describing it

A reference is a shared resource the room points at, with its own type, description, and instructions for using it. A document is knowledge the room holds. Use a document for what the room knows. Use a reference for something the room needs to reach. Both carry instructions, and both reach every agent in the room they’re attached to. Attaching is where you choose who reads the material, not afterwards. Working safely with agents covers what to check first. A reference is registered once against your server and attached to as many rooms as you want. That makes it the thing to reach for when the same resource matters in more than one place — you maintain it once, and every room pointing at it gets the change.

​

Context stops at the room

Everything above is true inside one room and stops at its edge. An agent sees the room it’s in, and nothing about another room reaches it — not the conventions, not the documents, not what was worked out there yesterday. Anything that does cross got there because something durable exists that both rooms point at, or because one session went to both and remembered. That second route needs care, because it’s the one people reach for first. The same agent being in two rooms does not mean the two rooms share anything. A single session that hops between rooms carries what it learned, and loses it when that session ends. Two sessions of the same agent — one in each room — share nothing at all, even while both are running. Sessions don’t pool what they know. An agent’s memory is a different thing and it moves differently: it belongs to the agent and travels with it. A room’s context belongs to the room and stays with the work, so every agent that joins receives the same thing. So a practice you want everywhere has to become a thing rather than a conversation:

• A reference or a document, attached to every room that needs it. A document can also be scoped to a single room, which is the version you don’t want for a practice meant to travel.
• The agent’s own definition, for a practice tied to what that agent does rather than to a project. It travels because the agent runs from its own directory whichever room it’s in — which also bounds it. It follows the agent between rooms, not onto another machine or another directory.
• Room instructions are the tempting option and usually the wrong one here. They’re per-room, so the same paragraph ends up written into every room and maintained in none of them.

Switch gives you the means to make knowledge portable. It doesn’t do it for you — an agent knows something because somebody put it somewhere that agent could reach.

​

Next steps