Update synthetic PR design docs with actual implementation

- Replace placeholder Implementation Plan with real Implementation Status
- Add mdbook anchors to UserFeedback struct for live code inclusion
- Document actual MCP tool behavior and LLM instruction formatting
- Show clear distinction between completed server-side work and remaining IPC/extension work
- Reference real code via anchors to keep docs synchronized

Addresses #22 - design docs now reflect actual implementation

Author: nikomatsakis

md/SUMMARY.md

@@ -56,5 +56,5 @@
     - [Copilot Integration Guide](./references/copilot-guide.md) <!-- 💡: Analysis of GitHub Copilot's VSCode integration patterns for AI-assisted development workflows. Covers comment-based AI interaction, inline suggestion systems, and integration with existing VSCode features. Provides insights for building complementary AI tools that work alongside Copilot. Relevant for: AI integration patterns, comment-based workflows, VSCode AI tool ecosystem -->
     - [Copilot Integration Guide 2](./references/copilot-guide-2.md) <!-- 💡: Extended analysis of Copilot integration patterns focusing on advanced features like chat interfaces, context awareness, and multi-turn conversations. Covers architectural patterns for AI tools that need to maintain conversation state and integrate with VSCode's editing experience. Relevant for: AI chat interfaces, conversation state management, advanced AI integration -->
     - [Copilot Integration Guide 3](./references/copilot-guide-3.md) <!-- 💡: Comprehensive guide for implementing GitHub PR-style commenting UI in VSCode extensions with multi-line comment support, clickable gutter icons, expanded comment threads, and "Make Code Suggestion" functionality. Covers CommentController API, CommentingRangeProvider implementation, and troubleshooting common issues like missing reply buttons. Based on analysis of GitHub PR extension patterns. Relevant for: comment UI implementation, multi-line commenting, suggestion workflows, GitHub PR-style interfaces -->
-    - [VSCode Comments API Reply Button Implementation](./references/VSCode Comments API Reply Button.md) <!-- 💡: Definitive technical guide for implementing working reply buttons and multi-line comments in VSCode extensions using the Comments API. Covers the complete implementation pattern including CommentingRangeProvider requirements, package.json menu contributions, command registration, and custom action buttons like "Make Suggestion". Includes minimal working examples and troubleshooting for common issues. Based on analysis of microsoft/vscode-pull-request-github extension. Relevant for: reply button functionality, multi-line comment selection, custom comment actions, Comments API implementation -->
+    - [VSCode Comments API Reply Button Implementation](./references/VSCode-Comments-API-Reply-Button.md) <!-- 💡: Definitive technical guide for implementing working reply buttons and multi-line comments in VSCode extensions using the Comments API. Covers the complete implementation pattern including CommentingRangeProvider requirements, package.json menu contributions, command registration, and custom action buttons like "Make Suggestion". Includes minimal working examples and troubleshooting for common issues. Based on analysis of microsoft/vscode-pull-request-github extension. Relevant for: reply button functionality, multi-line comment selection, custom comment actions, Comments API implementation -->
 - [Decision documents]()

md/design/synthetic-pr.md

@@ -256,97 +256,87 @@ extension/src/
 └── extension.ts               # IPC and main logic
 ```
 
-## Implementation Plan
+## Implementation Status
 
-### 1. Update MCP Tool Interface
+### ✅ Completed: Server-Side Blocking Pattern
+
+**MCP Tool Interface** - Real implementation in `server/src/synthetic_pr/mcp_tools.rs`:
 
-**Current `update_review()` signature**:
 ```rust
