a-organvm/iterative-code-exploration

Iterative Code Exploration

A systematic pattern for progressively exploring and understanding unfamiliar codebases through iterative context refinement.

The Problem

When working with new codebases, you often don't know:

• Which files contain relevant code
• What patterns and conventions exist
• What terminology the project uses
• How components interact

Standard approaches fail:

• Read everything: Time-consuming and overwhelming
• Guess locations: Often misses critical context
• Ask broad questions: Returns too much irrelevant information

The Solution: 4-Phase Iterative Loop

┌─────────────────────────────────────────────┐
│                                             │
│   ┌──────────┐      ┌──────────┐            │
│   │ DISCOVER │─────▶│ EVALUATE │            │
│   └──────────┘      └──────────┘            │
│        ▲                  │                 │
│        │                  ▼                 │
│   ┌──────────┐      ┌──────────┐            │
│   │   LOOP   │◀─────│  REFINE  │            │
│   └──────────┘      └──────────┘            │
│                                             │
│        Max 3-4 cycles, then synthesize      │
└─────────────────────────────────────────────┘

Phase 1: DISCOVER

Start with broad exploration:

# Find entry points
find . -name "main.*" -o -name "index.*" -o -name "app.*" | head -20

# Discover project structure
tree -L 3 -I 'node_modules|dist|build'

# Find configuration
find . -name "*.config.*" -o -name "package.json" -o -name "*.toml"

# Identify key patterns
grep -r "export class" --include="*.ts" src/ | head -20
grep -r "def " --include="*.py" . | head -20

Document initial findings:

• Project type (web app, library, service, etc.)
• Tech stack (languages, frameworks)
• Architecture hints (monorepo, microservices, etc.)

Phase 2: EVALUATE

Assess discovered files for relevance:

# Read high-value files
cat README.md
cat ARCHITECTURE.md 2>/dev/null
cat docs/overview.md 2>/dev/null

# Check package manifests
cat package.json | jq '.dependencies, .scripts'
cat Cargo.toml 2>/dev/null
cat requirements.txt 2>/dev/null

Scoring Criteria:

• Critical (★★★): Entry points, core logic, main configs
• Important (★★): Utilities, shared components, types
• Supporting (★): Tests, docs, examples
• Noise (-): Generated files, vendored code

Phase 3: REFINE

Focus on specific areas identified as relevant:

# Dive into specific modules
ls -la src/core/
cat src/core/index.ts

# Trace dependencies
grep -r "import.*from.*core" --include="*.ts" src/ | head -20

# Find related patterns
grep -A 5 -B 5 "class UserService" src/**/*.ts

# Check tests for usage examples
find . -name "*.test.*" -o -name "*.spec.*" | head -10

Build mental model:

• How components connect
• What patterns are used consistently
• Where similar functionality lives

Phase 4: LOOP

Decision point - do you need more context?

Continue if:

• Key functionality still unclear
• Dependencies not fully traced
• Patterns inconsistent or confusing

Stop if:

• Core logic understood
• Can explain main flows
• Ready to make changes confidently

Practical Workflow

For Feature Implementation

1. Discover: Find similar existing features

   grep -r "feature-name" src/
   find . -name "*feature*"
   

2. Evaluate: Review implementation patterns

   cat src/features/similar-feature/index.ts
   

3. Refine: Check tests and edge cases

   cat src/features/similar-feature/*.test.ts
   

4. Loop: Trace dependencies until clear

For Bug Fixing

1. Discover: Locate error origin

   grep -r "error message" src/
   git log -S "error message"
   

2. Evaluate: Understand surrounding context

   cat path/to/file.ts | grep -A 20 -B 20 "error location"
   

3. Refine: Check call sites and callers

   grep -r "functionName" --include="*.ts" src/
   

4. Loop: Expand context as needed

For Refactoring

1. Discover: Map current structure

   find src/ -name "*.ts" | xargs wc -l | sort -n
   grep -r "class\|interface" --include="*.ts" src/ | wc -l
   

2. Evaluate: Identify coupling points

   grep -r "import.*from.*module" src/ | cut -d: -f2 | sort | uniq -c | sort -rn
   

3. Refine: Find all usages

   grep -r "ComponentName" --include="*.ts" src/
   

4. Loop: Ensure all references found

Output Template

After each loop iteration, document:

## Iteration N

**Query**: What I was looking for
**Found**: X files, Y patterns, Z components
**Relevance**: High/Medium/Low with reasons
**Gaps**: What's still unclear
**Next**: What to explore in next iteration

**Key Files**:
- path/to/file.ts - Core implementation (★★★)
- path/to/other.ts - Supporting utility (★★)

**Mental Model Update**:
- New understanding of X
- Connection between Y and Z
- Pattern: Description

Integration Points

Complements:

• knowledge-architecture: For documenting discoveries
• second-brain-librarian: For saving exploration notes
• project-orchestration: For planning exploration strategy
• testing-patterns: For learning through tests

Tips

• Start wide, then narrow focus
• Document assumptions to validate
• Use tests as documentation
• Follow imports/exports
• Check git history for context
• Look for comments explaining "why"