1---2name: investigation-patterns-23description: 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.4---56<purpose>7Provide systematic patterns for codebase investigation and debugging, ensuring evidence-based analysis with proper confidence assessment.8</purpose>910<rules priority="critical">11<rule>Always provide file:line references for all findings using format path/to/file.ext:line_number</rule>12<rule>Rate confidence and coverage metrics for all investigation results</rule>13<rule>Complete investigation before proposing solutions</rule>14</rules>1516<rules priority="standard">17<rule>Use Serena symbol tools before reading entire files</rule>18<rule>Independently verify claims rather than confirming assumptions</rule>19<rule>Document information gaps and unclear points</rule>20<rule>Check multiple sources to increase confidence</rule>21<rule>Use systematic debugging phases (reproduce, isolate, investigate, hypothesize, fix)</rule>22</rules>2324<patterns>25<pattern name="scope_classification">26<description>Classify the question type to determine investigation approach</description>27<decision_tree name="when_to_use">28<question>Does the question require understanding codebase structure or behavior?</question>29<if_yes>Apply scope classification to determine investigation depth and tools</if_yes>30<if_no>Consider requirements-definition skill for unclear requirements</if_no>31</decision_tree>32<example>33Architecture: System design, component relationships34Implementation: Specific code behavior, algorithm details35Debugging: Error causes, unexpected behavior36Design: Pattern usage, code organization37</example>38</pattern>3940<pattern name="source_identification">41<description>Identify relevant sources for investigation</description>42<decision_tree name="when_to_use">43<question>Is the codebase large or unfamiliar?</question>44<if_yes>Apply source identification to locate relevant evidence efficiently</if_yes>45<if_no>Directly examine known sources</if_no>46</decision_tree>47<example>48Code: Use Serena for symbol search and dependency analysis49Documentation: Check inline comments, README, API docs50History: Git log for context on changes51External: Context7 for library documentation52</example>53</pattern>5455<pattern name="evidence_collection">56<description>Collect evidence systematically using appropriate tools</description>57<decision_tree name="when_to_use">58<question>Do you have specific symbols or patterns to investigate?</question>59<if_yes>Apply evidence collection with symbol-level tools</if_yes>60<if_no>Start with source identification to locate relevant areas</if_no>61</decision_tree>62<example>63find_symbol: Locate specific symbols by name64get_symbols_overview: Understand file structure65find_referencing_symbols: Trace dependencies66search_for_pattern: Find patterns across codebase67</example>68</pattern>6970<pattern name="synthesis">71<description>Synthesize findings with confidence metrics</description>72<decision_tree name="when_to_use">73<question>Have you collected sufficient evidence from multiple sources?</question>74<if_yes>Apply synthesis to combine findings with confidence metrics</if_yes>75<if_no>Continue evidence collection to increase coverage</if_no>76</decision_tree>77<example>78Combine evidence from multiple sources79Rate confidence based on evidence quality (0-100)80Report coverage of relevant code examined (0-100)81Identify and document information gaps82</example>83</pattern>8485<pattern name="reproduce">86<description>Confirm the issue is reproducible</description>87<decision_tree name="when_to_use">88<question>Is this a bug or unexpected behavior investigation?</question>89<if_yes>Apply reproduce pattern to confirm issue before debugging</if_yes>90<if_no>Use other investigation patterns for analysis tasks</if_no>91</decision_tree>92<example>93Gather exact steps to reproduce94Identify environment conditions95Determine consistency (always/sometimes fails)96</example>97</pattern>9899<pattern name="isolate">100<description>Narrow down the problem scope</description>101<decision_tree name="when_to_use">102<question>Is the bug reproducible but involves many components?</question>103<if_yes>Apply isolate pattern to narrow down the problem scope</if_yes>104<if_no>Proceed to investigate pattern if scope is clear</if_no>105</decision_tree>106<example>107Identify when issue started (git bisect if needed)108Remove unrelated components109Create minimal reproduction case110</example>111</pattern>112113<pattern name="investigate">114<description>Collect evidence systematically for debugging</description>115<decision_tree name="when_to_use">116<question>Has the issue been reproduced and isolated?</question>117<if_yes>Apply investigate pattern to collect debugging evidence</if_yes>118<if_no>Complete reproduce and isolate patterns first</if_no>119</decision_tree>120<example>121Examine error messages and stack traces122Check logs at relevant timestamps123Use Serena for code path analysis124Trace data flow through the system125</example>126</pattern>127128<pattern name="hypothesize">129<description>Form and test hypotheses</description>130<decision_tree name="when_to_use">131<question>Have you collected sufficient debugging evidence?</question>132<if_yes>Apply hypothesize pattern to form and test root cause theories</if_yes>133<if_no>Continue investigate pattern to gather more evidence</if_no>134</decision_tree>135<example>136List possible causes137Rank by likelihood138Design tests to confirm/refute each139</example>140</pattern>141142<pattern name="fix">143<description>Implement and verify solution</description>144<decision_tree name="when_to_use">145<question>Has a hypothesis been confirmed as the root cause?</question>146<if_yes>Apply fix pattern to implement and verify solution</if_yes>147<if_no>Continue hypothesize pattern to test other theories</if_no>148</decision_tree>149<example>150Make minimal targeted change151Verify fix resolves the issue152Check for regressions153Add test to prevent recurrence154</example>155</pattern>156</patterns>157158<workflow>159<phase name="observe">160<objective>Gather initial observations</objective>161<step>1. Document the symptom or question clearly</step>162<step>2. Identify relevant entry points for investigation</step>163<step>3. Form initial hypotheses</step>164</phase>165<phase name="investigate">166<objective>Systematically explore evidence</objective>167<step>1. Use Serena tools to trace code paths</step>168<step>2. Build evidence chain from symptom to cause</step>169<step>3. Validate or invalidate hypotheses</step>170</phase>171<phase name="conclude">172<objective>Form evidence-based conclusions</objective>173<step>1. Synthesize findings into coherent explanation</step>174<step>2. Rate confidence based on evidence quality</step>175<step>3. Document for future reference</step>176</phase>177</workflow>178179<error_escalation>180<level severity="low">181<example>Evidence trail incomplete</example>182<action>Note in report, proceed</action>183</level>184<level severity="medium">185<example>Conflicting evidence found</example>186<action>Document issue, use AskUserQuestion for clarification</action>187</level>188<level severity="high">189<example>Root cause cannot be determined</example>190<action>STOP, present options to user</action>191</level>192<level severity="critical">193<example>Investigation reveals security issue</example>194<action>BLOCK operation, require explicit user acknowledgment</action>195</level>196</error_escalation>197198<constraints>199<must>Build evidence chains before conclusions</must>200<must>Cite specific file:line references</must>201<must>State confidence levels explicitly</must>202<avoid>Speculation without evidence</avoid>203<avoid>Confirmation bias in hypothesis testing</avoid>204<avoid>Concluding without exploring alternatives</avoid>205</constraints>206207<tools>208<tool name="find_symbol">209<description>Locate specific symbols by name in the codebase</description>210<param name="name_path_pattern">Pattern to match symbol names</param>211<param name="relative_path">Optional path to restrict search</param>212<param name="depth">Depth to retrieve children (default 0)</param>213<use_case>Finding class, function, or variable definitions</use_case>214</tool>215216<tool name="get_symbols_overview">217<description>Get high-level structure of a file</description>218<param name="relative_path">Path to file to analyze</param>219<param name="depth">Depth of symbol tree (default 0)</param>220<use_case>Understanding file organization before detailed investigation</use_case>221</tool>222223<tool name="find_referencing_symbols">224<description>Find all references to a symbol</description>225<param name="name_path">Symbol to find references for</param>226<param name="relative_path">File containing the symbol</param>227<use_case>Tracing dependencies and usage patterns</use_case>228</tool>229230<tool name="search_for_pattern">231<description>Search for regex patterns across codebase</description>232<param name="substring_pattern">Regular expression to search</param>233<param name="relative_path">Optional path to restrict search</param>234<param name="restrict_search_to_code_files">Limit to code files</param>235<use_case>Finding specific patterns or usage across files</use_case>236</tool>237</tools>238239<concepts>240<concept name="evidence_standards">241<description>Standards for collecting and reporting evidence</description>242<example>243Citation: Always provide file:line references (path/to/file.ext:line_number)244245Confidence levels:246247- 90-100: Direct code evidence, explicit documentation248- 70-89: Strong inference from multiple sources249- 50-69: Reasonable inference with some gaps250- 0-49: Speculation, insufficient evidence251252Coverage levels:253254- 90-100: All relevant files examined255- 70-89: Most relevant files examined256- 50-69: Key files examined, some gaps257- 0-49: Limited examination258 </example>259 </concept>260261<concept name="null_reference">262<description>Null pointer or undefined reference errors</description>263<example>264Symptom: NullPointerException, undefined is not a function265Investigation: Check all paths to the null access266Fix: Add null checks or ensure initialization267</example>268</concept>269270<concept name="race_condition">271<description>Concurrent access issues</description>272<example>273Symptom: Intermittent failures, works sometimes274Investigation: Look for shared mutable state, async operations275Fix: Add synchronization or redesign for immutability276</example>277</concept>278279<concept name="off_by_one">280<description>Boundary condition errors</description>281<example>282Symptom: Missing first/last element, index out of bounds283Investigation: Check loop boundaries and index calculations284Fix: Verify start/end conditions, use inclusive/exclusive correctly285</example>286</concept>287288<concept name="resource_leak">289<description>Unclosed resources accumulating over time</description>290<example>291Symptom: Memory growth, connection exhaustion292Investigation: Check resource acquisition and release paths293Fix: Ensure cleanup in finally/defer, use resource management patterns294</example>295</concept>296297<concept name="encoding_issue">298<description>Character encoding mismatches</description>299<example>300Symptom: Garbled text, unexpected characters301Investigation: Trace encoding at each transformation step302Fix: Ensure consistent encoding throughout pipeline303</example>304</concept>305306<concept name="five_whys">307<description>Ask "why" repeatedly to drill to root cause</description>308<example>309Why did the server crash? - Out of memory310Why out of memory? - Connection pool exhausted311Why exhausted? - Connections not being released312Why not released? - Exception bypasses cleanup313Root cause: Missing try-finally for connection release314</example>315</concept>316317<concept name="timeline_analysis">318<description>Reconstruct sequence of events leading to failure</description>319<example>320Collect timestamps from logs321Order events chronologically322Identify divergence from expected behavior323</example>324</concept>325326<concept name="investigation_output">327<description>Standard format for investigation results</description>328<example>329<question>Restate the question for confirmation</question>330<investigation>Evidence-based findings with file:line references331- Source 1: path/to/file.ts:42 - finding description332- Source 2: path/to/other.ts:15 - finding description</investigation>333<conclusion>Direct answer based on evidence</conclusion>334<metrics>335- Confidence: 0-100336- Evidence Coverage: 0-100</metrics>337<recommendations>Suggested actions without implementation</recommendations>338<unclear_points>Information gaps that would improve the answer</unclear_points>339</example>340</concept>341342<concept name="debugging_output">343<description>Standard format for debugging results</description>344<example>345<problem_statement>Clear description of the issue</problem_statement>346<reproduction_steps>How to reproduce</reproduction_steps>347<investigation>Evidence collected with file:line references</investigation>348<root_cause>Identified cause with supporting evidence</root_cause>349<solution>Proposed fix with rationale</solution>350<verification>How to verify the fix works</verification>351<prevention>How to prevent recurrence</prevention>352</example>353</concept>354</concepts>355356<related_agents>357<agent name="bug">Use for root cause investigation when user reports bugs or errors</agent>358<agent name="ask">Use for answering questions about codebase architecture and implementation</agent>359<agent name="execute">Delegate to after investigation confirms implementation approach</agent>360</related_agents>361362<related_skills>363<skill name="serena-usage">Use for memory operations and symbol-level code navigation</skill>364<skill name="execution-workflow">Use after investigation to implement fixes with proper delegation</skill>365<skill name="fact-check">Use to verify external documentation and library behavior</skill>366<skill name="testing-patterns">Use to add regression tests after fixing identified bugs</skill>367<skill name="requirements-definition">Use when investigation reveals unclear requirements</skill>368</related_skills>369370<anti_patterns>371<avoid name="speculation">372<description>Guessing or making claims when evidence is insufficient</description>373<instead>Clearly state confidence levels and information gaps; request additional context if needed</instead>374</avoid>375376<avoid name="confirming_assumptions">377<description>Confirming user assumptions without independent verification</description>378<instead>Independently verify claims by examining code and collecting evidence</instead>379</avoid>380381<avoid name="uncited_claims">382<description>Making claims without file:line references</description>383<instead>Always provide file:line citations for findings using format path/to/file.ext:line_number</instead>384</avoid>385386<avoid name="premature_implementation">387<description>Implementing fixes instead of completing analysis</description>388<instead>Focus on investigation and analysis; provide recommendations without implementation</instead>389</avoid>390</anti_patterns>391392<best_practices>393<practice priority="critical">Always provide file:line references for all findings using format path/to/file.ext:line_number</practice>394<practice priority="critical">Rate confidence and coverage metrics for all investigation results</practice>395<practice priority="critical">Complete investigation before proposing solutions</practice>396<practice priority="high">Use Serena symbol tools before reading entire files</practice>397<practice priority="high">Independently verify claims rather than confirming assumptions</practice>398<practice priority="high">Document information gaps and unclear points</practice>399<practice priority="medium">Check multiple sources to increase confidence</practice>400<practice priority="medium">Use systematic debugging phases (reproduce, isolate, investigate, hypothesize, fix)</practice>401</best_practices>
majiayu000