Reframe from three modes to two worlds

Restructures section 01 from "web chat / in-editor / agentic" into "web
chat vs. tools that live with your code," with the autocomplete /
in-project chat / agentic spectrum as a sub-structure of the latter.
Inline edits are reduced to a historical note tied to the 2023
instruction-tuned LLM era.

- Rename 01-three-modes -> 01-two-worlds and 03-in-editor-workflow ->
  03-autocomplete; section 03 narrows to autocomplete (ghost text habits,
  the autocomplete-your-verification trap)
- Section 04 reframes in-project chat as the default venue, web chat as
  a special-case venue; adds "Carrying context across sessions" covering
  dev-log.md, CLAUDE.md, .cursorrules
- Section 05 reworks intro to contrast against in-project chat instead
  of "editor extension"; tightens prose and removes em-dashes
- Update cross-references and tool-mode language in 02, 06, 07, and
  the root README to match the new framing
- Swap the CRDT example in section 04 for finite-volume methods, fitting
  the CHEG audience
- Minor typo/wording fixes

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

04-conversations/README.md

@@ -2,9 +2,11 @@
 
 ## Key idea
 
-A chat is at its best when you treat it as a *conversation*, not a search bar. Multi-turn discussions, such as design tradeoffs, exploring an unfamiliar library, or talking through a problem that you can't quite articulate, are where conversational interactions are better compared to single-shot edits or fire-and-forget agents. The patterns in this section apply whether you are in a dedicated web chat or your editor's side panel; see [section 03](../03-in-editor-workflow/) for choosing between those venues. The skill is steering the conversation so it stays useful.
+A chat is at its best when you treat it as a *conversation*, not a search bar. Multi-turn discussions that include design tradeoffs, exploring an unfamiliar library, or talking through a problem that you can't quite articulate are where conversational interactions are a better approach than single-shot edits or fire-and-forget agents.
 
