investigation-patterns

name	Investigation Patterns
description	This skill should be used when the user asks to "investigate code", "analyze implementation", "find patterns", "understand codebase", "debug issue", "find bug", "troubleshoot", or needs evidence-based code analysis and debugging. Provides systematic investigation and debugging methodology.

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

<error_escalation> Evidence trail incomplete Note in report, proceed Conflicting evidence found Document issue, use AskUserQuestion for clarification Root cause cannot be determined STOP, present options to user Investigation reveals security issue BLOCK operation, require explicit user acknowledgment </error_escalation>

Build evidence chains before conclusions Cite specific file:line references State confidence levels explicitly Speculation without evidence Confirmation bias in hypothesis testing Concluding without exploring alternatives Locate specific symbols by name in the codebase Pattern to match symbol names Optional path to restrict search Depth to retrieve children (default 0) Finding class, function, or variable definitions Get high-level structure of a file Path to file to analyze Depth of symbol tree (default 0) Understanding file organization before detailed investigation Find all references to a symbol Symbol to find references for File containing the symbol Tracing dependencies and usage patterns Search for regex patterns across codebase Regular expression to search Optional path to restrict search Limit to code files Finding specific patterns or usage across files Standards for collecting and reporting evidence 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>

Null pointer or undefined reference errors Symptom: NullPointerException, undefined is not a function Investigation: Check all paths to the null access Fix: Add null checks or ensure initialization Concurrent access issues Symptom: Intermittent failures, works sometimes Investigation: Look for shared mutable state, async operations Fix: Add synchronization or redesign for immutability Boundary condition errors 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 Unclosed resources accumulating over time Symptom: Memory growth, connection exhaustion Investigation: Check resource acquisition and release paths Fix: Ensure cleanup in finally/defer, use resource management patterns Character encoding mismatches Symptom: Garbled text, unexpected characters Investigation: Trace encoding at each transformation step Fix: Ensure consistent encoding throughout pipeline Ask "why" repeatedly to drill to root cause 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 Reconstruct sequence of events leading to failure Collect timestamps from logs Order events chronologically Identify divergence from expected behavior Standard format for investigation results Restate the question for confirmation 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 Direct answer based on evidence - Confidence: 0-100 - Evidence Coverage: 0-100 Suggested actions without implementation Information gaps that would improve the answer Standard format for debugging results Clear description of the issue How to reproduce Evidence collected with file:line references Identified cause with supporting evidence Proposed fix with rationale How to verify the fix works How to prevent recurrence

<related_agents> Use for root cause investigation when user reports bugs or errors Use for answering questions about codebase architecture and implementation Delegate to after investigation confirms implementation approach </related_agents>

<related_skills> Use for memory operations and symbol-level code navigation Use after investigation to implement fixes with proper delegation Use to verify external documentation and library behavior Use to add regression tests after fixing identified bugs Use when investigation reveals unclear requirements </related_skills>

<anti_patterns> Guessing or making claims when evidence is insufficient Clearly state confidence levels and information gaps; request additional context if needed

Confirming user assumptions without independent verification Independently verify claims by examining code and collecting evidence Making claims without file:line references Always provide file:line citations for findings using format path/to/file.ext:line_number Implementing fixes instead of completing analysis Focus on investigation and analysis; provide recommendations without implementation

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