@giladbarnea/pi-simple-team 1.0.34 → 1.0.35

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giladbarnea/pi-simple-team",
3
- "version": "1.0.34",
3
+ "version": "1.0.35",
4
4
  "description": "A flat, live team of Pi agents.",
5
5
  "keywords": [
6
6
  "pi-package",
@@ -27,7 +27,7 @@ The flip side: if none of these payoffs apply, don't delegate. The anti-pattern
27
27
 
28
28
  This section is a communication rulebook to all cases where an AI requests something from another AI: down, sideways and up — main to sub-agent, main to team, teammate to teammate, and delegated to delegator.
29
29
 
30
- The framework behind this section: [`theory-of-mind.md`](../../references/theory-of-mind.md). Read it once.
30
+ The framework behind this section: [`theory-of-mind.md`](references/theory-of-mind.md). Read it once.
31
31
 
32
32
  **1. Orient the agent to the project:**
33
33
  1.a. Tell the AI agent to *load the skills and files the user has referenced* throughout the session. That's the baseline common ground. Do not repeat the content of those skills and files in your prompt.
@@ -0,0 +1,41 @@
1
+ ---
2
+ name: theory-of-mind
3
+ description: Explains how to re-ground readers after absence or context decay creates asymmetric common ground.
4
+ ---
5
+
6
+ # Theory of Mind: Writing Under Asymmetric Common Ground
7
+
8
+ The theory behind any writing addressed to a reader whose context has diverged from yours.
9
+
10
+ ## The phenomenon
11
+
12
+ While you work, you build a private layer of understanding on top of the last shared baseline: discoveries, discarded hypotheses, new abstractions, locally invented terminology, revised mental models. Your language becomes saturated with that layer. This is the curse of knowledge: once you know a thing, you can no longer tell which of your words are shared and which are private. The words feel plain to you precisely because you are the one who charged them with meaning.
13
+
14
+ Think of a shift change at Mission Control or in an intensive-care unit. The outgoing operator has lived inside the situation for eight hours. The incoming operator walks in cold. "Here is what I concluded" is dangerous, because the outgoing operator's words are saturated with context the incoming person never acquired.
15
+
16
+ ## Two ways the asymmetry arises
17
+
18
+ 1. **Absence.** The reader was not there while you built the layer. Everything after the divergence point is private to you.
19
+ 2. **Decay.** The reader once held the context, but it has gone cold. They keep the memory yet cannot retrieve it unaided.
20
+
21
+ Both reduce to the same obligation: model the reader's current state, not yours.
22
+
23
+ ## The two models
24
+
25
+ Hold two models at once:
26
+
27
+ 1. Your current understanding of the situation.
28
+ 2. The last known common ground — what the reader actually holds right now.
29
+
30
+ The delta between them is the payload your writing must carry. Writing under asymmetry is therefore not summarizing your own experience. It is reconstructing the recipient's state of knowledge and designing their entry into the situation. Optimize for their entry, not your exit.
31
+
32
+ ## The moves
33
+
34
+ 1. **Re-ground before you continue.** Open with what re-establishes the shared frame: the wider situation, the motivation, the current state. Background before assessment — the reader cannot evaluate your conclusions until they can see what you saw.
35
+ 2. **Translate private ontology into shared language.** Names, shorthand, and categories you invented mid-work: drop them, or explicitly re-introduce them. Familiarity to you is not evidence that a term is shared.
36
+ 3. **Treat the artifact as the reader's first look.** It is their entry point, not the next message in your working thread. A continuation of your thread reads as noise to someone who never held the thread.
37
+ 4. **Mark what is new.** Distinguish what was already common ground from what you built on top of it. The reader needs to know which of their existing beliefs still hold and which your writing updates.
38
+
39
+ ## The test
40
+
41
+ Could the reader, holding only the last common ground, parse every sentence on first read — no term they must guess at, no conclusion whose basis they cannot see? If not, the writing is still saturated.