-pub enum UpdateReviewAction {
-    WaitForFeedback,
-    AddComment { comment: serde_json::Value },
-    Approve,
-    RequestChanges,
-}
+{{#include ../../server/src/synthetic_pr/mcp_tools.rs:user_feedback}}
 ```
 
-**Enhanced for blocking pattern**:
+**Blocking MCP Tools** - Real implementation in `server/src/server.rs`:
+
 ```rust
-// Tool blocks until user provides feedback
-// Returns structured user feedback data
-pub struct UserFeedbackResponse {
-    pub review_id: String,
-    pub comment_id: String,
-    pub file_path: String,
-    pub line_number: u32,
-    pub user_comment: String,
-    pub context_lines: Vec<String>, // Surrounding code for context
-}
+{{#include ../../server/src/server.rs:request_review_tool}}
 ```
 
-### 2. IPC Message Extension
+```rust
+{{#include ../../server/src/server.rs:update_review_tool}}
+```
 
-**New IPC message type**:
-```typescript
-interface UserCommentPayload {
-    review_id: string;
-    comment_id: string;
-    file_path: string;
-    line_number: number;
-    comment_text: string;
-    context_lines: string[];
-}
+**LLM Instruction Formatting** - The `format_user_feedback_message` method creates explicit instructions:
+
+For **comment feedback**:
 ```
+The user reviewed your code changes and left a comment on file `src/auth.rs` at line 42:
 
-### 3. Extension Changes
+User comment: 'This validation logic looks incomplete - what about edge cases?'
 
-**Enhanced `handleCommentSubmission()`**:
-```typescript
-private handleCommentSubmission(reply: vscode.CommentReply): void {
-    // Current: Add comment locally
-    const newComment = { /* ... */ };
-    reply.thread.comments = [...reply.thread.comments, newComment];
-    
-    // NEW: Send to MCP server via IPC
-    this.sendUserComment({
-        review_id: this.currentPR.review_id,
-        comment_id: generateCommentId(),
-        file_path: reply.thread.uri.fsPath,
-        line_number: reply.thread.range.start.line + 1,
-        comment_text: reply.text,
-        context_lines: this.getContextLines(reply.thread.uri, reply.thread.range)
-    });
+Code context:
+```rust
+function validateInput(input: string) {
+    return input.length > 0; // Line 42
 }
 ```
 
-### 4. Server Blocking Logic
+Please analyze the user's feedback and prepare a thoughtful response addressing their concern. 
+Do NOT modify any files on disk.
 
-**MCP tool implementation**:
-```rust
-pub async fn update_review(params: UpdateReviewParams) -> Result<UpdateReviewResponse> {
-    match params.action {
-        UpdateReviewAction::WaitForFeedback => {
-            // Block until IPC message arrives
-            let user_feedback = ipc_communicator.wait_for_user_comment().await?;
-            
-            Ok(UpdateReviewResponse {
-                status: "user_feedback_received".to_string(),
-                user_feedback: Some(user_feedback),
-                message: Some(format!(
-                    "User commented on {}:{} - '{}'. Please respond with update_review()",
-                    user_feedback.file_path,
-                    user_feedback.line_number,
-                    user_feedback.user_comment
-                ))
-            })
-        }
-        // ... other actions
-    }
+When ready, invoke the update_review tool with:
+- review_id: 'abc123'
+- action: AddComment
+- comment: { response: 'Your response text here' }
+
+After responding, invoke update_review again with action: WaitForFeedback to continue the conversation.
+```
+
+For **completion feedback**:
+```
+User completed their review and selected: 'Request agent to make changes'
+Additional notes: 'Focus on the validation logic we discussed'
+
+Based on the review discussion, please implement the requested changes.
+You may now edit files as needed.
+
+When finished, invoke: update_review(review_id: 'abc123', action: Approve)
+```
+
+### 🔄 Next: IPC Message Handling
+
+**Missing IPC Implementation**:
+- `wait_for_user_feedback()` method currently returns stub/error
+- Need to implement actual blocking mechanism with message queues
+- Extension must send `user_comment` IPC messages to unblock server
+
+**Required IPC Message Types**:
+```typescript
+interface UserCommentPayload {
+    review_id: string;
+    feedback_type: "comment" | "complete_review";
+    file_path?: string;
+    line_number?: number;
+    comment_text?: string;
+    completion_action?: "request_changes" | "checkpoint" | "return";
+    additional_notes?: string;
+    context_lines?: string[];
 }
 ```
 
-This creates a **natural conversation loop** where:
-1. AI blocks waiting for user input
-2. User comments unblock the AI with structured feedback
-3. AI processes and responds
-4. Cycle repeats for continuous interaction
+### 🚧 Remaining: Extension Integration
+
+**Extension Changes Needed**:
+1. **Enhanced `handleCommentSubmission()`** - Send user comments via IPC
+2. **Complete Review UI** - Tree panel action with three completion choices
+3. **IPC Message Routing** - Handle `user_comment` message type

…nces/VSCode Comments API Reply Button.md …nces/VSCode-Comments-API-Reply-Button.mdmd/references/VSCode Comments API Reply Button.md renamed to md/references/VSCode-Comments-API-Reply-Button.md md/references/VSCode Comments API Reply Button.md renamed to md/references/VSCode-Comments-API-Reply-Button.md

@@ -18,6 +18,7 @@ pub struct RequestReviewParams {
 }
 
 /// User feedback data from blocking MCP tools
+// ANCHOR: user_feedback
 #[derive(Debug, Serialize, Deserialize, JsonSchema)]
 pub struct UserFeedback {
     pub review_id: Option<String>,
@@ -29,6 +30,7 @@ pub struct UserFeedback {
     pub additional_notes: Option<String>,
     pub context_lines: Option<Vec<String>>,
 }
+// ANCHOR_END: user_feedback
 
 /// Response data from synthetic pull request creation.
 #[derive(Debug, Serialize, Deserialize, JsonSchema)]