1---2name: investigation-patterns3description: 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. Use when this capability is needed.4---56<purpose>7Provide systematic patterns for codebase investigation and debugging, ensuring evidence-based analysis with proper confidence assessment.8</purpose>910<patterns>11<pattern name="scope_classification">12<description>Classify the question type to determine investigation approach</description>13<example>14Architecture: System design, component relationships15Implementation: Specific code behavior, algorithm details16Debugging: Error causes, unexpected behavior17Design: Pattern usage, code organization18</example>19</pattern>2021<pattern name="source_identification">22<description>Identify relevant sources for investigation</description>23<example>24Code: Use Serena for symbol search and dependency analysis25Documentation: Check inline comments, README, API docs26History: Git log for context on changes27External: Context7 for library documentation28</example>29</pattern>3031<pattern name="evidence_collection">32<description>Collect evidence systematically using appropriate tools</description>33<example>34find_symbol: Locate specific symbols by name35get_symbols_overview: Understand file structure36find_referencing_symbols: Trace dependencies37search_for_pattern: Find patterns across codebase38</example>39</pattern>4041<pattern name="synthesis">42<description>Synthesize findings with confidence metrics</description>43<example>44Combine evidence from multiple sources45Rate confidence based on evidence quality (0-100)46Report coverage of relevant code examined (0-100)47Identify and document information gaps48</example>49</pattern>5051<pattern name="reproduce">52<description>Confirm the issue is reproducible</description>53<example>54Gather exact steps to reproduce55Identify environment conditions56Determine consistency (always/sometimes fails)57</example>58</pattern>5960<pattern name="isolate">61<description>Narrow down the problem scope</description>62<example>63Identify when issue started (git bisect if needed)64Remove unrelated components65Create minimal reproduction case66</example>67</pattern>6869<pattern name="investigate">70<description>Collect evidence systematically for debugging</description>71<example>72Examine error messages and stack traces73Check logs at relevant timestamps74Use Serena for code path analysis75Trace data flow through the system76</example>77</pattern>7879<pattern name="hypothesize">80<description>Form and test hypotheses</description>81<example>82List possible causes83Rank by likelihood84Design tests to confirm/refute each85</example>86</pattern>8788<pattern name="fix">89<description>Implement and verify solution</description>90<example>91Make minimal targeted change92Verify fix resolves the issue93Check for regressions94Add test to prevent recurrence95</example>96</pattern>97</patterns>9899<tools>100<tool name="find_symbol">101<description>Locate specific symbols by name in the codebase</description>102<param name="name_path_pattern">Pattern to match symbol names</param>103<param name="relative_path">Optional path to restrict search</param>104<param name="depth">Depth to retrieve children (default 0)</param>105<use_case>Finding class, function, or variable definitions</use_case>106</tool>107108<tool name="get_symbols_overview">109<description>Get high-level structure of a file</description>110<param name="relative_path">Path to file to analyze</param>111<param name="depth">Depth of symbol tree (default 0)</param>112<use_case>Understanding file organization before detailed investigation</use_case>113</tool>114115<tool name="find_referencing_symbols">116<description>Find all references to a symbol</description>117<param name="name_path">Symbol to find references for</param>118<param name="relative_path">File containing the symbol</param>119<use_case>Tracing dependencies and usage patterns</use_case>120</tool>121122<tool name="search_for_pattern">123<description>Search for regex patterns across codebase</description>124<param name="substring_pattern">Regular expression to search</param>125<param name="relative_path">Optional path to restrict search</param>126<param name="restrict_search_to_code_files">Limit to code files</param>127<use_case>Finding specific patterns or usage across files</use_case>128</tool>129</tools>130131<concepts>132<concept name="evidence_standards">133<description>Standards for collecting and reporting evidence</description>134<example>135Citation: Always provide file:line references (path/to/file.ext:line_number)136137Confidence levels:138139- 90-100: Direct code evidence, explicit documentation140- 70-89: Strong inference from multiple sources141- 50-69: Reasonable inference with some gaps142- 0-49: Speculation, insufficient evidence143144Coverage levels:145146- 90-100: All relevant files examined147- 70-89: Most relevant files examined148- 50-69: Key files examined, some gaps149- 0-49: Limited examination150 </example>151 </concept>152153<concept name="null_reference">154<description>Null pointer or undefined reference errors</description>155<example>156Symptom: NullPointerException, undefined is not a function157Investigation: Check all paths to the null access158Fix: Add null checks or ensure initialization159</example>160</concept>161162<concept name="race_condition">163<description>Concurrent access issues</description>164<example>165Symptom: Intermittent failures, works sometimes166Investigation: Look for shared mutable state, async operations167Fix: Add synchronization or redesign for immutability168</example>169</concept>170171<concept name="off_by_one">172<description>Boundary condition errors</description>173<example>174Symptom: Missing first/last element, index out of bounds175Investigation: Check loop boundaries and index calculations176Fix: Verify start/end conditions, use inclusive/exclusive correctly177</example>178</concept>179180<concept name="resource_leak">181<description>Unclosed resources accumulating over time</description>182<example>183Symptom: Memory growth, connection exhaustion184Investigation: Check resource acquisition and release paths185Fix: Ensure cleanup in finally/defer, use resource management patterns186</example>187</concept>188189<concept name="encoding_issue">190<description>Character encoding mismatches</description>191<example>192Symptom: Garbled text, unexpected characters193Investigation: Trace encoding at each transformation step194Fix: Ensure consistent encoding throughout pipeline195</example>196</concept>197198<concept name="five_whys">199<description>Ask "why" repeatedly to drill to root cause</description>200<example>201Why did the server crash? - Out of memory202Why out of memory? - Connection pool exhausted203Why exhausted? - Connections not being released204Why not released? - Exception bypasses cleanup205Root cause: Missing try-finally for connection release206</example>207</concept>208209<concept name="timeline_analysis">210<description>Reconstruct sequence of events leading to failure</description>211<example>212Collect timestamps from logs213Order events chronologically214Identify divergence from expected behavior215</example>216</concept>217218<concept name="investigation_output">219<description>Standard format for investigation results</description>220<example>221<question>Restate the question for confirmation</question>222<investigation>Evidence-based findings with file:line references223- Source 1: path/to/file.ts:42 - finding description224- Source 2: path/to/other.ts:15 - finding description</investigation>225<conclusion>Direct answer based on evidence</conclusion>226<metrics>227- Confidence: 0-100228- Evidence Coverage: 0-100</metrics>229<recommendations>Suggested actions without implementation</recommendations>230<unclear_points>Information gaps that would improve the answer</unclear_points>231</example>232</concept>233234<concept name="debugging_output">235<description>Standard format for debugging results</description>236<example>237<problem_statement>Clear description of the issue</problem_statement>238<reproduction_steps>How to reproduce</reproduction_steps>239<investigation>Evidence collected with file:line references</investigation>240<root_cause>Identified cause with supporting evidence</root_cause>241<solution>Proposed fix with rationale</solution>242<verification>How to verify the fix works</verification>243<prevention>How to prevent recurrence</prevention>244</example>245</concept>246</concepts>247248<anti_patterns>249<avoid name="speculation">250<description>Guessing or making claims when evidence is insufficient</description>251<instead>Clearly state confidence levels and information gaps; request additional context if needed</instead>252</avoid>253254<avoid name="confirming_assumptions">255<description>Confirming user assumptions without independent verification</description>256<instead>Independently verify claims by examining code and collecting evidence</instead>257</avoid>258259<avoid name="uncited_claims">260<description>Making claims without file:line references</description>261<instead>Always provide file:line citations for findings using format path/to/file.ext:line_number</instead>262</avoid>263264<avoid name="premature_implementation">265<description>Implementing fixes instead of completing analysis</description>266<instead>Focus on investigation and analysis; provide recommendations without implementation</instead>267</avoid>268</anti_patterns>269270<best_practices>271<practice priority="critical">Always provide file:line references for all findings using format path/to/file.ext:line_number</practice>272<practice priority="critical">Rate confidence and coverage metrics for all investigation results</practice>273<practice priority="critical">Complete investigation before proposing solutions</practice>274<practice priority="high">Use Serena symbol tools before reading entire files</practice>275<practice priority="high">Independently verify claims rather than confirming assumptions</practice>276<practice priority="high">Document information gaps and unclear points</practice>277<practice priority="medium">Check multiple sources to increase confidence</practice>278<practice priority="medium">Use systematic debugging phases (reproduce, isolate, investigate, hypothesize, fix)</practice>279</best_practices>280281---282> Converted and distributed by [TomeVault](https://tomevault.io/claim/mtaku3) — claim your Tome and manage your conversions.283<!-- tomevault:4.0:skill_md:2026-04-13 -->
tomevault-io