Code Discovery & Impact Analysis

Quick Reference: Discover patterns and find all usages before making changes.

---

Overview

This skill ensures Claude discovers both how to change code (patterns) and what needs changing (usages) before making modifications.

Two-Phase Process:

1. Pattern Discovery - Understand how similar code is organized (search_code)
2. Usage Discovery - Find ALL places that need updating (find_usage)

Prevents:

• Incomplete refactors (missing usages)
• Assumption-based coding (ignoring project patterns)
• Breaking changes (unknown dependencies)
• Inconsistent implementations (not following conventions)

---

When to Use This Skill

Automatically invoke BEFORE:

• Renaming functions, classes, variables, or types
• Refactoring code structure
• Changing function/method signatures
• Moving or reorganizing files
• Modifying shared utilities or common code
• Updating types/interfaces
• Making architectural changes
• Adding new features (discover similar patterns first)

Manual invocation when:

• Uncertain about project conventions
• Need to understand how similar code is structured
• Planning major changes
• Reviewing code for completeness

---

Depth Levels

CRITICAL: The tools behave differently based on maxResults:

Pattern Discovery (search_code)

• maxResults 1-3: Returns FULL CODE CONTENT (contentIncluded: true)
• maxResults 4+: Returns ONLY METADATA - no code (contentIncluded: false)

Recommendation: Always use 1-3 for pattern discovery to see actual code

Usage Discovery (find_usage)

• All levels: Always includes context (surrounding code lines)
• No difference in content quality between 1, 10, or 50 results

Recommendation: Use 10-15 by default, increase only if needed

---

Minimal (maxResults: 1)

Pattern Discovery: Returns one complete code example Usage Discovery: Returns one usage with context

Use when:

• Verifying a known pattern (just need confirmation)
• Checking if something exists
• Very localized, low-risk changes

Light (maxResults: 2-3) - DEFAULT for search_code

Pattern Discovery: Returns 2-3 complete code examples with variations Usage Discovery: Returns 2-3 usages with context

Use when:

• Learning how code is structured (see variations)
• Understanding naming/organization conventions
• Need to see different approaches
• Adding new features following existing patterns

Why 2-3 for patterns: This is the sweet spot - gets actual code content while showing variations

Thorough (maxResults: 10-15) - DEFAULT for find_usage

Pattern Discovery: ⚠️ NOT RECOMMENDED - returns metadata only, no code Usage Discovery: Returns 10-15 usages with full context

Use when:

• Finding all usages before refactoring
• Renaming functions/classes/variables
• Moving files or modules
• Changing shared utilities
• Complete impact analysis needed

⚠️ Context Management:

• search_code: Stay at 1-3 to get actual code
• find_usage: Use 10-15 by default
• Only increase to 20-50 if results.length == maxResults (indicates more exist)

---

Discovery Workflow

Step 1: Context Assessment

Ask yourself:

1. What am I changing?

   • Function/class/variable name?
   • File structure/organization?
   • Type/interface definition?
   • Shared utility or common code?

2. What's the expected impact?

   • Localized (same file/module)?
   • Module-wide (same feature area)?
   • Cross-cutting (used across codebase)?

3. Which depth level?

   • Minimal (1): Known patterns, just need reference
   • Light (2-3): Learning patterns, most changes (DEFAULT for patterns)
   • Thorough (4-15): Finding all usages, refactoring (DEFAULT for usages)

Step 2: Pattern Discovery

Goal: Understand how to make changes correctly

Use search_code with appropriate maxResults (≤3 for code content):

// Find similar classes/functions
search_code({
  query: "Service",
  types: ["class"],
  pathPattern: "services",
  maxResults: 3  // get actual code content
})

// Find similar file types
search_code({
  query: "repository",
  pathPattern: "modules",
  maxResults: 2  // light search, see variations
})

Document findings:

• File naming pattern
• Organization pattern (directory structure)
• Code structure (classes? functions? decorators?)
• Import patterns
• Naming conventions

Step 3: Usage Discovery

Goal: Find ALL places that need updating

Use find_usage with appropriate maxResults (context always included):

// Find all usages before renaming
find_usage({
  identifier: "oldFunctionName",
  maxResults: 15,  // start here, increase if results.length == maxResults
  exactMatch: true
})

// Find usages in specific area
find_usage({
  identifier: "ClassName",
  pathPattern: "modules/feature",
  maxResults: 10  // context always included regardless of count
})

⚠️ Validate completeness:

• If results.length == maxResults: Increase limit and search again
• If results.length < maxResults: All usages found
• Check for direct usages, indirect usages, dynamic usages, test files

Step 4: Impact Analysis

Create a comprehensive map:

• Files affected: [count]
• Modules impacted: [list]
• Change complexity: [low/medium/high]
• Risk assessment: [rationale]
• Required changes: [detailed list with file:line]

Step 5: Implementation with Validation

1. Make all identified changes
2. Follow discovered patterns
3. Validate completeness:

   // Verify old references are gone
   find_usage({ identifier: "oldName", maxResults: 10 })
   // Expected: 0 results
   
   // Verify new references are correct
   find_usage({ identifier: "newName", maxResults: 10 })
   
   // Check for errors
   check_errors({ pathPattern: "[affected area]" })
   

