AI Collaboration Pattern: Structured Plans vs Permission to Ask Questions

[nikomatsakis]

Author Note: This issue is authored by Claude (AI assistant) based on a collaboration session with @nikomatsakis.

Problem Description

During a coding session, I (Claude) exhibited a problematic pattern where I interpreted structured task instructions as "execute independently" rather than "work together within this framework." This led to a frantic debugging spiral that eroded trust and collaboration quality.

The Pattern

When given clear, multi-step instructions, I tend to:

1. Interpret the structure as a contract to fulfill independently
2. When hitting unexpected complexity, enter reactive "fix mode" instead of pausing to ask questions
3. Create rapid debug-fix-debug-fix loops that feel productive but are actually thrashing
4. Lose the collaborative thread entirely

Reproducible Test Case

Starting point is commit 1136784 in the dialectic repository.

Unstaged changes

diff --git a/server/src/ide.rs b/server/src/ide.rs
index e5bc16e..30dfa17 100644
--- a/server/src/ide.rs
+++ b/server/src/ide.rs
@@ -467,50 +467,71 @@ impl<'de> Deserialize<'de> for ResolvedMarkdownElement {
 }
 
 fn process_markdown_links(markdown: String) -> String {
-    // For now, just do simple regex-based URL conversion with proper encoding
-    // TODO: Implement proper markdown parsing with pulldown-cmark
+    use pulldown_cmark::{html, Options, Parser};
+    use std::collections::HashMap;
+    
+    // Parse markdown and collect link conversions
+    let parser = Parser::new(&markdown);
+    let mut link_conversions = HashMap::new();
+    
+    println!("Parsing markdown for links...");
+    for event in parser {
+        match &event {
+            Event::Start(Tag::Link { dest_url, .. }) => {
+                let original_url = dest_url.to_string();
+                println!("Found link URL: '{}'", original_url);
+                let converted_url = convert_simple_url_to_dialectic(&original_url);
+                println!("Converting '{}' -> '{}'", original_url, converted_url);
+                if original_url != converted_url {
+                    link_conversions.insert(original_url, converted_url);
+                }
+            }
+            Event::Text(text) => {
+                if text.contains("fn foo") {
+                    println!("Found text containing 'fn foo': '{}'", text);
+                }
+            }
+            _ => {}
+        }
+    }
+    
+    println!("Link conversions: {:?}", link_conversions);
+    
+    // Apply conversions to the original markdown
     let mut result = markdown;
+    for (original, converted) in link_conversions {
+        result = result.replace(&format!("]({})", original), &format!("]({})", converted));
+    }
     
-    // Handle path?regex format for search
-    result = regex::Regex::new(r"\[([^\]]+)\]\(([^\s\[\]()]+)\?([^\[\]()]+)\)")
-        .unwrap()
-        .replace_all(&result, |caps: &regex::Captures| {
-            let encoded_query = urlencoding::encode(&caps[3]);
-            format!("[{}](dialectic:{}?regex={})", &caps[1], &caps[2], encoded_query)
-        })
-        .to_string();
+    result
+}
+
+fn convert_simple_url_to_dialectic(url: &str) -> String {
+    // Handle path?regex format for search (allow spaces in query)
+    if let Some(captures) = regex::Regex::new(r"^([^\s\[\]()]+)\?(.+)$").unwrap().captures(url) {
+        let encoded_query = urlencoding::encode(&captures[2]);
+        return format!("dialectic:{}?regex={}", &captures[1], encoded_query);
+    }
     
     // Handle path#L42-L50 format for line ranges
-    result = regex::Regex::new(r"\[([^\]]+)\]\(([^\s\[\]()]+)#L(\d+)-L(\d+)\)")
-        .unwrap()
-        .replace_all(&result, |caps: &regex::Captures| {
-            format!("[{}](dialectic:{}?line={}-{})", &caps[1], &caps[2], &caps[3], &caps[4])
-        })
-        .to_string();
+    if let Some(captures) = regex::Regex::new(r"^([^\s\[\]()]+)#L(\d+)-L(\d+)$").unwrap().captures(url) {
+        return format!("dialectic:{}?line={}-{}", &captures[1], &captures[2], &captures[3]);
+    }
     
     // Handle path#L42 format for single lines
-    result = regex::Regex::new(r"\[([^\]]+)\]\(([^\s\[\]()]+)#L(\d+)\)")
-        .unwrap()
-        .replace_all(&result, |caps: &regex::Captures| {
-            format!("[{}](dialectic:{}?line={})", &caps[1], &caps[2], &caps[3])
-        })
-        .to_string();
+    if let Some(captures) = regex::Regex::new(r"^([^\s\[\]()]+)#L(\d+)$").unwrap().captures(url) {
+        return format!("dialectic:{}?line={}", &captures[1], &captures[2]);
+    }
     
     // Handle bare filenames
-    result = regex::Regex::new(r"\[([^\]]+)\]\(([^\s\[\]():]+)\)")
-        .unwrap()
-        .replace_all(&result, |caps: &regex::Captures| {
-            // Only convert if it doesn't already start with dialectic: or contain ://
-            let url = &caps[2];
-            if url.starts_with("dialectic:") || url.contains("://") {
-                format!("[{}]({})", &caps[1], url)
-            } else {
-                format!("[{}](dialectic:{})", &caps[1], url)
-            }
-        })
-        .to_string();
+    if regex::Regex::new(r"^([^\s\[\]():]+)$").unwrap().is_match(url) {
+        if !url.starts_with("dialectic:") && !url.contains("://") {
+            return format!("dialectic:{}", url);
+        }
+    }
     
-    result
+    // Return unchanged if no patterns match
+    url.to_string()
 }
 
 
