---

name: repo-map description: Comprehensive reference for understanding any repo fast. All patterns for docs, code, configs, git, and conversation history. The complete playbook. allowed-tools: Bash, Read, Grep, Glob

Repo Map - Complete Understanding Playbook

Everything you need to understand a repository in minimal tokens.

The 5 Dimensions of Repo Understanding

---

1. DOCUMENTATION PATTERNS

Headings

Markdown Elements

Key Doc Files

Copyls -la README.md CLAUDE.md CONTRIBUTING.md CHANGELOG.md LICENSE 2>/dev/null
ls -la docs/ doc/ documentation/ 2>/dev/null

---

2. CODE PATTERNS

Entry Points

API Routes

Definitions

Models & Schemas

Imports & Dependencies

Copy# Most used Python packages
rg "^(from\|import) " --type py | cut -d' ' -f2 | cut -d'.' -f1 | sort | uniq -c | sort -rn | head -20

# Most used JS/TS imports
rg "^import .* from" --type ts --type js | grep -oP "from ['\"].*?['\"]" | sort | uniq -c | sort -rn | head -20

Decorators & Patterns

Copy# Python decorators
rg "^@\w+" --type py | cut -d':' -f2 | sort | uniq -c | sort -rn | head -15

# Error classes
rg "class.*Exception|class.*Error\(" --type py -n

---

3. CONFIG PATTERNS

Project Configs

Environment

Copy# Find env files
ls -la .env* env.* 2>/dev/null

# Env var names (NOT values)
grep -h "^[A-Z]" .env* 2>/dev/null | cut -d'=' -f1 | sort | uniq

Cloud & CI/CD

Copy# GCP
ls app.yaml cloudbuild.yaml *.tf 2>/dev/null

# GitHub Actions
ls .github/workflows/*.y*ml 2>/dev/null

# Docker
ls Dockerfile docker-compose*.yml 2>/dev/null

Build Tools

Copyls Makefile BUILD.bazel *.bzl 2>/dev/null

---

4. GIT PATTERNS

Copy# Current state
git status --short | head -20

# Current branch
git branch -v | grep "^\*"

# Recent commits
git log --oneline -10

# Changed files (staged)
git diff --cached --name-only

# Contributors
git shortlog -sn | head -10

---

5. CONVERSATION HISTORY

Copycd ~/.claude/services

# Recent sessions
python3 conversation-search.py --list-sessions | head -5

# Search for topic
python3 conversation-search.py "TOPIC" --max 3 --full

# Last exchanges
python3 conversation-search.py "." --session SESSION_ID --max 10 --full

---

QUICK REFERENCE CARD

Minimal Startup (30 sec)

Copy# 1. Sessions
cd ~/.claude/services && python3 conversation-search.py --list-sessions | head -3

# 2. Doc headings
cd - && find . -name "*.md" -not -path "*/.git/*" | xargs grep -n "^# " 2>/dev/null | head -20

# 3. Entry points
rg "if __name__|^func main" --type py --type go -l 2>/dev/null | head -5

# 4. Git state
git status --short | head -10

Full Startup (60 sec)

Copyecho "=== HISTORY ===" && cd ~/.claude/services && python3 conversation-search.py --list-sessions | head -3
echo "=== DOCS ===" && cd - > /dev/null && find . -name "*.md" -not -path "*/.git/*" | xargs grep -n "^# " 2>/dev/null | head -20
echo "=== ENTRY POINTS ===" && rg "if __name__|^func main" --type py --type go -l 2>/dev/null | head -5
echo "=== CLASSES ===" && rg "^class " --type py -c 2>/dev/null | head -10
echo "=== CONFIGS ===" && ls pyproject.toml package.json app.yaml .env* 2>/dev/null
echo "=== GIT ===" && git status --short | head -10 && git branch -v | grep "^\*"

---

Token Budget Guide

Rule: Index everything, read selectively.

---

Related Skills