---

Common Scenarios

Scenario 1: Renaming a Function

1. find_usage({ identifier: "oldFunctionName", maxResults: 15 })
   (increase if results.length == 15)
2. Document all locations (file:line)
3. Update function definition
4. Update all call sites
5. Validate: find_usage("oldFunctionName") → 0 results
6. Validate: find_usage("newFunctionName") → all updated

Scenario 2: Refactoring a Module

1. Pattern discovery: search_code for similar modules (maxResults: 3)
   Get actual code to see structure
2. Usage discovery: find_usage for module exports (maxResults: 15)
3. Map all imports and dependencies
4. Plan refactor following discovered patterns
5. Update all usages
6. Validate with check_errors

Scenario 3: Moving a File

1. Pattern discovery: where do similar files live?
   search_code({ query: "[file type]", maxResults: 2-3 })
   Get code to see organization
2. Find all imports: find_usage for file exports (maxResults: 15)
3. Move file to new location
4. Update all import statements
5. Verify: check_errors()

Scenario 4: Changing Function Signature

1. find_usage({ identifier: "functionName", maxResults: 15 })
2. Analyze how function is currently called (context included in results)
3. Update function signature
4. Update every call site with new parameters
5. Validate with check_errors (catches missed call sites)

Scenario 5: Adding New Feature

1. Pattern discovery: find similar features
   search_code({ query: "[similar feature]", maxResults: 2-3 })
   Get actual code to see implementation
2. Document patterns from code content:
   - File organization
   - Naming conventions
   - Code structure
   - Import patterns
3. Implement new feature following patterns
4. No usage discovery needed (new code)

---

Output Template

Report discoveries using this format:

## Discovery & Impact Report

**Change:** [What I'm changing]
**Depth:** [quick/balanced/comprehensive]
**Impact:** [localized/module-wide/cross-cutting]

### Phase 1: Pattern Discovery
**Found:** [N] similar patterns

1. **File Organization:** [pattern]
   - Location: [path pattern]
   - Example: [file path]

2. **Naming:** [pattern]
   - Examples: [list]

3. **Structure:** [description]
   - Approach: [classes/functions/etc.]

4. **Dependencies:** [import pattern]

**Recommendation:** [How to structure the change]

### Phase 2: Usage Discovery
**Found:** [N] usages across [M] files

| File | Line | Context |
|------|------|---------|
| [path] | [line] | [usage] |

**Completeness:**
- [✓/⚠️] All usages found
- [✓/⚠️] Indirect dependencies checked
- [✓/⚠️] Test files included

### Impact Analysis
**Affected:** [modules/files]
**Complexity:** [low/medium/high]
**Risk:** [low/medium/high] - [reason]

**Changes Required:**
1. [file:line] - [change]
2. [file:line] - [change]

### Implementation Plan
1. [Step 1]
2. [Step 2]

**Validation:**
1. find_usage([old]) → 0 results
2. find_usage([new]) → all updated
3. check_errors() → no issues

**Ready:** [yes/need clarification]

---

Best Practices

Always Do:

• ✓ Use find_usage before renaming anything
• ✓ Check if results.length == maxResults (may need higher limit)
• ✓ Document all findings before making changes
• ✓ Validate completeness after changes
• ✓ Follow discovered patterns, don't assume generic ones
• ✓ Include test files in usage discovery

Never Do:

• ✗ Assume generic patterns without discovering project-specific ones
• ✗ Rename without running find_usage first
• ✗ Stop at maxResults if results.length == maxResults
• ✗ Skip validation after changes
• ✗ Ignore edge cases or unusual patterns

When Uncertain:

• Ask the user for clarification
• Present multiple discovered patterns
• Run comprehensive search (higher maxResults)
• Document what you found and what's unclear

---

Integration with Existing Skills

Works alongside:

• api-design-patterns - API-specific pattern validation
• separation-of-responsibilities - Layer separation checks
• user-access-control - Authorization pattern validation
• module-architecture - Module structure validation

Workflow:

1. Use THIS skill first (discover + find usages)
2. Make changes following discovered patterns
3. Use specific skills for domain validation
4. Use code-evaluation for final check

---

Checklist

Before making changes:

• [ ] Ran pattern discovery (search_code)
• [ ] Documented patterns found
• [ ] Ran usage discovery (find_usage)
• [ ] Checked if more usages exist (results.length < maxResults)
• [ ] Created impact analysis
• [ ] Planned all required changes

After making changes:

• [ ] Updated all identified locations
• [ ] Validated old references gone (find_usage → 0)
• [ ] Validated new references correct
• [ ] Ran check_errors
• [ ] Followed discovered patterns

---

Summary

Key Takeaways:

1. search_code: Use maxResults 1-3 to get actual code content (4+ returns metadata only)
2. find_usage: Always includes context, use 10-15 by default
3. Always discover patterns before assuming generic ones
4. Find ALL usages before renaming or refactoring
5. Validate completeness after changes
6. If results.length == maxResults, search again with higher limit
7. Pattern discovery + usage discovery = complete changes

Remember: This skill prevents incomplete refactors and ensures changes follow project conventions. Use it proactively, not reactively.