Code Reading
Strategic Reading Protocol
1. Entry Points First
Start where execution begins. Never read alphabetically.
# Find entry points
grep -r "app.run\|app.listen\|@app.route\|def main\|if __name__" --include="*.py" --include="*.js"
Read order: Main entry -> route definitions -> request handlers -> business logic -> data layer -> utilities
2. Data Flow Tracing
Follow: INPUT -> VALIDATION -> PROCESSING -> STORAGE -> OUTPUT
At each step ask: Where does data enter? What validations? How transformed? Where stored? What side effects?
3. Error Path Mapping
grep -r "try:\|except\|catch\|raise\|throw" --include="*.py" --include="*.js"
Map: What fails? How detected? How handled (retry/fallback/propagate)? What messages returned? Errors logged with context?
4. Integration Points
Identify system boundaries (high-risk areas): APIs, databases, message queues, file systems, external services.
Document for each: expected format, return format, failure modes, retry logic, timeouts.
Comprehension Levels
| Level |
Question |
Technique |
| L1: Behavior |
What does it DO? (inputs, outputs, side effects) |
Read signature + docstring + tests |
| L2: Mechanics |
HOW does it work? (algorithm, data structures, steps) |
Read implementation |
| L3: Design |
WHY this way? (tradeoffs, constraints, optimization target) |
Comments, git log/blame, issue tracker |
| L4: Impact |
What ELSE affected? (callers, dependencies, blast radius) |
grep -r "function_name", check tests |
Legacy Code Protocol
- Run existing tests -- verify current behavior is captured
- Add characterization tests -- document current behavior (even if "wrong")
- Map dependency graph -- who calls this? what does this call?
- Identify load-bearing walls -- critical code that MUST NOT break
- Find seams -- safe change points (object, preprocessing, link seams)
See references/legacy-code-protocol.md for detailed steps and seam patterns.
Reading Techniques
| Technique |
Purpose |
| Follow happy path first |
Understand main flow before edge cases |
| Map side effects |
Find hidden consequences (DB writes, API calls, emails) |
| Identify invariants |
Assumptions that must ALWAYS hold |
| Note coupling points |
High coupling = high risk areas |
See references/reading-techniques.md for detailed guidance and examples.
Reading Checklist
Starting a new codebase:
Before Changing Legacy Code
Common Patterns to Recognize
Predict structure without reading every line:
- Model-View-Controller -- separation of concerns
- Repository Pattern -- data access abstraction
- Strategy Pattern -- algorithm selection
- Observer Pattern -- event notification
- Factory Pattern -- object creation
- Decorator Pattern -- behavior extension
- Adapter Pattern -- interface translation
1---2name: code-reading3description: Strategic code comprehension protocol for navigating existing codebases. ALWAYS trigger on "understand this code", "how does this work", "refactor", "before changing", "legacy code", "code review", "what does this do", "explain this codebase", "walk me through", "unfamiliar code", "read through". Use when exploring unfamiliar code, preparing to modify legacy systems, debugging complex issues, or conducting code reviews. Different from pattern-transfer which maps known solutions across domains -- this skill builds accurate mental models of existing code.4---5<!-- Last reviewed: 2026-03 -->67# Code Reading89## Strategic Reading Protocol1011### 1. Entry Points First1213Start where execution begins. Never read alphabetically.1415```bash16# Find entry points17grep -r "app.run\|app.listen\|@app.route\|def main\|if __name__" --include="*.py" --include="*.js"18```1920**Read order:** Main entry -> route definitions -> request handlers -> business logic -> data layer -> utilities2122### 2. Data Flow Tracing2324Follow: INPUT -> VALIDATION -> PROCESSING -> STORAGE -> OUTPUT2526At each step ask: Where does data enter? What validations? How transformed? Where stored? What side effects?2728### 3. Error Path Mapping2930```bash31grep -r "try:\|except\|catch\|raise\|throw" --include="*.py" --include="*.js"32```3334Map: What fails? How detected? How handled (retry/fallback/propagate)? What messages returned? Errors logged with context?3536### 4. Integration Points3738Identify system boundaries (high-risk areas): APIs, databases, message queues, file systems, external services.3940Document for each: expected format, return format, failure modes, retry logic, timeouts.4142## Comprehension Levels4344| Level | Question | Technique |45|-------|----------|-----------|46| L1: Behavior | What does it DO? (inputs, outputs, side effects) | Read signature + docstring + tests |47| L2: Mechanics | HOW does it work? (algorithm, data structures, steps) | Read implementation |48| L3: Design | WHY this way? (tradeoffs, constraints, optimization target) | Comments, git log/blame, issue tracker |49| L4: Impact | What ELSE affected? (callers, dependencies, blast radius) | `grep -r "function_name"`, check tests |5051## Legacy Code Protocol52531. **Run existing tests** -- verify current behavior is captured542. **Add characterization tests** -- document current behavior (even if "wrong")553. **Map dependency graph** -- who calls this? what does this call?564. **Identify load-bearing walls** -- critical code that MUST NOT break575. **Find seams** -- safe change points (object, preprocessing, link seams)5859See `references/legacy-code-protocol.md` for detailed steps and seam patterns.6061## Reading Techniques6263| Technique | Purpose |64|-----------|---------|65| Follow happy path first | Understand main flow before edge cases |66| Map side effects | Find hidden consequences (DB writes, API calls, emails) |67| Identify invariants | Assumptions that must ALWAYS hold |68| Note coupling points | High coupling = high risk areas |6970See `references/reading-techniques.md` for detailed guidance and examples.7172## Reading Checklist7374Starting a new codebase:7576- [ ] Find entry points (main, routes, handlers)77- [ ] Trace data flow for one request/feature78- [ ] Map error handling and failure modes79- [ ] Identify external dependencies80- [ ] Run existing tests81- [ ] Locate critical business logic82- [ ] Note high coupling points83- [ ] Document in 1-page architecture diagram8485## Before Changing Legacy Code8687- [ ] Run existing tests (capture baseline)88- [ ] Add characterization tests (document current behavior)89- [ ] Map dependency graph (who calls this? what does this call?)90- [ ] Identify load-bearing walls (critical paths)91- [ ] Find seams (safe change points)92- [ ] Make smallest change possible93- [ ] Verify behavior unchanged (tests pass)9495## Common Patterns to Recognize9697Predict structure without reading every line:9899- **Model-View-Controller** -- separation of concerns100- **Repository Pattern** -- data access abstraction101- **Strategy Pattern** -- algorithm selection102- **Observer Pattern** -- event notification103- **Factory Pattern** -- object creation104- **Decorator Pattern** -- behavior extension105- **Adapter Pattern** -- interface translation
aj-geddes