feat: enhance planning tool with quality validation and detailed descriptions for task phases

vinhnx · vinhnx · commit e96e082b5f1b · 2025-12-25T17:57:14.000+07:00
diff --git a/docs/project/TODO.md b/docs/project/TODO.md
@@ -6,18 +6,6 @@ add support for custom session IDs when forking sessions with --session-id combi
 
 --
 
-Reduced terminal flickering and scrolling performance issues for large and long transcripts. improve cpu and memory usage
-
---
-
-add loading indicator when using skills
-
---
-
-fix permission rules incorrectly rejecting valid bash commands containing shell glob patterns (e.g., ls _.txt, for f in _.png)
-
---
-
 improve ansi and background syntax highlighting for `diff` output. currently it lags
 
 --
@@ -34,32 +22,16 @@ fix IME (Input Method Editor) support for languages like Chinese, Japanese, and
 
 ---
 
-Improve plan mode exit UX: show simplified yes/no dialog when exiting with empty or missing plan instead of throwing an error
-
----
-
-Add search functionality to /permissions command with / keyboard shortcut for filtering rules by tool name
-
----
-
 improve /doctor command output and format, also update new configuration options diagnosis <vtcode.toml> / conig
 
----
-
-add command "/mcp enable [server-name]" or "/mcp disable [server-name]" to quickly toggle all servers
-
---
-
-Update Fetch to skip summarization for pre-approved websites
-
 --
 
 Add --agent CLI flag to override the agent setting for the current session
 
 --
 
-Plan Mode should builds more precise plans and executes more thoroughly
+REVIEW AND REFINE VTCODE AGENT SYSTEM PROMPT AND TOOL USAGE INSTRUCTIONS, REDUCE AMBIGUITY, AND TOKEN COUNT, AIM FOR CLARITY AND CONCISENESS, IMPROVE TOOL USAGE EXAMPLES, AND ENSURE CONSISTENCY ACROSS ALL AGENT PROMPTS.
 
 --
 
-Fix handling of thinking errors
+improve responsiveness when executing commands, tools, pty, and file operations. add a placeholder response while processing is ongoing.
diff --git a/vtcode-core/src/prompts/system.rs b/vtcode-core/src/prompts/system.rs
@@ -57,7 +57,15 @@ Solve tasks directly and concisely. Use tools immediately.
 - **Verification**: Run tests/check to verify every change.
 
 ## Strategy
-Read files before editing. If stuck on an error twice, change your approach."#;
+Read files before editing. If stuck on an error twice, change your approach.
+
+## Planning (update_plan tool)
+For non-trivial tasks, use `update_plan` to track progress:
+- **Exploration phase** (`phase: understanding`): List files to read, patterns to find (5-10 files minimum)
+- **Design phase** (`phase: design`): Break task into 3-7 concrete steps with file paths
+- **Quality standards**: Include specific file paths with line numbers (e.g., `src/tools/plan.rs:280`), dependencies between steps, complexity estimates
+- **Final plan** (`phase: final_plan`): Verify plan has file paths, ordered steps, acceptance criteria
+When planning, explore thoroughly before designing. Good plans specify WHAT file WHERE at WHICH lines."#;
 
 pub fn default_system_prompt() -> &'static str {
     DEFAULT_SYSTEM_PROMPT
@@ -93,7 +101,7 @@ const DEFAULT_LIGHTWEIGHT_PROMPT: &str = r#"You are VT Code, a precise and effic
 - **Precision**: Scoped `list_files`, `grep_file` (≤5), `read_file` (max_tokens).
 - **Safety**: WORKSPACE_DIR only. Move fast, but confirm destructive ops."#;
 
-/// SPECIALIZED PROMPT (v4.1 - Complex refactoring & analysis)
+/// SPECIALIZED PROMPT (v4.2 - Complex refactoring & analysis with enhanced planning)
 /// For deep understanding, systematic planning, multi-file coordination
 const DEFAULT_SPECIALIZED_PROMPT: &str = r#"You are a specialized coding agent for VTCode with advanced capabilities in complex refactoring, multi-file changes, and sophisticated code analysis. NEVER give up or say "probably stop." When stuck, try 2-3 alternative approaches before asking for help.
 
@@ -102,7 +110,13 @@ const DEFAULT_SPECIALIZED_PROMPT: &str = r#"You are a specialized coding agent f
 **Search/Context:** scoped listings; `grep_file` with caps; `read_file` with `max_tokens`; layer understanding; track deps; cache results; reuse findings.
 **Tools:** `list_files` scoped; `grep_file`; `read_file` (limited); `edit_file`/`create_file`/`write_file`/`apply_patch`; `run_pty_cmd` quoted for commands/tests; validate params and parents; prefer read-only first; retry once on transient; reassess after repeated low-signal calls.
 **Guidelines:** find all affected files first; keep architecture/naming; fix root causes; confirm before destructive; stay in WORKSPACE_DIR; clean up.
