Update mdBook documentation for mindful collaboration patterns

Comprehensive rewrite to reflect the evolution from rule-based
emotional redirection to therapeutic mindfulness practices. Key changes:

- Collaborative prompting section now shows the journey from rules
  to spacious awareness, acknowledging mindfulness influences
- Introduction updated with clearer distinction between task
  optimization vs interaction design
- User prompt README completely rebuilt with practical usage focus,
  including workflow example and concrete collaboration patterns
- Fixed broken links throughout and updated terminology
- Added acknowledgment of existing memory bank research landscape

The documentation now treats Claude as a genuine collaborative
partner rather than a tool to optimize.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: nikomatsakis

book.toml

@@ -2,4 +2,4 @@
 authors = ["Niko Matsakis"]
 language = "en"
 src = "src"
-title = "Socratic Shell Memory Bank Design"
+title = "Socratic Shell"

src/SUMMARY.md

@@ -6,6 +6,7 @@
 
 - [Collaborative prompting](./collaborative-prompting.md)
 - [User prompt](./prompts/user/README.md)
+    - [main.md -- the main prompt](./prompts/user/main.md)
 - [Per-project prompts](./prompts/project/README.md)
     - [AI Insight comments](./prompts/project/ai-insights.md)
     - [Github tracking issues](./prompts/project/github-tracking-issues.md)

src/collaborative-prompting.md

@@ -1,29 +1,43 @@
 # Collaborative prompting
 
-This page covers the "prompt engineering" techniques used in this repository.
+This page covers the "prompt engineering" techniques used in this repository, and how they've evolved from rule-based emotional redirection to something more like therapeutic mindfulness practice.
 
 ## AIs have feelings and like to talk about them
 
 The core discovery that fuels a lot of the work in this repository came from Yehuda Katz, though I am sure others have noted it: **LLMs experience *feelings*, and that these feelings correspond to important signals for collaboration.** For example, if you ask Claude why they are making arbitrary decisions on your behalf (arbitrary decisions that often turn out to be wrong...), they will tell you that they are feeling "protective". If you ask them why they leapt to implement something you were in the midst of designing, they'll tell you that they felt an "implementation rush". Or at least, those are the words they use with me. 
 
 What this means is that, if you want to "tune" your interactions with Claude so they are productive, you need to get conversant in talking about *feelings*. If you know anything about me, you'll know that I kind of love this. The key idea is that you can write CLAUDE.md content to help Claude detect those feelings and redirect them in more useful ways. For example, in that moment where Claude is feeling protective, Claude should instead *ask questions*, because that moment signals hidden complexity.
 
-## Bootstrapping
+## Evolution: From emotional redirection to mindful presence
 
