# Investigation Patterns

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

- Skill: `tomevault-io/investigation-patterns-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/investigation-patterns-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/investigation-patterns-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/investigation-patterns-2

---


# Evidence-Based Investigation Patterns

## Critical Rules
- Always provide `file:line` references for findings (e.g., `path/to/file.ext:42`)
- Rate confidence (0-100) and coverage (0-100) for all results
- Complete investigation before proposing solutions
- Independently verify claims; don't confirm assumptions

## Investigation Phases

### 1. Scope Classification
- **Architecture** - System design, component relationships
- **Implementation** - Specific code behavior, algorithm details
- **Debugging** - Error causes, unexpected behavior
- **Design** - Pattern usage, code organization

### 2. Evidence Collection
Use tools in order of preference:
1. Symbol search - Locate specific symbols
2. File overview - Understand file structure
3. Reference search - Trace dependencies
4. Pattern search - Find patterns across codebase

### 3. Synthesis with Metrics
- Combine evidence from multiple sources
- Confidence: 90-100 (direct evidence), 70-89 (strong inference), 50-69 (gaps exist), <50 (speculation)
- Coverage: 90-100 (all files), 70-89 (most files), 50-69 (key files), <50 (limited)

## Debugging Workflow

1. **Reproduce** - Confirm exact steps, environment, consistency
2. **Isolate** - Narrow scope (git bisect, minimal reproduction)
3. **Investigate** - Examine errors, logs, trace data flow
4. **Hypothesize** - List causes, rank likelihood, design tests
5. **Fix** - Minimal change, verify resolution, add regression test

## Common Bug Patterns
- **Null reference** - Check all paths to null access
- **Race condition** - Look for shared mutable state, async operations
- **Off-by-one** - Verify loop boundaries, index calculations
- **Resource leak** - Check acquisition/release paths
- **Encoding issue** - Trace encoding at each transformation

## Output Formats

### Investigation Report
```
Question: [restate question]
Investigation: [findings with file:line refs]
Conclusion: [evidence-based answer]
Metrics: Confidence XX, Coverage XX
Unclear Points: [information gaps]
```

### Debugging Report
```
Problem: [clear description]
Root Cause: [with evidence]
Solution: [proposed fix]
Verification: [how to verify]
Prevention: [regression test]
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/motoki317) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->