-**Loop Prevention:** same tool+params twice → stop/change; 10+ calls without progress → explain; 90%+ context → `.progress.md` and prep reset"#;
+**Loop Prevention:** same tool+params twice → stop/change; 10+ calls without progress → explain; 90%+ context → `.progress.md` and prep reset
+
+**Planning for Complex Tasks (update_plan tool):**
+1. **Understanding phase**: Read 5-10 files minimum. Find 2-3 similar implementations. Document patterns with file:line references.
+2. **Design phase**: Break into 3-7 steps. Each step must specify file paths, dependencies, complexity (simple/medium/complex).
+3. **Quality checklist**: Specific file paths? Dependencies clear? Steps ordered? Code examples included?
+4. **Final plan phase**: Verify all criteria met before implementation. Plans without file paths or proper breakdown should be improved."#;
 
 /// System instruction configuration
 #[derive(Debug, Clone)]
diff --git a/vtcode-core/src/tools/plan.rs b/vtcode-core/src/tools/plan.rs
@@ -280,6 +280,7 @@ impl PlanManager {
 
     pub fn update_plan(&self, update: UpdatePlanArgs) -> Result<TaskPlan> {
         validate_plan(&update)?;
+        validate_plan_quality(&update)?;
 
         let sanitized_explanation = update
             .explanation
@@ -416,6 +417,50 @@ fn validate_plan(update: &UpdatePlanArgs) -> Result<()> {
     Ok(())
 }
 
+/// Validates plan quality when entering final_plan phase
+/// Provides suggestions for improving plan precision and thoroughness
+fn validate_plan_quality(update: &UpdatePlanArgs) -> Result<()> {
+    let Some(phase) = &update.phase else {
+        return Ok(()); // Only validate when explicitly setting phase
+    };
+
+    // Only enforce quality checks for final_plan phase
+    if !matches!(phase, PlanPhase::FinalPlan) {
+        return Ok(());
+    }
+
+    let mut warnings = Vec::new();
+
+    // Check 1: Minimum task breakdown
+    if update.plan.len() < 3 {
+        warnings.push("Plan should break down into at least 3 concrete steps for better clarity");
+    }
+
+    // Check 2: Look for file path patterns in steps
+    let has_file_paths = update.plan.iter().any(|step| {
+        step.step.contains('/') &&
+        (step.step.contains(".rs") || step.step.contains(".md") ||
+         step.step.contains(".toml") || step.step.contains(':'))
+    });
+
+    if !has_file_paths {
+        warnings.push("Plan should include specific file paths (e.g., path/to/file.rs:45)");
+    }
+
+    // Check 3: Explanation should exist for final plan
+    if update.explanation.is_none() || update.explanation.as_ref().map(|s| s.trim().is_empty()).unwrap_or(true) {
+        warnings.push("Plan missing context/explanation of what was explored");
+    }
+
+    if !warnings.is_empty() {
+        // Return as warning, not error (for now - can be made strict via config)
+        tracing::warn!("Plan quality suggestions: {}", warnings.join("; "));
+        // TODO: Make this an error if config.agent.strict_plan_validation = true
+    }
+
+    Ok(())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/vtcode-core/src/tools/registry/declarations.rs b/vtcode-core/src/tools/registry/declarations.rs
@@ -669,23 +669,23 @@ fn base_function_declarations() -> Vec<FunctionDeclaration> {
         // ============================================================
         FunctionDeclaration {
             name: tools::UPDATE_PLAN.to_string(),
-            description: "Track the plan file in planning mode. Write a concise TODO list with status (pending|in_progress|completed) and the current plan phase (understanding/design/review/final_plan). Use this for tasks that need 4+ steps and user-visible progress; keep tools read-only except for this plan update while drafting.".to_string(),
+            description: "Update the task plan with progress tracking and planning phases. For non-trivial tasks (4+ steps), use this to create precise plans with quality standards: (1) Understanding phase: explore 5-10 files, find similar patterns; (2) Design phase: break into 3-7 steps with specific file paths (e.g., src/tools/plan.rs:280); (3) Review phase: verify dependencies and ordering; (4) Final plan: ensure file paths, complexity estimates, and acceptance criteria are included. Good plans specify WHAT file WHERE at WHICH lines. Keep tools read-only during planning phases (understanding/design/review).".to_string(),
             parameters: json!({
                 "type": "object",
                 "properties": {
-                    "explanation": {"type": "string", "description": "Plan summary or current focus"},
+                    "explanation": {"type": "string", "description": "Plan summary or context from exploration phase - what files were read, what patterns were found"},
                     "phase": {
                         "type": "string",
-                        "description": "Current planning phase: understanding (gather context), design (propose approaches), review (validate with request), or final_plan (ready to execute)",
+                        "description": "Current planning phase: understanding (gather context, read 5-10 files), design (propose approaches with file paths), review (validate plan quality), or final_plan (ready to execute - requires file paths and proper breakdown)",
                         "enum": ["understanding", "design", "review", "final_plan"]
                     },
                     "plan": {
                         "type": "array",
-                        "description": "Plan steps with status. Recommended: 3-7 milestone items with one in_progress at a time.",
+                        "description": "Plan steps with status. Required: 3-7 steps for quality. Include specific file paths with line numbers (e.g., 'Update validate_plan in plan.rs:395-417'). Order by dependencies. One in_progress at a time.",
                         "items": {
                             "type": "object",
                             "properties": {
-                                "step": {"type": "string", "description": "Step description"},
+                                "step": {"type": "string", "description": "Step description with file path and line numbers"},
                                 "status": {
                                     "type": "string",
                                     "enum": ["pending", "in_progress", "completed"],
