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.
version	0.2.0

Provide systematic patterns for codebase investigation and debugging, ensuring evidence-based analysis with proper confidence assessment. Classify the question type to determine investigation approach 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 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 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 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 Gather exact steps to reproduce Identify environment conditions Determine consistency (always/sometimes fails) Narrow down the problem scope Identify when issue started (git bisect if needed) Remove unrelated components Create minimal reproduction case Collect evidence systematically for debugging 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 List possible causes Rank by likelihood Design tests to confirm/refute each Implement and verify solution Make minimal targeted change Verify fix resolves the issue Check for regressions Add test to prevent recurrence 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

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

<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>