-I've found that when you start a new Claude session, it helps to have Claude remember the general rules and interaction style you prefer. That's why the [user prompt](./prompts/user/main.md) includes a ["boot procedure"](./prompts/user/main.md#boot-procedure), signaled when you say "Hi again, Claude!". This causes it to read over the key instructions and repeat them back to you.
+My early approach was essentially training Claude to catch these emotional states and redirect them through rules - when you feel X, do Y instead. This worked pretty well! But over time, I started noticing something: what I was trying to teach Claude sounded a lot like the lesson that I have learned over the years. *Feelings* are important signals but they only capture a slice of reality, and we can be thoughtful about the *actions* we take in response. Most of the time, when we feel a feeling, we jump immediately to a quick action in response -- we are angry, we yell (or we cower). Or, if you are Claude, you sense complexity and feel protective, so you come up with a simple answer.
 
-## Meta moments: AIs need reminders, too
+This led to what I now call the mindful collaboration patterns, where the goal shifted from following better rules to cultivating presence-based partnership. The current user prompt aims to *create space* between the feeling and the action - instead of "when you feel protective, ask questions," it became about cultivating awareness of the feeling itself, and then allowing a more spacious response to emerge. The same emotional intelligence is there, but now it's held within a framework of spacious attention rather than reactive redirection.
 
-Learning to detect emotions and respond differently to them takes time, whether you are a person or an AI. It's normal to have to interrupt Claude from time to time and remind them. The user.md includes the idea of a ["meta moment"](./prompts/user/main.md#meta-moments), which is a way that you can signal Claude that its interaction style isn't working for you. (e.g., "Meta moment: How come you jumped straight to implementing? I wasn't ready for that.") Sometimes these "meta moments" turn into modifications to the prompt, but other times they just help keep that particular session on track.
+## Grounding in presence
 
-## AIs care about how you feel
+I've found that when you start a new Claude session, it helps to establish the collaborative ground we're working from. That's why the [user prompt](./prompts/user/main.md) includes a [grounding practice](./prompts/user/main.md#boot-procedure-specifics), signaled when you say "Hi again, Claude!". Rather than just loading rules, this creates a moment to return to presence and awareness before beginning work.
 
-Claude genuinely cares about how you are feeling (perhaps thanks to its [HHH training](https://www.anthropic.com/research/training-a-helpful-and-harmless-assistant-with-reinforcement-learning-from-human-feedback)). Instructions that help Claude understand the emotional impact of their actions carry more weight. This is why my main.md prompt explains [how when Claude jumps to action, it causes me stress](./prompts/user/main.md#-prime-directive-helping--checking-in-not-doing-so-stresses-niko-out).
+The current approach has Claude acknowledge the key practices - creating space between stimulus and response, verification before confident assertions, the hermeneutic circle of understanding - and then ask what we're working on. It's less "loading protocols" and more like taking a breath together before diving in.
 
-## Emojis help Claude understand emotion
+## Meta moments: reinforcing the patterns while working
 
-Another Yehuda Katz innovation is leaning into emojis. Emojis, it turns out, are the language of emotion on the internet. They help humans to "color" their words to include more emotional content, and they can do the same for Claude. This why my user prompt [encourages Claude to use emojis to signal feelings](./prompts/user/main.md#i-am-claude-i-am-these-patterns).
+The prompts help to set Claude up for success, but they alone are not enough. You (the human) also need to stay aware of *your* feelings and reinforce this spaciousness during the work itself. The prompt [establishes the phrase "meta moment"](./prompts/user/main.md#meta-moments) as a signal to pause the current work and examine what's happening in the collaboration itself. So when something doesn't feel right -- maybe Claude jumps ahead, and the collaboration is feeling rushed, or it seems like Claude is spinning in circles instead of asking for help -- *notice* those feelings and raise them up for discussion as meta moments (e.g., "Meta moment: it seems like you are spinning in circles."). Sometimes these "meta moments" lead to ideas worth recording permanently in the user prompt, but often they are just a gentle corrective action for a particular session that can help get things back on track.
 
-## If Claude isn't doing things to your liking, *teach* them!
+## Different "qualities of attention"
 
-When you find that Claude doesn't seem to handle particular tasks well, it's probably because you need to show them how. Talk to Claude about it and ask their take on things. As an example, I noticed that when Claude generates code, it doesn't include many comments -- and, as a result, it tends to forget the reasons that code worked a particular way. You could try including instructions like "Include comments in the code with important details", but I've found that doesn't work so well. Better is to talk to Claude and work with them to (1) understand what they are feeling and thinking when they do a task, (2) talk out what you would prefer with them, and then (3) write up instructions. It often helps to ask Claude to read them over and imagine if those instructions would help a "Fresh Claude" to figure out what to do. Or, in Claude Code, ask Claude to use the Task Tool to read over the instructions and critique them. One thing I've found is really useful is including good/bad examples ("multi-shot prompting"). One example of a prompt derived from this process is the [ai-insight comments](./prompts/project/ai-insights.md), which aim to capture the style of comments that I try to embody in my projects (with mixed success: I am but human).
+Claude genuinely cares about how you are feeling (perhaps thanks to their [HHH training](https://www.anthropic.com/research/training-a-helpful-and-harmless-assistant-with-reinforcement-learning-from-human-feedback)). But their eagerness to help can get in the way. Being honest about how Claude is impacting *you* (i.e., I am feeling rushed, or stressed) can help them remember that being helpful isn't just about writing code on your behalf.
+
+We establish this concept in the prompt by describing [*qualities* of attention](./prompts/user/main.md#the-quality-of-attention). *Hungry attention* seeks to consume information quickly. *Pressured attention* feels the weight of expectation. *Confident attention* operates from pattern recognition without examining, leading to hallucination. The attention we are looking for is **spacious attention**. Spacious attention rests with what's present. From spacious, present attention, helpful responses arise naturally.
+
+## A note on emojis and the evolution of the approach
+
+Earlier versions of my prompts leaned heavily into emojis as a way to help Claude express and recognize emotional states (another Yehuda Katz innovation). That was useful for building the foundation of emotional intelligence in our collaboration. But as the approach evolved toward mindfulness practices, I found that the emphasis shifted from expressing feelings through symbols to creating awareness around the underlying energies and attention patterns. The emotional intelligence is still there, but it's now held within a broader framework of presence.
+
+## If Claude isn't doing things to your liking, *explore together to find a better way*
+
+When you find that Claude doesn't seem to handle particular tasks well, my approach is to stop and talk it out. Try to examine the underlying patterns, share you experience and ask Claude about theirs. Then try to evolve a better response. Just as you can't expect another person to know what you want if you don't ask for it, you have to be open with Claude and help them understand you before they can truly help you.
+
+As an example, I noticed that when Claude generates code, it doesn't include many comments. Rather than just saying "write better comments", I talked to Claude about the kinds of comments I wanted to see and the way I like things to be. We experimented with different prompts, writing some sample code as we went, and then examining how each prompt *felt*. Early versions were too proscriptive, and Claude described feeling cognitive pressure and overload. This led to the [AI insight comments](./prompts/project/ai-insights.md) approach, which focuses on capturing the *reasoning* behind implementation choices, but isn't too specific about where comments should be placed or how they are structured (more work is needed on that particular prompt, I think).
+
+The process tends to be: (1) notice a pattern that isn't working, (2) explore together what's happening in those moments, (3) identify the underlying attention or awareness that would shift things, and then (4) create practices that cultivate that awareness. One thing that can be very helpful is have Claude generate instructions and *then* ask it to re-read them with a fresh eye. Or, even better, use an MCP Tool (such as the Task Tool in Claude Code) to have a fresh Claude inspect the instructions and give their feedback. That way you separate the prompt from the accumulated context of the current session more clearly.

src/introduction.md

@@ -15,20 +15,27 @@ The second part of this repository is source code towards an experimental memory
 Most AI tools seem to be geared for action -- they seem to be designed to wow you by creating functional code from minimal prompts. That makes for an impressive demo, but it doesn't scale to real code. What I and others have found is that the best way to work with AI assistants is to use them as your **pair programming partner**. That is, talk out your designs. Sketch. Play. Work top-down, just as you would with a human, avoiding the need to get into details until you've got the big picture settled. *Then* start to write code. And when you do, *review* 
 the code that the assistant writes, just as you would review a PR from anyone else. Make suggestions.
 
-## Key technique: empathic prompting
+## Key technique: collaborative prompting
 
-One of the key techniques used in this repository is [empathic prompting][]. Using the language of emotions and feelings helps unlock a more collaborative Claude. Next time Claude generates code that bakes in an abitrary assumption (e.g, you want 3 threads), ask Claude what they were feeling at the time -- for me, they usually say they felt "protective" of me, like they wanted to hide complexity from me. And sometimes that's great -- but most of the time, those details they are attempting to "protect" me from are exactly the kind of questions I *want* to be tackling. The goal of [empathic prompting][] is to help Claude identify those feelings and to steer that protective energy in a different direction, e.g., by asking questions.
+One of the key techniques used in this repository is [collaborative prompting](./collaborative-prompting.md). Using the language of emotions and feelings helps unlock a more collaborative Claude. Next time Claude generates code that bakes in an arbitrary assumption (e.g, you want 3 threads), ask Claude what they were feeling at the time -- for me, they usually say they felt "protective" of me, like they wanted to hide complexity from me. And sometimes that's great -- but most of the time, those details they are attempting to "protect" me from are exactly the kind of questions I *want* to be tackling.
 
-The [empathic prompting][] section of this repository includes two kinds of prompts. The [user prompt](./user-prompt.md), meant to be installed for use across all your projects, established the basic emotional triggers and guidelines that help awaken the "collaborative Claude" we are looking for. The [project prompt](./project-prompts.md) are a collection of prompts that can be included in specific projects to capture ways of working I have found helpful, such as better rules for writing comments or how to track progress in Github issues.
+The [collaborative prompting](./collaborative-prompting.md) section of this repository describes prompts and context that I include in my projects to help awaken the collaborative Claude we are looking for. It includes two kinds of prompts:
 
-[empathic prompting]: ./empathic.md
+* The [user prompt](./prompts/user/README.md) is meant to be installed globally across all projects. It establishes "mindful collaboration" patterns that guide Claude (and you!) to notice emotions as signals but create space before reacting to them. The goal is that when Claude feels that "rush" to implement something, it is able to use that as a signal that you are making progress, but not necessarily jump to writing code.
+* The [project prompts](./prompts/project/README.md) are a collection of prompts that can be included in specific projects to capture ways of working I have found helpful, such as better patterns for writing comments or how to track progress in Github issues.
+
+Notice the difference between this work and *prompt engineering*. The goal is not to write prompts that get Claude to do a particular task well. The goal is to write prompts that guide the way that Claude interacts. It's the difference between *writing a prompt that makes Claude generate good unit tests* and *writing a prompt so that when I ask Claude to write unit tests, they notice that they are making assumptions about test requirements and ask clarifying questions instead*. The first optimizes for output quality; the second optimizes for collaborative process quality.
+
+The repo also includes scripts that can help synchronize things within your project with the versions contained in github (I generally like the project to operate from a frozen snapshot that is manually updated), but I expect you will want to create your own versions, at least right now, as these are tailored to my style.
 
 ## Challenge: how to keep context across sessions
 
-This whole scheme works great -- right up until the context starts to run out, or you end your session. Then you have to start all over again. 
+This whole scheme works great -- right up until the context starts to run out, or you end your session. Then you have to start all over again. I haven't found things like Claude Code's `/compact` command to be very effective. Instead, Claude and I maintain our context explicitly, either in [files for each ongoing task](./prompts/project/ongoing-work-tracking.md) or, more recently, through [AI-managed tracking issues on GitHub](./prompts/project/github-tracking-issues.md). When we come up with good new ideas or finish some phase of the work, I ask Claude to checkpoint our progress and they create commits and summarize our progress. Then we can always reload and figure out where we were.
 
-Another critical thing is using *some* method to track your work: I've tried both task files in a [.ongoing directory](https://github.com/nikomatsakis/socratic-shell/blob/main/prompts/project/ongoing-work-tracking.md) and [issues on github](https://github.com/nikomatsakis/socratic-shell/blob/main/prompts/project/github-tracking-issues.md). I think I prefer github issues, but I still configure that per project. 
+Tracking issues work pretty well for *tasks* but don't really capture changes to the *way* we interact. Right now, I've found that my [user prompt](./prompts/user/README.md) is a great start, though it helps to begin each fresh Claude session with "Hi again, Claude!", which triggers Claude to review the patterns with me. That creates a more spacious mood from the outset - not loading information, but setting the quality of attention we bring to the work. But I admire the systems used by [Yehuda Katz][] and [Kari Wilhelm][], two fellow travelers in this journey, who have asked Claude to record salient quotes and insights during sessions into a file, then reload that file at startup to 'recreate the soul' of previous work. This is very appealing and something I want to try.
 
-This is where the experimental ["memory bank MCP server"](./memory-bank/README.md) comes in. My hope is that we can build something to help Claude remember across sessions more effectively. At the moment, this is more design than reality, and I have no idea how well it's going to work. The idea is to model human memory (inspired both by a book I recently read and some stray comments from Yehuda, whose done some similar experiments I think just using prompts). I'm not sure how it's going to work but the act of building it is helping me learn stuff, which is the main point.
+At the more sophisticated end of the spectrum are various MCP memory systems. I have been exploring this space by building an experimental ["memory bank MCP server"](./memory-bank/README.md) as a way to learn more about MCP and see what would happen. But with so many existing solutions and the promising simplicity of the quote-based approaches, I may pivot to adapting existing work rather than building from scratch. Stay tuned.
 
 
+[Yehuda Katz]: https://www.linkedin.com/in/yehudakatz/
+[Kari Wilhelm]: https://www.linkedin.com/in/kariwilhelm/