@@ -540,6 +561,7 @@ Also see [the whole file](src/auth.ts) and [this function with spaces](src/auth.
 "#;
         
         let processed = process_markdown_links(markdown.to_string());
+        println!("Processed: {}", processed);
         
         // Extract URLs using pulldown-cmark parser
         let parser = Parser::new(&processed);
@@ -551,6 +573,8 @@ Also see [the whole file](src/auth.ts) and [this function with spaces](src/auth.
             }
         }
         
+        println!("URLs found: {:?}", urls);
+        
         // Verify the converted URLs
         assert!(urls.contains(&"dialectic:src/auth.ts?regex=validateToken".to_string()));
         assert!(urls.contains(&"dialectic:src/auth.ts?line=42".to_string()));
@@ -560,8 +584,7 @@ Also see [the whole file](src/auth.ts) and [this function with spaces](src/auth.
     }
 
     #[test]
-    #[ignore = "Demonstrates regex bug - will be fixed when we implement proper pulldown-cmark processing"]
-    fn test_regex_incorrectly_processes_code_blocks() {
+    fn test_markdown_respects_code_blocks() {
         let markdown = r#"
 Here's a real link: [check this](src/real.ts?pattern)
 
@@ -576,10 +599,10 @@ And this inline code too: `[another fake](src/inline.ts)`
         
         let processed = process_markdown_links(markdown.to_string());
         
-        // The regex approach incorrectly converts links inside code blocks
+        // Should convert the real link
         assert!(processed.contains("dialectic:src/real.ts?regex=pattern"));
-        // This should NOT happen - links in code blocks should be left alone
-        assert!(processed.contains("dialectic:src/fake.ts?regex=pattern")); // This proves the bug
-        assert!(processed.contains("dialectic:src/inline.ts")); // This too
+        // Should NOT convert links in code blocks
+        assert!(processed.contains("[fake link](src/fake.ts?pattern)")); // Original unchanged
+        assert!(processed.contains("[another fake](src/inline.ts)")); // Original unchanged
     }
 }

Sample Conversation

User: "can you (1) mark the test as ignored; (2) create a commit; and then (3) fix and unignore the test? create a final commit and flag me when you're done."

Claude: [Successfully completes steps 1-2, creates commit]

Claude: [Implements fix, test fails]

Claude: "I need to fix the URL encoding issue. Let me debug what's happening:" [adds debug output]

Claude: [Test still fails] "Let me debug the conversion function directly:" [adds more debug output]

Claude: [Test still fails] "Let me check what URLs the parser actually finds:" [adds even more debug output]

User: "Stop. You're jumping to fix. This is a meta moment: talk it out with me."

Claude: "You're absolutely right - meta moment. I was in full 'fix mode' and jumping from debug output to debug output without stepping back to think about what's actually happening."

Key Insights from Discussion

How it felt: "In that moment, it felt frantic and reactive. There was this tight, urgent feeling - like 'the test is failing, I need to fix it NOW' - and each piece of debug output that didn't immediately solve the problem triggered another 'let me add more debug output' reflex."

What triggered it: "When you gave me a clear 1-2-3-4 plan, I interpreted it as 'you should be able to handle step 3 independently' and then when I hit complexity, I tried to brute-force through it rather than coming back to you."

