Checkpoint: Complete review system with tree view + diff commenting

**Current State: Elaborate UI system complete but may need simplification**

**What We Built:**
- ✅ Eliminated disruptive QuickPick modal
- ✅ Tree view action buttons (Request Changes, Checkpoint, Close Review)
- ✅ Inline diff commenting with full callback system
- ✅ Auto-show reviews (no info messages)
- ✅ Clean branding: 'Socratic Shell: Code Review' with SVG logo
- ✅ Complex promise/callback feedback collection system

**Key Insight from User:**
'The comment UI is nifty, but actually, I'm not sure it's as practical as you might think. I kind of think interacting with the terminal is more practical.'

**Next Iteration Direction:**
- Consider terminal-based interaction instead of complex UI
- 'Ask Socratic Shell' pattern: inject text into terminal
- Non-blocking approach vs current blocking feedback system
- Merge request_review and code walkthrough logic

**Status:** Solid foundation built, ready to pivot to simpler terminal approach

Author: nikomatsakis

extension/activitybar-logo.svg

@@ -64,7 +64,7 @@
         {
           "id": "dialectic",
           "title": "Socratic Shell",
-          "icon": "logo.svg"
+          "icon": "activitybar-logo.svg"
         }
       ]
     },
@@ -112,4 +112,4 @@
   "dependencies": {
     "markdown-it": "^14.1.0"
   }
-}
+}

extension/logo.svg

@@ -24,6 +24,7 @@
     - [AI Guidance design considerations](./design/ai-guidance.md) <!-- 💡: Design decisions made specifically to work well with AI collaboration patterns from socratic shell -->
     - [Codebase structure](./design/codebase-structure.md) <!-- 💡: Overview of project structure, key files, and how components connect for contributors -->
 - [How each feature works]() <!-- 💡: Walk through the flow of particular features -->
+    - [Code walkthroughs](./design/code-walkthroughs.md)
     - [Present Review](./design/present-review.md) <!-- 💡: How AI assistants present code reviews, message flows, and implementation details -->
     - [Synthetic Pull Requests](./design/synthetic-pr.md) <!-- 💡: Git operations with git2, AI comment parsing (💡❓TODO/FIXME), MCP tool implementation, and VSCode CommentController integration for PR-like workflows -->
     - [Ask Socratic Shell](./design/ask-socratic-shell.md) <!-- 💡: How Ask Socratic Shell works, message flows, and implementation details -->
@@ -34,6 +35,7 @@
 - [VSCode extension](./design/extension.md) <!-- 💡: Highlights of the VSCode Extension design and implementation: activation, establishing IPC protocol -->
 - [Dialect language](./design/dialect-language.md) <!-- 💡: JSON mini-language semantics for IDE operations - function composition, value types, and execution model -->
 
+
 # References
 
 - [Research reports]() <!-- 💡: Background research that informed design decisions - consult when discussing related technical topics -->

extension/logo1.svg

@@ -0,0 +1,119 @@
+# Code walkthroughs
+
+Code walkthroughs are triggered in circumstances like:
+
+1. the AI agent completes a set of related changes or encounters an obstacle where it requires the users help
+2. the user asks to review the agent's work
+3. the user asks the agent to explain a given codepath or to walk through some portion of the code.
+
+In these cases, the agent triggers the `present_walkthrough` tool. Walkthroughs are usually (but not always) related to code; they can also be useful for documents or other files, however.
+
+## Example of a walkthrough
+
+We begin with examples before defining the full structure. A *walkthrough* is defined by a JSON object with a standard set of actions. All fields are optional.
+
+```json
+{
+    // The introduction section covers the .
+    "introduction": [
+        "These entries are markdown paragraphs.",
+        "Each paragraph can be a separate entry.",
+        {
+            "mermaid": "...",
+        } // but other options are also allowed
+    ],
+
+    // The "highlights" section is used to highlight areas
+    // that the agent wishes to call attention to. These are
+    // either key points in the walkthrough.
+    "highlights": [
+        {
+            // A "question"  is used to highlight an area of uncertainty.
+            "question": {
+                // The file
+                "file": "src/foo.rs",
+
+                // The regular expression to search for within the file.
+                // LLMs are not good at using line numbers.
+                "regex": "fn foo\\b", 
+
+                // The question being asked.
+                "content": [
+                    "I was not sure what the name of this function should be. Please double check it!"
+                ],
+            },
+
+            // A "warning" is used to bring something to the user's attention that may be wrong.
+            "warning": {
+                "file": "src/foo.rs",
+                "regex": "panic!()", 
+                "comment": [
+                    "This function does not accept negative numbers."
+                ],
+            },
+
+            // A "note"  is used to bring something to the user's attention in a less forceful fashion.
+            "note": {
+                "file": "src/foo.rs",
+                "regex": "", 
+                "comment": [
+                    "This is the most important part of the function."
+                ],
+            }
+        }
+    ],
+
+    // The "changes" section is used to document the full set of changes.
+    "changes": [
+        {
+            // A "diff" presents changes from a range of git commits.
+            // It can also include 
+            "gitdiff": {
+                // The range can be a range of commits (e.g., `HEAD~3..HEAD~1`)
+                // of a single commit. 
+                "range": "HEAD^..",
+
+                // If the range includes HEAD, then by default we will include
+                // unstaged and staged changes. The excluded parameter can
+                // be used to exclude those.
+                "exclude": {
+                    "unstaged": false,
+                    "staged": false
+                }
+            }
+        }
+    ]
+
+    // The actions section is used to give the user choices on how
+    // to proceed. Actions can technically be embedded anywhere.
+    //
+    // The following is the default actions if none are otherwise given.
+    "actions": [
+        {
+            "action": {
+                // Description
+                "description": "If you are satisfied with these changes, checkpoint them to update tracking documents.",
+
+                // Text on the button.
+                "button": "Checkpoint",
+
+                // Text sent to the agent
+                "tell_agent": "Checkpoint"
+            },
+
+             "action": {
+                // Description
+                "description": "Request the agent to make more changes.",
+
+                // Text on the button.
+                "button": "Request changes",
+
+                // Text sent to the agent
+                "tell_agent": "I'd like to make more changes. Please discuss with them with me."
+            }
+        },
+    ]
+}
+```
+
+## Walkthrough format