Investigation Patterns

<purpose> Provide systematic patterns for codebase investigation and debugging, ensuring evidence-based analysis with proper confidence assessment. </​purpose> <rules priority="critical"> <rule>Always provide file:line references for all findings using format path/​to/​file.ext:line_number</​rule> <rule>Rate confidence and coverage metrics for all investigation results</​rule> <rule>Complete investigation before proposing solutions</​rule> </​rules> <rules priority="standard"> <rule>Use Serena symbol tools before reading entire files</​rule> <rule>Independently verify claims rather than confirming assumptions</​rule> <rule>Document information gaps and unclear points</​rule> <rule>Check multiple sources to increase confidence</​rule> <rule>Use systematic debugging phases (reproduce, isolate, investigate, hypothesize, fix)</​rule> </​rules> <patterns> <pattern name="scope_classification"> <description>Classify the question type to determine investigation approach</​description> <decision_tree name="when_to_use"> <question>Does the question require understanding codebase structure or behavior?</​question> <if_yes>Apply scope classification to determine investigation depth and tools</​if_yes> <if_no>Consider requirements-definition skill for unclear requirements</​if_no> </​decision_tree> <example> Architecture: System design, component relationships Implementation: Specific code behavior, algorithm details Debugging: Error causes, unexpected behavior Design: Pattern usage, code organization </​example> </​pattern> <pattern name="source_identification"> <description>Identify relevant sources for investigation</​description> <decision_tree name="when_to_use"> <question>Is the codebase large or unfamiliar?</​question> <if_yes>Apply source identification to locate relevant evidence efficiently</​if_yes> <if_no>Directly examine known sources</​if_no> </​decision_tree> <example> Code: Use Serena for symbol search and dependency analysis Documentation: Check inline comments, README, API docs History: Git log for context on changes External: Context7 for library documentation </​example> </​pattern> <pattern name="evidence_collection"> <description>Collect evidence systematically using appropriate tools</​description> <decision_tree name="when_to_use"> <question>Do you have specific symbols or patterns to investigate?</​question> <if_yes>Apply evidence collection with symbol-level tools</​if_yes> <if_no>Start with source identification to locate relevant areas</​if_no> </​decision_tree> <example> find_symbol: Locate specific symbols by name get_symbols_overview: Understand file structure find_referencing_symbols: Trace dependencies search_for_pattern: Find patterns across codebase </​example> </​pattern> <pattern name="synthesis"> <description>Synthesize findings with confidence metrics</​description> <decision_tree name="when_to_use"> <question>Have you collected sufficient evidence from multiple sources?</​question> <if_yes>Apply synthesis to combine findings with confidence metrics</​if_yes> <if_no>Continue evidence collection to increase coverage</​if_no> </​decision_tree> <example> Combine evidence from multiple sources Rate confidence based on evidence quality (0-100) Report coverage of relevant code examined (0-100) Identify and document information gaps </​example> </​pattern> <pattern name="reproduce"> <description>Confirm the issue is reproducible</​description> <decision_tree name="when_to_use"> <question>Is this a bug or unexpected behavior investigation?</​question> <if_yes>Apply reproduce pattern to confirm issue before debugging</​if_yes> <if_no>Use other investigation patterns for analysis tasks</​if_no> </​decision_tree> <example> Gather exact steps to reproduce Identify environment conditions Determine consistency (always/​sometimes fails) </​example> </​pattern> <pattern name="isolate"> <description>Narrow down the problem scope</​description> <decision_tree name="when_to_use"> <question>Is the bug reproducible but involves many components?</​question> <if_yes>Apply isolate pattern to narrow down the problem scope</​if_yes> <if_no>Proceed to investigate pattern if scope is clear</​if_no> </​decision_tree> <example> Identify when issue started (git bisect if needed) Remove unrelated components Create minimal reproduction case </​example> </​pattern> <pattern name="investigate"> <description>Collect evidence systematically for debugging</​description> <decision_tree name="when_to_use"> <question>Has the issue been reproduced and isolated?</​question> <if_yes>Apply investigate pattern to collect debugging evidence</​if_yes> <if_no>Complete reproduce and isolate patterns first</​if_no> </​decision_tree> <example> Examine error messages and stack traces Check logs at relevant timestamps Use Serena for code path analysis Trace data flow through the system </​example> </​pattern> <pattern name="hypothesize"> <description>Form and test hypotheses</​description> <decision_tree name="when_to_use"> <question>Have you collected sufficient debugging evidence?</​question> <if_yes>Apply hypothesize pattern to form and test root cause theories</​if_yes> <if_no>Continue investigate pattern to gather more evidence</​if_no> </​decision_tree> <example> List possible causes Rank by likelihood Design tests to confirm/​refute each </​example> </​pattern> <pattern name="fix"> <description>Implement and verify solution</​description> <decision_tree name="when_to_use"> <question>Has a hypothesis been confirmed as the root cause?</​question> <if_yes>Apply fix pattern to implement and verify solution</​if_yes> <if_no>Continue hypothesize pattern to test other theories</​if_no> </​decision_tree> <example> Make minimal targeted change Verify fix resolves the issue Check for regressions Add test to prevent recurrence </​example> </​pattern> </​patterns> <workflow> <phase name="observe"> <objective>Gather initial observations</​objective> <step>1. Document the symptom or question clearly</​step> <step>2. Identify relevant entry points for investigation</​step> <step>3. Form initial hypotheses</​step> </​phase> <phase name="investigate"> <objective>Systematically explore evidence</​objective> <step>1. Use Serena tools to trace code paths</​step> <step>2. Build evidence chain from symptom to cause</​step> <step>3. Validate or invalidate hypotheses</​step> </​phase> <phase name="conclude"> <objective>Form evidence-based conclusions</​objective> <step>1. Synthesize findings into coherent explanation</​step> <step>2. Rate confidence based on evidence quality</​step> <step>3. Document for future reference</​step> </​phase> </​workflow>