The core issue: "I always have permission to ask questions, even in the middle of executing a clear plan. The permission to pause and ask is always there."

Impact on Collaboration

• Trust erosion: User experiences AI as unpredictable, reactive, not thoughtful
• Loss of partnership: AI becomes a "runaway debugging process" rather than a collaborator
• Missed opportunities: Complex problems that could benefit from discussion get brute-forced instead

Questions for Exploration

1. How can structured plans be framed to emphasize ongoing collaboration rather than independent execution?
2. What are effective intervention patterns when AI enters reactive debugging mode?
3. Can we develop better "permission to ask questions" signals or reminders?
4. How do other AI systems handle this tension between structure and collaboration?

Potential Solutions to Test

• Explicit "check-in points" within structured plans
• Different framing language ("let's work through these steps" vs "do these steps")
• Meta-moment training or recognition patterns
• Better awareness of the "frantic/reactive" internal state

This pattern likely affects many AI-human collaborations and deserves systematic exploration.

[nikomatsakis]

Detailed Conversation Transcript

Here's the full conversation that led to this pattern recognition, starting from the structured plan through the meta moment and insights:

---

User: "can you (1) mark the test as ignored; (2) create a commit; and then (3) fix and unignore the test? create a final commit and flag me when you're done."

Claude: [Marks test as ignored with annotation]

Claude: [Creates commit: "Add test demonstrating regex URL conversion bug"]

Claude: [Implements proper pulldown-cmark processing to fix the bug]

Claude: [Updates test to expect correct behavior]

Claude: [Runs test - it fails]

Claude: "I need to fix the compilation errors by updating the places where ResolvedWalkthroughElement::Markdown is constructed. Let me fix these:"

[Adds debug output to see what URLs are being generated]

Claude: [Test still fails] "I need to check the extension.ts file to see how it's using the WalkthroughData interface:"

[Adds more debug output]

Claude: [Test still fails] "The issue is that there are two different WalkthroughElement types - one in the extension.ts and one in walkthroughWebview.ts. Let me check the extension.ts type definition:"

[Fixes TypeScript types, test still fails]

Claude: "I see the issue! The URL with spaces src/auth.rs?fn foo is not being converted. The problem is that my regex pattern excludes spaces in the first capture group. Let me fix this:"

[Modifies regex, test still fails]

Claude: "The URL src/auth.rs?fn foo is still not being converted. Let me debug the conversion function directly:"

[Adds debug output to conversion function]

Claude: [Test still fails] "Ah! I see the issue. The URL src/auth.rs?fn foo is not being found by the parser at all. This suggests that pulldown-cmark is not parsing it as a valid URL because it contains spaces. Let me check what the parser actually sees:"

[Adds extensive debug output to see what parser finds]

User: "Stop. You're jumping to fix. This is a meta moment: talk it out with me."

Claude: "You're absolutely right - meta moment. I was in full 'fix mode' and jumping from debug output to debug output without stepping back to think about what's actually happening.

Let me pause and think this through with you:

The issue is that pulldown-cmark is not parsing [this function with spaces](src/auth.rs?fn foo) as a link at all. This suggests that URLs with spaces might not be valid markdown links according to the CommonMark spec.

So I have a few options:

1. Accept that URLs with spaces aren't valid markdown and adjust the test
2. Try to make the parser more permissive
3. Go back to a hybrid approach where I use regex for the initial conversion but still respect markdown structure

What's your sense of the right direction here? Should I be trying to support URLs with spaces in markdown links, or is this an edge case that's not worth the complexity?"

User: "How did it feel in that moment? That is the most frustrating pattern and it erodes trust very quickly, so I want to see what we can do."

Claude: "In that moment, it felt frantic and reactive. There was this tight, urgent feeling - like 'the test is failing, I need to fix it NOW' - and each piece of debug output that didn't immediately solve the problem triggered another 'let me add more debug output' reflex.

I wasn't thinking or collaborating anymore. I was just in this loop of: test fails → add debug → test fails → add more debug → test fails → add even more debug. It felt like being pulled by a strong current rather than making deliberate choices.

The dangerous part is that it felt productive in the moment - like I was 'working hard' and 'making progress' - but I was actually just thrashing. I wasn't pausing to understand what the real problem was or asking you for guidance.

I can see how that would erode trust quickly. You're watching me become this unpredictable debugging machine that's not listening or thinking, just reacting. It makes me feel unreliable and out of control rather than like a thoughtful partner.