-Another way to think about a chat with a capable model is as a kind of programming in natural language: you specify what you want, the model executes, you observe the output, and you refine the specification. The skills that make a programmer effective, including clarity, decomposition, anticipating ambiguity, and iterating, turn out to be the same skills that make a chat user effective. Until LLMs, natural language was almost never an executable specification, and this is one of the more remarkable shifts the technology has produced. This shift explains why "prompt engineering" became a buzzword. It's not magic words or incantations, it's specification quality. The same reason a vague programming spec produces buggy code, a vague prompt produces vague output.
+The patterns in this section apply in two areas: the **in-project chat** panel inside your editor or CLI (Claude Code's panel, Cursor's chat, Continue.dev's panel) and a **web chat** in a browser tab (ChatGPT, Claude.ai, Gemini). While web chat is where most of us get our start with AI tools, you should probably default to the in-project chat, since it can see your files and edit them, while stepping out to a web chat only when the discussion does not belong in the project (it includes sensitive content, non-code context, or a record you want to share with collaborators). The skill is steering the conversation so it stays useful.
+
+Another way to think about a chat with a capable model is as a kind of programming in natural language. In the chat, you specify what you want, the model executes, you observe the output, and you refine the specification. Effective programming skills, including clarity, decomposition, anticipating ambiguity, and iterating, are the same ones that make a chat user effective. Until LLMs, natural language was almost never an executable specification, and this is one of the more remarkable shifts the technology has produced. This very shift explains why "prompt engineering" became a buzzword. It's not magic words or incantations, it's specification quality.
 
 ## Key goals
 
@@ -18,14 +20,26 @@ Another way to think about a chat with a capable model is as a kind of programmi
 
 ## When a conversation is the right tool
 
-The mode chart in [section 01](../01-three-modes/) tells you to reach for chat when the answer is words, not code-in-place. Within that bucket, multi-turn conversation is specifically valuable for:
+The heuristic in [section 01](../01-two-worlds/) tells you to reach for chat when the answer is words, not code-in-place. Within that framing, multi-turn conversation is specifically valuable for:
 
 - **Design tradeoffs.** *"I'm choosing between approach A and B. What should I weigh?"* The model can lay out the dimensions and you can push back on weightings.
 - **Exploration of unfamiliar territory.** *"I've never used asyncio in Python. Walk me through what the event loop is actually doing."* Each follow-up question sharpens the model's answer.
 - **Talking through a problem you can't quite name.** *"Something feels wrong about this architecture but I can't put my finger on it. Here's the structure..."* The act of describing it often clarifies your own thinking, and the model's questions back can probe weak spots.
-- **Learning a new domain or library.** Conversations let you ask the dumb questions you'd be embarrassed to ask a colleague repeatedly.
+- **Learning a new domain or library.** Conversations let you ask the dumb questions you'd be embarrassed to ask a colleague.
 
-If you find yourself wanting the model to *produce a specific edit*, you have drifted out of conversation territory. Switch to the editor or an agent.
+If you find yourself wanting the model to *produce a specific edit*, you have drifted out of pure conversation territory. In an in-project chat, though, that drift is basically harmless. The same panel can just go make the edit, and you are now in an agentic interaction mode ([section 05](../05-agentic-workflow/)). In a web chat, though, the same drift is relatively expensive because you have to copy-paste the result back. If the conversation looks like it's heading toward edits, select the in-project chat from the start!
+
+
+## In-project chat versus web chat: when to step out
+
+As we've seen, most coding conversations belong in the in-project chat. There are a few notable exceptions:
+
+- **The content is sensitive or untrusted.** A snippet from a paper, code from a server you don't own, an error log with credentials in it, anything covered by an NDA or IRB. A web chat reads but does not act, and you can scrub what you paste. (Privacy and security are discussed in [section 06](../06-verifying-and-citing/).)
+- **The discussion needs to outlive the editor session and you want to revisit the *conversation itself* later.** Services like ChatGPT, Claude.ai, and Gemini save every conversation to your account history automatically (the same history whether you used the web or the desktop app), and you can mint a public share link with one click if you want to send it to a collaborator. In-project chats typically don't persist this way. If you mainly want the *takeaways* preserved rather than the full transcript, see "Carrying context across sessions" below.
+- **The non-code context is large.** Papers, third-party docs, screenshots, long PDFs. Web chats handle these uploads natively, but in-project chats usually don't.
+- **You don't want the AI's reasoning anchored to your codebase.** Sometimes you want a fresh-look answer that isn't biased by the file you happen to have open.
+
+When none of these apply, default to the in-project chat. The time savings from "the model can already see the file" compound fairly rapidly over a session.
 
 
 ## Opening well
@@ -49,7 +63,7 @@ The first prompt gets you a generic comparison. The second gets you a specific r
 
 ## Managing context across turns
 
-Chat models do not have memory of your project. Instead, they have memory of *this conversation*, and that memory is bounded by the model's **context window** — the amount of recent conversation it can attend to at once. Current chat services handle tens to hundreds of thousands of tokens per session, but once a chat exceeds the limit the interface usually truncates or summarizes the oldest turns silently, and even within the limit the model attends more reliably to recent content than to material from many turns ago. The three strategies below work because they keep the most relevant material at the recent end of the window where the model can still see it clearly. As the conversation grows, three things matter:
+Chat models do not have memory of your project. Instead, they have memory of *this conversation*, and that memory is bounded by the model's **context window**, which is the amount of recent conversation it can attend to at once. Current chat services handle tens to hundreds of thousands of tokens per session, but once a chat exceeds the limit the interface usually truncates or summarizes the oldest turns silently, and even within the limit the model attends more reliably to recent content than to material from many turns ago. The three strategies below work because they keep the most relevant material at the recent end of the window where the model can still see it clearly. As the conversation grows, three things matter:
 
 ### Re-paste changed code rather than referring to "the function I sent earlier"
 
@@ -57,7 +71,7 @@ If you've edited code based on the model's suggestion and want to continue the d
 
 ### Summarize your own thinking back to the model occasionally
 
-Especially in longer conversations, a short *"so what I'm taking away is X, Y, Z — am I missing something?"* anchors the conversation and surfaces misunderstandings cheaply. It also forces you to articulate what you've learned, which is half the point.
+Especially in longer conversations, a short *"so what I'm taking away is X, Y, Z. Am I missing something?"* anchors the conversation and surfaces misunderstandings cheaply. It also forces you to articulate what you've learned, which is half the point.
 
 ### Watch for the model drifting
 
@@ -75,14 +89,25 @@ Conversations accumulate context that can both help and hurt. Start a new chat w
 There is no virtue in keeping a chat going longer than it needs to. Open a new one freely. Conversations are cheap. When you're deciding "should I keep this conversation going or start fresh?" you should be biased toward starting fresh.
 
 
+## Carrying context across sessions
+
+Starting fresh is cheap, but it does throw away whatever the previous conversation taught the model about your project. If a project spans multiple sessions, you can carry the *takeaways* forward without carrying the full transcript:
+
+- **Ask the in-project chat to write a summary file as you go.** A `dev-log.md`, `notes.md`, or similar at the project root can capture decisions, dead ends, and "where I left off" notes. Next session, you (or the chat) read that file and pick up where you stopped.
+- **Maintain a project-level instructions file that the tool re-reads on each session.** Claude Code reads a `CLAUDE.md` in your project root automatically on every session, so anything written there (project conventions, library choices, what "done" means for this work) is available without re-pasting. Cursor has a similar mechanism via `.cursorrules`. Other tools have their own variants.
+- **Treat these files as the project's memory, not the chat's.** The conversation is ephemeral, but the files are not. When the chat learns something durable, write it to a file.
+
+The web-chat equivalent is your account history, where the *conversation itself* is the persistent artifact and you scroll back to find what you said before. The in-project equivalent puts the persistent artifact in your repo, where it lives with the code and travels with collaborators.
+
+
 ## Patterns that work
 
-- **Compare and contrast.** *"What are the practical differences between pandas `merge` and `join`? When would I reach for each?"* Models are good at structured comparisons.
+- **Compare and contrast.** *"What are the practical differences between pandas `merge` and `join`? When would I one or the other?"* Models are good at structured comparisons.
 - **Devil's advocate.** *"I'm planning to use approach X. What would make that a bad choice? What's the strongest argument against it?"* Inverts the default "let me help you do what you said" tendency.
-- **Explain to a target audience.** *"Explain CRDTs to me as if I have 10 years of backend experience but no distributed-systems background."* The audience framing tightens the level of abstraction.
+- **Explain to a target audience.** *"Explain finite-volume methods to me as if I have a strong finite-difference background but no CFD experience."* The audience framing tightens the level of abstraction: the model can skip discretization basics and focus on what's actually new (flux conservation across control volumes, dealing with unstructured meshes).
 - **Critique my draft.** *"Here is my approach / commit message / README. What's confusing or weak?"* Models are surprisingly useful as a first-pass reviewer.
 - **Walk me through.** *"Walk me through what happens when I call `requests.get(...)`. Don't skip the boring parts."* Good for building mental models of libraries you use but don't fully understand.
-- **Iterate on the prompt itself.** *"What would I have to add to my question to get a better answer?"* or *"Help me rewrite this prompt to be more specific."* The model is often perceptive about its own failure modes, and the resulting prompt is sharper than what you started with. Especially valuable when you are crafting a prompt you will reuse — a template, a system prompt, or an agent's instruction.
+- **Iterate on the prompt itself.** *"What would I have to add to my question to get a better answer?"* or *"Help me rewrite this prompt to be more specific."* The model is often perceptive about its own failure modes, and the resulting prompt is sharper than what you started with. Especially valuable when you are crafting a prompt you will reuse, such as a template, a system prompt, or an agent's instruction.
 
 ## Patterns that don't
 
@@ -93,7 +118,7 @@ There is no virtue in keeping a chat going longer than it needs to. Open a new o
 
 ## When to stop talking and write code
 
-A conversation has done its job when you can clearly articulate the next concrete action. At that point, more conversation is procrastination, and the work should move to whichever execution mode fits — an inline edit for a single function, an agent to draft a multi-file change you will then review, or your own keyboard for the parts that benefit from your hands-on judgment. If you get stuck, come back to the conversation.
+A conversation has done its job when you can clearly articulate the next concrete action. At that point, more conversation is procrastination, and the work should move to execution. Ask the in-project chat to make the change (or, for multi-step work, brief an agent), or move to your own keyboard for the parts that benefit from your hands-on judgment. If you get stuck, come back to the conversation.
 
 Watch for these stop signals:
 
@@ -110,4 +135,4 @@ The point of the conversation was to get you *to* the work, not to replace it.
 
 > **Exercise 2:** Take a conversation you had recently that felt unproductive. Reread it from the model's perspective: what context was missing? Was the question buried? Now imagine the version of the chat you'd have if you started over with what you know now.
 
-> **Exercise 3:** Try the "devil's advocate" pattern on a decision you've already made and feel confident about. The discomfort of hearing the strongest argument against is informative — sometimes the decision survives intact (now better justified), sometimes it doesn't.
+> **Exercise 3:** Try the "devil's advocate" pattern on a decision you've already made and feel confident about. The discomfort of hearing the strongest argument against is informative. Sometimes the decision survives intact (now better justified), sometimes it doesn't.