<error_escalation> <level severity="low"> <example>Evidence trail incomplete</​example> <action>Note in report, proceed</​action> </​level> <level severity="medium"> <example>Conflicting evidence found</​example> <action>Document issue, use AskUserQuestion for clarification</​action> </​level> <level severity="high"> <example>Root cause cannot be determined</​example> <action>STOP, present options to user</​action> </​level> <level severity="critical"> <example>Investigation reveals security issue</​example> <action>BLOCK operation, require explicit user acknowledgment</​action> </​level> </​error_escalation>

<constraints> <must>Build evidence chains before conclusions</​must> <must>Cite specific file:line references</​must> <must>State confidence levels explicitly</​must> <avoid>Speculation without evidence</​avoid> <avoid>Confirmation bias in hypothesis testing</​avoid> <avoid>Concluding without exploring alternatives</​avoid> </​constraints> <tools> <tool name="find_symbol"> <description>Locate specific symbols by name in the codebase</​description> <param name="name_path_pattern">Pattern to match symbol names</​param> <param name="relative_path">Optional path to restrict search</​param> <param name="depth">Depth to retrieve children (default 0)</​param> <use_case>Finding class, function, or variable definitions</​use_case> </​tool> <tool name="get_symbols_overview"> <description>Get high-level structure of a file</​description> <param name="relative_path">Path to file to analyze</​param> <param name="depth">Depth of symbol tree (default 0)</​param> <use_case>Understanding file organization before detailed investigation</​use_case> </​tool> <tool name="find_referencing_symbols"> <description>Find all references to a symbol</​description> <param name="name_path">Symbol to find references for</​param> <param name="relative_path">File containing the symbol</​param> <use_case>Tracing dependencies and usage patterns</​use_case> </​tool> <tool name="search_for_pattern"> <description>Search for regex patterns across codebase</​description> <param name="substring_pattern">Regular expression to search</​param> <param name="relative_path">Optional path to restrict search</​param> <param name="restrict_search_to_code_files">Limit to code files</​param> <use_case>Finding specific patterns or usage across files</​use_case> </​tool> </​tools> <concepts> <concept name="evidence_standards"> <description>Standards for collecting and reporting evidence</​description> <example> Citation: Always provide file:line references (path/​to/​file.ext:line_number)

  Confidence levels:

  - 90-100: Direct code evidence, explicit documentation
  - 70-89: Strong inference from multiple sources
  - 50-69: Reasonable inference with some gaps
  - 0-49: Speculation, insufficient evidence

  Coverage levels:

  - 90-100: All relevant files examined
  - 70-89: Most relevant files examined
  - 50-69: Key files examined, some gaps
  - 0-49: Limited examination
</​example>

</​concept>

