From unicorn-team
Navigates unfamiliar codebases using strategic reading: entry points, data flow tracing, error path mapping, and integration analysis. Useful for code review, refactoring, and legacy system modification.
How this skill is triggered — by the user, by Claude, or both
Slash command
/unicorn-team:code-readingThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
<!-- Last reviewed: 2026-03 -->
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
Follow: INPUT -> VALIDATION -> PROCESSING -> STORAGE -> OUTPUT
At each step ask: Where does data enter? What validations? How transformed? Where stored? What side effects?
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?
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.
| 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 |
See references/legacy-code-protocol.md for detailed steps and seam patterns.
| 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.
Starting a new codebase:
Predict structure without reading every line:
npx claudepluginhub aj-geddes/unicorn-team --plugin unicorn-teamExplores project structure, configurations, code patterns, conventions, tests, and dependencies before modifying existing code to understand context and avoid bugs.
Maps unfamiliar codebases in phases: structure, entry points, data flow, patterns, landmines. Use before coding in new, inherited, or revisited projects.
Explores codebase areas: maps files, traces data flows, identifies patterns and dependencies. For 'how does X work', architecture queries, or pre-change analysis.