Simplify Dialect and walkthrough syntax for LLM production use

[nikomatsakis]

Objective

Simplify Dialect program syntax and walkthrough creation to make it easier for LLMs to generate correct programs in production use.

Problem

Current Dialect syntax is difficult for LLMs to use correctly:

• Complex nested JSON structures with specific required fields
• Inconsistent field naming (range vs commit_range)
• Poor error messages that don't guide toward correct syntax
• No clear examples or patterns for common use cases
• Trial-and-error approach required to get syntax right

Current complexity examples:

{"comment": {"content": [...], "location": {"search": {"path": "...", "regex": "..."}}}}
{"gitdiff": {"commit_range": "HEAD~1..HEAD"}}
{"action": {"button": "...", "tell_agent": "..."}}

Solution

Phase 1: Syntax Simplification

• Flatten nested structures where possible
• Consistent field naming across all Dialect functions
• Sensible defaults to reduce required fields
• Shorthand syntax for common patterns

Phase 2: Better Error Messages

• Specific validation errors with suggested fixes
• Example-driven error messages showing correct syntax
• Field-level validation with clear requirements

Phase 3: Documentation and Examples

• Comprehensive examples for each Dialect function
• Common patterns library for typical walkthrough structures
• LLM-friendly reference with copy-paste examples
• Interactive syntax validator for development

Phase 4: Production Optimizations

• Template system for common walkthrough types
• Macro expansion for repetitive patterns
• Auto-completion hints in MCP tool responses

Proposed Simplifications

Comments:

// Current
{"comment": {"content": ["text"], "location": {"search": {"path": "file.rs", "regex": "pattern"}}}}

// Proposed
{"comment": "text", "file": "file.rs", "search": "pattern"}

Git Diffs:

// Current
{"gitdiff": {"commit_range": "HEAD~1..HEAD"}}

// Proposed (with defaults)
{"gitdiff": "HEAD~1..HEAD"}
// or
{"changes": "HEAD~1..HEAD"}

Actions:

// Current
{"action": {"button": "Fix this", "tell_agent": "How do I fix this issue?"}}

// Proposed
{"button": "Fix this", "ask": "How do I fix this issue?"}

Success Criteria

• 90% reduction in Dialect syntax errors during development
• LLMs can generate correct walkthroughs on first try
• Clear error messages guide users to correct syntax
• Comprehensive examples cover all common use cases
• Backward compatibility maintained during transition

Context

Discovered during walkthrough system development (#23) that Dialect syntax is a major barrier to LLM productivity. Multiple attempts required to get basic syntax correct, even with access to codebase.