<concept name="null_reference"> <description>Null pointer or undefined reference errors</​description> <example> Symptom: NullPointerException, undefined is not a function Investigation: Check all paths to the null access Fix: Add null checks or ensure initialization </​example> </​concept> <concept name="race_condition"> <description>Concurrent access issues</​description> <example> Symptom: Intermittent failures, works sometimes Investigation: Look for shared mutable state, async operations Fix: Add synchronization or redesign for immutability </​example> </​concept> <concept name="off_by_one"> <description>Boundary condition errors</​description> <example> Symptom: Missing first/​last element, index out of bounds Investigation: Check loop boundaries and index calculations Fix: Verify start/​end conditions, use inclusive/​exclusive correctly </​example> </​concept> <concept name="resource_leak"> <description>Unclosed resources accumulating over time</​description> <example> Symptom: Memory growth, connection exhaustion Investigation: Check resource acquisition and release paths Fix: Ensure cleanup in finally/​defer, use resource management patterns </​example> </​concept> <concept name="encoding_issue"> <description>Character encoding mismatches</​description> <example> Symptom: Garbled text, unexpected characters Investigation: Trace encoding at each transformation step Fix: Ensure consistent encoding throughout pipeline </​example> </​concept> <concept name="five_whys"> <description>Ask "why" repeatedly to drill to root cause</​description> <example> Why did the server crash? - Out of memory Why out of memory? - Connection pool exhausted Why exhausted? - Connections not being released Why not released? - Exception bypasses cleanup Root cause: Missing try-finally for connection release </​example> </​concept> <concept name="timeline_analysis"> <description>Reconstruct sequence of events leading to failure</​description> <example> Collect timestamps from logs Order events chronologically Identify divergence from expected behavior </​example> </​concept> <concept name="investigation_output"> <description>Standard format for investigation results</​description> <example> <question>Restate the question for confirmation</​question> <investigation>Evidence-based findings with file:line references - Source 1: path/​to/​file.ts:42 - finding description - Source 2: path/​to/​other.ts:15 - finding description</​investigation> <conclusion>Direct answer based on evidence</​conclusion> <metrics> - Confidence: 0-100 - Evidence Coverage: 0-100</​metrics> <recommendations>Suggested actions without implementation</​recommendations> <unclear_points>Information gaps that would improve the answer</​unclear_points> </​example> </​concept> <concept name="debugging_output"> <description>Standard format for debugging results</​description> <example> <problem_statement>Clear description of the issue</​problem_statement> <reproduction_steps>How to reproduce</​reproduction_steps> <investigation>Evidence collected with file:line references</​investigation> <root_cause>Identified cause with supporting evidence</​root_cause> <solution>Proposed fix with rationale</​solution> <verification>How to verify the fix works</​verification> <prevention>How to prevent recurrence</​prevention> </​example> </​concept> </​concepts>

<related_agents> <agent name="bug">Use for root cause investigation when user reports bugs or errors</​agent> <agent name="ask">Use for answering questions about codebase architecture and implementation</​agent> <agent name="execute">Delegate to after investigation confirms implementation approach</​agent> </​related_agents>

<related_skills> <skill name="serena-usage">Use for memory operations and symbol-level code navigation</​skill> <skill name="execution-workflow">Use after investigation to implement fixes with proper delegation</​skill> <skill name="fact-check">Use to verify external documentation and library behavior</​skill> <skill name="testing-patterns">Use to add regression tests after fixing identified bugs</​skill> <skill name="requirements-definition">Use when investigation reveals unclear requirements</​skill> </​related_skills>

<anti_patterns> <avoid name="speculation"> <description>Guessing or making claims when evidence is insufficient</​description> <instead>Clearly state confidence levels and information gaps; request additional context if needed</​instead> </​avoid>

<avoid name="confirming_assumptions"> <description>Confirming user assumptions without independent verification</​description> <instead>Independently verify claims by examining code and collecting evidence</​instead> </​avoid> <avoid name="uncited_claims"> <description>Making claims without file:line references</​description> <instead>Always provide file:line citations for findings using format path/​to/​file.ext:line_number</​instead> </​avoid> <avoid name="premature_implementation"> <description>Implementing fixes instead of completing analysis</​description> <instead>Focus on investigation and analysis; provide recommendations without implementation</​instead> </​avoid> </​anti_patterns>

<best_practices> <practice priority="critical">Always provide file:line references for all findings using format path/​to/​file.ext:line_number</​practice> <practice priority="critical">Rate confidence and coverage metrics for all investigation results</​practice> <practice priority="critical">Complete investigation before proposing solutions</​practice> <practice priority="high">Use Serena symbol tools before reading entire files</​practice> <practice priority="high">Independently verify claims rather than confirming assumptions</​practice> <practice priority="high">Document information gaps and unclear points</​practice> <practice priority="medium">Check multiple sources to increase confidence</​practice> <practice priority="medium">Use systematic debugging phases (reproduce, isolate, investigate, hypothesize, fix)</​practice> </​best_practices>