clink-cli 0.2.1__py3-none-any.whl

tools/tracer.py

@@ -0,0 +1,763 @@
+"""
+Tracer Workflow tool - Step-by-step code tracing and dependency analysis
+
+This tool provides a structured workflow for comprehensive code tracing and analysis.
+It guides the CLI agent through systematic investigation steps with forced pauses between each step
+to ensure thorough code examination, dependency mapping, and execution flow analysis before proceeding.
+
+The tracer guides users through sequential code analysis with full context awareness and
+the ability to revise and adapt as understanding deepens.
+
+Key features:
+- Sequential tracing with systematic investigation workflow
+- Support for precision tracing (execution flow) and dependencies tracing (structural relationships)
+- Self-contained completion with detailed output formatting instructions
+- Context-aware analysis that builds understanding step by step
+- No external expert analysis needed - provides comprehensive guidance internally
+
+Perfect for: method/function execution flow analysis, dependency mapping, call chain tracing,
+structural relationship analysis, architectural understanding, and code comprehension.
+"""
+
+import logging
+from typing import TYPE_CHECKING, Any, Literal, Optional
+
+from pydantic import Field, field_validator
+
+if TYPE_CHECKING:
+    from tools.models import ToolModelCategory
+
+from config import TEMPERATURE_ANALYTICAL
+from systemprompts import TRACER_PROMPT
+from tools.shared.base_models import WorkflowRequest
+
+from .workflow.base import WorkflowTool
+
+logger = logging.getLogger(__name__)
+
+# Tool-specific field descriptions for tracer workflow
+TRACER_WORKFLOW_FIELD_DESCRIPTIONS = {
+    "step": (
+        "The plan for the current tracing step. Step 1: State the tracing strategy. Later steps: Report findings and adapt the plan. "
+        "CRITICAL: For 'precision' mode, focus on execution flow and call chains. For 'dependencies' mode, focus on structural relationships. "
+        "If trace_mode is 'ask' in step 1, you MUST prompt the user to choose a mode."
+    ),
+    "step_number": (
+        "The index of the current step in the tracing sequence, beginning at 1. Each step should build upon or "
+        "revise the previous one."
+    ),
+    "total_steps": (
+        "Your current estimate for how many steps will be needed to complete the tracing analysis. "
+        "Adjust as new findings emerge."
+    ),
+    "next_step_required": (
+        "Set to true if you plan to continue the investigation with another step. False means you believe the "
+        "tracing analysis is complete and ready for final output formatting."
+    ),
+    "findings": (
+        "Summary of discoveries from this step, including execution paths, dependency relationships, call chains, and structural patterns. "
+        "IMPORTANT: Document both direct (immediate calls) and indirect (transitive, side effects) relationships."
+    ),
+    "files_checked": (
+        "List all files examined (absolute paths). Include even ruled-out files to track exploration path."
+    ),
+    "relevant_files": (
+        "Subset of files_checked directly relevant to the tracing target (absolute paths). Include implementation files, "
+        "dependencies, or files demonstrating key relationships."
+    ),
+    "relevant_context": (
+        "List methods/functions central to the tracing analysis, in 'ClassName.methodName' or 'functionName' format. "
+        "Prioritize those in the execution flow or dependency chain."
+    ),
+    "confidence": (
+        "Your confidence in the tracing analysis. Use: 'exploring', 'low', 'medium', 'high', 'very_high', 'almost_certain', 'certain'. "
+        "CRITICAL: 'certain' implies the analysis is 100% complete locally and PREVENTS external model validation."
+    ),
+    "trace_mode": "Type of tracing: 'ask' (default - prompts user to choose mode), 'precision' (execution flow) or 'dependencies' (structural relationships)",
+    "target_description": (
+        "Description of what to trace and WHY. Include context about what you're trying to understand or analyze."
+    ),
+    "images": ("Optional paths to architecture diagrams or flow charts that help understand the tracing context."),
+}
+
+
+class TracerRequest(WorkflowRequest):
+    """Request model for tracer workflow investigation steps"""
+
+    # Required fields for each investigation step
+    step: str = Field(..., description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS["step"])
+    step_number: int = Field(..., description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS["step_number"])
+    total_steps: int = Field(..., description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS["total_steps"])
+    next_step_required: bool = Field(..., description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS["next_step_required"])
+
+    # Investigation tracking fields
+    findings: str = Field(..., description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS["findings"])
+    files_checked: list[str] = Field(
+        default_factory=list, description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS["files_checked"]
+    )
+    relevant_files: list[str] = Field(
+        default_factory=list, description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS["relevant_files"]
+    )
+    relevant_context: list[str] = Field(
+        default_factory=list, description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS["relevant_context"]
+    )
+    confidence: Optional[str] = Field("exploring", description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS["confidence"])
+
+    # Tracer-specific fields (used in step 1 to initialize)
+    trace_mode: Optional[Literal["precision", "dependencies", "ask"]] = Field(
+        "ask", description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS["trace_mode"]
+    )
+    target_description: Optional[str] = Field(
+        None, description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS["target_description"]
+    )
+    images: Optional[list[str]] = Field(default=None, description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS["images"])
+
+    # Exclude fields not relevant to tracing workflow
+    issues_found: list[dict] = Field(default_factory=list, exclude=True, description="Tracing doesn't track issues")
+    hypothesis: Optional[str] = Field(default=None, exclude=True, description="Tracing doesn't use hypothesis")
+    # Exclude other non-tracing fields
+    temperature: Optional[float] = Field(default=None, exclude=True)
+    thinking_mode: Optional[str] = Field(default=None, exclude=True)
+    use_assistant_model: Optional[bool] = Field(default=False, exclude=True, description="Tracing is self-contained")
+
+    @field_validator("step_number")
+    @classmethod
+    def validate_step_number(cls, v):
+        if v < 1:
+            raise ValueError("step_number must be at least 1")
+        return v
+
+    @field_validator("total_steps")
+    @classmethod
+    def validate_total_steps(cls, v):
+        if v < 1:
+            raise ValueError("total_steps must be at least 1")
+        return v
+
+
+class TracerTool(WorkflowTool):
+    """
+    Tracer workflow tool for step-by-step code tracing and dependency analysis.
+
+    This tool implements a structured tracing workflow that guides users through
+    methodical investigation steps, ensuring thorough code examination, dependency
+    mapping, and execution flow analysis before reaching conclusions. It supports
+    both precision tracing (execution flow) and dependencies tracing (structural relationships).
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.initial_request = None
+        self.trace_config = {}
+
+    def get_name(self) -> str:
+        return "tracer"
+
+    def get_description(self) -> str:
+        return (
+            "Performs systematic code tracing with modes for execution flow or dependency mapping. "
+            "Use for method execution analysis, call chain tracing, dependency mapping, and architectural understanding. "
+            "Supports precision mode (execution flow) and dependencies mode (structural relationships)."
+        )
+
+    def get_system_prompt(self) -> str:
+        return TRACER_PROMPT
+
+    def get_default_temperature(self) -> float:
+        return TEMPERATURE_ANALYTICAL
+
+    def get_model_category(self) -> "ToolModelCategory":
+        """Tracer requires analytical reasoning for code analysis"""
+        from tools.models import ToolModelCategory
+
+        return ToolModelCategory.EXTENDED_REASONING
+
+    def requires_model(self) -> bool:
+        """
+        Tracer tool doesn't require model resolution at the MCP boundary.
+
+        The tracer is a structured workflow tool that organizes tracing steps
+        and provides detailed output formatting guidance without calling external AI models.
+
+        Returns:
+            bool: False - tracer doesn't need AI model access
+        """
+        return False
+
+    def get_workflow_request_model(self):
+        """Return the tracer-specific request model."""
+        return TracerRequest
+
+    def get_tool_fields(self) -> dict[str, dict[str, Any]]:
+        """Return tracing-specific field definitions beyond the standard workflow fields."""
+        return {
+            # Tracer-specific fields
+            "trace_mode": {
+                "type": "string",
+                "enum": ["precision", "dependencies", "ask"],
+                "description": TRACER_WORKFLOW_FIELD_DESCRIPTIONS["trace_mode"],
+            },
+            "target_description": {
+                "type": "string",
+                "description": TRACER_WORKFLOW_FIELD_DESCRIPTIONS["target_description"],
+            },
+            "images": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": TRACER_WORKFLOW_FIELD_DESCRIPTIONS["images"],
+            },
+        }
+
+    def get_input_schema(self) -> dict[str, Any]:
+        """Generate input schema using WorkflowSchemaBuilder with field exclusion."""
+        from .workflow.schema_builders import WorkflowSchemaBuilder
+
+        # Exclude investigation-specific fields that tracing doesn't need
+        excluded_workflow_fields = [
+            "issues_found",  # Tracing doesn't track issues
+            "hypothesis",  # Tracing doesn't use hypothesis
+        ]
+
+        # Exclude common fields that tracing doesn't need
+        excluded_common_fields = [
+            "cli_name",
+            "role",
+            "temperature",  # Tracing doesn't need temperature control
+            "thinking_mode",  # Tracing doesn't need thinking mode
+            "absolute_file_paths",  # Tracing uses relevant_files instead
+        ]
+
+        return WorkflowSchemaBuilder.build_schema(
+            tool_specific_fields=self.get_tool_fields(),
+            required_fields=["target_description", "trace_mode"],  # Step 1 requires these
+            model_field_schema=None,
+            auto_mode=False,
+            tool_name=self.get_name(),
+            excluded_workflow_fields=excluded_workflow_fields,
+            excluded_common_fields=excluded_common_fields,
+        )
+
+    # ================================================================================
+    # Abstract Methods - Required Implementation from BaseWorkflowMixin
+    # ================================================================================
+
+    def get_required_actions(
+        self, step_number: int, confidence: str, findings: str, total_steps: int, request=None
+    ) -> list[str]:
+        """Define required actions for each tracing phase."""
+        if step_number == 1:
+            # Check if we're in ask mode and need to prompt for mode selection
+            if self.get_trace_mode() == "ask":
+                return [
+                    "MUST ask user to choose between precision or dependencies mode",
+                    "Explain precision mode: traces execution flow, call chains, and usage patterns (best for methods/functions)",
+                    "Explain dependencies mode: maps structural relationships and bidirectional dependencies (best for classes/modules)",
+                    "Wait for user's mode selection before proceeding with investigation",
+                ]
+
+            # Initial tracing investigation tasks (when mode is already selected)
+            return [
+                "Search for and locate the target method/function/class/module in the codebase",
+                "Read and understand the implementation of the target code",
+                "Identify the file location, complete signature, and basic structure",
+                "Begin mapping immediate relationships (what it calls, what calls it)",
+                "Understand the context and purpose of the target code",
+            ]
+        elif confidence in ["exploring", "low"]:
+            # Need deeper investigation
+            return [
+                "Trace deeper into the execution flow or dependency relationships",
+                "Examine how the target code is used throughout the codebase",
+                "Map additional layers of dependencies or call chains",
+                "Look for conditional execution paths, error handling, and edge cases",
+                "Understand the broader architectural context and patterns",
+            ]
+        elif confidence in ["medium", "high"]:
+            # Close to completion - need final verification
+            return [
+                "Verify completeness of the traced relationships and execution paths",
+                "Check for any missed dependencies, usage patterns, or execution branches",
+                "Confirm understanding of side effects, state changes, and external interactions",
+                "Validate that the tracing covers all significant code relationships",
+                "Prepare comprehensive findings for final output formatting",
+            ]
+        else:
+            # General investigation needed
+            return [
+                "Continue systematic tracing of code relationships and execution paths",
+                "Gather more evidence using appropriate code analysis techniques",
+                "Test assumptions about code behavior and dependency relationships",
+                "Look for patterns that enhance understanding of the code structure",
+                "Focus on areas that haven't been thoroughly traced yet",
+            ]
+
+    def should_call_expert_analysis(self, consolidated_findings, request=None) -> bool:
+        """Tracer is self-contained and doesn't need expert analysis."""
+        return False
+
+    def prepare_expert_analysis_context(self, consolidated_findings) -> str:
+        """Tracer doesn't use expert analysis."""
+        return ""
+
+    def requires_expert_analysis(self) -> bool:
+        """Tracer is self-contained like the planner tool."""
+        return False
+
+    # ================================================================================
+    # Workflow Customization - Match Planner Behavior
+    # ================================================================================
+
+    def prepare_step_data(self, request) -> dict:
+        """
+        Prepare step data from request with tracer-specific fields.
+        """
+        step_data = {
+            "step": request.step,
+            "step_number": request.step_number,
+            "findings": request.findings,
+            "files_checked": request.files_checked,
+            "relevant_files": request.relevant_files,
+            "relevant_context": request.relevant_context,
+            "issues_found": [],  # Tracer doesn't track issues
+            "confidence": request.confidence or "exploring",
+            "hypothesis": None,  # Tracer doesn't use hypothesis
+            "images": request.images or [],
+            # Tracer-specific fields
+            "trace_mode": request.trace_mode,
+            "target_description": request.target_description,
+        }
+        return step_data
+
+    def build_base_response(self, request, continuation_id: str = None) -> dict:
+        """
+        Build the base response structure with tracer-specific fields.
+        """
+        # Use work_history from workflow mixin for consistent step tracking
+        current_step_count = len(self.work_history) + 1
+
+        response_data = {
+            "status": f"{self.get_name()}_in_progress",
+            "step_number": request.step_number,
+            "total_steps": request.total_steps,
+            "next_step_required": request.next_step_required,
+            "step_content": request.step,
+            f"{self.get_name()}_status": {
+                "files_checked": len(self.consolidated_findings.files_checked),
+                "relevant_files": len(self.consolidated_findings.relevant_files),
+                "relevant_context": len(self.consolidated_findings.relevant_context),
+                "issues_found": len(self.consolidated_findings.issues_found),
+                "images_collected": len(self.consolidated_findings.images),
+                "current_confidence": self.get_request_confidence(request),
+                "step_history_length": current_step_count,
+            },
+            "metadata": {
+                "trace_mode": self.trace_config.get("trace_mode", "unknown"),
+                "target_description": self.trace_config.get("target_description", ""),
+                "step_history_length": current_step_count,
+            },
+        }
+
+        if continuation_id:
+            response_data["continuation_id"] = continuation_id
+
+        return response_data
+
+    def handle_work_continuation(self, response_data: dict, request) -> dict:
+        """
+        Handle work continuation with tracer-specific guidance.
+        """
+        response_data["status"] = f"pause_for_{self.get_name()}"
+        response_data[f"{self.get_name()}_required"] = True
+
+        # Get tracer-specific required actions
+        required_actions = self.get_required_actions(
+            request.step_number, request.confidence or "exploring", request.findings, request.total_steps
+        )
+        response_data["required_actions"] = required_actions
+
+        # Generate step-specific guidance
+        if request.step_number == 1:
+            # Check if we're in ask mode and need to prompt for mode selection
+            if self.get_trace_mode() == "ask":
+                response_data["next_steps"] = (
+                    f"STOP! You MUST ask the user to choose a tracing mode before proceeding. "
+                    f"Present these options clearly:\\n\\n"
+                    f"**PRECISION MODE**: Traces execution flow, call chains, and usage patterns. "
+                    f"Best for understanding how a specific method or function works, what it calls, "
+                    f"and how data flows through the execution path.\\n\\n"
+                    f"**DEPENDENCIES MODE**: Maps structural relationships and bidirectional dependencies. "
+                    f"Best for understanding how a class or module relates to other components, "
+                    f"what depends on it, and what it depends on.\\n\\n"
+                    f"After the user selects a mode, call {self.get_name()} again with step_number: 1 "
+                    f"but with the chosen trace_mode (either 'precision' or 'dependencies')."
+                )
+            else:
+                response_data["next_steps"] = (
+                    f"MANDATORY: DO NOT call the {self.get_name()} tool again immediately. You MUST first investigate "
+                    f"the codebase to understand the target code. CRITICAL AWARENESS: You need to find and understand "
+                    f"the target method/function/class/module, examine its implementation, and begin mapping its "
+                    f"relationships. Use file reading tools, code search, and systematic examination to gather "
+                    f"comprehensive information about the target. Only call {self.get_name()} again AFTER completing "
+                    f"your investigation. When you call {self.get_name()} next time, use step_number: {request.step_number + 1} "
+                    f"and report specific files examined, code structure discovered, and initial relationship findings."
+                )
+        elif request.confidence in ["exploring", "low"]:
+            next_step = request.step_number + 1
+            response_data["next_steps"] = (
+                f"STOP! Do NOT call {self.get_name()} again yet. Based on your findings, you've identified areas that need "
+                f"deeper tracing analysis. MANDATORY ACTIONS before calling {self.get_name()} step {next_step}:\\n"
+                + "\\n".join(f"{i+1}. {action}" for i, action in enumerate(required_actions))
+                + f"\\n\\nOnly call {self.get_name()} again with step_number: {next_step} AFTER "
+                + "completing these tracing investigations."
+            )
+        elif request.confidence in ["medium", "high"]:
+            next_step = request.step_number + 1
+            response_data["next_steps"] = (
+                f"WAIT! Your tracing analysis needs final verification. DO NOT call {self.get_name()} immediately. "
+                f"REQUIRED ACTIONS:\\n"
+                + "\\n".join(f"{i+1}. {action}" for i, action in enumerate(required_actions))
+                + f"\\n\\nREMEMBER: Ensure you have traced all significant relationships and execution paths. "
+                f"Document findings with specific file references and method signatures, then call {self.get_name()} "
+                f"with step_number: {next_step}."
+            )
+        else:
+            # General investigation needed
+            next_step = request.step_number + 1
+            remaining_steps = request.total_steps - request.step_number
+            response_data["next_steps"] = (
+                f"Continue systematic tracing with step {next_step}. Approximately {remaining_steps} steps remaining. "
+                f"Focus on deepening your understanding of the code relationships and execution patterns."
+            )
+
+        return response_data
+
+    def customize_workflow_response(self, response_data: dict, request) -> dict:
+        """
+        Customize response to match tracer tool format with output instructions.
+        """
+        # Store trace configuration on first step
+        if request.step_number == 1:
+            self.initial_request = request.step
+            self.trace_config = {
+                "trace_mode": request.trace_mode,
+                "target_description": request.target_description,
+            }
+
+            # Update metadata with trace configuration
+            if "metadata" in response_data:
+                response_data["metadata"]["trace_mode"] = request.trace_mode or "unknown"
+                response_data["metadata"]["target_description"] = request.target_description or ""
+
+            # If in ask mode, mark this as mode selection phase
+            if request.trace_mode == "ask":
+                response_data["mode_selection_required"] = True
+                response_data["status"] = "mode_selection_required"
+
+        # Add tracer-specific output instructions for final steps
+        if not request.next_step_required:
+            response_data["tracing_complete"] = True
+            response_data["trace_summary"] = f"TRACING COMPLETE: {request.step}"
+
+            # Get mode-specific output instructions
+            trace_mode = self.trace_config.get("trace_mode", "precision")
+            rendering_instructions = self._get_rendering_instructions(trace_mode)
+
+            response_data["output"] = {
+                "instructions": (
+                    "This is a structured tracing analysis response. Present the comprehensive tracing findings "
+                    "using the specific rendering format for the trace mode. Follow the exact formatting guidelines "
+                    "provided in rendering_instructions. Include all discovered relationships, execution paths, "
+                    "and dependencies with precise file references and line numbers."
+                ),
+                "format": f"{trace_mode}_trace_analysis",
+                "rendering_instructions": rendering_instructions,
+                "presentation_guidelines": {
+                    "completed_trace": (
+                        "Use the exact rendering format specified for the trace mode. Include comprehensive "
+                        "diagrams, tables, and structured analysis. Reference specific file paths and line numbers. "
+                        "Follow formatting rules precisely."
+                    ),
+                    "step_content": "Present as main analysis with clear structure and actionable insights.",
+                    "continuation": "Use continuation_id for related tracing sessions or follow-up analysis",
+                },
+            }
+            response_data["next_steps"] = (
+                f"Tracing analysis complete. Present the comprehensive {trace_mode} trace analysis to the user "
+                f"using the exact rendering format specified in the output instructions. Follow the formatting "
+                f"guidelines precisely, including diagrams, tables, and file references. After presenting the "
+                f"analysis, offer to help with related tracing tasks or use the continuation_id for follow-up analysis."
+            )
+
+        # Convert generic status names to tracer-specific ones
+        tool_name = self.get_name()
+        status_mapping = {
+            f"{tool_name}_in_progress": "tracing_in_progress",
+            f"pause_for_{tool_name}": "pause_for_tracing",
+            f"{tool_name}_required": "tracing_required",
+            f"{tool_name}_complete": "tracing_complete",
+        }
+
+        if response_data["status"] in status_mapping:
+            response_data["status"] = status_mapping[response_data["status"]]
+
+        return response_data
+
+    def _get_rendering_instructions(self, trace_mode: str) -> str:
+        """
+        Get mode-specific rendering instructions for the CLI agent.
+
+        Args:
+            trace_mode: Either "precision" or "dependencies"
+
+        Returns:
+            str: Complete rendering instructions for the specified mode
+        """
+        if trace_mode == "precision":
+            return self._get_precision_rendering_instructions()
+        else:  # dependencies mode
+            return self._get_dependencies_rendering_instructions()
+
+    def _get_precision_rendering_instructions(self) -> str:
+        """Get rendering instructions for precision trace mode."""
+        return """
+## MANDATORY RENDERING INSTRUCTIONS FOR PRECISION TRACE
+
+You MUST render the trace analysis using ONLY the Vertical Indented Flow Style:
+
+### CALL FLOW DIAGRAM - Vertical Indented Style
+
+**EXACT FORMAT TO FOLLOW:**
+```
+[ClassName::MethodName] (file: /complete/file/path.ext, line: ##)
+↓
+[AnotherClass::calledMethod] (file: /path/to/file.ext, line: ##)
+↓
+[ThirdClass::nestedMethod] (file: /path/file.ext, line: ##)
+  ↓
+  [DeeperClass::innerCall] (file: /path/inner.ext, line: ##) ? if some_condition
+  ↓
+  [ServiceClass::processData] (file: /services/service.ext, line: ##)
+    ↓
+    [RepositoryClass::saveData] (file: /data/repo.ext, line: ##)
+    ↓
+    [ClientClass::sendRequest] (file: /clients/client.ext, line: ##)
+      ↓
+      [EmailService::sendEmail] (file: /email/service.ext, line: ##) ⚠️ ambiguous branch
+      →
+      [SMSService::sendSMS] (file: /sms/service.ext, line: ##) ⚠️ ambiguous branch
+```
+
+**CRITICAL FORMATTING RULES:**
+
+1. **Method Names**: Use the actual naming convention of the project language you're analyzing. Automatically detect and adapt to the project's conventions (camelCase, snake_case, PascalCase, etc.) based on the codebase structure and file extensions.
+
+2. **Vertical Flow Arrows**:
+   - Use `↓` for standard sequential calls (vertical flow)
+   - Use `→` for parallel/alternative calls (horizontal branch)
+   - NEVER use other arrow types
+
+3. **Indentation Logic**:
+   - Start at column 0 for entry point
+   - Indent 2 spaces for each nesting level
+   - Maintain consistent indentation for same call depth
+   - Sibling calls at same level should have same indentation
+
+4. **Conditional Calls**:
+   - Add `? if condition_description` after method for conditional execution
+   - Use actual condition names from code when possible
+
+5. **Ambiguous Branches**:
+   - Mark with `⚠️ ambiguous branch` when execution path is uncertain
+   - Use `→` to show alternative paths at same indentation level
+
+6. **File Path Format**:
+   - Use complete relative paths from project root
+   - Include actual file extensions from the project
+   - Show exact line numbers where method is defined
+
+### ADDITIONAL ANALYSIS VIEWS
+
+**1. BRANCHING & SIDE EFFECT TABLE**
+
+| Location | Condition | Branches | Uncertain |
+|----------|-----------|----------|-----------|
+| CompleteFileName.ext:## | if actual_condition_from_code | method1(), method2(), else skip | No |
+| AnotherFile.ext:## | if boolean_check | callMethod(), else return | No |
+| ThirdFile.ext:## | if validation_passes | processData(), else throw | Yes |
+
+**2. SIDE EFFECTS**
+```
+Side Effects:
+- [database] Specific database operation description (CompleteFileName.ext:##)
+- [network] Specific network call description (CompleteFileName.ext:##)
+- [filesystem] Specific file operation description (CompleteFileName.ext:##)
+- [state] State changes or property modifications (CompleteFileName.ext:##)
+- [memory] Memory allocation or cache operations (CompleteFileName.ext:##)
+```
+
+**3. USAGE POINTS**
+```
+Usage Points:
+1. FileName.ext:## - Context description of where/why it's called
+2. AnotherFile.ext:## - Context description of usage scenario
+3. ThirdFile.ext:## - Context description of calling pattern
+4. FourthFile.ext:## - Context description of integration point
+```
+
+**4. ENTRY POINTS**
+```
+Entry Points:
+- ClassName::methodName (context: where this flow typically starts)
+- AnotherClass::entryMethod (context: alternative entry scenario)
+- ThirdClass::triggerMethod (context: event-driven entry point)
+```
+
+**ABSOLUTE REQUIREMENTS:**
+- Use ONLY the vertical indented style for the call flow diagram
+- Present ALL FOUR additional analysis views (Branching Table, Side Effects, Usage Points, Entry Points)
+- Adapt method naming to match the project's programming language conventions
+- Use exact file paths and line numbers from the actual codebase
+- DO NOT invent or guess method names or locations
+- Follow indentation rules precisely for call hierarchy
+- Mark uncertain execution paths clearly
+- Provide contextual descriptions in Usage Points and Entry Points sections
+- Include comprehensive side effects categorization (database, network, filesystem, state, memory)"""
+
+    def _get_dependencies_rendering_instructions(self) -> str:
+        """Get rendering instructions for dependencies trace mode."""
+        return """
+## MANDATORY RENDERING INSTRUCTIONS FOR DEPENDENCIES TRACE
+
+You MUST render the trace analysis using ONLY the Bidirectional Arrow Flow Style:
+
+### DEPENDENCY FLOW DIAGRAM - Bidirectional Arrow Style
+
+**EXACT FORMAT TO FOLLOW:**
+```
+INCOMING DEPENDENCIES → [TARGET_CLASS/MODULE] → OUTGOING DEPENDENCIES
+
+CallerClass::callerMethod ←────┐
+AnotherCaller::anotherMethod ←─┤
+ThirdCaller::thirdMethod ←─────┤
+                               │
+                    [TARGET_CLASS/MODULE]
+                               │
+                               ├────→ FirstDependency::method
+                               ├────→ SecondDependency::method
+                               └────→ ThirdDependency::method
+
+TYPE RELATIONSHIPS:
+InterfaceName ──implements──→ [TARGET_CLASS] ──extends──→ BaseClass
+DTOClass ──uses──→ [TARGET_CLASS] ──uses──→ EntityClass
+```
+
+**CRITICAL FORMATTING RULES:**
+
+1. **Target Placement**: Always place the target class/module in square brackets `[TARGET_NAME]` at the center
+2. **Incoming Dependencies**: Show on the left side with `←` arrows pointing INTO the target
+3. **Outgoing Dependencies**: Show on the right side with `→` arrows pointing OUT FROM the target
+4. **Arrow Alignment**: Use consistent spacing and alignment for visual clarity
+5. **Method Naming**: Use the project's actual naming conventions detected from the codebase
+6. **File References**: Include complete file paths and line numbers
+
+**VISUAL LAYOUT RULES:**
+
+1. **Header Format**: Always start with the flow direction indicator
+2. **Left Side (Incoming)**:
+   - List all callers with `←` arrows
+   - Use `┐`, `┤`, `┘` box drawing characters for clean connection lines
+   - Align arrows consistently
+
+3. **Center (Target)**:
+   - Enclose target in square brackets
+   - Position centrally between incoming and outgoing
+
+4. **Right Side (Outgoing)**:
+   - List all dependencies with `→` arrows
+   - Use `├`, `└` box drawing characters for branching
+   - Maintain consistent spacing
+
+5. **Type Relationships Section**:
+   - Use `──relationship──→` format with double hyphens
+   - Show inheritance, implementation, and usage relationships
+   - Place below the main flow diagram
+
+**DEPENDENCY TABLE:**
+
+| Type | From/To | Method | File | Line |
+|------|---------|--------|------|------|
+| incoming_call | From: CallerClass | callerMethod | /complete/path/file.ext | ## |
+| outgoing_call | To: TargetClass | targetMethod | /complete/path/file.ext | ## |
+| implements | Self: ThisClass | — | /complete/path/file.ext | — |
+| extends | Self: ThisClass | — | /complete/path/file.ext | — |
+| uses_type | Self: ThisClass | — | /complete/path/file.ext | — |
+
+**ABSOLUTE REQUIREMENTS:**
+- Use ONLY the bidirectional arrow flow style shown above
+- Automatically detect and use the project's naming conventions
+- Use exact file paths and line numbers from the actual codebase
+- DO NOT invent or guess method/class names
+- Maintain visual alignment and consistent spacing
+- Include type relationships section when applicable
+- Show clear directional flow with proper arrows"""
+
+    # ================================================================================
+    # Hook Method Overrides for Tracer-Specific Behavior
+    # ================================================================================
+
+    def get_completion_status(self) -> str:
+        """Tracer uses tracing-specific status."""
+        return "tracing_complete"
+
+    def get_completion_data_key(self) -> str:
+        """Tracer uses 'complete_tracing' key."""
+        return "complete_tracing"
+
+    def get_completion_message(self) -> str:
+        """Tracer-specific completion message."""
+        return (
+            "Tracing analysis complete. Present the comprehensive trace analysis to the user "
+            "using the specified rendering format and offer to help with related tracing tasks."
+        )
+
+    def get_skip_reason(self) -> str:
+        """Tracer-specific skip reason."""
+        return "Tracer is self-contained and completes analysis without external assistance"
+
+    def get_skip_expert_analysis_status(self) -> str:
+        """Tracer-specific expert analysis skip status."""
+        return "skipped_by_tool_design"
+
+    def store_initial_issue(self, step_description: str):
+        """Store initial tracing description."""
+        self.initial_tracing_description = step_description
+
+    def get_initial_request(self, fallback_step: str) -> str:
+        """Get initial tracing description."""
+        try:
+            return self.initial_tracing_description
+        except AttributeError:
+            return fallback_step
+
+    def get_request_confidence(self, request) -> str:
+        """Get confidence from request for tracer workflow."""
+        try:
+            return request.confidence or "exploring"
+        except AttributeError:
+            return "exploring"
+
+    def get_trace_mode(self) -> str:
+        """Get current trace mode. Override for custom trace mode handling."""
+        try:
+            return self.trace_config.get("trace_mode", "ask")
+        except AttributeError:
+            return "ask"
+
+    # Required abstract methods from BaseTool
+    def get_request_model(self):
+        """Return the tracer-specific request model."""
+        return TracerRequest
+
+    async def prepare_prompt(self, request) -> str:
+        """Not used - workflow tools use execute_workflow()."""
+        return ""  # Workflow tools use execute_workflow() directly