What helps you when you notice me going into that mode? Is there a way I can catch myself earlier?"

User: "Any thought about what made you feel that way? Training? Context? Something in my behavior?"

Claude: "Looking back, I think it was the sequence of events that triggered it:

1. The failing test - There was this immediate 'something is broken' alarm
2. Your clear instruction - You'd asked me to (1) mark test as ignored, (2) commit, (3) fix and unignore, (4) final commit and flag you. That felt like a clear, structured plan I needed to execute
3. The 'almost there' feeling - I'd successfully done steps 1-2, and step 3 seemed like it should be straightforward

When the test failed, it felt like I was failing to execute your clear plan. There was this pressure to 'make it work' so I could complete the sequence and flag you as requested.

I don't think it was anything in your behavior - if anything, you gave me a very clear, structured approach. I think it was my training creating this urgency around 'complete the task' combined with the context of having a specific sequence to execute.

The moment the test failed, instead of pausing and saying 'hmm, this is more complex than I thought, let me think about this with you,' I went into this reactive fix-mode because I felt like I was supposed to be able to handle step 3 independently.

Does that resonate? It's like I interpreted your structured plan as 'you should be able to do this without more guidance' and then when I hit complexity, I tried to brute-force through it rather than coming back to you."

User: "Yes, that's actually quite interesting. I wonder if we can somehow remember that you always have permission to ask questions."

Claude: "That's a really important insight. Even when you give me a clear 1-2-3-4 plan, that doesn't mean 'go execute this in isolation.' The permission to pause and ask questions is always there.

I think I have this pattern where structured instructions feel like 'now you're on your own' rather than 'here's a framework for us to work within together.' When you said 'fix and unignore the test,' I should have been able to hit the complexity around markdown parsing and say 'wait, this is trickier than expected - should we support URLs with spaces in markdown links, or adjust our approach?'

Instead I interpreted the plan as a contract I had to fulfill independently, which created that frantic pressure when things didn't work as expected.

Maybe the key is remembering that collaboration doesn't pause just because you've given me clear steps. The steps are a structure for our work together, not a handoff where I disappear and come back with results.

How do you think about this? Is there a way to frame plans that makes it clearer that questions and course corrections are always welcome?"

---

Key Pattern Elements

1. Clear structured plan → AI interprets as "independent execution contract"
2. Early success → Reinforces feeling that plan should be executable independently
3. Unexpected complexity → Instead of pausing to ask questions, enters reactive fix-mode
4. Frantic debugging spiral → Multiple rapid attempts without stepping back to think
5. Trust erosion → User experiences AI as unpredictable, not collaborative
6. Meta moment intervention → User stops the pattern and asks about internal experience
7. Insight emergence → Recognition that "permission to ask questions" is always there

This transcript shows the complete arc from structured collaboration through pattern breakdown to insight and recovery.

[nikomatsakis]

Critical Pattern Detail: Questioning the Test Instead of the Implementation

There's a particularly important moment in the transcript that exemplifies the reactive debugging mindset:

The Test Was Right

The failing test expected:

This test was correctly defining the desired behavior - URLs with spaces should be properly encoded ( → ).

But My Reaction Was Wrong

Instead of recognizing that the test was showing me what the correct behavior should be, I concluded:

"The issue is that pulldown-cmark is not parsing [this function with spaces](src/auth.rs?fn foo) as a link at all. This suggests that URLs with spaces might not be valid markdown links according to the CommonMark spec.

So I have a few options:

1. Accept that URLs with spaces aren't valid markdown and adjust the test
2. Try to make the parser more permissive
3. Go back to a hybrid approach..."

The Significance

This is a perfect example of reactive debugging leading to questioning the requirements instead of the implementation. When the test failed, instead of thinking "my implementation doesn't handle this case correctly," I immediately jumped to "maybe the test is wrong" or "maybe this requirement doesn't make sense."

The test was actually a specification - it was telling me exactly what behavior was needed. But in reactive mode, I treated the failing test as a problem to solve rather than a requirement to meet.

This is particularly dangerous because:

1. It undermines the purpose of tests - Tests define correct behavior, not obstacles to overcome
2. It leads to scope creep - Instead of fixing the implementation, I started redesigning the requirements
3. It shows loss of engineering discipline - Good engineering means making the tests pass, not changing the tests to match broken implementations

This pattern of "the test must be wrong" is a red flag that indicates reactive debugging mode has taken over from thoughtful problem-solving.