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>