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	2.1.0

Provide systematic patterns for codebase investigation and debugging, ensuring evidence-based analysis with proper confidence assessment. 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 (use Bash grep or Glob) Regular expression to search Optional path to restrict search scope Finding specific patterns or usage across files; follow up with Serena find_symbol or find_referencing_symbols for navigation 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 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 Grep: 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 Before adding a feature to an unfamiliar codebase, produce a written architecture analysis that turns exploration into a concrete integration plan. This is the deliverable of the investigation and precedes any implementation. Prefer reusing an existing abstraction over inventing one. If the existing abstraction is fundamentally incompatible with the new requirement, say so explicitly and justify a rewrite rather than forcing an ill-fitting extension. When a feature or decision is blocked on an external dependency maturing, record it as a deferred decision instead of leaving an open loop or re-investigating from scratch each time. The decision, its date, and the next scheduled review date. A table of conditions that must ALL hold to unblock, each with a target and a concrete "how to check" (a release page, a changelog, a capability list). A periodic cadence (for example quarterly) plus event triggers (on a dependency release, on renewed demand). The implementation outline and the reference implementations to follow once unblocked. What to do if the dependency stalls (seek active forks, choose an alternative approach, or close with an explanation). An append-only log of each review: date, observed dependency version or state, and outcome. Make revisit conditions checkable without re-investigation: name the exact capability (for example a required protocol method) or version threshold, so a future review is a lookup rather than a fresh analysis. Remove dead code by confirming it is unreferenced, not by matching tokens Confirm no references with a semantic reference search, not a raw occurrence count: package-qualified names and re-exported symbols make token counting produce false positives. Search across both source and tests: tests may reference private helpers directly, so a source-only search can wrongly mark a symbol dead. Treat build-system definitions (component or module manifests, barrel or index files) as the boundary of the removal: deleting a file cleanly usually requires updating the manifest that lists it. After removal, reload or build the affected unit (load the system, run the type or compile check, run the relevant test slice) to prove nothing dangles. Thin compatibility barrels that only re-export concrete modules: remove by pointing each consumer at the concrete module, then delete the barrel. Single-use private helpers whose only call sites are local: inline them, keeping the public entry point as the sole behavioral surface.

<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) Before adding a feature to an unfamiliar codebase, write an architecture analysis: existing patterns, a reference implementation, integration points, risks, and the explicit change surface including files that need no change (architecture_analysis_before_feature) Record work blocked on an external dependency as a deferred decision with checkable revisit conditions, not an open loop (deferred_decision_record) Remove dead code by semantic reference confirmation across source and tests, with a build or reload check after removal (dead_code_removal_discipline) </best_practices>

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

<error_escalation inherits="core-patterns#error_escalation"> Evidence trail incomplete Conflicting evidence found Root cause cannot be determined Investigation reveals security issue </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

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

<related_agents> Codebase discovery and file-level evidence gathering Cross-check investigation findings for completeness Consensus verification when investigation findings conflict </related_agents>